generate-package-skill

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.