ark-documentation
Guidance for structuring Ark documentation using the Diataxis framework. Use this skill when creating new docs, deciding where content belongs, reviewing documentation PRs, or restructuring existing documentation.
74
62%
Does it follow best practices?
Impact
93%
1.17xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.claude/skills/documentation/SKILL.mdQuality
Discovery
75%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 is well-structured with a clear 'what' and 'when' clause, and targets a distinct niche (Ark + Diataxis). Its main weakness is that the 'what' portion is somewhat vague—'guidance for structuring' doesn't convey the specific actions or outputs the skill provides. Adding more concrete capabilities and natural trigger terms would strengthen it.
Suggestions
Replace the vague 'Guidance for structuring' with specific actions like 'Categorizes content into tutorials, how-to guides, reference, and explanation pages according to the Diataxis framework'
Add more natural trigger terms users might use, such as 'doc structure', 'where should this doc go', 'tutorials vs how-to guides', 'documentation organization'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (Ark documentation, Diataxis framework) and some actions (creating docs, deciding content placement, reviewing PRs, restructuring), but the actions are somewhat general and lack concrete specifics about what the skill actually does beyond 'guidance for structuring.' | 2 / 3 |
Completeness | Clearly answers both 'what' (guidance for structuring Ark documentation using Diataxis framework) and 'when' (creating new docs, deciding where content belongs, reviewing documentation PRs, restructuring existing documentation) with explicit trigger scenarios. | 3 / 3 |
Trigger Term Quality | Includes relevant terms like 'docs', 'documentation', 'PRs', 'Diataxis', and 'Ark', but misses natural variations users might say such as 'where should this doc go', 'doc structure', 'tutorials vs how-to guides', or 'documentation organization.' | 2 / 3 |
Distinctiveness Conflict Risk | The combination of 'Ark' (specific project), 'Diataxis framework' (specific methodology), and documentation structuring creates a clear niche that is unlikely to conflict with other skills. | 3 / 3 |
Total | 10 / 12 Passed |
Implementation
50%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-organized documentation framework guide with good classification criteria and a useful decision tree. Its main weaknesses are the lack of concrete step-by-step workflows for the stated use cases (creating docs, reviewing PRs, restructuring) and some verbosity in areas Claude would already understand (general writing style conventions). The skill would benefit from being more prescriptive about the actual process of applying the framework rather than primarily describing the framework itself.
Suggestions
Add explicit step-by-step workflows for each stated use case (e.g., 'When creating new documentation: 1. Use the decision guide to classify content type, 2. Check the persona table to identify the audience, 3. Place the file in the correct directory, 4. Update the relevant hub page').
Move the general writing guidelines (style, bullets, capitalization, headings, links) to a separate WRITING_STYLE.md file and reference it, keeping only ARK-specific conventions (like 'ARK' not 'Ark') in the main skill.
Add a concrete before/after example showing how to classify a piece of ambiguous content using the decision guide, demonstrating the framework in action.
Trim standard technical writing advice that Claude already knows (active voice, US English, Oxford commas) and focus on ARK-specific conventions and the Diataxis classification logic.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient and well-structured, but includes some content Claude would already know (e.g., general Diataxis framework descriptions, basic writing style advice like 'use active voice'). The writing guidelines section could be tightened since much of it is standard technical writing advice. | 2 / 3 |
Actionability | The decision guide and 'content belongs here if' checklists provide concrete guidance for classification decisions. However, the skill is primarily descriptive rather than instructive—it lacks concrete examples of applying the framework (e.g., 'given this draft content, here's how to classify and place it') and has no executable commands or file manipulation steps. | 2 / 3 |
Workflow Clarity | The decision tree flowchart provides a clear classification sequence, and the quadrant descriptions give good criteria. However, there's no explicit workflow for the stated use cases (creating new docs, reviewing PRs, restructuring). A step-by-step process like 'when reviewing a PR: 1. identify the content type using the decision guide, 2. verify it's in the correct section, 3. check for content mixing' is missing. | 2 / 3 |
Progressive Disclosure | The content is well-organized with clear sections and tables, but it's a fairly long monolithic document (~180 lines) that could benefit from splitting detailed writing guidelines into a separate file. The references at the bottom link externally but there's no internal file structure for deeper content. | 2 / 3 |
Total | 8 / 12 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 — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- mckinsey/agents-at-scale-ark
- Commit
fc5746e
- 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.