CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

specification-writing

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

Quality

85%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

86%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 strong instruction-only skill body: concrete templates for every spec section, worked examples, and exemplary on-demand reference loading with stated conditions. The only real costs are length in the worked-example sections and slight redundancy between the body's decision-hygiene summary and its reference file.

DimensionReasoningScore

Conciseness

The body is dense and opinionated with copy-paste templates and assumes Claude's competence (no padding explaining what a spec is), but the long worked catalog and call-site examples and the decision-class table duplicated between body and references/decision-hygiene.md could be trimmed or condensed, so it sits at 'efficient; minor instances that could be trimmed' rather than lean.

4 / 5

Actionability

Every section ships an executable markdown template, plus a concrete naming convention (specs/YYYYMMDDThhmmss-feature-name.md), placement rules, a decision-classification table, and fully worked before/after call-site examples with file:line references — copy-paste-ready guidance covering the common cases.

5 / 5

Workflow Clarity

The Document Structure section gives a clear ordered sequence, and the one-sentence-test plus the 'How to read this spec' block act as explicit checkpoints, but there is no end-to-end writing workflow (e.g., draft → apply test → classify decisions → retire) with validation feedback loops, keeping it below the top anchor.

4 / 5

Progressive Disclosure

The References section states explicit conditional load triggers ('If writing a spec with many trade-offs... read references/decision-hygiene.md'), the referenced file exists in the bundle, is one level deep, and the body keeps only the summary table while the reference file holds the examples and failure modes — a clear overview with well-signaled one-level-deep references.

5 / 5

Total

18

/

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 well-formed description with an explicit trigger clause and natural quoted phrases, in the recommended third-person imperative voice. Its main weakness is thin capability coverage — it names the single action of writing specs without hinting at what the skill actually governs (structure, decision hygiene, placement, lifecycle).

Suggestions

Add one or two more concrete capabilities to the description, e.g., 'Structure specs with templates for motivation, research findings, design decisions, and verification' so the 'what' is more than a single action.

Consider adding a common synonym trigger such as 'specification' or 'design doc' to catch phrasings users say instead of 'spec'.

DimensionReasoningScore

Specificity

"Write technical specs that let agents implement autonomously" names the domain and one concrete action with a purpose, but lists no further capabilities (e.g., sectioning specs, decision classification, placement conventions), matching the '1-2 concrete actions, not comprehensive' anchor rather than the 'several specific actions' anchor above.

3 / 5

Completeness

It clearly answers both what ("Write technical specs that let agents implement autonomously") and when ("Use for 'write a spec', 'plan this feature', 'create a planning doc'") with concrete trigger phrases, exactly matching the top anchor.

5 / 5

Trigger Term Quality

Three natural quoted phrases ("write a spec", "plan this feature", "create a planning doc") that users would plausibly say, but common synonyms like "specification", "design doc", or "RFC" are missing, so coverage is good rather than comprehensive.

4 / 5

Distinctiveness Conflict Risk

The spec-writing niche is distinct, but the trigger "plan this feature" is broad enough to overlap with general planning or project-management skills, so it is mostly distinct with minor overlap risk rather than a fully clear niche.

4 / 5

Total

16

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

relative_links

Relative link issues: 6 suspicious

Warning

Total

15

/

16

Passed

Repository

EpicenterHQ/epicenter

Path

.agents/skills/specification-writing/SKILL.md

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.