How-to › Expose your API to agents

How to distribute agent skills to a team#

Ship one SKILL.md inside the SDK package you already publish, list that package in a Claude Code plugin marketplace at an exact version, and check every pin in CI.

Audience
Platform team
Level
intermediate
Topic
Write agent skills and instruction files
Languages
TypeScript
Verified

Read first: Organize agent skills across many related repositories

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
Claude Code plugin marketplaceMany repositories, and skills released on their own scheduleA catalog repository to own, and one marketplace add per engineerAll the work happens in one repository
Committed .claude/skills folderOne repository, where the commit already pins the skill to the codeA copy in every repository, and copies that drift once there are severalThree repositories need the same skill
Hey APIYou own the package and generate the client into one folder of itThe output folder is emptied on each run, so the skill lives outside itYou want the generator to write the skill
OpenAPI GeneratorA generated package whose skill should name its own versionA config file and a Mustache template to keep per generator you runYour package must list its files explicitly
sdkgen templates in the SDK packageAn sdkgen project whose npm package should carry the skillAn edited package component, and doctor exits 1 on the added templateCI 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.

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

  1. The npm documentation for files names the few things packed whatever the list says: package.json, the README, the license, and the files named in main and bin. A README needs no entry and a skill does. The same page lists files that cannot be packed at all, package-lock.json among them. ↩︎ Back to text

  2. 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

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.