mcollina/documentation
Creates, structures, and reviews technical documentation following the Diátaxis framework (tutorials, how-to guides, reference, and explanation pages). Use when a user needs to write or reorganize docs, structure a tutorial vs. a how-to guide, build reference docs or API documentation, create explanation pages, choose between Diátaxis documentation types, or improve existing documentation structure. Trigger terms include: documentation structure, Diátaxis, tutorials vs how-to guides, organize docs, user guide, reference docs, technical writing.
91
87%
Does it follow best practices?
Impact
96%
1.11xAverage score across 5 eval scenarios
Passed
No known issues
Quality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is an excellent skill description that hits all the key criteria. It provides specific concrete actions, includes a comprehensive 'Use when...' clause with diverse trigger scenarios, and explicitly lists trigger terms. The Diátaxis framework focus gives it a clear, distinctive niche that minimizes conflict risk with other documentation or writing skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'Creates, structures, and reviews technical documentation', names the Diátaxis framework explicitly, and enumerates the four documentation types (tutorials, how-to guides, reference, explanation pages). | 3 / 3 |
Completeness | Clearly answers both 'what' (creates, structures, reviews technical documentation following Diátaxis framework) and 'when' (explicit 'Use when...' clause with multiple specific trigger scenarios, plus an explicit list of trigger terms). | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural terms users would say: 'documentation structure', 'Diátaxis', 'tutorials vs how-to guides', 'organize docs', 'user guide', 'reference docs', 'technical writing', 'API documentation'. These are terms users would naturally use when seeking this kind of help. | 3 / 3 |
Distinctiveness Conflict Risk | The Diátaxis framework focus and the specific documentation type distinctions (tutorials vs how-to guides, reference, explanation) create a clear niche that is unlikely to conflict with generic writing or coding skills. The framework name itself is a strong distinctive anchor. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
62%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured skill that clearly teaches the Diátaxis framework with a logical four-step workflow and useful decision aids. Its main weaknesses are moderate verbosity (some redundancy between the decision table and decision tree, and explanatory framing Claude doesn't need) and a lack of complete, copy-paste-ready document templates that would make it more immediately actionable. The validation checklist in Step 4 is a strong feature.
Suggestions
Replace the example intros with complete document skeleton templates (full markdown structure with placeholder content) for each documentation type, making the skill more immediately actionable.
Remove the 'When to use' section or reduce it to a single line — the YAML frontmatter description already covers this, and Claude can infer applicability from the instructions themselves.
Consolidate the decision checklist table and the quick decision tree into a single decision aid to reduce redundancy.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill includes some unnecessary framing (e.g., 'When to use' section largely restates what Claude would infer from context). The decision table and type-specific patterns are useful but could be tighter — example intros are helpful but add length. Some redundancy between the decision checklist and the quick decision tree. | 2 / 3 |
Actionability | The skill provides structured guidance with clear patterns, title conventions, and example intros, but it's fundamentally an instruction-only skill about writing documentation — there are no executable code examples or copy-paste templates. The 'example intro' snippets are illustrative but not complete enough to serve as full templates. The guidance is concrete but stops short of providing ready-to-use document skeletons. | 2 / 3 |
Workflow Clarity | The four-step workflow is clearly sequenced: identify type → apply patterns → maintain separation → validate. Each step has explicit criteria, and Step 4 provides a validation checklist per documentation type. The decision table in Step 1 provides a clear routing mechanism. For a non-destructive documentation task, this level of workflow clarity is appropriate and complete. | 3 / 3 |
Progressive Disclosure | All content is inline in a single file with no bundle files or external references. While the content is well-organized with clear headings, the type-specific patterns section is lengthy and could benefit from being split into separate reference files (e.g., TUTORIAL_PATTERN.md, REFERENCE_PATTERN.md). For a skill of this length (~100 lines of substantive content), keeping everything inline is borderline acceptable but not ideal. | 2 / 3 |
Total | 9 / 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_version | 'metadata.version' is missing | Warning |
Total | 10 / 11 Passed | |
Reviewed
Table of Contents