CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

spec-workflow

Use when medium-to-large changes need explicit requirements, technical design, and task planning before implementation, especially for multi-module work, unclear acceptance criteria, or architecture-heavy requests.

57

Quality

72%

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 ./config/.claude/skills/spec-workflow/SKILL.md

The canonical home for this skill is spec-workflow in TencentCloudBase/CloudBase-AI-Toolkit

SKILL.md
Quality
Evals
Security

Quality

Content

67%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, genuinely actionable workflow skill: clear phases, concrete templates, explicit gates, and graceful handling of missing sibling skills. Its main weaknesses are redundancy — the use/skip decision is repeated across three sections — and the absence of templates for the user-story and design phases.

Suggestions

Collapse 'Activation Contract', 'When to use this skill', and 'Decision rule' into a single use/skip section; the current layout restates the same triggers three to four times.

Fold 'Common mistakes / gotchas' into the phase where each mistake occurs (e.g., vague tasks belongs in Phase 3) instead of a standalone list.

Add a short user-story format and a design.md skeleton alongside the existing EARS and task templates so all three artifacts are equally executable.

DimensionReasoningScore

Conciseness

No filler or explanations of concepts Claude already knows, but the when-to-use guidance is stated three times — 'Activation Contract' (use-first/do-not-use/checklist), 'When to use this skill', and 'Decision rule' (use-full/skip-full) — and the 'Minimal checklist' restates it a fourth time. Mostly efficient with a genuine tightening opportunity, hence 3 rather than 4; not 2 because every section is directive and none is padded prose.

3 / 5

Actionability

Concrete, executable guidance throughout: exact file paths ('specs/<spec_name>/requirements.md'), a copy-paste EARS template with a worked example, and a ready-to-use task-format block. Not 5 because Phase 1's user stories and Phase 2's design content get no template or example; not 3 because the guidance is directly usable, not high-level hints.

4 / 5

Workflow Clarity

Four phases are explicitly sequenced with confirmation gates ('Only start implementation after the user confirms the task plan', 'Require confirmation between requirements, design, and task breakdown') plus a minimal checklist. Not 5 because there is no error-recovery feedback loop (e.g., what to do when the user rejects the requirements — revise and re-confirm is only implicit); not 3 because checkpoints are explicit, not missing.

4 / 5

Progressive Disclosure

A single well-sectioned file with no nested references; sibling references ('../ui-design/SKILL.md', '../data-model-creation/SKILL.md') are one level deep, clearly signaled, and carry an explicit fallback when missing (they do not resolve in this environment, though the skill anticipates that). Nothing at this size clearly belongs in a separate file. Not 5 because the skill ships no bundle structure of its own and its cross-references cannot be verified to exist here; not 3 because organization and signaling are solid.

4 / 5

Total

15

/

20

Passed

Description

66%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, specific trigger description with natural phrasing and a well-scoped niche, but it is one-sided: it says when to use the skill without ever saying what the skill does (the phased spec workflow and its artifacts are only implied). Adding a leading what-clause would lift it into the top band.

Suggestions

Lead with an explicit what-clause, e.g., 'Guides a four-phase spec workflow (requirements, design, tasks, execution) producing specs/<name>/requirements.md, design.md, and tasks.md', before the 'Use when' trigger.

Add the synonyms users naturally say for this activity — 'spec', 'specification', 'write/plan a spec', 'feature spec' — to the trigger list.

State the key mechanism inline (EARS acceptance criteria and phase-gate user confirmation) so the description distinguishes the skill from generic planning tools.

DimensionReasoningScore

Specificity

Names several concrete capability areas — 'explicit requirements, technical design, and task planning' — anchored to real practice. Falls short of 5 because it never states the actual actions or artifacts (e.g., producing requirements/design/tasks documents or running a phased workflow), and above 3 because it lists more than 1-2 concrete actions.

4 / 5

Completeness

The 'when' is explicit and well-qualified ('Use when medium-to-large changes need... especially for multi-module work, unclear acceptance criteria, or architecture-heavy requests'), but the 'what' is never stated as an action — the sentence is entirely a when-clause, with the skill's behavior only implied through nouns. This mirrors anchor 3 (one half clear, the other weakly implied) rather than 4, which requires both halves present.

3 / 5

Trigger Term Quality

Good natural-language coverage: 'requirements', 'technical design', 'task planning', 'multi-module work', 'acceptance criteria', 'architecture-heavy requests'. Not 5 because common synonyms users actually say — 'spec', 'specification', 'feature', 'PRD' — are absent; not 3 because coverage goes beyond 'some relevant keywords' with multiple natural trigger phrases.

4 / 5

Distinctiveness Conflict Risk

The requirements + design + task-planning trio for medium-to-large changes carves a fairly distinct pre-implementation niche. Not 5 because broad terms like 'architecture-heavy requests' and 'task planning' overlap with general planning and architecture skills; not 3 because the combined trigger set is clearly more specific than generic workflow skills.

4 / 5

Total

15

/

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

frontmatter_unknown_keys

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

Warning

Total

15

/

16

Passed

Repository

TencentCloudBase/CloudBase-AI-Toolkit

Path

config/.claude/skills/spec-workflow/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.