spec-writer
Skill1 starsChanged 2 months agoMITView on GitHub
Turn a message, prompt, or feature idea into a numbered spec document (0001-title.md) with status, created/updated dates, and the author pulled from git config. Use this whenever the user says "write a spec", "spec this out", "turn this into a spec", "create a spec for X", "add a spec", asks to update or mark a spec as implemented, or describes a feature/change and asks for it to be written up as a formal document — even if they don't use the word "spec" but clearly want a durable, numbered design or requirements doc in the repo.
25 other projects use a version of this.
Adopted by
Most recently taken up by
- krystaleicher/claude-skillstheir own version, first seen Nov 16, 2026
- JPeetz/agent-skillstheir own version, first seen Nov 14, 2026
- fx/skillstheir own version, first seen Nov 8, 2026
- newkirkjosh/skillstheir own version, first seen Nov 1, 2026
- jaydenluckertjes-ai/Carmack-Counciltheir own version, first seen Oct 13, 2026
- dayvisonassis/sdd-skillstheir own version, first seen Oct 12, 2026
Used with
Projects with it also use security-reviewer, code-reviewer and 1 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.
JeffallanSkillsecurity-reviewer
Identifies security vulnerabilities, generates structured audit reports with severity ratings, and provides actionable remediation guidance. Use when conducting security audits, reviewing code for vulnerabilities, or analyzing infrastructure security. Invoke for SAST scans, penetration testing, DevSecOps practices, cloud security reviews, dependency audits, secrets scanning, or compliance checks. Produces vulnerability reports, prioritized recommendations, and compliance checklists.
Also in 3 projects that use this
GoogleSkillcode-reviewer
Also in 4 projects that use this
genomewalkerSkilllearn
Learn from web sources, generate SKILL.md, and store key patterns in soul memory. Trigger keywords: learn, skill-gen, web-learn, documentation, tutorial.
Also in 3 projects that use this
Other versions25 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 25
- MageByte-Zero/spec-superflow★ 875same name
- AlpacaLabsLLC/skills-for-architects★ 420same name
- SamJHudson01/Carmack-Council★ 52same name
- dannwaneri/spec-writer★ 26same name
- JPeetz/agent-skills★ 17same name
- kambleakash0/agent-skills★ 10same name
- Ecoa-PUC-Rio/GAIDE★ 8same name
- jcarlos78/GAIDE★ 8same name
- AskExe/exe-build-skills★ 4same name
- fx/skills★ 4same name
15 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 repository4 other files it gives its agents.
- software-engineerSkill
- implement-specSkill
- pm-feature-advisorSkill
- spec-to-issueSkill
The file
We split this skill into the rules it gives an agent
8 rules. 0 are common, 5 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 21 edited versions we read keep these.
5
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
- Distinctive: line 14
Every spec opens with YAML frontmatter, then the body:
- Very specific: line 62
Default to docs/specs/, creating it if it doesn't exist.
- Very specific: line 63
If the repo already keeps specs somewhere else — a root-level specs/, .specs/, rfcs/ — use that instead.
- Very specific: line 65
If existing specs use a different layout (a NNNN-title/ directory per spec, a different frontmatter shape, an extra section every spec …
- Distinctive: line 69
Do this _after_ resolving any open questions with the user (see below) — a spec file that sits half-written on disk while the user is still …
- Distinctive: line 95
Keep specifics verbatim where the user was precise — exact field names, numbers, error codes, and formats they gave are decisions, not …
- Distinctive: line 96
Don't invent scope. A spec that quietly adds three features the user never mentioned is harder to review than one that's honestly thin.
- Distinctive: line 142
Never renumber an existing spec.
“Common” is measured: kept by at least 6 in 10 of the 21 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 Writer
Turn a rough message, prompt, or feature description into a numbered spec file that lives in the repository alongside the code.
What a spec looks like
Filename: NNNN-kebab-case-title.md, where NNNN is a zero-padded sequential number starting at 0001. Examples: 0001-user-authentication.md, 0002-rate-limit-public-api.md.
Every spec opens with YAML frontmatter, then the body:
---
number: "0001"
title: User authentication
status: Draft
author: Jane Doe
created: 2026-09-08
updated: 2026-09-08
---
# 0001 — User authentication
## Summary
One paragraph: what this is and why it exists.
## Motivation
The problem being solved, and what happens if it isn't.
## Goals
- Bulleted, concrete, checkable.
## Non-goals
- Explicitly out of scope, so the boundary is clear later.
## Requirements
Numbered so they can be referenced in review and in commits.
1. ...
2. ...
## Design
How it works. Data model, interfaces, flow, file layout — whatever the change actually needs. Skip subsections that don't apply rather than padding them.status is Draft or Implemented — nothing else, so the values stay greppable.
There is no "Open questions" section, and that's deliberate: a finished spec has none. See "Resolve the gaps before writing" below.
Where specs go
- Default to
docs/specs/, creating it if it doesn't exist. - If the repo already keeps specs somewhere else — a root-level
specs/,.specs/,rfcs/— use that instead. Matching the convention already in the repo matters more than any default, and scattering specs across two directories is worse than either choice alone.
If existing specs use a different layout (a NNNN-title/ directory per spec, a different frontmatter shape, an extra section every spec has), read one of them first and match it. A spec that looks unlike its neighbors is worse than a slightly non-standard one.
Creating a spec
Do this after resolving any open questions with the user (see below) — a spec file that sits half-written on disk while the user is still deciding is easy to forget and easy to commit by accident.
Compute the number, author, and date with the shell rather than by memory — the number depends on what's already on disk, and the author has to come from git config. Run this first:
SPEC_DIR=docs/specs # or whatever the repo already uses
mkdir -p "$SPEC_DIR"
last=$(ls -1 "$SPEC_DIR" 2>/dev/null | sed -nE 's/^([0-9]{4}).*/\1/p' | sort -n | tail -1)
# Strip leading zeros before the increment, or 0008 is read as octal and fails.
next=$(( $(printf '%s' "${last:-0}" | sed 's/^0*//; s/^$/0/') + 1 ))
num=$(printf '%04d' "$next")
author=$(git config user.name || git config user.email || echo "${USER:-unknown}")
today=$(date +%Y-%m-%d)
echo "number=$num author=$author date=$today"Then slugify the title (lowercase, non-alphanumerics to single hyphens, no leading or trailing hyphen) and write $SPEC_DIR/$num-$slug.md with the frontmatter above filled in from those values. Check the path doesn't already exist before writing.
Turning the message into the spec
The user's message is source material, not the spec. Do not paste it in as the summary.
- Expand terse phrasing into concrete requirements. "Should be fast" becomes a stated latency target.
- Keep specifics verbatim where the user was precise — exact field names, numbers, error codes, and formats they gave are decisions, not suggestions.
- Don't invent scope. A spec that quietly adds three features the user never mentioned is harder to review than one that's honestly thin.
Resolve the gaps before writing
A finished spec contains no open questions. Anything you'd otherwise park under an "Open questions" heading is a decision the user needs to make, so ask them for it instead of deferring — an unanswered question in a merged spec tends to stay unanswered until it surfaces as a bug.
So: draft the spec in your head first, collect everything you'd have to guess at, and ask before creating the file.
Ask once, not one at a time. Work out the complete list, then put it in a single message. Drip-feeding questions turns a two-minute exchange into a twenty-message interview, and the user can't see where it ends.
Give each question a recommended answer. The user should be able to reply "all your defaults are fine" and be done. A question with no suggested answer pushes the whole design burden back onto them, which is what they asked you to do in the first place.
Before I write this up, four things I need from you:
1. Rate limit scope — per API key, or per IP? (I'd suggest per key; IP breaks
for customers behind shared NAT.)
2. Limit value — I'd suggest 1000 req/min, but that's a guess without traffic data.
3. What happens at the limit — 429 with Retry-After, or silent queueing?
(Suggest 429; queueing hides the problem from clients.)
4. Do admin tokens bypass the limit entirely, or get a higher ceiling?Only ask what changes the document. Questions with real consequences for the requirements or design belong here. Choices that can be made freely at implementation time — variable naming, which helper file something lives in, the sort order of an internal list — don't, and asking about them buries the questions that matter.
If the user declines to decide, or answers only some, take your recommended answer for the rest, write it into the spec as a settled decision, and tell them plainly which ones you chose. "You decide" is a valid answer; it isn't a reason to leave a hole in the document.
Match the level of detail to what you were given. A one-line prompt needs more questions before it can become a spec; a detailed message may need none at all — in which case don't manufacture any, just write it.
Updating a spec
Any edit to a spec bumps updated. Restrict the substitution to the frontmatter block so a stray line in the body can't be clobbered:
f=docs/specs/0001-user-authentication.md
sed -i.bak -E "1,/^---$/{ s/^updated: .*/updated: $(date +%Y-%m-%d)/ }" "$f" && rm -f "$f.bak"To also change the status, add the second expression:
sed -i.bak -E "1,/^---$/{ s/^updated: .*/updated: $(date +%Y-%m-%d)/; s/^status: .*/status: Implemented/ }" "$f" && rm -f "$f.bak"created never changes. Mark a spec Implemented when the described behavior actually exists in the code — not when the work starts. If the implementation drifted from the spec, update the spec body to match reality in the same pass, otherwise Implemented becomes a lie people stop trusting.
Never renumber an existing spec. Numbers are permanent identifiers; superseded specs stay in place, and a newer spec references the one it replaces.
Wrapping up
Report the created or modified path, the assigned number, and the status.
If you settled any question on the user's behalf — because they said "you decide", or didn't answer that one — list those decisions in the chat. They're the parts of the spec most likely to be wrong, and they're easy to miss inside a finished document that reads as though everything was settled.
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.

