---
name: skilld
description: Generate and maintain version-aware skills from your project's real npm dependencies so agents write code for the versions you actually have installed.
---

# skilld: Version-Aware Dependency Skills

## Purpose

Models have a training cutoff. Their picture of any library is a statistical
average of that library's whole history, which biases them toward stale APIs —
old import paths, renamed exports, changed defaults, removed methods. This skill
generates compact, version-specific guidance from the dependencies in THIS
project's lockfile, so the agent writes code for the versions actually installed.

Use this skill whenever you are setting up or refreshing the version-aware skills
for a project, or when you suspect the agent is producing guidance for the wrong
version of a dependency.

## When to use

- Initial setup of a project's skills directory.
- After bumping a major or minor of a library you write code against.
- During any dependency-upgrade pass (Renovate, Dependabot, manual).
- When the agent reaches for an API that no longer matches the installed types.

## When NOT to use

- For patch bumps that don't change the API surface (skip unless the patch fixes
  a footgun the current skill warns about).
- For transitive dependencies you never write code against — generating skills
  for the whole tree creates noise, not value.

## Core workflow

### 1. Resolve the real versions

The lockfile is the source of truth, not `package.json`. `package.json` says
`^5.0.0`; the lockfile says `5.4.2`. Generate against the resolved version.

```bash
cd <project-root>   # must contain node_modules and a lockfile
npx -y skilld
```

### 2. Scope to what you write against

Only generate skills for the libraries the team uses directly:

- framework / meta-framework
- data layer (ORM, query client)
- validation library
- component / UI kit
- test runner

Mental model: "the libraries whose docs I keep open in a browser tab while I work."
Everything else is noise.

### 3. Ground each skill in real sources

For each in-scope dependency at its resolved version, the generated skill should
draw from:

- Installed type definitions in `node_modules` (the on-disk contract — cannot be
  stale relative to your install; this is the floor of correctness).
- Package docs (shipped + hosted) for the current API surface.
- Release notes / changelog for what changed and when.
- GitHub issues for real footguns and workarounds that docs never mention.

### 4. Synthesize, don't dump

Never paste a library's whole documentation into context — that re-introduces the
historical noise that caused the staleness problem, and burns tokens. The skill
should be a briefing:

- Short, imperative guidance the agent can follow directly.
- Explicit "THIS CHANGED" callouts that counteract the model's prior
  (e.g. "import path moved from X to Y in 5.0").
- Current code patterns for common tasks using the real import paths.
- A footgun list pulled from issues, phrased as "don't do X, do Y instead".

### 5. Write skills where the agent loads them

Generated skills go into the project's skills directory as plain Markdown with
YAML frontmatter. They are readable, editable, and committed to version control
next to the code they describe.

## Keeping skills current with releases

A version-aware skill is bound to a version. The single most important rule:

> Regenerate when the version changes. Commit the regenerated skill in the SAME
> commit as the lockfile change so the skill can never silently drift behind the
> dependency.

Bind regeneration to the upgrade itself:

```bash
# inside an upgrade PR
npm install <lib>@latest
npx -y skilld
git add .   # lockfile change + regenerated skills travel together
```

Checklist for an upgrade PR:

- [ ] Dependency version bumped in lockfile.
- [ ] `npx -y skilld` re-run for affected in-scope libraries.
- [ ] Regenerated skill reviewed — "THIS CHANGED" callouts kept.
- [ ] Obsolete footgun warnings removed if the issue was fixed.
- [ ] Skill file + lockfile committed together.

## Reviewing generated output

The tool synthesizes from sources; a human is the editor. Before committing:

1. Read the skill. Confirm the import paths match the installed types.
2. Keep the load-bearing "this changed" and footgun callouts.
3. Trim guidance irrelevant to how the team uses the library.
4. Sanity-check version numbers against the lockfile.

## What to avoid

- Generating for the entire dependency tree — scope to direct usage.
- Treating output as final — it needs editing.
- Letting skills rot after upgrades — a skill three majors behind is worse than
  no skill, because the agent trusts it.
- Regenerating without committing alongside the lockfile change.
- Assuming "latest" is correct when the project is pinned back on purpose —
  generate against the pinned version.

## Composing with other skill sources

- If a dependency ships its OWN `SKILL.md` inside its package (versioned with the
  release), prefer the maintainer's skill — it's authoritative. Use skilld to
  cover the dependencies that don't.
- If the team spans multiple agent harnesses, use a distribution CLI to install
  the skills consistently everywhere, so every agent shares the same grounding.

## Quick reference

| Situation | Action |
| --- | --- |
| New project | Run skilld, scope to direct deps, review, commit |
| Major/minor bump | Regenerate, commit with lockfile |
| Patch bump | Skip, unless it fixes a warned-about footgun |
| Agent uses stale API | Regenerate — skill drifted from lockfile |
| Dep ships own skill | Use the maintainer's; skilld covers the rest |

## Success criteria

- Every in-scope dependency has a skill matching its resolved lockfile version.
- Import paths and APIs in the skills match the installed type definitions.
- Skills and lockfile move together through version control.
- The agent stops suggesting patterns from older versions of your libraries.