write-design
Skill1 starsChanged 15 days agoMITView on GitHub
Write a technical design for one initiative — approach, contracts, failure, security, and delivery slices. Use when the user asks for a technical design, tech spec, or how we will build this. Do not write product code. Do not design a one-line bug.
1 other project uses a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- rpraharaj/ai-sdlcedited, first seen Nov 1, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 1
- rpraharaj/ai-sdlc★ 035% same
Wrote their own version · 0
None found.
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 repository34 other files it gives its agents.
- AGENTS.mdAGENTS.md
- templates/AGENTS.mdAGENTS.md
- commitSkill
- cut-releaseSkill
- data-changeSkill
- debugSkill
- engineering-barSkill
- explain-codeSkill
- explore-codebaseSkill
- fix-ciSkill
- handoffSkill
- implement-changeSkill
- incident-triageSkill
- lean-reviewSkill
- open-prSkill
- performanceSkill
- production-passSkill
- ready-to-mergeSkill
- record-decisionSkill
- refactor-safelySkill
- resolve-conflictsSkill
- revert-changeSkill
- review-changeSkill
- security-passSkill
- shape-workSkill
- ship-notesSkill
- start-projectSkill
- upgrade-depsSkill
- verify-uiSkill
- write-architectureSkill
- write-dev-tasksSkill
- write-docsSkill
- write-prdSkill
- write-testsSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 2 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
Do not implement. Do not start coding "just the first slice."
- Very specific: line 26
If product "why" is still unknown, stop and run write-prd.
- Very specific: line 28
Read AGENTS.md if present.
- Distinctive: line 34
Ask at most a few blocking questions (product fork, compatibility, environment).
- Very specific: line 38
Use the first that exists: docs/design/, docs/designs/, docs/specs/, a path AGENTS.md names.
- Very specific: line 40
If none: write in the reply, and offer to create docs/design/ in this repo's markdown style.
≈ “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
Write design
Describe how this initiative will be built in this repository. This is not a PRD (write-prd), not durable system shape (write-architecture), and not a ticket list (write-dev-tasks).
Do not implement. Do not start coding "just the first slice."
Is this the right skill?
| Signal | Do this instead |
| Users / success / non-goals still open | write-prd first |
| New system boundaries or greenfield shape | write-architecture first |
| One sticky library/store choice only | record-decision |
| One small, already-clear change | shape-work |
| Break an existing design into tickets | write-dev-tasks |
If product "why" is still unknown, stop and run write-prd. If the first slice is the whole goal, say so and offer shape-work instead of a design doc.
Read AGENTS.md if present. Skim entry points and an existing pattern. If you have not mapped the repo and the change is more than a few files, run explore-codebase or say the design is incomplete.
Carry forward agreed upstream decisions and acceptance checks by reference. Add only missing detail for this deliverable; do not regenerate or seek approval again for settled decisions. Existing authorization to implement continues to apply once blocking decisions are resolved.
Ask only when blocked
Ask at most a few blocking questions (product fork, compatibility, environment). Prefer a recommended answer. Non-blocking questions go in the doc.
Find the home
Use the first that exists: docs/design/, docs/designs/, docs/specs/, a path AGENTS.md names.
If none: write in the reply, and offer to create docs/design/ in this repo's markdown style.
Name the file like existing designs. If there are none, docs/design/YYYY-MM-DD-<slug>.md.
Write
Copy headings from references/design-template.md in this skill directory. Keep every heading; write n/a when a section does not apply. Do not invent extra sections. If that file is missing, use the same headings: Summary, Problem, Goals and non-goals, Constraints, Current vs proposed, Approach, Public surface, Data and contracts, Sequence, UI, Failure, Security, Performance, Observability, Rollout and rollback, Compatibility and migration, Config, Testing, Alternatives, Key decisions, Risks, Assumptions, Open questions, Delivery, Next.
Fill from the repo and any PRD/architecture the user pointed at:
- Approach names real files, types, or layers — or says none exist (greenfield).
- Data and contracts stay expand-then-contract. Destructive shape change is a later
data-change, not this doc's "also drop the column." - Config is names only — never secret values.
- Delivery is ordered slices, each independently reviewable. Do not write full tickets here (
write-dev-tasksdoes that). - Key decisions that are expensive to reverse get
record-decision, not a buried paragraph. - Load
engineering-bar(paths in that skill) and check the design against Minimum path, Failure, Data, Security, UI. Do not paste the bar.
Quality
- An engineer could start slice 1 without guessing the approach.
- Alternatives include a smaller option (reuse / stdlib / native).
- At least one Delivery slice is smaller than the whole initiative.
- Unused sections are
n/a, not deleted. - No secrets.
Done
- Path or the full text in the reply
- Chosen approach in a few sentences
- Slice 1, and the next skill
Continue into implementation only when the user has authorized it, blocking decisions are resolved, and slice 1 is fully specified — then shape-work or implement-change on that slice only.
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.