--- name: ship-skills-with-package description: Author, version, and ship SKILL.md files inside your npm package so agents get version-accurate guidance on every install. --- # Ship Skills With Your Package This skill teaches library maintainers how to author, version, and ship `SKILL.md` files inside their published npm package. The goal: every consumer who runs `npm install your-lib` gets agent guidance that is pinned to the exact version they installed, and that guidance updates automatically on every release. Treat the skill as a public API artifact, like `.d.ts` files. ## When to use this skill Reach for this when: - You maintain a library, framework, or SDK published to npm. - Coding agents frequently write outdated or incorrect code against your API. - You answer the same "how do I use X" questions repeatedly. - You want your migration guidance to travel with each release. ## Core principle A `SKILL.md` is to the agent what `.d.ts` is to the type checker: instructions generated from your source, shipped in the tarball, pinned to the version. It must live in the same repo, the same PR, and the same release as the code it describes. Co-location is what prevents drift. ## Step 1: Scaffold the structure Initialize the skill layout in your repo: ```bash npx @tanstack/intent scaffold ``` If you scaffold by hand instead, create this structure: ``` your-lib/ package.json src/ dist/ skills/ your-lib/ SKILL.md # the main skill migration-5.md # optional: version-to-version migration notes CHANGELOG.md ``` Keep skills under a top-level `skills/` directory, namespaced by package name so monorepos can host several. ## Step 2: Make the skill ship in the tarball The skill is worthless if `npm publish` strips it. Add the directory to the `files` array in `package.json`: ```json { "name": "your-lib", "version": "5.4.0", "files": [ "dist", "skills" ] } ``` Verify what will actually be published before you release: ```bash npm pack --dry-run # Confirm skills/your-lib/SKILL.md appears in the file list ``` ## Step 3: Write the SKILL.md body Structure the skill so an agent can load it and immediately produce correct, current code. Recommended sections: ### Frontmatter ```yaml --- name: your-lib description: One line stating what the library does and that this guidance is version-accurate for the installed release. --- ``` ### Lead with the current idiom State the single correct way to do the most common task, in the current version's syntax. Do not narrate API history. Example shape: ```md ## The common case Always create the client once at module scope and pass it down: \`\`\`ts import { createClient } from 'your-lib' export const client = createClient({ retry: 2 }) \`\`\` Do NOT create a client per request — it was valid before 5.0 and now leaks. ``` ### Encode the gotchas List the questions you answer over and over, as "do / don't / why": ```md ## Gotchas - DO set `staleTime` explicitly. As of 5.0 the default changed to 0. - DON'T mutate the options object after init; it is frozen in 5.2+. - DON'T import from 'your-lib/internal'; it is not a public entry point. ``` ### Pin defaults and breaking changes The model cannot know post-cutoff defaults. State them: ```md ## Version facts (5.x) - Default transport: fetch (was XHR before 5.0) - `timeout` is now milliseconds (was seconds before 4.0) - `onError` removed in 5.0; use the result's `error` field ``` ### Show runnable snippets Every recommended pattern should have a copyable code block in the real current syntax. Snippets beat prose for agents. ### Keep it tight This loads into a context window. Cover the high-frequency core and link to full docs for the long tail. Aim for relevance over completeness. ## Step 4: Version with every release Make updating the skill a non-optional release step. Add it to your checklist: ```md ## Release checklist - [ ] Update CHANGELOG.md - [ ] Update skills/your-lib/SKILL.md for any API change - [ ] Update version facts section if a default changed - [ ] npm pack --dry-run confirms skill is included - [ ] Tag and publish ``` The rule: if a PR changes public behavior, it must update the skill in the same PR. Reviewers should reject API changes that leave the skill stale, the same way they reject changes that leave types or docs stale. For breaking changes, ship a focused migration note alongside the main skill (`skills/your-lib/migration-5.md`) so agents can help users upgrade. ## Step 5: Test the skill A skill that misleads the agent is worse than none. Validate before release. ### Manual smoke test 1. Install your prerelease in a scratch project. 2. Point an agent at it via the Vercel CLI: ```bash npx skills add ./node_modules/your-lib/skills/your-lib ``` 3. Ask the agent to perform the three most common tasks. 4. Confirm it uses the current API, correct defaults, and no deprecated calls. ### Regression check on gotchas For each "don't" in your skill, ask the agent to do the thing and confirm it now avoids the trap. If it still falls in, the guidance is not phrased strongly enough — make it more explicit. ### Accuracy audit - Run every code snippet in the skill against the actual current version. - Grep the skill for version numbers and confirm they match `package.json`. - Check that no removed API names still appear in examples. ## Step 6: Help consumers install Document the install command in your README so users can wire the shipped skill into any agent: ```bash # From the installed package npx skills add ./node_modules/your-lib/skills/your-lib # Or directly from your GitHub repo npx skills add your-org/your-lib ``` For Kiro users, note that dropping skills into `.kiro/skills/` loads them automatically. ## Anti-patterns to avoid - Shipping a skill that just restates the README. Add the gotchas and version facts the README lacks. - Letting the skill drift from the code. Co-locate changes in one PR. - Writing for a version you do not pin. Always state which major version the guidance targets. - Globbing in untrusted skills from elsewhere. Author your own from source. - Bloating the skill. Trim to the high-frequency core; link out for the rest. ## Definition of done - `SKILL.md` exists under `skills//` and is listed in `files`. - `npm pack --dry-run` shows the skill in the tarball. - All snippets run against the current version; all version facts are correct. - Release checklist includes updating the skill. - An agent loaded with the skill performs the top tasks correctly and avoids the documented gotchas.