Adding a skill or distribution

Use Author Skill when creating, revising, migrating, or reviewing a skill. It first identifies the target repository’s conventions. The steps below are the concrete source and build rules for this repository.

Start with one editable owner under src/skills/<canonical-name>/. The distribution catalog then declares each installation form that the repository actually supports. Do not create a second authored copy under skills/ or plugins/.

1. Choose the smallest owner

A prompt-only skill needs SKILL.md and only the resources its instructions use. complexity-review is the minimal example: its generated standalone unit contains instructions and one reference, with no runtime or artificial build.json.

An executable skill adds source under src/ and lists its runtime entrypoints in build.json. See session-export-transcript/build.json. Entrypoints may be TypeScript or authored .mjs; authored .mjs requires an adjacent .d.mts declaration. The builder follows imports, rejects package dependencies and source escapes, then bundles the runtime closure into each target. Source, tests, and declarations do not enter the installed payload.

Set one quoted stable metadata.version in the canonical SKILL.md. Do not add a top-level skill version.

2. Declare supported targets

Add one owner entry to src/distributions.ts:

{
  owner: 'example-skill',
  source: 'src/skills/example-skill',
  targets: [
    {
      kind: 'standalone',
      name: 'example-skill',
      output: 'skills/example-skill',
    },
    {
      kind: 'plugin',
      plugin: 'example-plugin',
      name: 'example',
      output: 'plugins/example-plugin/skills/example',
    },
  ],
}

Declare only the forms you intend to support. owner and source identify the canonical source. A target defines its kind, installed name, and constrained output path. Add allowedSourceRoots only for code the entrypoint is allowed to bundle from another owned source root.

3. Keep code dependencies separate from workflow references

Use requiredSkills for a workflow that must already be installed and optionalSkills for an integration whose absence does not block core work. Each reference has a canonical skill name and install URL. In canonical instructions, use explicit {{skill:<canonical-name>}} or {{skill-identities:<canonical-name>}} slots where a target-specific identity is needed. The build resolves those slots for standalone and plugin-local forms and fails if a reference is undeclared or unresolved.

Workflow references are not runtime imports. They are not bundled or installed automatically. The relationship is summarized in Generated installation units.

4. Distinguish plugin membership from a new plugin

Adding a skill to an existing plugin requires a plugin target in the owner's distribution entry and whatever focused inventory/manifest evidence that membership changes.

Adding a new plugin also requires independently owned provider manifests and marketplace/catalog registration, plus an entry in pluginReleaseTargets. Those release surfaces are not inferred from skill targets and are not fully generated by the skill packager. Follow the current release guidance in RELEASING.md rather than copying another plugin's version or claiming provider availability.

5. Build and inspect

For an ordinary intentional edit:

1. Edit the canonical owner and distribution declaration.
2. Bump the owner's metadata.version when required by the version-impact rules.
3. Run pnpm run build.
4. Inspect every generated target for its installed name, complete payload, links, and executable modes.
5. Run focused owner/shared tests, the relevant packaging tests, and pnpm run build:check.

When auditing a branch that may already contain drift, run pnpm run build:check before a repairing build so the original freshness failure remains observable. See the failure table for recovery boundaries.

Promotion and provenance

When promoting an existing skill into this repository, establish one canonical owner and make every shipped form a declared generated consumer. Preserve the origin and cutover rationale in the appropriate project or decision record, not as another maintained source tree or a private-path checklist in public docs. Remove or archive the old editable owner only through its separately authorized cutover. This keeps provenance visible without creating compatibility aliases or parallel payloads.