CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

speckit-plan

Execute the implementation planning workflow using the plan template to generate design artifacts.

Quality

64%

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 ./apps/reference/.claude/skills/speckit-plan/SKILL.md

The canonical home for this skill is speckit-plan in RihardsJ/software-factory

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.

The body is a genuinely executable workflow: exact commands, file paths, gate checks, and a completion checklist give Claude unambiguous instructions for the happy path. Its main weaknesses are structural — the hook protocol is duplicated verbatim across pre- and post-execution sections, inflating token cost, and the artifact-generation phases lean on an external template whose content is never surfaced.

Suggestions

Extract the hook rules (YAML error handling, enabled/condition filtering, dot-to-hyphen mapping, emission blocks) into a single shared section or reference file and have both Pre-Execution and Post-Execution sections point to it, removing ~30 duplicated lines.

Define what happens after an ERROR state (e.g. 'on gate failure, report the violation and stop; do not generate Phase 1 artifacts') so the validation checkpoints have recovery paths, not just failure signals.

Show a brief outline of the IMPL_PLAN template's structure (section names for Technical Context, Constitution Check, phases) so the 'Execute plan workflow' step does not depend entirely on an unseen file.

DimensionReasoningScore

Conciseness

The body is terse and imperative with no explanation of concepts Claude already knows, but the entire hook protocol (YAML parse-error handling, 'Filter out hooks where `enabled` is explicitly `false`', condition handling, the dot-to-hyphen replacement rule, and the emission blocks) is repeated nearly verbatim in both 'Pre-Execution Checks' and 'Mandatory Post-Execution Hooks' — roughly 30 duplicated lines that a shared rules section would eliminate. This is more than the 'minor instances' of anchor 4, fitting anchor 3's 'mostly efficient but could be tightened', though not anchor 2 since there is no conceptual padding.

3 / 5

Actionability

Concrete, executable guidance dominates: the exact command '.specify/scripts/bash/setup-plan.sh --json', specific paths ('.specify/extensions.yml', '.specify/memory/constitution.md'), named artifacts, a shell-quoting escape example, and precise skip/emit rules. Minor gaps keep it below anchor 5: the research dispatch block is placeholder text ('Task: "Research {unknown} for {feature context}"') and the core execution depends on an IMPL_PLAN template whose structure is never shown.

4 / 5

Workflow Clarity

The sequence is clearly ordered (Pre-Execution Checks → Outline → Phase 0 → Phase 1 → Post-Execution Hooks → Completion Report) with explicit checkpoints: Constitution Check with re-evaluation post-design, 'ERROR if violations unjustified', 'ERROR on gate failures or unresolved clarifications', a 'Prerequisites: research.md complete' gate, and a 'Done When' checklist. It falls short of anchor 5 because ERROR states define failure conditions but no recovery/feedback path for what to do after an ERROR.

4 / 5

Progressive Disclosure

Sections are well-organized with clear headers, but roughly 60 of the ~160 lines are hook mechanics that (being shared across speckit commands and duplicated twice) clearly belong in a separate reference file, and no bundle references exist at all. This matches anchor 3 ('content that should be separate is inline'); it is not 2 because the inlined content is still navigable under clear headings, and not 4 because the misplaced bulk exceeds 'minor organization gaps'.

3 / 5

Total

14

/

20

Passed

Description

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

The description states a clear, domain-specific capability but stops at the midpoint on every dimension: no trigger conditions, no enumerated artifacts, and no spec-kit branding to distinguish it from generic planning skills. It reads as a functional one-liner rather than an effective routing description.

Suggestions

Add an explicit 'when' clause, e.g. 'Use when the user asks to plan implementation for a feature spec, create an implementation plan, or generate design artifacts in a spec-kit project.'

Enumerate the concrete outputs (data-model.md, contracts/, quickstart.md, research.md) so the 'what' is comprehensive rather than summarized as 'design artifacts'.

Include distinguishing keywords users naturally say — 'spec-kit', 'specify', 'feature spec', 'implementation plan' — to reduce overlap with generic planning skills.

DimensionReasoningScore

Specificity

"Execute the implementation planning workflow using the plan template to generate design artifacts" names the domain and 1-2 concrete actions but never enumerates the artifacts (research.md, data-model.md, contracts, quickstart) or the workflow steps. It is above anchor 2 because the actions are domain-specific rather than generic, but below anchor 4 because no list of several specific actions is given.

3 / 5

Completeness

The "what" is clear (execute the planning workflow, generate design artifacts) but there is no "Use when..." clause or equivalent explicit trigger guidance, which caps completeness at 3 per the judging guidelines. It is not 2 because the "what" is genuinely clear, not vague.

3 / 5

Trigger Term Quality

"implementation planning" and "design artifacts" are relevant keywords, but the natural terms a spec-kit user would say — "spec", "spec-kit", "feature", "implementation plan" — are absent. Some relevant keywords with missing common variations matches anchor 3, not 4 (coverage is not good enough) and not 2 (more than one or two generic keywords).

3 / 5

Distinctiveness Conflict Risk

"implementation planning workflow" is somewhat specific but could still overlap with general planning or architecture skills; the description omits the "spec-kit"/"specify" branding that would establish a clear niche. Matches anchor 3 rather than 4 because the overlap risk with generic planning skills is more than minor.

3 / 5

Total

12

/

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

metadata_version

'metadata.version' is missing

Warning

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

14

/

16

Passed

Repository

RihardsJ/software-factory

Path

apps/reference/.claude/skills/speckit-plan/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.