spec-feature

Spec a new feature — recall architecture knowledge, create a spec document, build an implementation plan, and break into tasks.

Quality

60%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/spec-feature/SKILL.md

Quality

Content

77%

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, highly actionable skill that clearly guides Claude through a feature specification process with concrete outputs, tool integrations, and validation checkpoints. Its main weakness is moderate verbosity — the inline spec template, detailed handoff explanation, and some auxiliary instructions (terminal title setting, diagram complexity rating) add bulk that could be trimmed or externalized. Overall it's a strong skill that effectively prevents premature implementation and enforces structured planning.

Suggestions

Consider extracting the spec document markdown template into a separate template file (e.g., `spec-template.md`) and referencing it, reducing the inline bulk of the SKILL.md.

Tighten the handoff explanation in step 8 — the detailed description of what the handoff skill does internally (frozen-state file, mcp session spawning, sidebar visibility) is implementation detail Claude doesn't need repeated here if the handoff skill handles it.

Dimension	Reasoning	Score
Conciseness	The skill is moderately efficient but includes some unnecessary verbosity — the diagram complexity callout box at the top, the detailed terminal title-setting bash snippet, and the lengthy explanation of the handoff mechanism in step 8 could be tightened. However, it mostly avoids explaining concepts Claude already knows.	2 / 3
Actionability	The skill provides highly concrete, actionable guidance: a specific file path for output, a complete markdown template for the spec document, explicit tool calls (recall, retain, mark_chapter), specific regex patterns, and clear commands. Each step tells Claude exactly what to do.	3 / 3
Workflow Clarity	The multi-step process is clearly sequenced with numbered steps, explicit ordering dependencies, and validation checkpoints (step 6 presents to user for review, step 1 includes clarification gates for vague/ambiguous input). The workflow includes clear boundaries (no implementation) and a structured handoff process with gating.	3 / 3
Progressive Disclosure	The skill references external skills (render-diagram, phase-handoff, writing-plans) and tools (Hindsight recall/retain, mark_chapter) appropriately, but the spec template is inlined as a large block that could potentially be a separate reference file. With no bundle files provided, the references to other skills are well-signaled but the monolithic inline template weighs it down slightly.	2 / 3
	Total	10 / 12 Passed

Description

42%

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 good job listing concrete steps in the feature spec workflow, giving it strong specificity. However, it lacks an explicit 'Use when...' clause, which hurts completeness and makes it harder for Claude to know exactly when to select this skill. Trigger terms are reasonable but could be broadened to cover more natural user phrasings.

Suggestions

Add an explicit 'Use when...' clause, e.g., 'Use when the user wants to spec out a new feature, write a technical design document, or plan implementation work.'

Include additional trigger term variations such as 'specification', 'design doc', 'RFC', 'technical design', 'project planning', 'epic breakdown', or 'ticket creation'.

Consider clarifying what 'recall architecture knowledge' means — e.g., 'references existing codebase architecture' — to reduce ambiguity and improve distinctiveness.

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions: recall architecture knowledge, create a spec document, build an implementation plan, and break into tasks. These are distinct, actionable steps in a workflow.	3 / 3
Completeness	Describes what the skill does but has no explicit 'Use when...' clause or equivalent trigger guidance. Per the rubric, a missing 'Use when...' clause caps completeness at 2, and since the 'when' is only weakly implied (the opening phrase 'Spec a new feature' hints at it), this falls to the lower end.	1 / 3
Trigger Term Quality	Includes some natural keywords like 'spec', 'feature', 'implementation plan', and 'tasks', but misses common variations users might say such as 'specification', 'design doc', 'technical design', 'RFC', 'project plan', or 'ticket breakdown'.	2 / 3
Distinctiveness Conflict Risk	The combination of spec creation + architecture recall + task breakdown is somewhat distinctive, but terms like 'feature', 'tasks', and 'implementation plan' could overlap with project management, task tracking, or general planning skills.	2 / 3
	Total	8 / 12 Passed

Validation

100%

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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: AndreJorgeLopes/devflow
Commit: 8d872bf

Reviewed: 1 day 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.