Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx skills add orlando-japan/claude-code-setting --skill spec-writinggit clone --depth 1 https://github.com/orlando-japan/claude-code-settingWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/skills/orlando-japan/claude-code-setting/spec-writing)<a href="https://agentmods.dev/skills/orlando-japan/claude-code-setting/spec-writing"><img src="https://agentmods.dev/badge/skills/orlando-japan/claude-code-setting/spec-writing.svg" alt="Measured on agentmods" height="20"></a>What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5.1 | $0.00034 | $0.00719 |
| Opus 5 | $0.00017 | $0.00360 |
| Sonnet 5 | $0.00007 | $0.00144 |
| Haiku 4.5 | $0.00003 | $0.00072 |
Grade A, and why
spec-writing scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 8d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 72 lines — stays where its author put it; the contents beside it link to each section on GitHub.
Spec writing
The test of a good spec: a different engineer reads it and implements the right thing without having to ask follow-up questions. If they would ask, the spec is incomplete.
Sections
A spec has four parts. They serve different purposes; don't mix them.
1. Problem statement (2–5 sentences)
Not the solution — the problem. Who is hitting it? What are they trying to do? Why is the current state insufficient? If this is fuzzy, the rest of the spec is built on sand.
2. Scope
In scope: bullet list of behaviors the change will produce. Concrete and observable.
Out of scope (non-goals): bullet list of things someone might reasonably expect to be included but aren't. Most spec disputes come from scope ambiguity — non-goals are load-bearing.
3. Requirements as scenarios
Not "the system shall X." Scenarios in Given / When / Then form:
Scenario: logged-out user hitting a protected route
Given a user with no active session
When they visit /settings
Then they are redirected to /login?return_to=/settings
And the return_to parameter URL-encodes the original path
Each scenario is testable. Each covers exactly one behavior. Edge cases get their own scenarios.
4. Design (if non-trivial)
If the implementation isn't obvious, add a design section:
- One-paragraph technical approach.
- Data model changes, if any (schema diff).
- New APIs, if any (shape, not implementation).
- At least one rejected alternative with the reason.
- Dependencies: what this assumes about existing code.
If the rejected alternative is a strawman ("we could do nothing, but that's bad"), you haven't thought hard enough.
Rules
- No code. Specs describe behavior; code goes in the implementation. Exception: interface shapes (API schema, type definitions).
- No "obviously." If it's obvious, state it — the implementer might not agree.
- No "we should probably." Decide or ask. Specs are decisions.
- Surface unknowns. A section labeled "Open questions" with "we need to decide X before we can ship Y" is more trustworthy than a spec that pretends to have all answers.
- Link prior art. If another spec or feature is related, link it. Don't re-derive.
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 8d ago First seen · 72 lines · 34 tokens per session scan A ad9df924e1d0
spec-writing is a skill published in the GitHub repository orlando-japan/claude-code-setting (2 stars, last pushed 3mo ago), licensed MIT. It adds 34 tokens to every session and 719 once invoked, about $0.0002 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.
Other skills, from other repositories
project-brainstorming
Guides project ideation via Socratic questioning to produce a validated brief. Use before specification when requirements are unclear.
project-specification
Transforms project briefs into testable specifications with user stories and acceptance criteria. Use after brainstorming, before planning.
derive-nfr-from-driver
Derives measurable NFRs from a parent business driver.
derive-security-from-risk
Derives security requirements from a named threat.
absolute-work
End-to-end, phase-gated SDLC for AI coding agents: relentless design interview → reviewed spec → dependency-graphed task board → safe-wave TDD execution → verification → converge. Handles features, bugs, refactors, greenfield projects, planning breakdowns, and migrations. Triggers on "absolute work", "build this…
absolute-spec
Lightweight standalone design spec for AI coding agents: codebase scan → bounded clarify pass (3–5 questions, not a grill) → reviewed design doc written to docs/plans/ → independent scored review → stop. No task board, no build. Use when you want a spec to discuss, hand off, or review before committing to…