A skill that stops your AI agent from guessing.
If you've ever asked an agent to "build the payment flow" and watched it confidently write 400 lines of code based on an assumption you never actually confirmed — this is for that problem.
git clone https://github.com/sdxdhruva/spec-driven-development.git ~/.config/Code/User/prompts/spec-driven-development
curl -L https://github.com/sdxdhruva/spec-driven-development/archive/main.zip | unzip - -d ~/.config/Code/User/prompts/See Installation below for detailed setup instructions by agent type.
AI agents are great at writing code. They're not great at knowing what code to write, especially on a codebase that already has history, edge cases, and three other features quietly depending on the thing you just asked it to change.
What usually happens: you describe a feature in one or two sentences, the agent starts coding immediately, and somewhere around the third file it makes a decision you never saw — a schema choice, an API shape, a "this seemed like the obvious way to do it" call — and you find out about it after it's already wired into five places. Then either you live with it, or you're doing surgery to undo it.
This skill makes the agent stop and write three documents before touching a single line of code: what needs to be true (requirements), how it'll actually be built (design), and the exact steps to get there (tasks). Each one gets approved by you before the next one starts. Nothing gets built that wasn't agreed on first.
It sounds like overhead. In practice it's the opposite — it's the fifteen minutes you spend up front instead of the two hours you spend later figuring out why the new feature broke the old one.
-
Clone the skill repository:
git clone https://github.com/sdxdhruva/spec-driven-development.git ~/.config/Code/User/prompts/spec-driven-development -
The skill is ready to use. Your AI agent will automatically discover it from the prompts folder.
-
Verify installation: Open VS Code, start a chat with Copilot, and mention "spec this out" in any feature request. The agent should recognize the skill.
If your agent loads skills from a custom directory:
git clone https://github.com/sdxdhruva/spec-driven-development.git /path/to/skills/spec-driven-developmentIf your agent requires skills to be in a specific location:
# Symlink to your agent's skills directory
ln -s /path/to/spec-driven-development /your/agent/skills/directory/spec-driven-developmentManual Installation (if git is not available):
- Download the repository as ZIP from GitHub
- Extract the folder to your agent's skills directory
- Rename it to
spec-driven-development(no version numbers in the folder name) - Ensure the folder contains:
SKILL.md,requirement/,design/, andtasks/subdirectories
After installation, verify the skill is accessible:
ls -la ~/.config/Code/User/prompts/spec-driven-development/SKILL.md
test -f ~/.config/Code/User/prompts/spec-driven-development/SKILL.md && \
test -f ~/.config/Code/User/prompts/spec-driven-development/requirement/requirement.md && \
test -f ~/.config/Code/User/prompts/spec-driven-development/design/design.md && \
test -f ~/.config/Code/User/prompts/spec-driven-development/tasks/task.md && \
echo "✓ Installation successful" || echo "✗ Installation incomplete"SKILL.md ← the whole methodology, read this first
requirement/requirement.md ← template for "what" — copy this for every new feature
design/design.md ← template for "how" — copy this after requirements are approved
tasks/task.md ← template for "steps" — copy this after design is approved
SKILL.md is the part your agent actually loads and follows. The other three are reference templates — when your agent starts a new feature, it copies these into your project under .spec/<feature-name>/ and fills them in.
You ask your agent to add something non-trivial. Instead of opening files and writing code, it does this:
- Reads what already exists — your project's own docs, any related specs already sitting in
.spec/, the actual code in the area you're touching. It's not allowed to write a requirement in ignorance of how the system currently works. - Writes
requirement.md— what the feature needs to do, what it explicitly does not do, and what currently-working stuff it might put at risk. Shows it to you. Waits. - Once you say it looks good, writes
design.md— the actual technical approach, what existing code gets touched, and critically, how to make the change without breaking what depends on it. Shows it to you. Waits again. - Once that's approved, writes
task.md— a checklist of small, ordered, individually verifiable steps. Then it starts coding, one task at a time, checking boxes as it goes.
If something turns out to be wrong halfway through — the design doesn't quite hold up against reality — the agent is instructed to stop and go back and fix the design, not quietly patch around it in the code. That's the whole point.
The requirements template uses a format called EARS (you'll see it referred to as "WHEN x THE SYSTEM SHALL y" type sentences). It looks a little stiff at first. The reason it's there: "the form should validate the email" means five different things to five different people. "WHEN a user submits an invalid email format, THE SYSTEM SHALL reject the submission and display 'Invalid email address'" means exactly one thing. That precision is annoying to write and incredibly cheap compared to building the wrong thing.
After installation, trigger the skill by asking your agent to spec out a feature:
Trigger phrases:
- "Add a [feature] — spec this out first."
- "Plan the implementation for [feature]."
- "I need to build [feature] without breaking existing functionality."
- "Spec out [feature] before we start coding."
- Any feature request that sounds non-trivial (more than a single function/file change).
The agent will automatically:
- Read your project context — existing code, related specs, documentation
- Write
requirement.md— what the feature does and does not do - Show it to you — wait for your approval (or feedback to revise)
- Write
design.md— the technical approach and blast radius analysis - Show it to you again — wait for approval
- Write
task.md— a checklist of small, ordered implementation steps - Start coding — one task at a time, with full traceability
Example conversation:
You: "Add a referral bonus system — spec this out first."
Agent: [Reads existing code]
[Writes requirement.md showing what the feature will do]
"I've drafted requirements. Please review and approve."
You: [Review] "Looks good, but add that this shouldn't affect free users."
Agent: [Updates requirement.md]
[Writes design.md with technical approach]
"Design is ready for review."
You: [Review] "Approved."
Agent: [Writes task.md with step-by-step tasks]
[Starts implementing, checking off tasks as it goes]
For small changes (typos, variable renames, obvious bug fixes), the agent should recognize these and skip the ceremony. Use your judgment or tell it directly if it's being too precious.
SKILL.md ← the whole methodology, read this first
requirement/requirement.md ← template for "what" — copy this for every new feature
design/design.md ← template for "how" — copy this after requirements are approved
tasks/task.md ← template for "steps" — copy this after design is approved
SKILL.md is the part your agent actually loads and follows. The other three are reference templates — when your agent starts a new feature, it copies these into your project under .spec/<feature-name>/ and fills them in.
You ask your agent to add something non-trivial. Instead of opening files and writing code, it does this:
- Reads what already exists — your project's own docs, any related specs already sitting in
.spec/, the actual code in the area you're touching. It's not allowed to write a requirement in ignorance of how the system currently works. - Writes
requirement.md— what the feature needs to do, what it explicitly does not do, and what currently-working stuff it might put at risk. Shows it to you. Waits. - Once you say it looks good, writes
design.md— the actual technical approach, what existing code gets touched, and critically, how to make the change without breaking what depends on it. Shows it to you. Waits again. - Once that's approved, writes
task.md— a checklist of small, ordered, individually verifiable steps. Then it starts coding, one task at a time, checking boxes as it goes.
If something turns out to be wrong halfway through — the design doesn't quite hold up against reality — the agent is instructed to stop and go back and fix the design, not quietly patch around it in the code. That's the whole point.
The requirements template uses a format called EARS (you'll see it referred to as "WHEN x THE SYSTEM SHALL y" type sentences). It looks a little stiff at first. The reason it's there: "the form should validate the email" means five different things to five different people. "WHEN a user submits an invalid email format, THE SYSTEM SHALL reject the submission and display 'Invalid email address'" means exactly one thing. That precision is annoying to write and incredibly cheap compared to building the wrong thing.
This only works if you actually read what the agent shows you at each gate instead of reflexively typing "looks good." The whole value of this system is a human checking the agent's understanding before the agent commits to a direction. If you rubber-stamp every gate without reading it, you've recreated the exact problem this was built to avoid, just with extra paperwork.
"The agent isn't using the skill"
- Verify installation: Run the verification command above
- Make sure you've used a trigger phrase like "spec this out"
- Check that SKILL.md is in the correct folder for your agent type
- Restart your agent/IDE after installation
"The agent skips requirements/design even when I ask for them"
- Be explicit: "Write out the full requirement.md before showing me anything else"
- The skill is designed to skip unnecessary ceremony for simple changes — if you need all three phases, state that clearly
"I want to customize the templates"
- Copy the files from
requirement/,design/, andtasks/folders - Modify the templates to match your team's conventions
- The agent will use your customized versions automatically
MIT — Use it, fork it, change the templates to match how your team actually works. The structure matters more than the exact wording.
Found a bug or have a suggestion?
- GitHub Issues: Report here
- Pull Requests: Contribute here
- Discussions: Join the conversation
After installation:
- ✓ Verify the skill is installed (run the verification command above)
- ✓ Ask your agent to spec out your next feature
- ✓ Read what it produces — that's the whole point
- ✓ Give feedback before it starts coding
If this saved you from a 2am "why is production broken" moment, that's the whole point. If you find a way to make it better, open a PR.