new-spec
Skill2 starsChanged 2 months agoMITView on GitHub
Scaffolds a new lightweight change spec by copying the spec template directory into a named spec folder. Use this when the user wants to start a spec, plan a change/feature, or create a design doc before implementing (e.g. "spec out the checkout redesign", "create a spec for the new auth flow").
12 other projects use a version of this.
Adopted by
Most recently taken up by
- eugenelim/agent-ready-repotheir own version, first seen Nov 14, 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★ 305same name
- eugenelim/agent-ready-repo★ 31same name
- brayandiazc/project-starter-template-es-ai★ 15same name
- eugenelim/llm-wiki-kit★ 12same name
- jhlee0409/omni-harness-kit★ 2same name
- dabodamjan/app-idea-to-spec★ 0same name
- gabo963/claude-skills★ 0same name
- kitloomlk-stack/spec-driven-planning-kit★ 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 repository20 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- accessibility-auditSkill
- changelogSkill
- commitSkill
- configure-repoSkill
- copywritingSkill
- design-system-auditSkill
- i18n-paritySkill
- identitySkill
- instantiateSkill
- migration-guardSkill
- new-adrSkill
- open-issueSkill
- open-prSkill
- port-changeSkill
- prototypeSkill
- releaseSkill
- seo-auditSkill
- update-templateSkill
The file
We split this skill into the rules it gives an agent
7 rules. 0 are common, 1 is distinctive, and 6 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.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 7
Create a new change spec named in $ARGUMENTS.
- Very specific: line 9
Read specs/README.md to learn the spec workflow, the folder naming convention, and what each template section expects.
- Distinctive: line 18
Leave problem, goals, non-goals, and approach as prompts for the author.
- Very specific: line 19
Fill in "Evidence": before the goal: who would pay and what backs that up, whether it already exists, and what experiment was run.
- Very specific: line 24
Tie the spec to the roadmap: Read docs/product/roadmap.md and fill the _Roadmap item_ field of proposal.md with the version and the literal …
- Very specific: line 31
If specs/README.md maintains an index of specs, add an entry for the new spec.
- Very specific: line 45
Do NOT start implementing the change, and do NOT delete or overwrite an existing spec folder — if any specs/*-<change-name>/ already exists …
“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
Create a new change spec named in $ARGUMENTS.
- Read
specs/README.mdto learn the spec workflow, the folder naming convention, and what each template section expects. Follow that doc if it differs from the steps below. - Slugify
$ARGUMENTSinto<change-name>(lowercase, hyphen-separated). - Compute
NNNN: the highest existing 4-digit numeric prefix acrossspecs/andspecs/archive/(if it exists), plus one; if there are none,0001. - Copy the entire
specs/_template/directory tospecs/NNNN-<change-name>/(preserve every file in the template). - In the copied files, fill in obvious metadata:
- The change title (human-readable form of
$ARGUMENTS) - Status:
Draft - Date: today's date (
YYYY-MM-DD) - Leave problem, goals, non-goals, and approach as prompts for the author.
- The change title (human-readable form of
- Fill in "Evidence" before the goal: who would pay and what backs that up, whether
it already exists, and what experiment was run. Look at
docs/product/roadmap.mdfirst — the answer may already be there. On afix/*or tooling spec, write "N/A: a fix": the section exists to decide what to build, not to stage theater around what is already broken. - Tie the spec to the roadmap. Read
docs/product/roadmap.mdand fill the Roadmap item field ofproposal.mdwith the version and the literal item this spec completes. If several candidates fit, ask with AskUserQuestion instead of picking on your own. If no item fits, say so: either it gets added to the roadmap now, or the change should first be weighed against the roadmap (does it belong in this version?, what comes out in exchange?). Note the spec next to the item in the roadmap too ((specs/NNNN-<slug>/)). - If
specs/README.mdmaintains an index of specs, add an entry for the new spec. - Report the created directory path and list the files the author still needs to complete.
Example: /new-spec checkout redesign → specs/0007-checkout-redesign/ (if the
latest spec was 0006).
Branch ↔ spec: the branch that implements this spec must be named
feat/<change-name> (or fix/<change-name>) — same slug. The spec-guardrails.sh hook
blocks editing code on feat/*/fix/* branches whose spec does not exist, so create the
spec BEFORE creating the implementation branch (or from the branch, before touching
code). The hook also blocks while proposal.md, design.md or tasks.md still hold
unfilled template lines: leave the files complete (or delete the sections that do not
apply) before implementing.
Do NOT start implementing the change, and do NOT delete or overwrite an existing spec
folder — if any specs/*-<change-name>/ already exists (with any NNNN- prefix; the
un-prefixed name will never exist), stop and ask.
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.

