writing-specs
Skill4 starsChanged 12 days agoMITView on GitHub
Write or edit a spec in ./specs/ for this repo — the Spec-First protocol. Covers where a spec lives (specs/<topic>/NN-short-description.md), the outline template (Objective, Context, Acceptance Criteria, Plan, Risks), and the MANDATORY MLA in-text citation format — (topic NN) — for referring to other specs. Use this whenever you create, author, extend, or revise any spec/outline/acceptance-criteria file, or need to cross-reference one spec from another.
10 other projects use a version of this.
Adopted by
Most recently taken up by
- alumpe/skillstheir own version, first seen Nov 16, 2026
- ekirton/Pouletheir own version, first seen Nov 15, 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
- augments-labs/sdlc-skills★ 1same name
- fireshort/skills★ 1same name
- xmtplabs/code-factory★ 1same name
- alumpe/skills★ 0same name
- ekirton/Poule★ 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 repository4 other files it gives its agents.
- AGENTS.mdAGENTS.md
- release-highlightsSkill
- release-notesSkill
- writing-codeSkill
The file
We split this skill into the rules it gives an agent
5 rules. 0 are common, 2 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 10 edited versions we read keep these.
2
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
- Very specific: line 45
When a spec mentions another spec, cite it with an MLA-style in-text citation: the main topic followed by the spec number, in parentheses.
- Very specific: line 56
Always parenthesized, lowercase topic, zero-padded number matching the file (03, not 3).
- Very specific: line 58
Never write prose forms like spec 03, (spec 03), see spec 3, or a bare file path when you mean *another spec*.
- Distinctive: line 77
Keep it concise — Hemingway, not academia.
- Distinctive: line 121
STOP and wait for the user: before writing any code. The spec is a checkpoint, not a formality.
“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
Writing specs
The Spec-First protocol: problem definition → small, safe change → change
review → refactor → repeat. No code is written until a spec exists and the
user has reviewed it. This skill is the authority on how a spec is structured
and how specs cite each other; AGENTS.md is the authority on the surrounding
workflow.
1. Where the spec lives
specs/
├── <topic>/
│ ├── 01-short-description.md
│ ├── 02-short-description.md
│ └── ...- Pick the closest existing topic folder or create one. Current topics:
core,providers,ui,widgets,ci,site. Only create a new topic folder if the work fits none of them. - Number sequentially within that topic folder. List the folder's files,
take the next number, zero-pad to two digits (
07, not7). - File name:
NN-short-description.md— kebab-case, intention-revealing, no spaces.
Topic guide
| Topic | What belongs here |
core | Provider protocol, hub, registry, Keychain, refresh |
providers | Individual provider implementations (z.ai, Claude, …) |
ui | Menu bar, popover, settings, app lifecycle |
widgets | Desktop widgets, Notification Center integration |
ci | GitHub Actions workflows, CI configuration, tooling |
site | Project website on GitHub Pages |
2. MLA cross-references (MANDATORY)
When a spec mentions another spec, cite it with an MLA-style in-text
citation: the main topic followed by the spec number, in parentheses.
This is the analogue of MLA's (Author Page) — here (topic number).
(core 03) one spec
(providers 02, ui 01) several specs, comma-separated
(providers 04 AC10) a specific acceptance criterion inside a specRules:
- Always parenthesized, lowercase topic, zero-padded number matching the file
(
03, not3). - Never write prose forms like
spec 03,(spec 03),see spec 3, or a bare file path when you mean another spec. Those are non-compliant. - A path like
`Sources/Core/ProviderHub.swift`pointing at source code is not a spec citation — leave those as file paths. - Citations stay in
specs/. Code, tests, scripts, and config never cite a spec or an AC. See thewriting-codeskill.
Fix on sight. Existing specs may use non-compliant spec 03 / (spec 03)
forms. If you edit a spec that contains a non-compliant reference, convert it:
| Non-compliant | Correct |
(spec 03) | (core 03) |
in spec 03 | (core 03) |
spec 04 AC10 | (providers 04 AC10) |
see spec 3 | (ui 03) |
3. The outline
Keep it concise — Hemingway, not academia. Short declarative sentences. Write as many acceptance criteria as the feature needs, no filler.
## Objective
1 sentence.
## Context
- Key files affected — `Sources/Core/Whatever.swift` — one line on why it matters
- Cross-referenced specs go here in MLA form, e.g. builds on (core 03)
## Acceptance Criteria
### AC1: <short description>
- **Given** <precondition>
- **When** <action>
- **Then** <outcome>
### AC2: ...
## Plan
Brief description of the approach. Code snippets ONLY when they clarify an
interface or data shape.
## Risks
- Any known regression or side effectSection rules
- Objective — exactly one sentence. If it needs two, the spec is doing too much; split it.
- Context — bullet list of affected files, each with a terse reason. This is where you name the reference implementations and cite related specs in MLA form.
- Acceptance Criteria — every AC is Given/When/Then. Number them
AC1,AC2, … so they can be cited as(topic NN ACx). Make each one testable — a reviewer should be able to check it off. - Plan — the approach, not a diff. No large code blocks; a small snippet is fine only to pin down a protocol signature or data shape.
- Risks — regressions and side effects a reviewer should watch for. Omit only if there are genuinely none.
4. After writing
- STOP and wait for the user before writing any code. The spec is a checkpoint, not a formality.
- During implementation the spec is the source of truth: re-read it before each
change, mark items
[x]as they land, and log new findings back into the spec.
Self-check before handing a spec back
- File is at
specs/<topic>/NN-short-description.md, number is the next free one in that folder, zero-padded. - Objective is one sentence.
- Every AC is Given/When/Then and testable.
- Every reference to another spec uses MLA
(topic NN)form — nospec 03, no bare(spec NN). - If I edited an existing spec, I converted any legacy
spec NNreferences I touched. - Plan has no diff-sized code blocks; Risks lists real regressions.
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.

