CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

spec-normalizer

Padroniza documentação existente no formato canônico Spec-Driven. Remove duplicação e melhora rastreabilidade.

Quality

66%

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

The body is a compact, well-sectioned instruction set with a clear sequenced process and built-in quality checks, suitable for a small no-bundle skill. Its main weakness is actionability — the normalizing rules lack templates and worked examples that would make outputs deterministic.

Suggestions

Add a short example of each key artifact: a 'Source' note, an Open Question, and a traceability link line (PRD goal → FR → AC → Design section).

Merge the "Canonical Structure Reminder" into Step 1 so the folder list appears once and consistently (resolve whether 30-features/ exists).

Add a feedback loop to Step 4, e.g. 'if vague terms or missing definitions are found, rewrite and re-check' to make the quality pass a verify → fix → retry cycle.

DimensionReasoningScore

Conciseness

The body is lean bullets with no explanation of concepts Claude already knows, but the canonical folder structure is listed twice — in Step 1 and again in "Canonical Structure Reminder" — with an inconsistency (30-features/ appears only in the reminder). Efficient overall with minor trimmable redundancy, matching anchor 4 rather than the every-token-earns-its-place anchor 5.

4 / 5

Actionability

Concrete directory names (spec/00-context/, spec/10-requirements/, etc.) and a numbered process give real guidance, but for an instruction-only skill key details are missing: no template or example of a "Source" note, no example Open Question, and no example traceability link format. This is "some concrete guidance but incomplete" — anchor 3, not 4.

3 / 5

Workflow Clarity

Steps 0–4 are clearly sequenced, and Step 4 "Quality Pass" plus Rules 2/5 (annotate ambiguity, escalate conflicts to Open Questions) act as checkpoints. However, there is no explicit fix-and-recheck feedback loop for this batch restructuring operation, so it matches anchor 4 ("most checkpoints present; minor validation gaps") rather than 5.

4 / 5

Progressive Disclosure

No bundle files exist (references/, scripts/, assets/ are absent) and the skill needs none; sections are clearly headed and navigable. The duplicated and inconsistent structure listing is a minor organization gap, placing it at anchor 4 rather than the fully clean anchor 5.

4 / 5

Total

15

/

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 "what" with a defined domain but stops at a mid-level score across the board: no explicit "Use when..." guidance, generic trigger words, and only moderately concrete actions. It is functional but under-specified for reliable skill routing.

Suggestions

Add an explicit 'Use when...' clause, e.g. 'Use when the user has messy or legacy markdown docs, wiki exports, or old PRDs/specs to reorganize.'

Expand trigger terms with natural phrases and synonyms users would actually say: 'clean up docs', 'restructure documentation', 'PRD', 'wiki export', 'messy docs'.

List more concrete capabilities in the description (e.g. 'adds PRD → FR → AC → Design traceability links and deduplicates content') and keep language consistent with the user base.

DimensionReasoningScore

Specificity

"Padroniza documentação existente no formato canônico Spec-Driven. Remove duplicação e melhora rastreabilidade" names the domain plus roughly three actions, but "melhora rastreabilidade" is abstract and coverage is incomplete (restructuring, templates, and conflict handling are absent). It sits at anchor 3 — more concrete than a bare domain claim, but short of the several specific, concrete actions of anchor 4.

3 / 5

Completeness

The "what" is clear (normalize docs into the canonical spec format, remove duplication, improve traceability), but there is no "Use when..." clause — the "when" exists only weakly through the terse triggers list, which the guidelines cap at 3. Not anchor 2, since the "what" is explicit and the "when" is weakly implied rather than absent.

3 / 5

Trigger Term Quality

Triggers "normalize, spec, docs, restructure" include some relevant keywords, but "docs" and "spec" are generic single words and common user phrasings ("clean up docs", "organize documentation", "messy docs", "PRD", "wiki export") are missing. The Portuguese-only description also limits natural term matching, fitting anchor 3.

3 / 5

Distinctiveness Conflict Risk

"formato canônico Spec-Driven" establishes a niche, but the triggers "docs" and "spec" are broad and would readily collide with other documentation- or spec-writing skills. This is "somewhat specific but could still overlap with similar skills" — anchor 3.

3 / 5

Total

12

/

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

fernandezbaptiste/cursor-multiagent-system

Path

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