CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

specify

Software specification expert for transforming high-level designs into detailed, implementable technical specifications. Use when converting requirements or designs into precise specs that developers can implement directly.

Quality

75%

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

Fix and improve this skill with Tessl

tessl review fix ./plugins/dev-skills/skills/specify/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

63%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 well-structured, actionable instruction skill whose template gives Claude a clear output contract, held back by redundancy and monolithic structure. The duplicated task-execution blocks and generic boilerplate inflate token cost, and the absence of any references/ files means the full template and example live inline instead of being progressively disclosed.

Suggestions

Delete the duplicated 'When given a design document' numbered list (and merge the two 'If a design document is specified' variants) into a single Task Execution sequence.

Cut the 'Best Practices' section, which restates the Quality Checklist and the precision rules already embedded in the FR template.

Move the detailed section templates and the Example Output Structure into a references/ file (e.g. references/template.md), keeping SKILL.md as a lean overview with clearly signaled links.

DimensionReasoningScore

Conciseness

The output template is purposeful scaffolding, but there is outright duplication (the 'If a design document is specified' bullets repeat almost verbatim as the 'When given a design document' numbered list), the 'Best Practices' section largely restates the Quality Checklist, and the NFR/security/testing sections list generic boilerplate Claude already knows. Borders on 2 due to the duplication, but the core is a coherent template rather than padded prose, so 3 fits best.

3 / 5

Actionability

Concrete and executable for an instruction-only skill: exact usage commands, a full functional-requirement template (Input/Processing/Output/Edge Cases/Validation), worked examples (Go struct, REST contract, pseudocode), and a detailed example output section. Not 5 because minor gaps remain — e.g. no guidance on where to write the spec despite the Write tool being allowed.

4 / 5

Workflow Clarity

The Task Execution section sequences work on $ARGUMENTS and the Quality Checklist ('Before finalizing, verify...') acts as an explicit validation checkpoint before output. Not 5 because there is no clarify/iterate feedback loop for ambiguous or incomplete designs, and the duplicated execution blocks muddy the sequence.

4 / 5

Progressive Disclosure

No bundle files exist and none are referenced; all ~310 lines (full section templates, the example specification, best practices) are inlined in one file. Internal headers give it real structure, so it is above the unstructured anchor 2, but content that belongs in references/ files is inline and there is no reference navigation, capping it at 3.

3 / 5

Total

14

/

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 strong description with correct third-person voice, an explicit 'Use when...' trigger clause, and natural phrasing. Its main weakness is specificity: it states one transformation action twice rather than listing the concrete specification outputs (API contracts, data models, integration specs) the skill produces.

Suggestions

Enumerate the concrete spec types the skill generates, e.g. 'transforming high-level designs into detailed technical specifications covering API contracts, data models, integration points, and testing strategies'.

Add common user phrasings as trigger terms, such as 'design doc', 'spec out', or 'write a technical spec', to broaden natural keyword coverage.

DimensionReasoningScore

Specificity

Names the domain and one concrete action — 'transforming high-level designs into detailed, implementable technical specifications' — but this is essentially restated ('converting requirements or designs into precise specs') rather than expanded; it never enumerates the spec types produced (API contracts, data models, integrations). Not 4 because it does not list several specific actions.

3 / 5

Completeness

Explicitly answers both: what ('transforming high-level designs into detailed, implementable technical specifications') and when ('Use when converting requirements or designs into precise specs that developers can implement directly'). Matches the anchor-5 pattern of a clear what plus a concrete trigger phrase, so 4 is too low.

5 / 5

Trigger Term Quality

'Use when converting requirements or designs into precise specs' uses natural phrasing users would say ('requirements', 'designs', 'specs'). Not 5 because common variations like 'design doc', 'spec out', or 'technical spec' are missing; not 3 because the core trigger phrase is genuinely natural rather than jargon.

4 / 5

Distinctiveness Conflict Risk

The design-to-specification conversion niche is mostly distinct with clear triggers, but it overlaps somewhat with general architecture/planning or task-breakdown skills. Minor overlap only, so 5 is not earned and 3 is too harsh.

4 / 5

Total

16

/

20

Passed

Validation

87%

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

Validation — 14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

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

14

/

16

Passed

Repository

rikdc/ai-skills

Path

plugins/dev-skills/skills/specify/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.