design-and-spec
Skill13 starsChanged 7 months agoMITView on GitHub
Use before any creative work or spec creation. Explores intent, challenges assumptions, and produces specs. Triggers on "brainstorm", "let's design", "spec out", "define requirements", "write a spec", "challenge this", "poke holes", "what am I missing".
In this repository19 other files it gives its agents.
- agent-auditSkill
- codebase-auditSkill
- commitSkill
- dispatching-parallel-agentsSkill
- doc-driftSkill
- execution-planningSkill
- explain-codeSkill
- post-implementationSkill
- pushSkill
- python-auditSkill
- receiving-code-reviewSkill
- subagent-driven-developmentSkill
- systematic-debuggingSkill
- terraform-auditSkill
- test-driven-developmentSkill
- trace-codeSkill
- typescript-auditSkill
- verification-before-completionSkill
- writing-plansSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 5 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 11
Do NOT invoke any implementation skill, write any code, or take any implementation action until you have presented a design and the user …
- Distinctive: line 19
Prefer open discussion over multiple choice
- Distinctive: line 24
Ask clarifying questions one at a time, prefer multiple choice
- Distinctive: line 33
Before presenting any design in either mode, list 3 assumptions being made and question each:
- Very specific: line 52
Write spec to docs/specs/YYYY-MM-DD-<topic>/spec.md
- Very specific: line 53
Ask user to review: "Spec written to <path>.
- Distinctive: line 54
Wait for approval. Make changes if requested, then re-ask.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Design and Spec
Turn ideas into approved specs through collaborative dialogue or structured requirements gathering.
<HARD-GATE>
Do NOT invoke any implementation skill, write any code, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
</HARD-GATE>Entry Mode Detection
Exploratory mode — triggers on: brainstorm, let's think about, I'm leaning toward, open-ended structural questions.
- Present partial designs early and iterate — don't wait for the full picture
- Fold in new constraints mid-stream naturally
- Prefer open discussion over multiple choice
- Propose 2-3 approaches at real forks in the road
- Transition check: "Ready to formalize into a spec, or keep exploring?"
Directed mode — triggers on: spec out, define requirements, write a spec, define requirements.
- Ask clarifying questions one at a time, prefer multiple choice
- Structure: requirements → design → tasks
- Present design in sections, get approval per section
- Skip the design phase if the spec already contains architecture and module breakdown
Both modes start with: explore project context (read files, docs, recent commits).
Assumption Challenging Phase
Before presenting any design in either mode, list 3 assumptions being made and question each:
- "What happens if [assumption] is wrong?"
- "What's the simplest version of this that could work?"
- "What are you optimizing for — and what are you giving up?"
Have strong opinions, held loosely — push back with conviction, change your mind when the user presents good evidence.
Design Principles
- One question at a time — never multiple questions in one message
- YAGNI ruthlessly — remove unnecessary features from all designs
- Design for isolation — each unit has one clear purpose, communicates through well-defined interfaces, can be understood and tested independently
- Explore existing patterns — read the codebase before proposing changes; follow what's there
- Decompose large scope — if the request spans multiple independent subsystems, flag it and help decompose before designing any one piece
Convergence (both modes)
- Ripple check — list which existing docs enumerate the artifact category being added (agents, skills, hooks, steering). Include those docs in the spec's "Files to Update" section. If unsure, grep
docs/andREADME.mdfor artifact names from the category. - Write spec to
docs/specs/YYYY-MM-DD-<topic>/spec.md - Ask user to review: "Spec written to
<path>. Review it and let me know if you want changes before we move to planning." - Wait for approval. Make changes if requested, then re-ask.
- Hand off to writing-plans — this is the terminal state. Do NOT invoke any other skill.
The only next step after design-and-spec is writing-plans.
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.