CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

source-command-doc-refactor

Restructure project documentation for clarity and accessibility

Quality

70%

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 ./.agents/skills/source-command-doc-refactor/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

80%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 content is a tight, well-structured instruction checklist that respects the token budget and gives genuinely actionable direction for a documentation refactor. Its one real weakness is the absence of validation steps for what is inherently a batch restructuring of the repo's files. Progressive disclosure is appropriate for a skill this size.

DimensionReasoningScore

Conciseness

The body is a lean 29-line checklist with zero explanations of concepts Claude already knows and no padding — every line instructs ("Move technical documentation to `docs/`", "Use Mermaid for all diagrams"). This matches anchor 5 ('lean and efficient; assumes Claude's competence; every token earns its place').

5 / 5

Actionability

As an instruction-only skill it gives concrete, specific guidance: named file targets (`docs/`, root README.md, module/package/service-level READMEs), named guide types with their contents, and a concrete tool choice (Mermaid). Minor gaps — no example structure or template showing what a finished layout looks like — keep it at anchor 4 rather than 5.

4 / 5

Workflow Clarity

Steps 1–7 are clearly sequenced, but the workflow is a batch operation that moves and rewrites many files with no validation or verification checkpoints (e.g. checking cross-references still resolve, confirming no documents were lost). Per the judging guidelines, missing validation in batch operations caps workflow clarity at 3 even though the sequence itself is clear.

3 / 5

Progressive Disclosure

The skill is under 50 lines with no need for external references — and none are cited, consistent with the absent references/scripts/assets directories. Sections ('Command Template', numbered steps, closing guidance) are well organized, so the simple-skill exception applies: well-organized sections alone merit 5.

5 / 5

Total

17

/

20

Passed

Description

45%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 names a clear domain and intent but stays at a high level of abstraction: one generic action, no 'when to use' guidance, and thin natural trigger vocabulary. It reads more like a category label than a trigger-matched capability statement. Most of the actionable detail lives in the body rather than the description where skill selection actually happens.

Suggestions

Add concrete capabilities to the description, e.g. 'Restructure project documentation: centralize docs into docs/, streamline the root README, add component-level READMEs, and create user/API/deployment guides.'

Append an explicit trigger clause, e.g. 'Use when the user asks to reorganize or clean up project docs, restructure documentation, or consolidate scattered README files.'

Include natural synonyms users would say (docs, reorganize, documentation structure, README) so the skill triggers on real phrasings rather than only the formal term 'restructure'.

DimensionReasoningScore

Specificity

"Restructure project documentation" names the domain, but "restructure ... for clarity and accessibility" is a single generic action plus a goal clause rather than concrete capabilities. It matches anchor 2 ('names the domain but actions are minimal or generic', e.g. 'Processes PDF files') — not 3, since there is no second concrete action, and not 1, since it is not pure abstraction.

2 / 5

Completeness

The 'what' is stated ("Restructure project documentation for clarity and accessibility") but the 'when' is entirely absent — there is no 'Use when...' clause or equivalent trigger guidance, which caps completeness at 3 per the judging guidelines. Not 4 because 'when' is missing outright, not merely implicit; not 2 because the 'what' is stated rather than extremely vague.

3 / 5

Trigger Term Quality

"documentation", "restructure", and "clarity" are relevant keywords, but common natural phrasings users would actually say ("docs", "reorganize", "clean up documentation", "README") are missing. This fits anchor 3 ('some relevant keywords but missing common variations or synonyms') better than 2, because "documentation" is a genuinely natural domain term unlike the purely generic "files".

3 / 5

Distinctiveness Conflict Risk

"Restructure project documentation" is somewhat specific (documentation restructuring) but could still overlap with related skills like doc writing, formatting, or README generation, matching anchor 3 ('somewhat specific but could still overlap with similar skills'). Without distinctive trigger phrases it does not reach 4.

3 / 5

Total

11

/

20

Passed

Validation

100%

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

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

tonykay/transcriber

Path

.agents/skills/source-command-doc-refactor/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.