agentleFS
debuffjpdebuffjp/debuff/.claude/skills/add-package/SKILL.md

add-package

Skill12 starsChanged 30 days agoMITView on GitHub

Add a new package to the debuff monorepo (packages/* for browser runtime, tooling/* for Node). Use before creating any new workspace, and to review one that was just added.

  • Reads credentials
  • Installs packages

6 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions6 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 6

    1. remix-run/remix★ 33ksame name
    2. robzolkos/LazyPi★ 488same name
    3. nrjdalal/zerostarter★ 65same name
    4. elastic/esql-js★ 14same name
    5. nrjdalal/inscope★ 3same name
    6. robmclarty/trailhead★ 0same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository2 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

3 rules. 0 are common, 0 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 6 edited versions we read keep these.

  • 0

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If the package changes an architectural decision (a new layer, a new peer relationship), write an ADR in docs/adr/ first.

    line 19
  2. Very specific:

    Add a changeset (npx changeset) describing the package for users.

    line 54
  3. Very specific:

    Follow the write-docs skill: a debuff.jp page in English and Japanese, and the docs ship before the release.

    line 62

“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Adding a package

A new package is a new public promise: a name on npm, a line in the docs and something to keep tree-shakeable. Check first that it can't be a module in an existing package.

1. Decide where it goes

FolderForRules
packages/<name>Browser runtimeNo Node APIs. "sideEffects": false. Dev-only code only inside import.meta.env.DEV or in @debuffjp/dev.
tooling/<name>Node CLI, MCP, scaffolderNode APIs are fine.

Runtime dependencies need a trade-off note in the PR (AGENTS.md). Prefer writing the small piece yourself; if you must depend, wrap it in one module of ours that every caller goes through, so replacing it later touches one file.

If the package changes an architectural decision (a new layer, a new peer relationship), write an ADR in docs/adr/ first.

2. Scaffold it

Copy the shape of packages/juice (the plainest runtime package):

  • package.json: name @debuffjp/<name>, the shared keywords, license, homepage, bugs, funding, repository.directory, "type": "module", exports with types before default, files: ["dist", "README.md"], scripts.build: "tsc -b", publishConfig.access: "public". Start at the current version of the other @debuffjp/* packages: changesets keeps them fixed together.
  • Other debuff packages it needs at runtime are peerDependencies (see docs/architecture.md), not dependencies.
  • tsconfig.json extending ../../tsconfig.base.json with rootDir: src, outDir: dist.
  • src/index.ts as the only entry unless there is a reason for subpath exports.
  • test/*.test.ts. The root vitest.config.ts picks up packages/*/test and tooling/*/test already.
  • README.md: one-line summary, install, a short example, link to debuff.jp.

3. Register it

Each of these is a place that lists packages by hand:

  • Root tsconfig.json references.
  • Package table in the root README.md.
  • The runtime package list in docs/architecture.md (runtime packages only).
  • D:/docs-live/typedoc.json entryPoints for runtime packages.

A standalone spin-off with its own name (myaku, plonkjs, keiko) skips the last two. It gets its own section on debuff.jp instead, and its README row says "Standalone".

  • Templates that should use it: their package.json (then npm install at the root).
  • The agent skill plugins/debuff/skills/debuff/SKILL.md (and its copy under plugins/openai/), if game authors should reach for the package.

4. Check it

npm install
npm run check

lint:packages runs publint and attw on every non-private package, so a broken exports map fails here, not on npm. Report the template's brotli size from the build output if a template now imports the package.

Add a changeset (npx changeset) describing the package for users.

5. First publish

A brand-new name can't have a trusted publisher until it exists on npm. The first version is published locally; see docs/releasing.md. That's the maintainer's step: say it's needed, don't run it.

6. Document it

Follow the write-docs skill: a debuff.jp page in English and Japanese, and the docs ship before the release.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.