CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

95

1.17x
Quality

Does it follow best practices?

Impact

93%

1.17x

Average score across 3 eval scenarios

SecuritybySnyk

Passed

No known issues

SKILL.md
Quality
Evals
Security

Quality

Content

92%

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

A dense, well-structured guidance skill that is lean and highly actionable for an instruction-only context. Its main weakness is progressive disclosure: everything lives in one large file with no reference files to offload the detailed style and quadrant material.

Suggestions

Split the detailed 'Writing guidelines' section (Lexicon, General style, Bullets, Capitalization, Headings, Instructions, Links, Avoid) into a separate reference file (e.g. references/writing-style.md) and summarize it in SKILL.md with a one-level-deep link.

Consider moving the per-quadrant detail into references/ (e.g. quadrants.md) and keeping only the decision guide, terminology table, and 'Content belongs here if' summaries in SKILL.md as a true overview.

Remove the minor duplications (ARK-vs-Ark capitalization in both Lexicon and General style; gerund guidance in both Headings and Avoid) to tighten the remaining inline content.

DimensionReasoningScore

Conciseness

The body is lean and bullet-driven with no padding of concepts Claude already knows (no 'what a tutorial is' exposition), assuming competence; minor duplication (ARK capitalization and gerund rules each appear twice) is not enough to drop it to the 'could be tightened' anchor at 2.

3 / 3

Actionability

Despite being instruction-only with no code, the guidance is concrete and specific — 'Use active voice: Creates agent not Agent is created', explicit hub-page filenames (tutorials.mdx, how-to-guides.mdx), and per-quadrant 'Content belongs here if' criteria — meeting the actionable bar for instruction skills.

3 / 3

Workflow Clarity

The ASCII decision guide gives an unambiguous classification sequence, and the 'Content belongs here if' criteria plus the 'What not to mix' table act as verification checkpoints for correct placement; this is clearer than the listed-but-checkpoint-missing anchor at 2.

3 / 3

Progressive Disclosure

Sections are well-organized, but the 225-line file is monolithic with no bundle files or one-level-deep references — the detailed writing guidelines and full quadrant specs are inline content that could be split out, matching the 'could be better organized / content that should be separate is inline' anchor rather than the split-with-refs anchor at 3.

2 / 3

Total

11

/

12

Passed

Description

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.

A well-crafted description that concisely states the skill's purpose and provides explicit, natural trigger conditions in third-person voice. It clearly answers both what the skill does and when to use it.

DimensionReasoningScore

Specificity

The description lists several concrete actions — 'creating new docs, deciding where content belongs, reviewing documentation PRs, or restructuring existing documentation' — matching the multiple-specific-actions anchor rather than the single-domain anchor at 2.

3 / 3

Completeness

It states what the skill does ('Guidance for structuring Ark documentation using the Diataxis framework') and gives an explicit 'Use this skill when...' trigger clause, satisfying both what and when; not capped at 2 since the trigger guidance is explicit.

3 / 3

Trigger Term Quality

Triggers use natural phrasing a user would actually say ('creating new docs', 'reviewing documentation PRs', 'restructuring existing documentation'), giving good coverage rather than the partial-keyword anchor at 2.

3 / 3

Distinctiveness Conflict Risk

The Diataxis-framework + Ark-specific niche with distinct documentation triggers makes it unlikely to fire for unrelated skills; it is more distinct than the 'somewhat specific but could overlap' anchor at 2.

3 / 3

Total

12

/

12

Passed

Validation

93%

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

Validation15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

relative_links

Relative link issues: 2 missing

Warning

Total

15

/

16

Passed

Repository
mckinsey/agents-at-scale-ark
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.