specification-writing

Write technical specs that let agents implement autonomously. Use for "write a spec", "plan this feature", "create a planning doc".

Quality

73%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/specification-writing/SKILL.md

Quality

Content

67%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A thorough, actionable spec-writing template with strong progressive disclosure and concrete examples. The main weakness is moderate verbosity in the philosophy/scaffolding prose that could be trimmed without losing clarity.

Suggestions

Tighten the opening philosophy paragraphs ('in-flight scaffolding, not the durable record' and the Core Philosophy list) to bullet essentials, removing restated intent.

Consider splitting the large Document Structure template catalog into a references file so SKILL.md stays a lean overview, lifting progressive_disclosure toward the top anchor.

Make the spec-writing workflow's validation checkpoints explicit (e.g., 'run the one-sentence-test; if it fails, stop and redesign') to push workflow_clarity to 5.

Dimension	Reasoning	Score
Conciseness	Mostly efficient template content, but several prose passages restate philosophy Claude already infers (e.g., 'A spec is in-flight scaffolding, not the durable record' and the Core Philosophy list) and could be tightened.	3 / 5
Actionability	Provides concrete, copy-paste-ready section templates, a specific naming convention (specs/YYYYMMDDThhmmss-feature-name.md), a decision-class table, and real file:line call-site examples; minor gaps remain because much is bracketed placeholder.	4 / 5
Workflow Clarity	Sequenced document structure (Header through Success Criteria) with an explicit one-sentence-test checkpoint and a Build/Prove/Remove wave ordering that includes a verify-before-delete step; a few validation checkpoints are implicit rather than spelled out.	4 / 5
Progressive Disclosure	References are well-signaled with conditional load triggers and one level deep; references/decision-hygiene.md is a real bundle file. The body is long but justifiably so as a section template, leaving minor organization gaps versus the top anchor.	4 / 5
	Total	15 / 20 Passed

Description

78%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A concise, well-formed description that clearly states both the capability and explicit trigger phrases. It is distinctive and complete, with only minor room to broaden trigger synonyms and enumerate more concrete spec-writing actions.

Dimension	Reasoning	Score
Specificity	Names the domain ('technical specs') and one concrete action ('Write technical specs that let agents implement autonomously'), but coverage is not comprehensive — it lists a single primary action rather than multiple specific actions.	3 / 5
Completeness	Explicitly answers both what ('Write technical specs that let agents implement autonomously') and when ('Use for ...') with concrete trigger phrases, matching the top anchor.	5 / 5
Trigger Term Quality	Includes natural user phrases ('write a spec', 'plan this feature', 'create a planning doc') that users would actually say; a few common synonyms like 'design doc' or 'RFC' are missing.	4 / 5
Distinctiveness Conflict Risk	The spec-writing niche with these triggers is mostly distinct, with only minor overlap risk against general planning or writing-voice skills; not quite the minimal-conflict top anchor.	4 / 5
	Total	16 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 5 suspicious	Warning

	Total	15 / 16 Passed

Repository: EpicenterHQ/epicenter
Path: .agents/skills/specification-writing/SKILL.md
Commit: abe10f3

Reviewed: 5 days ago

Table of Contents

Discovery Implementation Validation

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.