saif-shines/authoring-cookbooks
Diagnose and fix documentation quality problems in cookbook-style writing — skimmability, writing clarity, and reader helpfulness.
46
57%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Quality
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. It lacks an explicit 'Use when...' clause, which limits its effectiveness as a skill selector. The cookbook-style qualifier helps with distinctiveness but could still overlap with general writing or documentation skills.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when reviewing or improving cookbook tutorials, how-to guides, or step-by-step documentation for readability and clarity.'
List more concrete actions such as 'restructure headings for scannability, simplify jargon, add summaries, improve code example annotations'.
Include natural trigger terms users might say, such as 'review my docs', 'improve readability', 'technical writing feedback', 'how-to guide', or 'tutorial editing'.
| 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 'docs review', 'technical writing', 'readability', 'improve my docs', or 'edit documentation'. | 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
47%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill demonstrates strong workflow clarity and a well-structured diagnostic framework, but suffers significantly from verbosity — the anti-patterns section restates the states section, concepts like left-branching sentences and demonstrative pronouns are explained unnecessarily, and operational metadata (integration graph, context management, output persistence) consumes substantial tokens. The content would benefit from being cut roughly in half while preserving the diagnostic process and tool commands.
Suggestions
Cut the Anti-Patterns section entirely — it restates what's already in the States section (e.g., 'The Noun Title' duplicates AC1's intervention, 'The Socratic Build-Up' duplicates AC2's intervention).
Remove explanations of linguistic concepts Claude already knows (left-branching, demonstrative pronouns, topic sentences) and just state the rule: e.g., 'Put the main clause first' instead of explaining what left-branching means.
Move the seven state definitions to a separate reference file (e.g., STATES.md) and keep only a summary table with state names, one-line symptoms, and top intervention in SKILL.md.
Compress the integration graph, context management, and output persistence sections into a single compact 'Operational Notes' section or move to a separate file — these consume ~400 tokens for metadata that rarely drives action.
| 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 are). The anti-patterns section largely restates what was already covered in the states section. The integration graph, context management, 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 specific interventions for each state, plus executable tool commands. However, the interventions are writing advice rather than executable steps — there's no concrete example of transforming a bad doc into a good one with before/after text. The tool usage examples are concrete and copy-paste ready, which helps. | 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 clear decision trees. The sequential vs parallelizable distinction and subagent candidates table add useful workflow structure. Validation is implicit in the 'triage before intervention' principle. | 3 / 3 |
Progressive Disclosure | The skill is monolithic — all seven states, anti-patterns, diagnostic process, example interactions, integration graphs, and context management are inline in a single file. The states and anti-patterns overlap significantly and could be split into a reference file. However, section headers are well-organized and the content is navigable within the single file. | 2 / 3 |
Total | 8 / 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 | |
Reviewed
Table of Contents