spec
Write and evolve technical specifications — grounded design documents for a project, epic, or story. Record hard-to-reverse decisions as ADRs. Push back when the design isn't yet grounded in the codebase.
58
68%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./develop/skills/spec/SKILL.mdQuality
Discovery
67%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description does a strong job articulating specific capabilities around technical specification writing and ADR creation, with a distinctive emphasis on codebase-grounded design. However, it lacks an explicit 'Use when...' clause, which limits Claude's ability to know when to select this skill, and could benefit from broader trigger term coverage including common abbreviations and synonyms.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to write a tech spec, design doc, RFC, or architecture decision record, or when planning a new feature or epic.'
Include common trigger term variations like 'tech spec', 'RFC', 'design doc', 'architecture decision record', 'TDD (technical design document)' to improve matching against natural user language.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: write/evolve technical specifications, create grounded design documents, record decisions as ADRs, push back on ungrounded designs. These are distinct, actionable capabilities. | 3 / 3 |
Completeness | The 'what' is well-covered (write specs, record ADRs, push back on ungrounded designs), but there is no explicit 'Use when...' clause or equivalent trigger guidance telling Claude when to select this skill. The 'when' is only implied. | 2 / 3 |
Trigger Term Quality | Includes some good natural terms like 'technical specifications', 'design documents', 'ADRs', 'epic', 'story', but misses common variations users might say like 'tech spec', 'RFC', 'architecture decision record', 'design doc', 'spec document', or 'technical design'. | 2 / 3 |
Distinctiveness Conflict Risk | The combination of technical specifications, ADRs, and grounded design documents creates a clear niche. The emphasis on codebase-grounded design and hard-to-reverse decisions makes this distinctly different from general documentation or coding skills. | 3 / 3 |
Total | 10 / 12 Passed |
Implementation
70%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured instructional skill with excellent workflow clarity and progressive disclosure. Its main weakness is the lack of concrete, copy-paste-ready examples — no sample spec skeleton, no example ADR output, no specific commands for the 'Ground' step. The writing is mostly efficient but could be tightened in places where it explains general engineering wisdom rather than providing novel, actionable instruction.
Suggestions
Add a concrete spec skeleton/template (even abbreviated) showing the expected sections with placeholder content, so Claude can copy-paste and fill in rather than reconstructing from prose descriptions.
Include a brief concrete example of the 'Ground' step — e.g., specific grep/read commands and what a 'Current state' section looks like when filled in.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is mostly efficient and well-written, but includes some sections that explain concepts Claude would already understand (e.g., what a spec is for, the general idea that you should read code before designing). The 'Your Stance' section is somewhat philosophical rather than instructional. However, most content earns its place and the failure modes section is genuinely useful. | 2 / 3 |
Actionability | The skill provides clear conceptual guidance and a structured methodology (Frame, Ground, Propose, Record), but lacks concrete executable examples — no sample spec template, no example grep commands, no example ADR output, no markdown skeleton to copy-paste. The guidance is specific in intent but abstract in execution. | 2 / 3 |
Workflow Clarity | The Four Moves provide a clear, well-sequenced workflow with explicit decision points and validation checkpoints (e.g., 'push back if code hasn't been read', 'hard-to-reverse test' before creating ADR, 'if more than a couple core questions are open, consider a spike first'). The Common Patterns section handles branching workflows well, and the Status Lifecycle provides clear state transitions. | 3 / 3 |
Progressive Disclosure | The skill provides a clear overview with well-signaled one-level-deep references to related artifacts (spec.md, adr.md, spike.md, model.md, guidelines.md). Content is appropriately scoped — the SKILL.md covers the methodology and stance while deferring schema details and per-type guides to referenced files. | 3 / 3 |
Total | 10 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
- Repository
- audenaert/etak
- Commit
632c389
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.