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.

1.32x

Quality

81%

Does it follow best practices?

Impact

97%

1.32x

Average score across 2 eval scenarios

Securityby

Passed

No findings from the security scan

Quality

Content

75%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A thorough, well-structured instruction-only skill with concrete placement criteria, a decision tree, and explicit verification guidance. It is slightly verbose in places and could offload detailed templates to reference files for better progressive disclosure.

Suggestions

Move the detailed reference-page structure template and the full writing-guidelines section into separate reference files (e.g. reference-page-template.md, writing-guidelines.md), keeping SKILL.md as a concise overview that links to them.

Remove the redundant opening line 'Guidance for structuring Ark documentation using Diataxis adapted for Ark's needs.' since it restates the frontmatter description.

Tighten the 'What not to mix' table or fold it into the quadrant sections to avoid repeating guidance already conveyed above.

Dimension	Reasoning	Score
Conciseness	Mostly lean, using tables, bullets, and a decision tree efficiently and assuming competence; minor redundancy such as the repeated intro line and the 'What not to mix' table restating quadrant guidance keeps it just below a 5.	4 / 5
Actionability	Provides concrete executable guidance — directory layout, 'Content belongs here if' criteria, writing rules, and a numbered reference-page template — with only minor gaps for an instruction-only skill.	4 / 5
Workflow Clarity	Clear numbered sequences (reference-page template, build-and-preview) with validation checkpoints ('Never push a docs change without a clean build', 'verify against the source'); a few checkpoints are implicit rather than framed as feedback loops.	4 / 5
Progressive Disclosure	Well-organized single-file structure with clear sections and no nested references, but at over 250 lines with no bundle files, portions like the reference-page template and writing guidelines could be split into one-level-deep reference files.	4 / 5
	Total	16 / 20 Passed

Description

87%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A well-crafted description that concisely states both purpose and concrete trigger conditions with a clearly distinct niche. Minor keyword synonym coverage is the only weakness.

Dimension	Reasoning	Score
Specificity	Names the domain ('Ark documentation', 'Diataxis framework') and several concrete actions — structuring, deciding where content belongs, reviewing PRs, restructuring — with only minor coverage gaps, fitting the 'lists several specific actions' anchor.	4 / 5
Completeness	Explicitly states 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 concrete trigger phrases.	5 / 5
Trigger Term Quality	Includes natural phrases users would say ('creating new docs', 'reviewing documentation PRs', 'restructuring existing documentation') with good coverage, though a few common synonyms are missing.	4 / 5
Distinctiveness Conflict Risk	Targets a clear niche — structuring Ark-specific documentation via Diataxis — with distinct triggers and minimal overlap risk with other skills.	5 / 5
	Total	18 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 2 missing	Warning

	Total	15 / 16 Passed

Repository: mckinsey/agents-at-scale-ark
Path: .claude/skills/documentation/SKILL.md
Commit: 26d4d0b

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

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.