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
- nrjdalal/inscopetheir own version, first seen Oct 13, 2026
- elastic/esql-jstheir own version, first seen Oct 9, 2026
- robzolkos/LazyPitheir own version, first seen Oct 9, 2026
- nrjdalal/zerostartertheir own version, first seen Oct 8, 2026
- remix-run/remixtheir own version, first seen Oct 8, 2026
- robmclarty/trailheadtheir own version, first seen Apr 18, 2026
Other versions6 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 6
- remix-run/remix★ 33ksame name
- robzolkos/LazyPi★ 488same name
- nrjdalal/zerostarter★ 65same name
- elastic/esql-js★ 14same name
- nrjdalal/inscope★ 3same name
- 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.
- AGENTS.mdAGENTS.md
- write-docsSkill
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
- Very specific: line 19
If the package changes an architectural decision (a new layer, a new peer relationship), write an ADR in docs/adr/ first.
- Very specific: line 54
Add a changeset (npx changeset) describing the package for users.
- Very specific: line 62
Follow the write-docs skill: a debuff.jp page in English and Japanese, and the docs ship before the release.
“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.
Files
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
| Folder | For | Rules |
packages/<name> | Browser runtime | No Node APIs. "sideEffects": false. Dev-only code only inside import.meta.env.DEV or in @debuffjp/dev. |
tooling/<name> | Node CLI, MCP, scaffolder | Node 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 sharedkeywords,license,homepage,bugs,funding,repository.directory,"type": "module",exportswithtypesbeforedefault,files: ["dist", "README.md"],scripts.build: "tsc -b",publishConfig.access: "public". Start at the current version of the other@debuffjp/*packages: changesets keeps themfixedtogether.- Other debuff packages it needs at runtime are
peerDependencies(seedocs/architecture.md), notdependencies. tsconfig.jsonextending../../tsconfig.base.jsonwithrootDir: src,outDir: dist.src/index.tsas the only entry unless there is a reason for subpath exports.test/*.test.ts. The rootvitest.config.tspicks uppackages/*/testandtooling/*/testalready.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.jsonreferences. - Package table in the root
README.md. - The runtime package list in
docs/architecture.md(runtime packages only). D:/docs-live/typedoc.jsonentryPointsfor 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(thennpm installat the root). - The agent skill
plugins/debuff/skills/debuff/SKILL.md(and its copy underplugins/openai/), if game authors should reach for the package.
4. Check it
npm install
npm run checklint: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.
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
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.

