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

Source: https://voxgig.com/howto/distribute-agent-skills-to-a-team

- Audience: platform-team
- Level: intermediate
- Languages: typescript
- Verified: 2026-11-21
- Published: 2026-11-21

## 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](https://agentskills.io/specification) requires. Laying out skills
across repositories is a separate task, covered in
[organize agent skills across many related repositories](/howto/organise-skills-across-a-multi-package-ecosystem).

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Claude Code plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces) | 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](https://code.claude.com/docs/en/skills) | 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](https://heyapi.dev/docs/openapi/typescript/configuration/output) | 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](https://openapi-generator.tech/docs/customization/) | 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](https://github.com/voxgig/sdkgen) | 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](/howto/first-sdk-with-sdkgen) 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](https://github.com/voxgig/sdkgen/blob/main/docs/how-to/customize-and-propagate-templates.md)
describes. In the run, `ProjectName` became `Bookshelf`.

```markdown title="overlay/tm/ts/skills/bookshelf-sdk/SKILL.md"
---
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`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json/),
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:

```ts title="overlay/src/cmp/ts/Package_ts.ts"
    files: ['dist', '!dist/**/*.tsbuildinfo', 'src', 'README.md', 'REFERENCE.md', 'skills'],
```

```aontu title="overlay/model/project.aontu"
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.

```bash
node inspect.mjs
```

```text output
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](https://code.claude.com/docs/en/plugins/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/`.

```json title="team-marketplace/.claude-plugin/marketplace.json"
{
  "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](https://code.claude.com/docs/en/plugins/loading) states.[^2] Each engineer
runs `claude plugin marketplace add` once with the catalog's location, then installs:

```bash
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](https://openapi-generator.tech/docs/customization/) documents. The
template can use generator variables, so the skill names the package version it ships in:

```yaml title="generated/openapi-generator/config.yaml"
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](https://heyapi.dev/docs/openapi/typescript/configuration/output) 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.

```bash
node check-pins.mjs team-marketplace app
```

```text output
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.

```bash
node --test skill.test.mjs
```

```text output
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.

```bash
node check-pins.mjs unpinned app; echo "exit $?"
```

```text output
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:

```text title="recorded/claude-run.txt"
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](https://code.claude.com/docs/en/plugins/host-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

- [Organize agent skills across many related repositories](/howto/organise-skills-across-a-multi-package-ecosystem)

- [Generate agent skills for your API from a semantic model](/howto/generate-agent-skills-from-an-api-model)

- [Install an API skill and check a coding agent uses it](/howto/install-an-api-skill-for-a-coding-agent)

- [Write a skill description that triggers at the right time](/howto/write-a-skill-description-that-triggers)

- [Publish an agent skills index for your site](/howto/publish-an-agent-skills-index)

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

[^1]: The npm documentation for [`files`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json/)
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.

[^2]: The [loading reference](https://code.claude.com/docs/en/plugins/loading) 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.