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.
89
89%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
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 marks. It provides specific concrete actions, comprehensive trigger terms that users would naturally use, explicit 'Use when' guidance with multiple scenarios, and a distinctive niche centered on the Diátaxis framework. The description is well-structured, concise, and uses proper third-person voice throughout.
| 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, and explanation pages). | 3 / 3 |
Completeness | Clearly answers both 'what' (creates, structures, and reviews technical documentation following Diátaxis) 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 help with documentation. | 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. The explicit framework name and documentation-structure focus make it unlikely to conflict with general writing or coding skills. | 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 instructional skill with a clear four-step workflow and useful decision aids (tables, decision trees, validation checklists). Its main weaknesses are moderate verbosity — some content explains concepts Claude already understands about documentation types — and a lack of truly executable/template-ready artifacts. The inline treatment of all four documentation types makes the skill longer than necessary for the SKILL.md level.
Suggestions
Replace the example intros with complete, copy-paste-ready document templates (e.g., a full tutorial skeleton with placeholder sections) to improve actionability.
Move the detailed type-specific patterns (tutorials, how-to guides, reference, explanations) into a separate DIATAXIS_TYPES.md file and link to it, keeping SKILL.md as a concise overview with the decision tree and validation table.
Remove the 'When to use' section since it duplicates the frontmatter description, and trim explanatory text that restates well-known Diátaxis concepts (e.g., 'each serving different user needs and contexts').
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill contains some unnecessary framing (e.g., 'When to use' section repeats what the frontmatter description already covers, and some explanations of the Diátaxis framework are things Claude already knows). However, the tables and decision trees are reasonably efficient. The example intros add value but also add length. | 2 / 3 |
Actionability | The skill provides structured guidance with decision tables, title patterns, and example intros, which are concrete and useful. However, it lacks executable code or copy-paste-ready templates — the examples are illustrative prose snippets rather than complete, usable documentation templates. The guidance is more descriptive ('structure it this way') than prescriptive with ready-to-use artifacts. | 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 tree in Step 1 is a clear checkpoint before proceeding. | 3 / 3 |
Progressive Disclosure | The content is well-structured with clear headings and sections, but it's entirely monolithic — all four documentation type patterns are fully inline rather than being split into separate reference files. For a skill of this length (~100 lines of substantive content), the type-specific patterns could be referenced out to keep the main skill leaner. | 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