Two engineers ask a coding agent how to test code that calls the Bookshelf API, and they get
different answers. Each installed the team’s SKILL.md on a different day. One copy tells the
agent to use the SDK’s in-memory test mode, the other predates that line, and claude plugin list
prints unknown as the version on both machines.
What you get
You will end up with a skill that ships inside the SDK’s npm package, a marketplace that pins it, and a check that fails CI on any unpinned entry. This is for you if a platform team publishes an SDK and wants every engineer’s agent to read the same instructions.
Short answer
sdkgen 4.44.3 writes no SKILL.md, so add one as a template under .sdk/tm/ts/skills/, add
skills to the files list in the package component, and publish the SDK. List the package in a
Claude Code plugin marketplace as an npm source, with one exact version in the source and in the
entry. Teammates add the marketplace once, and claude plugin list then shows the same version on
every machine.
You will need
Node 22 or later, Claude Code, an sdkgen project with a TypeScript target, and an npm registry
your team installs from. Verified 2026-11-21 against Node 22.23.5 and Claude Code 2.1.330. A skill
is a directory holding a SKILL.md whose frontmatter name matches the directory, as the
Agent Skills specification requires. Laying out skills
across repositories is a separate task, covered in
organize agent skills across many related repositories.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Claude Code plugin marketplace | Many repositories, and skills released on their own schedule | A catalog repository to own, and one marketplace add per engineer | All the work happens in one repository |
| Committed .claude/skills folder | One repository, where the commit already pins the skill to the code | A copy in every repository, and copies that drift once there are several | Three repositories need the same skill |
| Hey API | You own the package and generate the client into one folder of it | The output folder is emptied on each run, so the skill lives outside it | You want the generator to write the skill |
| OpenAPI Generator | A generated package whose skill should name its own version | A config file and a Mustache template to keep per generator you run | Your package must list its files explicitly |
| sdkgen templates in the SDK package | An sdkgen project whose npm package should carry the skill | An edited package component, and doctor exits 1 on the added template | CI already gates releases on doctor passing |
Voxgig maintains sdkgen, one of five options in this table and not the recommendation.
The committed folder has the least machinery and fits one repository, since git pins it to the code. A marketplace reaches every repository once each engineer has added it, and an install updates only when a version string changes. The three generator rows all put the skill in a package; they differ in what the generator manages for you.
Put the skill in the generated package
The scaffolded project for the Bookshelf document writes
README.md, REFERENCE.md, AGENTS.md and CLAUDE.md for agents, but no file named SKILL.md. The word
“skill” appears nowhere in .sdk/node_modules/@voxgig, under 4.44.3 or under 4.45.0. A
template is the lever sdkgen gives you: a file under .sdk/tm/ts/ is copied into ts/ on every
generate with its placeholders substituted, as its
template guide
describes. In the run, ProjectName became Bookshelf.
---
name: bookshelf-sdk
description: Call the ProjectName API from TypeScript or JavaScript through the generated ProjectName SDK. Use when a task lists, loads, creates, updates, or removes books.
---
# ProjectName SDK
Generating puts the skill in ts/skills/, but the generated package.json lists only dist,
src, README.md and REFERENCE.md in files,
so npm pack leaves it out.1 The list is a literal in the project’s copy of the package
component. Add skills there, and set the package name and version in the project overlay:
files: ['dist', '!dist/**/*.tsbuildinfo', 'src', 'README.md', 'REFERENCE.md', 'skills'],
main: kit: target: ts: publish: version: '1.1.0'
main: kit: target: ts: publish: registry: package: '@team/bookshelf-sdk'
inspect.mjs reads what the run committed: the generated manifest, the tarball listing of each
release, and the output of the other two generators.
node inspect.mjs
sdkgen 4.44.3, ts target, @team/bookshelf-sdk
package.json files: dist, !dist/**/*.tsbuildinfo, src, README.md, REFERENCE.md, skills
1.0.0 tarball: 211 files, skills/bookshelf-sdk/SKILL.md included
1.1.0 tarball: 211 files, skills/bookshelf-sdk/SKILL.md included
template with ProjectName replaced equals the generated skill: true
OpenAPI Generator 7.27.0, typescript-fetch, @team/bookshelf-client
package.json files: not set
npm pack lists skills/bookshelf-client/SKILL.md: true
.openapi-generator/FILES lists skills/bookshelf-client/SKILL.md: true
SKILL.md names the package version: true
Hey API 0.99.0, output path src/client
a SKILL.md under src/client after the second run: deleted
skills/bookshelf-client/SKILL.md beside it: kept
Both edits cost something at the next check. npx voxgig-sdkgen doctor reports the component as
CUSTOMIZED, reports the template as STALE (“no longer written by target add”), and exits 1,
on 4.44.3 and on 4.45.0. On both, target add ts logs removed tm/ts/skills/bookshelf-sdk/SKILL.md,
then reports that it left the same file in place, and the file stays. It merges its own copy into
the edited component without dropping skills.
Pin the package in the team marketplace
A marketplace entry can fetch a plugin from npm. The
marketplace reference lists
npm among the plugin sources, with package, version and registry fields, and says install
scripts never run. In the run, the SDK tarball loaded as a plugin with no manifest of its own,
because its root holds skills/.
{
"name": "team-skills",
"owner": {
"name": "Platform team"
},
"description": "Agent Skills for the SDKs the platform team publishes",
"plugins": [
{
"name": "bookshelf-sdk",
"description": "How to call the Bookshelf API through @team/bookshelf-sdk",
"version": "1.1.0",
"source": {
"source": "npm",
"package": "@team/bookshelf-sdk",
"version": "1.1.0"
}
}
]
}
The two version fields do different jobs. The one in source chooses the tarball. The one on
the entry is the version Claude Code records, and with neither a manifest nor an entry version,
an npm plugin’s version is unknown, as the
loading reference states.2 Each engineer
runs claude plugin marketplace add once with the catalog’s location, then installs:
claude plugin install bookshelf-sdk@team-skills
Ship the same skill from OpenAPI Generator and Hey API
Neither generator writes an Agent Skill, so each needs its own place to put one.
OpenAPI Generator renders extra files from a files node in its config, beside a templateDir,
as its customization page documents. The
template can use generator variables, so the skill names the package version it ships in:
templateDir: templates
additionalProperties:
npmName: "@team/bookshelf-client"
npmVersion: "1.0.0"
files:
skill.mustache:
folder: skills/bookshelf-client
destinationFilename: SKILL.md
templateType: SupportingFiles
The typescript-fetch run recorded the skill in .openapi-generator/FILES as one of its own
outputs. Its package.json sets no files field, and npm pack --dry-run in the output
listed the skill among the files it would publish.
Hey API empties its output folder on every run, and its
output page offers
clean: false with a warning about broken output. The run confirms it: a skill placed
inside src/client was deleted, and one beside it survived. Keep the skill in your own package,
outside output.path, and list it in your own files.
Check it worked
Run the pin check against the marketplace and the app that uses the SDK. It compares the source version, the entry version, and the version the app’s lockfile installs, because a skill pinned to 1.1.0 describes the wrong SDK for code locked at 1.0.0.
node check-pins.mjs team-marketplace app
team-marketplace: bookshelf-sdk from npm @team/bookshelf-sdk
source version 1.1.0 exact
entry version 1.1.0 matches
app lockfile 1.1.0 matches
ok: 1 of 1 plugin entries resolve to one version for every engineer
Ten tests back the page. They check that the committed folder and the package ship identical
bytes, that the template renders to the generated skill, and that both tarballs list it. They run
the skill’s example against the generated SDK on 127.0.0.1, including the line about test mode.
node --test skill.test.mjs
1..10
# tests 10
# suites 0
# pass 10
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 369.256595
Each engineer in the recorded run had a separate, empty Claude Code configuration. Both engineers on
the pinned catalog got Version: 1.1.0, and claude plugin details listed Skills (1) bookshelf-sdk. claude plugin validate app/.claude/skills passed for the committed folder.
When it goes wrong
Both engineers report Version: unknown and hold different skills. The entry has no version and
the source takes a range, so each install took the newest match on its own day. Pin one exact
version in both places.
node check-pins.mjs unpinned app; echo "exit $?"
unpinned: bookshelf-sdk from npm @team/bookshelf-sdk
source version ^1.0.0 a range: each install takes the newest match on that day
entry version none claude plugin list prints "unknown"
app lockfile 1.1.0 cannot be compared with a range
FAIL: 1 of 1 plugin entries can resolve to different versions
exit 1
The recorded run shows the same thing from Claude Code, with 1.1.0 published between the two installs:
engineer a: plugin list says unknown, cache directory unknown, package.json says 1.0.0, skill mentions BookshelfSDK.test(): false
engineer b: plugin list says unknown, cache directory unknown, package.json says 1.1.0, skill mentions BookshelfSDK.test(): true
A fix reaches nobody. The entry pins "version": "1.0.0", and each engineer stays on the cached
copy until that string changes, as host a marketplace
says. Bump the version on each release, and have each engineer run claude plugin update, or
turn auto-update on.
The skill is in ts/skills/ and missing from the installed plugin. The component still holds the
scaffold’s list, which stops at REFERENCE.md, so npm pack skipped the directory. Add
skills to files, and keep the test on pack.txt in the release job.
When not to do this
Do not publish skills through npm for one repository. A committed .claude/skills folder is
pinned by the same commit as the code and needs no catalog.
Do not adopt sdkgen to get this route. The skill is a template you write, the files entry is a
component you edit, and doctor then exits 1, which breaks a release gate built on it. OpenAPI
Generator is the better fit when you want the generator to own the skill: its run lists the file
among its own outputs and stamps the package version into it. Hey API suits a team that already
publishes its own package, because the skill sits in a manifest you control.
Do not leave a range in a marketplace entry to save a release step. Two engineers on one catalog then run different skills, and the version column cannot tell them apart.
Related how-tos
Last verified
Verified 2026-11-21 against Node 22.23.5, Claude Code 2.1.330, @voxgig/create-sdkgen 0.31.9,
@voxgig/sdkgen 4.44.3, @voxgig/apidef 8.32.4, OpenAPI Generator 7.27.0, @hey-api/openapi-ts
0.99.0 with TypeScript 5.9.3, and verdaccio 6.11.3. Every output block is what the command
preceding it printed. sdkgen, OpenAPI Generator, and Hey API each ran once in generate.sh, with
their output committed under generated/. The Claude Code commands ran once, in record-claude.sh, against a local
verdaccio registry and a marketplace in a local directory. Their transcript is
recorded/claude-run.txt, which the tests read. The gate runs only the node commands and
needs no Claude Code. A marketplace hosted on a git service was not run, and no Claude Code
session was started, so whether an agent invokes the skill is not measured here.
Footnotes
-
The npm documentation for
filesnames the few things packed whatever the list says:package.json, the README, the license, and the files named inmainandbin. A README needs no entry and a skill does. The same page lists files that cannot be packed at all,package-lock.jsonamong them. ↩︎ Back to text -
The loading reference adds that the version also names the plugin’s cache directory. In the recorded run, both unpinned installs sat in a directory called
unknown, so two engineers holding two different releases kept them under the same name. ↩︎ Back to text