CtrlK
BlogDocsLog inGet started
Tessl Logo

specification-writing

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

66

Quality

83%

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

82%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: every section is template-driven, concrete, and free of basic-concept padding, with real validation checkpoints (one-sentence test, decision classes, success criteria) woven through. The main improvement opportunities are trimming the very long worked examples and ensuring cross-skill references resolve within the deployed bundle.

Suggestions

Move the ~70-line field.* catalog and call-site worked examples into a references/ file (e.g., references/spec-examples.md) linked from the Catalogs and Call Sites sections, tightening the main body.

Verify or make resilient the sibling-skill links (../writing-voice, ../one-sentence-test, ../pull-request/references/body-patterns.md, ../rethink/references/clean-breaks.md) — four of six cross-bundle references currently do not resolve.

Add a short explicit drafting sequence (one-sentence test -> motivation/research -> decisions -> structure -> success criteria) near the top so the workflow is a single ordered list rather than inferred from section order.

DimensionReasoningScore

Conciseness

The body is dense and opinionated ('A spec is in-flight scaffolding, not the durable record'; 'No process theater') and explains nothing Claude already knows, matching the score-4 anchor 'efficient; minor instances of over-explanation that could be trimmed'. The ~70-line field.* catalog example and the fully worked call-site example are longer than needed to convey the pattern, which is what keeps it from the lean score-5 anchor.

4 / 5

Actionability

Guidance is fully concrete and copy-paste ready: exact naming convention 'specs/YYYYMMDDThhmmss-feature-name.md', a decision-classification table with rules, markdown templates for every section with [PLACEHOLDER] markers, and a verbatim before/after call-site pattern with file:line references. This matches the score-5 anchor 'fully executable; copy-paste ready; specific examples cover the common cases'.

5 / 5

Workflow Clarity

The writing sequence is clear with most checkpoints present: apply the one-sentence-test before outlining ('If you can't name what this spec is about in one concrete sentence... the spec is not ready'), classify every material decision, record crystallized decisions as Proposed ADRs, and verify with Success Criteria checkboxes ('Tests pass / build succeeds'). It falls short of the score-5 anchor because the steps are distributed across prose sections rather than presented as one explicit ordered procedure with feedback loops for the drafting process itself.

4 / 5

Progressive Disclosure

Structure is good: an up-front References section with conditional on-demand loading ('Load these on demand based on the spec's decision surface'), and the one bundle reference, references/decision-hygiene.md, exists and is one level deep with clear trigger conditions. This matches the score-4 anchor 'good structure; most content is appropriately placed; references mostly clear; minor organization gaps' — the gaps being several sibling-skill cross-references (../writing-voice/SKILL.md, ../pull-request/references/body-patterns.md, ../rethink/references/clean-breaks.md, ../../../specs/README.md) that do not resolve within this bundle, and long inline worked examples that could live in references.

4 / 5

Total

17

/

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 with an explicit 'Use for' trigger list of natural user phrases. Its main weakness is thin capability coverage — it names only the top-level action rather than the concrete spec-writing activities the skill actually performs.

Suggestions

Add 1-2 concrete capability phrases, e.g., 'structure research findings, decision tables, and implementation plans' — this would lift specificity from one action to several.

Include common synonyms in the trigger list such as 'specification', 'design doc', or 'technical design' to broaden natural-term coverage.

Narrow the 'plan this feature' trigger (e.g., 'write a spec for this feature') to reduce overlap with general planning skills.

DimensionReasoningScore

Specificity

The description names the domain and a single concrete action — 'Write technical specs that let agents implement autonomously' — which matches the anchor 'names domain and 1-2 concrete actions, but not comprehensive'. It does not list several specific actions (e.g., structure research findings, design decision tables, plan implementation phases), so it does not reach the score-4 anchor 'lists several specific actions'.

3 / 5

Completeness

It clearly answers 'what' ('Write technical specs that let agents implement autonomously') and 'when' with an explicit 'Use for' clause containing three concrete trigger phrases, matching the score-5 anchor 'clearly and explicitly answers both what AND when with concrete trigger phrases'.

5 / 5

Trigger Term Quality

Three quoted natural trigger phrases ('write a spec', 'plan this feature', 'create a planning doc') are exactly what a user would say, giving good keyword coverage. A few natural synonyms are missing (e.g., 'specification', 'design doc', 'RFC'), which keeps it below the comprehensive score-5 anchor.

4 / 5

Distinctiveness Conflict Risk

'Write technical specs' plus the specific quoted triggers carve out a mostly distinct niche from adjacent writing/planning skills. However, 'plan this feature' is a broad phrase that could overlap with general planning or architecture skills, so it does not fully meet the 'minimal conflict risk' of the score-5 anchor.

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
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.