new-spec
Skill0 starsChanged 44 days agoMITView on GitHub
Create a new specification (capability or entity spec) in the right area with the correct format. Use when the user says "new spec", "spec this endpoint/entity/behavior", or new externally observable behavior is being designed. Also use unprompted when a change adds or alters externally observable behavior (a route, command, flag, exit code, or invariant) that no existing spec covers.
12 other projects use a version of this.
Adopted by
Most recently taken up by
- eugenelim/agent-ready-repotheir own version, first seen Nov 8, 2026
- phanijapps/memextheir own version, first seen Oct 17, 2026
- kitloomlk-stack/spec-driven-planning-kittheir own version, first seen Oct 15, 2026
- gabo963/claude-skillstheir own version, first seen Oct 15, 2026
- gofixpoint/amikatheir own version, first seen Oct 8, 2026
- RocketChat/Rocket.Chat.Electrontheir own version, first seen Oct 8, 2026
Other versions12 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 12
- RocketChat/Rocket.Chat.Electron★ 1.7ksame name
- a16z/jolt★ 1.1ksame name
- gofixpoint/amika★ 301same name
- eugenelim/agent-ready-repo★ 28same name
- brayandiazc/project-starter-template-es-ai★ 15same name
- eugenelim/llm-wiki-kit★ 12same name
- brayandiazc/project-starter-template-en-ai★ 2same name
- jhlee0409/omni-harness-kit★ 2same name
- dabodamjan/app-idea-to-spec★ 0same name
- gabo963/claude-skills★ 0same name
2 more not listed
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 repository21 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- first-runSkill
- fix-ciSkill
- new-adrSkill
- new-packageSkill
- new-specSkill
- prSkill
- releaseSkill
- sync-templateSkill
- update-depsSkill
- verify-docsSkill
- first-runSkill
- fix-ciSkill
- new-adrSkill
- new-packageSkill
- prSkill
- releaseSkill
- sync-templateSkill
- update-depsSkill
- verify-docsSkill
The file
We split this skill into the rules it gives an agent
5 rules. 0 are common, 1 is distinctive, and 4 are very specific to this project.
0
Common
Most of the 11 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Create a spec under docs/internal/specs/<area>/.
- Very specific: line 10
If this is the roots template itself, write nothing under docs/internal/specs/.
- Very specific: line 13
Every child starts with a copy of docs/internal/specs/, so it stays clean here (see "What roots chose" in docs/template/conventions.md).
- Very specific: line 31
Run pnpm docs:gen, then pnpm docs:check.
- Distinctive: line 35
If the request names the capability or entity, use it.
“Common” is measured: kept by at least 6 in 10 of the 11 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
New specification
Create a spec under docs/internal/specs/<area>/.
- If this is the roots template itself, write nothing under
docs/internal/specs/. Use the fork and template checks in step 0 of thefirst-runskill; a contribution fork of roots counts as the template. Every child starts with a copy ofdocs/internal/specs/, so it stays clean here (see "What roots chose" indocs/template/conventions.md). A template mechanic's contract lives in its page underdocs/template/, in the shape ofsync-template.md: Source, Tests, and Last reviewed bullets, whichpnpm docs:checkholds to the spec rules. Edit that page, or add one and list it indocs/template/README.md, then stop. - Decide the kind, capability or entity, per "Spec kinds" in
docs/template/spec-discipline.md. - Pick or create the
<area>folder (for exampleapi/,cli/,domain/). The handbook sidebar andpnpm docs:listdiscover new areas automatically. - Copy
docs/internal/specs/_template.mdto<area>/<name>.mdand fill it: Source and Tests bullets as backticked repo-relative paths ((pending)is legal spec-first),- **Last reviewed:**today. Purpose, Non-goals, Contract (precise inputs/outputs or invariants), Behavior as Given/When/Then branches, Edge cases. - Behavior is numbered branches, each a binary check. The test the spec must
pass is under "Spec kinds" in
docs/template/spec-discipline.md; a branch that fails it is not specified yet. - Run
pnpm docs:gen, thenpnpm docs:check; both must pass. If this spec ships with a behavior change, source and tests move in the same PR (three-place sync).
If the request names the capability or entity, use it.
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.