CtrlK
BlogDocsLog inGet started
Tessl Logo

documentation-strategy

Design and run a documentation system for a team or product. Use this skill when planning what to document, choosing a documentation tool, organizing existing docs, fixing stale documentation, designing a maintenance cadence, or scoping technical writing work. Triggers on documentation, docs, tech writing, knowledge base, wiki, runbook, README, internal docs, doc audit, doc maintenance, stale docs, where do we document. Also triggers when the team is repeatedly answering the same questions or when onboarding takes too long.

63

Quality

75%

Does it follow best practices?

Impact

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/documentation-strategy/SKILL.md
SKILL.md
Quality
Evals
Security

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 clearly defines its scope (documentation system design and maintenance), lists concrete actions, and provides comprehensive trigger terms including both keyword-based and situational triggers. It follows best practices by using third person voice, including an explicit 'Use this skill when...' clause, and covering natural language variations users would actually say.

DimensionReasoningScore

Specificity

Lists multiple specific concrete actions: planning what to document, choosing a documentation tool, organizing existing docs, fixing stale documentation, designing a maintenance cadence, and scoping technical writing work.

3 / 3

Completeness

Clearly answers both 'what' (design and run a documentation system, with six specific sub-tasks) and 'when' (explicit 'Use this skill when...' clause plus a detailed 'Triggers on' list with natural keywords and situational triggers).

3 / 3

Trigger Term Quality

Excellent coverage of natural terms users would say: documentation, docs, tech writing, knowledge base, wiki, runbook, README, internal docs, doc audit, doc maintenance, stale docs, 'where do we document'. Also includes situational triggers like repeated questions and slow onboarding.

3 / 3

Distinctiveness Conflict Risk

Occupies a clear niche around documentation systems and strategy. The specific triggers like 'doc audit', 'runbook', 'stale docs', and 'maintenance cadence' make it highly distinguishable from general writing or coding skills.

3 / 3

Total

12

/

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 comprehensive documentation strategy skill that covers the topic thoroughly with a clear framework (Diátaxis + tiering) and a logical 10-step workflow. Its main weaknesses are verbosity (could be 40% shorter without losing value), lack of executable artifacts (templates, checklists, scripts), and missing validation checkpoints in the workflow. The content reads more like a knowledge article than an actionable skill for Claude to execute.

Suggestions

Add a concrete, copy-paste-ready documentation strategy template (markdown) in the output format section so Claude can fill it in directly rather than interpreting a bullet list of what to include.

Compress the failure patterns section into a two-column table (pattern | fix) to cut ~50% of that section's tokens while preserving all the information.

Add explicit validation checkpoints in the workflow, especially after Step 4 (confirm deletions with stakeholders before archiving) and after Step 6 (verify every doc has an owner assigned).

Move the detailed Diátaxis framework descriptions, tooling comparison, and specific patterns (ADR, runbook, etc.) into separate reference files to reduce the main skill's length and improve progressive disclosure.

DimensionReasoningScore

Conciseness

The skill is quite long (~400 lines) and includes some content Claude would already know (e.g., explaining what ADRs are, what READMEs should contain, basic descriptions of wiki tools). The Diátaxis framework explanation is useful but could be more compressed. The failure patterns section, while valuable, is verbose—many points could be condensed into a table. However, most content does earn its place as domain-specific guidance.

2 / 3

Actionability

The skill provides a clear 10-step workflow and specific patterns (ADR template, README checklist, runbook structure), which are concrete. However, it's primarily descriptive/advisory rather than executable—there are no commands, scripts, or copy-paste-ready artifacts. The output format section tells you what to include but doesn't provide a template. The ADR template is the most actionable element.

2 / 3

Workflow Clarity

The 10-step workflow is clearly sequenced and logically ordered (audit → categorize → gaps → dead weight → tooling → ownership → cadence → integration → discovery → measure). However, there are no explicit validation checkpoints or feedback loops between steps. For a strategy that involves destructive actions like deleting/archiving docs (Step 4), there's no verification step to confirm the right docs are being removed.

2 / 3

Progressive Disclosure

The skill references external skills (team-onboarding-playbook, incident-response, backup-and-disaster-recovery, content-and-copy, etc.) and one bundle file (references/doc-types-guide.md), which is good structure. However, the main file is very long and monolithic—the tooling comparison, failure patterns, and specific patterns sections could be split into reference files. The bundle file referenced doesn't actually exist in the provided bundle.

2 / 3

Total

8

/

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.

Validation10 / 11 Passed

Validation for skill structure

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

10

/

11

Passed

Repository
rampstackco/claude-skills
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.