Generate a package Skill

Write a short Skill that stops an Agent from misusing one package version. The reader knows the language, the framework, and the domain. Write only what it would get wrong.

Inputs

Take a package name, directory, or prepared source. Ask for the destination only when it is missing. In a monorepo, put the Skill in the published package directory. Write one Skill per installed package, unless a second package has distinct users. Skip an internal package, whose users are the repository's own packages, such as a shared engine or types package. Report why, and write nothing. assets/ holds the Harness request. A direct run ignores it.

1. Research

1. Record the exact version the destination branch publishes: its package.json version and the npm dist-tag that carries it. If npm latest is an older major, test the branch's version. If the branch is ahead of its last release, read source at that release tag and report the unreleased changes.
2. Read the manifest, every exported entry point, and the public types. For many sibling integrations, read the shared runtime and the most used few, and report which you sampled.
3. For a framework module, read what setup registers: auto-imports, components, the config key and defaults, hooks, server routes.
4. If the package wraps, re-exports, or peers on another package, read the types or tagged source of the version the consumer gets, never a default branch.
5. Read the current official docs and examples, and release notes only for breaking changes and removed APIs. When docs cover several frameworks, read the consumer's framework pages first, then the core pages they link.

To update an existing Skill after a release, use update-package-skill. It tests only what the release changed.

2. Test the examples

Observed behaviour beats documentation.

1. Create a minimal consumer fixture outside the package source. Install the recorded version, or link the local build. Before packing, build the package and its native code (NAPI, WASM); prepack can need them. Pack with the repository's package manager: npm pack leaves pnpm catalog: versions. Give the fixture its own pnpm-workspace.yaml, so a parent workspace cannot satisfy its imports. Install only the package, documented peers, and check tools such as typescript. A resolution error is a finding. Install each peer at npm latest. If latest is outside the peer range, test both versions.
2. Use consumer defaults. The package repository's config and fixtures can turn them off. In Nuxt, keep test modules out of modules/; Nuxt registers every module there. One fixture page can exercise many examples.
3. Run each example you include. Compare output with the claim: HTML, return values, type errors, build logs, exit codes, report files. Each concrete claim in prose is an example too: a value, count, default, result shape, error text, exit code, or bundle effect. Run it, or report it read from source. Run each example with one failure input as well, such as an unreachable URL, a bad token, or a stalled request. Run each example under each global setting the Skill describes, such as a staging environment or a site-wide switch. For each claim that a setting or dependency is required, run once without it and record what fails. Test each mode the package declares: framework modes (SSR, SPA, streaming, dev, build), each condition in exports, the oldest runtime in engines, and each CLI binary with a config file and with flags. Report other modes untested. Wrap every run in timeout 120. Grep the package for agent and CI detection, such as CLAUDECODE or CI; unset each variable it reads with env -u VAR. Read dev warnings in the dev log, prerender results in build output, and runtime results from the production server. If a trap says nothing happens, run it and confirm the silence. To fetch from a server, run scripts/serve-fixture.mjs in the fixture: node SKILL_DIR/scripts/serve-fixture.mjs --fetch / -- node .output/server/index.mjs. Quote '{port}' in a server argument, since some shells expand it. --header 'User-Agent: Googlebot/2.1' sends a header, Host included. For a binary, use --fetch-raw PATH --out DIR. DIR/responses.json lists each status, content type, and response headers. For an HTTP client package, start a fake target on port 0 inside the test, and assert on the requests it receives. Without --fetch, it holds the server until SIGTERM. Background it with your tool's option; & and nohup die with the shell call. Start servers from your own test script and record each process ID you start; stop only those. Never kill by port or with pkill -f: another Agent can own that process. In a browser, set a desktop user agent; a package can treat HeadlessChrome as a bot.
4. If documentation and behaviour disagree, write the behaviour and report the mismatch.
5. Keep an unrunnable example only when the types prove it; report it untested.

Do not fix the package or its docs in the Skill change.

3. Write

Include:

• Setup that differs from the framework default, such as a required config key.
• What the package does automatically, and how to turn it off.
• Traps: silent failures, plausible wrong calls, documentation mismatches, version limits.
• One small example per common task the types do not make obvious.
• Breaking changes an Agent trained on an older version would repeat: old call, new call.
• A deploy section, such as CI cache or Cloudflare, when most traps live there.

Cut:

• Self-explanatory config options; link the config reference. Keep a table when values are the API, such as priorities.
• Internals the consumer cannot act on, such as tree shaking.
• Changelog paraphrase, fixed bugs, release history.
• Generic debug advice, such as "view source" or public validators.
• path:line citations. Put evidence in the report.
• Any second copy of content, such as a list repeating inline reference links.

Shape:

• Name the package and tested version in the first paragraph, not the frontmatter.
• Order, dropping empty sections: setup, automatic behaviour, common tasks, integrations, traps, version limits, config, debug.
• A config example that is a common task goes there; the config section only lists options.
• Write each code block as a complete file with the imports the framework accepts. Start it with a path comment, such as // server/api/search.ts, so it can be extracted.
• Write the tested version once, in the first paragraph. Other version literals, such as a User-Agent string, go stale.
• A trap detailed in a reference gets one linking line in traps.
• Aim for 150 lines and about 2,000 tokens in SKILL.md. Never exceed 500 lines. Past the aim, keep silent failures before loud ones and common-path traps before rare ones. Merge traps that share a fix. Cut a common-task example before a trap.
• Keep one file. Move a topic to references/<topic>.md only past about 40 lines and when under a third of tasks need it.
• Link each reference from SKILL.md, one level deep. A reference over 100 lines starts with contents.
• Write at most eight reference files. Add scripts/ only when running code beats reading it.
• Skillgen maintains only SKILL.md and Markdown under references/: at most 9 files and 64 KiB in total. It never updates scripts/.
• Never include credentials, caches, build output, or dependency directories.

The frontmatter contains name and description. It may also contain license, compatibility, metadata, and allowed-tools. If the source declares a license, copy its identifier into license. Never infer a license. Include compatibility only for specific tool, runtime, network, or product requirements, at most 500 characters. Omit it for general guidance. Do not repeat the package name, tested version, or implementation details. metadata maps string keys to string values. allowed-tools is an experimental space-separated string of pre-approved tools. The name uses lowercase letters, numbers, and single hyphens, at most 64 characters, and matches the directory. For a scoped package, drop the @ and replace / with a hyphen: @nuxtjs/seo becomes nuxtjs-seo. The description, at most 1024 characters in third person, says what the Skill does, then when to use it, in the words a user types: package name, main exports, config key, error symptoms. Write it as one plain line of 300 to 450 characters. Skill loaders parse frontmatter with different YAML parsers, so use no double quotes, backticks, or %. Name an error symptom in plain words, never as a quoted message. Good: Adds and debugs Schema.org JSON-LD in Nuxt with nuxt-schema-org. Use when a task mentions structured data, rich results, useSchemaOrg, defineArticle, or the schemaOrg config key.

4. Check and report

Cross-Agent portability

Keep one source Skill for compatible Agents. Keep their discovery paths outside the generated Skill. Use capability descriptions instead of provider-specific tool names. Ask for inputs explicitly; do not depend on $ARGUMENTS, hooks, or dynamic context injection. Resolve bundled files from the Skill directory and consumer commands from the consumer project root. Name script runtimes, binaries, network access, and credential requirements beside their use. If a required capability is unavailable, report it and stop that dependent step. Never invent evidence or silently skip a required check.

Check a matching task, an unrelated task, and a missing-input task. When available, use a fresh session in each Agent the user asks to support. If the user names no Agent, validate the format with skilld run SKILL_DIR --json and expect _tag: Success. Test the current Agent if it can start a fresh session. Record its version, model, task, output, and required permissions. Distinguish format validation, discovery, activation, and task completion. Report unavailable Agent paths untested. Package example checks do not prove cross-Agent execution.

Before finishing, extract every block with scripts/extract-blocks.mjs: node SKILL_DIR/scripts/extract-blocks.mjs SKILL.md DIR. Copy each block into the fixture and run it unchanged. Never test a copy you edited by hand. Repeat after each edit. --replace https://example.com=http://localhost:PORT swaps a placeholder. DIR/blocks.json maps each block to its line.

Confirm:

• Each example ran against the recorded version, or is reported untested.
• Each reference is linked. Delete stale files from an earlier Skill.
• The frontmatter follows the rules above, parses with a strict YAML parser, and skilld run SKILL_DIR --json returns _tag: Success. Fix each failure before you finish.

Report to the user:

• The files and the tested version.
• Each untested example, and each mismatch: example, documented result, observed result. These are package bugs. Draft them as one issue for the package Repository, ordered by impact: silent wrong results, crashes, doc mismatches, cleanups. Give each item expected, observed, a minimal repro with its output, and a source link at the release tag. File it only if asked.
• The source path or documentation URL behind each version-specific rule.
• If the Skill sits inside the published package directory, add its directory to files in package.json. After one build, list packed files with npm pack --dry-run --ignore-scripts; pnpm pack rejects that flag.
• For npm packages, use skills/<name>/SKILL.md beside the package's package.json. Include linked files in the tarball. pnpm 12.11 and newer link Skills from approved direct dependencies. Document pnpm approve for developers who want these links. Approval covers every Skill and later version of the package. Never approve a package for the user without their request. pnpm owns its links, dependency updates, and removal.
• Edit the README beside the Skill's package.json. If it already links the skilld.dev page, keep that link. Else add the badge below after the others. Replace a skilld add tip that names this package in place with the tip below. Else add the tip after the install command. Replace OWNER, REPOSITORY, and PACKAGE. Count every SKILL.md in the Repository, hidden Agent folders included; the skilld.dev indexer skips test and fixture folders. If it holds several Skills, append /SKILL_NAME to the page and badge paths. The README omits the run command; the page shows it.

<a href="https://skilld.dev/gh/OWNER/REPOSITORY">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://skilld.dev/b/OWNER/REPOSITORY?theme=dark">
    <source media="(prefers-color-scheme: light)" srcset="https://skilld.dev/b/OWNER/REPOSITORY?theme=light">
    <img alt="Skill repository on skilld.dev" src="https://skilld.dev/b/OWNER/REPOSITORY?theme=light">
  </picture>
</a>

> [!TIP]
> Using an AI agent? Get the PACKAGE Skill on [skilld.dev/gh/OWNER/REPOSITORY](https://skilld.dev/gh/OWNER/REPOSITORY).

For a direct run, show the files for review, or open a pull request if asked. Replace an existing Skill only with user approval. A direct run has no Harness checks; never claim it passed them.