ark-documentation
tessl i github:mckinsey/agents-at-scale-ark --skill ark-documentationGuidance 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.
Validation
69%| Criteria | Description | Result |
|---|---|---|
description_trigger_hint | Description may be missing an explicit 'when to use' trigger hint (e.g., 'Use when...') | Warning |
metadata_version | 'metadata' field is not a dictionary | Warning |
license_field | 'license' field is missing | Warning |
body_output_format | No obvious output/return/format terms detected; consider specifying expected outputs | Warning |
body_steps | No step-by-step structure detected (no ordered list); consider adding a simple workflow | Warning |
Total | 11 / 16 Passed | |
Implementation
100%This is an excellent skill document that efficiently teaches documentation structure decisions for the Ark project. It uses tables, decision trees, and clear categorization criteria to make content placement unambiguous. The writing guidelines section provides concrete, actionable style rules without over-explaining.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient, using tables and structured lists to convey information without unnecessary explanation. It assumes Claude understands documentation concepts and Diataxis framework basics, focusing only on Ark-specific adaptations. | 3 / 3 |
Actionability | Provides concrete, actionable guidance with clear decision trees, specific file paths, persona mappings, and explicit 'Content belongs here if' criteria. The decision guide flowchart and 'What not to mix' table give copy-paste-ready classification rules. | 3 / 3 |
Workflow Clarity | The decision guide provides a clear flowchart for classifying content. For a documentation structure skill (non-destructive, classification-focused), the workflow is appropriately simple with unambiguous decision points and no need for validation checkpoints. | 3 / 3 |
Progressive Disclosure | Content is well-organized with clear sections, tables for quick reference, and external links to Diataxis framework and related issues/PRs for deeper context. The structure allows quick scanning while providing detail where needed. | 3 / 3 |
Total | 12 / 12 Passed |
Activation
75%This description has good structure with explicit 'Use when' guidance and a clear niche focus on Ark documentation with Diataxis. However, it could be stronger by listing more concrete actions (e.g., 'categorize into tutorials, how-tos, reference, explanation') and including more natural trigger terms users might actually say when needing documentation help.
Suggestions
Add more specific concrete actions like 'categorize content into tutorials, how-to guides, reference, and explanation sections' to improve specificity
Include additional natural trigger terms such as 'write docs', 'readme', 'tutorials', 'reference pages', 'how-to guides' that users commonly say when needing documentation help
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (Ark documentation, Diataxis framework) and mentions some actions (creating docs, deciding content placement, reviewing PRs, restructuring), but doesn't list concrete specific actions like 'write tutorials', 'create reference pages', or 'categorize content into how-to guides'. | 2 / 3 |
Completeness | Clearly answers both what ('Guidance for structuring Ark documentation using the Diataxis framework') and when ('Use this skill when creating new docs, deciding where content belongs, reviewing documentation PRs, or restructuring existing documentation') with explicit trigger scenarios. | 3 / 3 |
Trigger Term Quality | Includes relevant terms like 'docs', 'documentation', 'PRs', and 'Diataxis', but misses common variations users might say such as 'readme', 'write docs', 'documentation structure', 'tutorials vs how-tos', or 'reference docs'. | 2 / 3 |
Distinctiveness Conflict Risk | The combination of 'Ark documentation' and 'Diataxis framework' creates a clear niche that is unlikely to conflict with general documentation or coding skills. The specific context makes it highly distinguishable. | 3 / 3 |
Total | 10 / 12 Passed |
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.