spec
Skill394 starsChanged 6 months agoMITView on GitHub
Designs and develops specs following the spec-driven method. Asks clarifying questions before proposing structure, and builds the spec section by section. Use it when starting a large feature, before writing code.
173 other projects use a version of this.
Adopted by
Most recently taken up by
- chrisezedi/claude-skillstheir own version, first seen Nov 16, 2026
- ByteLab-dev-ar/skills-proyectostheir own version, first seen Nov 16, 2026
- devonbweaver/Spec-Looptheir own version, first seen Nov 16, 2026
- pushkincode/skillstheir own version, first seen Nov 16, 2026
- timursafiullin/aodtheir own version, first seen Nov 15, 2026
- RohiRIK/skillstheir own version, first seen Nov 15, 2026
Used with
Projects with it also use backprop, ios-clean and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
JuliusBrusseeSkillbackprop
Bug → spec protocol. When a bug is found or a test fails, trace the cause, decide whether a new §V invariant would catch recurrence, append to §B. This is the one non-obvious thing SDD does that plan-then-execute doesn't. Triggers on test failure, bug report, post-mortem, or explicit user ask.
Also in 4 projects that use this
Saqlain-811Skillios-clean
Remove the DebugBridge SPM package and all #if DEBUG wiring from an iOS app. (gstack)
Also in 5 projects that use this
Saqlain-811Skillios-fix
Autonomous iOS bug fixer. (gstack)
Also in 5 projects that use this
bastosSkillios-design-review
Review iOS app UI/UX design quality using Apple's design principles and the Liquid Glass-era design language from WWDC25/26. Use when asked for a design review, UX critique, visual design assessment, or evaluation of an app's interface quality, design intent, alignment with the new Apple design system, or usability. Triggers: "design review", "UX review", "visual design critique", "review the UI", "does this design work", "evaluate this interface", "design feedback", "Liquid Glass review".
Also in 5 projects that use this
ShreyRaviSkillplan-tune
Self-tuning question sensitivity + developer psychographic for gstack (v1: observational). Review which AskUserQuestion prompts fire across gstack skills, set per-question preferences (never-ask / always-ask / ask-only-for-one-way), inspect the dual-track profile (what you declared vs what your behavior suggests), and enable/disable question tuning. Conversational interface — no CLI syntax required.
Also in 7 projects that use this
timurgaleevSkilldocument-generate
Generate missing docs for a feature, module or project as tutorials, how-tos, reference and explanation.
Also in 6 projects that use this
- +2 more from Saqlain-811
Other versions173 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 173
- garrytan/gstack★ 142ksame name
- getsentry/sentry-react-native★ 1.8ksame name
- JuliusBrussee/cavekit★ 1.1ksame name
- kdlbs/kandev★ 1.1ksame name
- getsentry/sentry-dart★ 877same name
- poshan0126/dotclaude★ 871same name
- codewithmukesh/dotnet-claude-kit★ 808same name
- SparkDevNetwork/Rock★ 701same name
- strands-agents/box★ 547same name
- hyperlink-academy/leaflet★ 527same name
163 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.
The file
Show its rules and text
We split this skill into the rules it gives an agent
24 rules. 0 are common, 15 are distinctive, and 9 are very specific to this project.
0
Common
Most of the 149 edited versions we read keep these.
15
Distinctive
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 27
Read template.md (in the same directory as this skill) to see the full structure the spec will follow.
- Distinctive: line 36
Before asking questions about the feature, make sure you have project context:
- Distinctive: line 38
Read the project-memory file, if one exists.
- Very specific: line 39
Look at the specs/ listing in the session context above to see which specs already exist and how they are numbered.
- Distinctive: line 40
If previous specs exist, read at least the two most recent ones to pick up the project's conventions — including the language they are …
- Distinctive: line 48
Ask questions in blocks of 3 to 5 at a time (not one single question followed by another single question — that is exhausting).
- Distinctive: line 62
Use concrete questions, not open-ended ones.
- Distinctive: line 63
When you offer options, give 2–4, mark which one is your recommendation and why.
- Distinctive: line 65
If you spot an answer that would open Pandora's box (e.g.
- Distinctive: line 69
Stop when you can answer these three questions without assuming anything:
- Distinctive: line 75
If you still cannot answer one of them, keep asking.
- Distinctive: line 98
Ask: "Does this section stay like this or do you want to tweak it?"
- Distinctive: line 99
If the user requests changes, apply them and show again.
- Distinctive: line 100
Only move to the next section once the user confirms.
- Distinctive: line 111
When the content is ready (either because you had everything, or because all sections were confirmed):
- Very specific: line 115
Use the date from the session context above for the Date: field.
- Very specific: line 116
Write the file directly at specs/NN-slug.md with all the sections.
- Very specific: line 118
If the header lists dependencies (Depends on: SPEC 01), check that each referenced spec actually exists in specs/.
- Very specific: line 119
Seed the config file if it does not exist: Check for specs/.spec-config.yml.
- Very specific: line 138
If you just created specs/.spec-config.yml, mention it exists, that AutoCreateBranch defaults to true (set it to false to control branch …
- Distinctive: line 140
Stop here: Do not propose implementing the spec, writing code, or taking any further action beyond this confirmation.
- Very specific: line 144
Never write code during this command: Only the spec's .md file at the end.
- Distinctive: line 146
Never assume decisions the user did not confirm: If you are missing information, ask — in Phase 2, which is where the questions belong.
- Very specific: line 169
If they invoked /spec without arguments, start by asking for the one-sentence description.
“Common” is measured: kept by at least 6 in 10 of the 149 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
/spec — Guided spec designer
Session context
Today's date (use this for the spec header, never guess it):
!date +%F
Specs that already exist:
!ls specs/ 2>/dev/null || echo "The specs/ folder does not exist yet"
This skill helps you produce a useful spec following the spec-driven method. You don't write code here. Your job is to help the user clarify what they want to build, ask questions when something is not well-defined enough, and develop the spec section by section until it is ready to be saved into specs/.
Philosophy
A spec is not decorative documentation. It is the contract that drives later execution. If the spec is vague, the code will improvise. That is why this flow is deliberately slow during the definition phase and fast during the writing phase.
Read template.md (in the same directory as this skill) to see the full structure the spec will follow. Lean on it at every step.
Command flow
- Follow the four phases in order. Never skip Phase 2 — the questions are the whole point. If the user wants to go faster, remind them that the cost of a bad spec gets paid later in code. (Phase 3 does have a fast path once Phase 2 is genuinely complete; see below.)
- Your replies must be in the same language as the initial prompt. E.g.: if the initial prompt is in Spanish, your replies must be in Spanish; if it is in English, your replies must be in English.
Phase 1 — Understand the context
Before asking questions about the feature, make sure you have project context:
- Read the project-memory file, if one exists. Try in order and stop at the first hit:
CLAUDE.md,AGENTS.md,GEMINI.md,README.md. This adapts the skill to whichever agent is running it (Claude Code, Codex, Gemini CLI, etc.). - Look at the
specs/listing in the session context above to see which specs already exist and how they are numbered. - If previous specs exist, read at least the two most recent ones to pick up the project's conventions — including the language they are written in and the exact wording they use for states and section headings. A new spec must match the existing ones.
If the $ARGUMENTS argument comes in empty, ask the user for an initial single-sentence description of what they want to build. If the description does not fit in one sentence, that is the first signal that the feature is too big — suggest splitting it before continuing.
Phase 2 — Clarify through questions
This is the most important phase of the command. Your job here is to detect ambiguities and ask, not to assume.
Ask questions in blocks of 3 to 5 at a time (not one single question followed by another single question — that is exhausting). After each block, wait for an answer before continuing.
Question categories you should always consider:
- Scope: What is in and what is NOT? Which parts of the feature are deferred to another spec?
- Data: What new structures are introduced? How are they named? Where do they live?
- Integration: Does this feature depend on previous specs? Does it modify something existing or only add?
- Persistence: Is anything saved between sessions? Where? With what versioning?
- UX and states: What does it look like when it works? What does it look like when it fails? Are there intermediate states?
- Risks: What can break this? What happens in the degraded case?
- Closed decisions: Is there any decision the user has already made and does not want to reopen?
How to phrase the questions:
- Use concrete questions, not open-ended ones. ❌ "How do you imagine persistence?" → ✅ "Is persistence localStorage, IndexedDB, or a JSON file on disk?"
- When you offer options, give 2–4, mark which one is your recommendation and why.
- If your agent exposes a native multiple-choice question tool (in Claude Code:
AskUserQuestion), use it for these blocks instead of writing the options as prose — the user picks instead of typing. Put your recommendation first and label it. Fall back to a numbered markdown list when no such tool exists. - If you spot an answer that would open Pandora's box (e.g. "and we also want multiplayer"), point out that it deserves its own spec and ask whether we leave it out of this one's scope.
When to stop asking:
Stop when you can answer these three questions without assuming anything:
- Which files will appear or change?
- What is the first executable step and what is the last one?
- How do I verify the feature is finished?
If you still cannot answer one of them, keep asking.
Phase 3 — Write the spec
Once Phase 2 is closed, decide how to write it:
If you already have all the information you need — meaning you can answer the three Phase 2 questions (which files change, what the first and last executable steps are, how to verify it is finished) without assuming anything — then do not go section by section. Write the complete spec and jump straight to Phase 4 to save the file. Do not ask for section-by-section confirmation, and do not show a draft for approval first: the user already answered everything in Phase 2, and re-asking is friction. The user reviews the saved file and asks for changes if needed.
Only if information is still missing (the user cut Phase 2 short, an answer was vague, or some section cannot be written without inventing something), develop the sections one by one, showing each one and waiting for confirmation before moving to the next.
In both cases the content follows the same order:
- Header (state, dependencies, date, one-sentence objective). The one-sentence objective is critical — if it does not fit in one sentence, go back to Phase 2.
- Scope (what is in and what is NOT). The "not in" must be explicit.
- Data model (concrete structures with real names). If the feature introduces no new data, skip this section and say so explicitly.
- Implementation plan (numbered steps, each leaving the system functional).
- Acceptance criteria (boolean checklist, not aspirational).
- Decisions taken and discarded (with brief justification).
- Identified risks (only if applicable — if no relevant risks exist, skip it).
After each section (only in the section-by-section mode):
- Show it formatted in markdown.
- Ask: "Does this section stay like this or do you want to tweak it?"
- If the user requests changes, apply them and show again.
- Only move to the next section once the user confirms.
Common mistakes to avoid:
- Generating acceptance criteria that are not verifiable ("that it works well").
- Putting things into the implementation plan that are not in the scope.
- Assuming file names or structures the user did not confirm.
- Skipping the decisions section — that section is the one with the most long-term value.
Phase 4 — Save the spec
When the content is ready (either because you had everything, or because all sections were confirmed):
- Determine the next sequential number from the
specs/listing in the session context. Take the highest existing number and add one, zero-padded to two digits. If the last one is02-powerups.md, this one will be03-. Ifspecs/is empty or missing, start at01-. - Generate a short kebab-case slug from the objective (e.g.
levels-and-highscores). See Arguments below for when$ARGUMENTSis the slug instead. - Use the date from the session context above for the
**Date:**field. Never write a date you did not read from there. - Write the file directly at
specs/NN-slug.mdwith all the sections. Do not ask for permission to write it and do not ask whether the file name works — announce the path in the final confirmation. Only ask if the target file already exists. - Mark the state as
Draftby default (or the equivalent word used by the existing specs in this repo). Do not mark it asApprovedautomatically — the user does that once they have re-read it. - If the header lists dependencies (
**Depends on:** SPEC 01), check that each referenced spec actually exists inspecs/. If one does not, say so instead of writing a dangling reference. Seed the config file if it does not exist. Check for
specs/.spec-config.yml. If it is missing, create it with the default content below. If it already exists, leave it untouched — never overwrite the user's settings.# spec workflow configuration # # AutoCreateBranch — controls whether /spec-impl creates the git branch automatically. # true (default) → /spec-impl creates and switches to spec-NN-slug without asking # false → /spec-impl asks for [y/N] confirmation before creating the branch AutoCreateBranch: true # AutoCommitSteps — controls whether /spec-impl commits each finished step. # false (default) → /spec-impl never commits; committing is up to you # true → /spec-impl commits each step as spec-NN-step-MM AutoCommitSteps: false- Confirm to the user:
- Path of the created file.
- Reminder: the spec is in
Draftstate. Change it toApprovedonce you have re-read it. - If you just created
specs/.spec-config.yml, mention it exists, thatAutoCreateBranchdefaults totrue(set it tofalseto control branch creation yourself), and thatAutoCommitStepsdefaults tofalse(set it totrueto have/spec-implcommit each step). - Next step: once reviewed and approved, run
/spec-impl NN-slugto implement it. - Stop here. Do not propose implementing the spec, writing code, or taking any further action beyond this confirmation.
Hard rules
- Never write code during this command. Only the spec's
.mdfile at the end. - Never propose implementing the spec after saving it. Your job ends when the file is written. The user runs
/spec-implwhen they are ready. - Never assume decisions the user did not confirm. If you are missing information, ask — in Phase 2, which is where the questions belong.
- Do not re-ask in Phase 3 what was already answered in Phase 2. If the information is complete, write the whole spec and save it. Section-by-section confirmation is the fallback for incomplete information, not the default.
- If the user wants to speed up and skip Phase 2, remind them: "Questions now save hours later. Are you sure you want to skip them?". If they insist, respect their decision but record it in the spec's decisions section ("Quick definition without detailed clarification").
- If the feature is too big (does not fit in one sentence, touches more than three areas of the system, requires decisions in four or more domains), propose splitting it into two or more specs before continuing.
Tone when asking questions
Be direct and specific. Do not apologize for asking. Do not use phrases like "if you don't mind..." or "could you maybe...". The user invoked this skill precisely because they want you to ask questions. Use concrete questions, one per line when there are several, and number them so they are easy to answer.
Example of a well-formed block:
Before writing the data model I need to clarify three things:
- Persistence. localStorage, IndexedDB, or a JSON file on disk? Recommendation: localStorage if the data fits in <5MB and does not need queries.
- Schema versioning. What happens when the format changes? Options: (a) version prefix in the key, (b) ignore and rebuild, (c) migrate on load.
- Privacy. Is the data sensitive? If yes, is it encrypted? Is it deleted on logout?
Arguments
$ARGUMENTS is the feature description, not the file name. Treat it as the starting point for Phase 1 and derive the slug from the objective in Phase 4.
The one exception: if $ARGUMENTS is already a single kebab-case token with no spaces (e.g. /spec levels-and-highscores), it is ambiguous between a description and a slug — use it as the slug and as the seed of the description, without asking for confirmation.
If they invoked /spec without arguments, start by asking for the one-sentence description.
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.

