writing-specs
Skill0 starsChanged 8 months agoApache-2.0View on GitHub
Specification writing standards — document structure, EARS template, Design by Contract, interface contracts, state machines, error specification, signal quality. Use when creating or editing specification/ files.
10 other projects use a version of this.
Adopted by
Most recently taken up by
- alumpe/skillstheir own version, first seen Nov 16, 2026
- victorhqc/filberttheir own version, first seen Nov 4, 2026
- iha2/superlitetheir own version, first seen Nov 1, 2026
- JetBrains/thinkrailtheir own version, first seen Oct 13, 2026
- whiteguo233/OpenBiliClawtheir own version, first seen Oct 8, 2026
- sergeyklay/.agentstheir own version, first seen Sep 28, 2026
Used with
Projects with it also use writing-plans.
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.
OpenAISkillwriting-plans
Use when you have a spec or requirements for a multi-step task, before touching code
Also in 3 projects that use this
Other versions10 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 10
- JetBrains/thinkrail★ 8.3ksame name
- whiteguo233/OpenBiliClaw★ 3.8ksame name
- iha2/superlite★ 311same name
- devstefancho/skills★ 13same name
- sergeyklay/.agents★ 6same name
- victorhqc/filbert★ 4same name
- augments-labs/sdlc-skills★ 1same name
- fireshort/skills★ 1same name
- xmtplabs/code-factory★ 1same name
- alumpe/skills★ 0same name
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 repository12 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- specification/CLAUDE.mdCLAUDE.md
- src/CLAUDE.mdCLAUDE.md
- tasks/CLAUDE.mdCLAUDE.md
- test/CLAUDE.mdCLAUDE.md
- cleanupSkill
- diagnoseSkill
- sddSkill
- triageSkill
- writing-architectureSkill
- writing-tasksSkill
- writing-testsSkill
The file
We split this skill into the rules it gives an agent
7 rules. 0 are common, 7 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 10 edited versions we read keep these.
7
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 29
Use domain language, not solution language.
- Distinctive: line 66
Always provide an explicit transition table -- never narrative.
- Distinctive: line 72
Every non-terminal state needs at least one outbound transition.
- Distinctive: line 83
Prefer tables over prose for structured content.
- Distinctive: line 84
No TBD/TODO -- make provisional decisions explicitly.
- Distinctive: line 85
No aspirational prose or redundant restatements.
- Distinctive: line 90
Keep language-agnostic content separate from language-specific content.
“Common” is measured: kept by at least 6 in 10 of the 10 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
Specification Writing Standards
Document Structure
1. Purpose [required]
2. Scope [required]
3. Definitions [if domain terms used]
4. Behavioral Requirements [required]
5. Data Model [if component owns/transforms data]
6. Interface Contracts [if component has boundaries]
7. State and Lifecycle [if behavior depends on history]
8. Error Specification [required]
9. Non-Functional Reqs [if applicable]
10. Examples [required for complex behaviors]
11. Language-Specific Notes [separate section or file]Order: happy path -> errors/edges -> NFRs -> nice-to-haves. Within components: inputs -> outputs -> errors -> internals.
Abstraction Level
- Describe what and why, with enough how to constrain -- not dictate.
- Use domain language, not solution language.
- Be precise at boundaries (inputs, outputs, errors, state transitions). Be abstract about internals.
- Platform-specific statements belong in Language-Specific Notes.
Requirements
Each requirement: atomic (one behavior), testable, unambiguous (one interpretation).
Banned terms (replace with measurables): robust, efficient, user-friendly, flexible, reliable, secure, fast, scalable, appropriate, various, quickly, "in a timely manner."
Fix ambiguity: replace pronouns with nouns, use active voice, split compound "and" statements.
EARS template:
[When <trigger>] [while <precondition>] the <system> shall <action> [the <object>]Behavioral Specs -- Design by Contract
| Element | Definition |
| REQUIRES | What must be true before (caller's obligation) |
| ENSURES | What must be true after (implementer's obligation) |
| MAINTAINS | What is always true (both sides) |
Include 2-3 concrete Given/When/Then examples per behavior, placed immediately after the requirement.
Data Model
Define entities with domain-level types. State all constraints, validation rules, and relationships with cardinality.
Interface Contracts
Per boundary operation: Input, Output, Guarantees, Error strategy, Concurrency, Idempotency (required for retriable operations). Complete when either side can be implemented without reading the other's internals.
State Machines
Always provide an explicit transition table -- never narrative.
| Current State | Event | Guard | Action | Next State |Every non-terminal state needs at least one outbound transition. Every event accounted for in every non-terminal state.
Error Specification
Classify per operation: input error, state error, dependency error, invariant violation.
Enumerate edge cases: empty input, boundary values, null/missing, duplicates, concurrent access, partial failure, repeated invocation.
Signal Quality
- Target <= 3,000 tokens per section.
- Prefer tables over prose for structured content.
- No TBD/TODO -- make provisional decisions explicitly.
- No aspirational prose or redundant restatements.
- Front-load critical requirements.
Language Separation
Keep language-agnostic content separate from language-specific content. The agnostic layer must survive a technology migration unchanged.
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.

