Diagnose and fix documentation quality problems in cookbook-style writing — skimmability, writing clarity, and reader helpfulness.
44
44%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/documentation/authoring-cookbooks/SKILL.mdQuality
Discovery
50%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 identifies a reasonably specific domain (cookbook-style documentation quality) and names three focus areas, but remains at a moderate level of specificity without listing concrete actions. The lack of an explicit 'Use when...' clause limits its effectiveness for skill selection, and the trigger terms could be broader to capture natural user language.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to review, improve, or edit cookbook-style docs, tutorials, guides, or how-to documentation.'
List more concrete actions such as 'restructure headings for scannability, simplify jargon, add summaries, improve code example annotations'.
Include natural trigger term variations like 'tutorial', 'how-to guide', 'technical writing', 'readability', 'docs review' to improve matching.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (documentation quality in cookbook-style writing) and some action areas (skimmability, writing clarity, reader helpfulness), but doesn't list specific concrete actions like 'restructure headings', 'simplify sentences', or 'add code examples'. | 2 / 3 |
Completeness | Answers 'what' (diagnose and fix documentation quality problems) reasonably well, but lacks an explicit 'Use when...' clause or equivalent trigger guidance, which per the rubric caps this at 2. | 2 / 3 |
Trigger Term Quality | Includes some relevant terms like 'documentation', 'cookbook', 'skimmability', 'writing clarity', but misses common user phrases like 'improve docs', 'technical writing', 'readability', 'edit my guide', or 'review my tutorial'. | 2 / 3 |
Distinctiveness Conflict Risk | The 'cookbook-style writing' qualifier adds some distinctiveness, but 'documentation quality' and 'writing clarity' could overlap with general writing/editing or code review skills. Not generic enough for a 1, but not sharply distinct enough for a 3. | 2 / 3 |
Total | 8 / 12 Passed |
Implementation
39%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill has strong workflow clarity with a well-sequenced diagnostic process and clear ordering rationale, but it is severely undermined by its verbosity and monolithic structure. The seven documentation states are well-defined but the content is heavily duplicated between the states section and the anti-patterns section. At its current length (~3k+ words), it violates its own principles about cognitive load and skimmability — the irony of a documentation quality skill that itself suffers from AC1 (Structure Void) and AC2 (Buried Takeaways).
Suggestions
Cut the anti-patterns section entirely — it restates what the states already cover. If kept, extract to a separate ANTI-PATTERNS.md reference file.
Move the integration graph, context management, subagent candidates, and output persistence sections to a separate operational reference file — these are metadata, not diagnostic instructions.
Compress each state to: 3-bullet symptoms, 1 key question, 3-bullet interventions. The current format is too verbose for a skill that will be loaded into context repeatedly.
Add a concrete before/after example showing a diagnosed paragraph transformed by an intervention — the current examples show reasoning approaches but not actual output artifacts.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | At ~3000+ words, this skill is extremely verbose. It explains concepts Claude already understands (what empathy in documentation means, what left-branching sentences are, what demonstrative pronouns do). The anti-patterns section largely restates what was already covered in the states section. The integration graph, context management, subagent candidates, and output persistence sections add significant token overhead for operational metadata that could be drastically compressed. | 1 / 3 |
Actionability | The skill provides concrete diagnostic questions and named interventions per state, plus executable CLI commands for the two tools. However, the interventions themselves are writing advice rather than executable steps — there are no templates, no before/after diffs, and the example interactions show reasoning approaches rather than concrete outputs. The tool commands are actionable but the core diagnostic work remains somewhat abstract. | 2 / 3 |
Workflow Clarity | The diagnostic process is clearly sequenced (7 numbered steps), with explicit ordering rationale (AC7 before AC1 before AC5). The example interactions demonstrate the diagnostic workflow applied to real scenarios. The sequential vs. parallelizable distinction and the 'triage before intervention' principle provide clear validation checkpoints. The 'one state at a time' constraint prevents scope creep. | 3 / 3 |
Progressive Disclosure | This is a monolithic wall of text with no references to external files despite being extremely long. The seven states, anti-patterns, example interactions, integration graph, context management, and tool documentation are all inline. No bundle files are provided, yet the content clearly warrants splitting — the anti-patterns could be a separate reference, the integration graph is operational metadata, and the states could be individual files referenced from a concise overview. | 1 / 3 |
Total | 7 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
metadata_field | 'metadata' should map string keys to string values | Warning |
Total | 10 / 11 Passed | |
b683754
Table of Contents
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.