CtrlK
BlogDocsLog inGet started
Tessl Logo

docs

Authors, audits, and maintains project documentation across CLAUDE.md / .claude/rules/, AGENTS.md, README.md, and Diátaxis docs/ trees (root + nested for monorepos). Four modes: init scaffolds a tiered docs setup from scratch; update detects drift (dead @imports, renamed commands, stale narrative) and incrementally refreshes via a Placement Resolver that pushes rules to the innermost-ancestor destination; readme writes or audits a README against the standard-readme spec; audit produces a documentation health report across every surface. Routes by kind: hard rules to CLAUDE.md, path-scoped patterns to .claude/rules/, narrative to docs/, marketing to README.md. Triggers on "init claude", "bootstrap docs", "scaffold CLAUDE.md", "update docs", "sync CLAUDE.md", "docs drift", "write a README", "audit our docs", "review the README", "Diátaxis", "/docs".

65

Quality

82%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

60%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.

The SKILL.md body is well-designed as a thin, mode-routed index with lean tables, explicit gates, and per-mode completion checklists, and its workflow sequencing is solid. However, its entire progressive-disclosure promise is unfulfilled in this bundle: the rules/ and templates/ files it instructs Claude to load do not exist, leaving most mode detail inaccessible and one bundled reference (research-sources.md) orphaned.

Suggestions

Ship the rules/ and templates/ files the body depends on (content-routing.md, placement-resolver.md, drift-detection.md, claude-md.md, readme.md, docs-folder.md, writing-style.md, maintenance.md, auto-update-loop.md, and the templates) — or inline the essential rules into SKILL.md if the bundle is meant to be single-file.

Link references/research-sources.md from the body (e.g., from Core Principles or a Sources section) so the one extra bundled file is discoverable and its role is stated, matching how archetypes.md is referenced.

Deduplicate the init hard rules from the Definition of Done checklists (and the mode table from the disambiguation list) so each rule appears once, trimming the body's token cost without losing the closing gates.

DimensionReasoningScore

Conciseness

Largely lean and prescriptive — mode-routing tables, argument tables, numbered phases, and one-liner anti-patterns rather than concept tutorials — but there is duplication: the init hard rules reappear in the Definition of Done checklists, the mode table plus the disambiguation list state the routing twice, and Core Principles restate routing rationale already given in mode sections. Not 5: these repeated blocks are tokens that could be trimmed; not 3: the padding is minor and the tone consistently assumes Claude's competence (e.g., no explanation of what git or markdown is).

4 / 5

Actionability

Some concrete guidance exists in-body — "CLAUDE.md ≤ 200 lines", "ln -s CLAUDE.md AGENTS.md", badge-count limits, AskUserQuestion options, dry-run flag, P0/P1/P2 tiers — but the executable meat of every mode is deferred to files that are not in the bundle: "see rules/drift-detection.md §1 for git diff commands", the Content Routing Rubric, the Placement Resolver algorithm, the mandatory README section order, and all templates/*.md skeletons are all missing. Not 4: the gaps are not minor — a run of any mode would stall at the first "load rules/X.md" instruction; not 2: the body still delivers specific routing, budgets, and gates that can be acted on alone.

3 / 5

Workflow Clarity

Each mode has a numbered phase sequence with checkpoints: init gates on AskUserQuestion before overwriting, update offers dry-run and asks confirmation for P1 items, audit is declared read-only, and every mode closes with a Definition of Done checklist ("Treat any unchecked item as a defect") including verification items like "Every @import added resolves to a real file" and "Every relative link resolves". Not 5: several checkpoints are implicit or underspecified in-body (drift-detection commands, README rubric scoring procedure) because the detail lives in absent rule files; not 3: explicit checklists and confirmation gates are present for the batch-write update flow, so the destructive/batch cap does not apply.

4 / 5

Progressive Disclosure

Scored against the actual bundle: the body declares itself "a thin index" pointing to rules/*.md (9 referenced files) and templates/*.md, but neither directory exists — only references/archetypes.md is present, so ~10 of 11 referenced paths are broken, and references/research-sources.md exists yet is never linked from the body. Not 3: the in-body structure and reference signaling are excellent on paper, but navigation to any detailed material is dead, and one bundled file is undiscoverable; not 1: the body itself is well-sectioned and contains substantial standalone guidance rather than being unnavigable.

2 / 5

Total

13

/

20

Passed

Description

100%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 model description: third-person voice, concrete per-mode actions, explicit routing semantics, and an enumerated trigger list covering natural phrasings and the slash-command form. It clearly answers both what the skill does and when to invoke it with essentially no fluff.

DimensionReasoningScore

Specificity

Multiple specific concrete actions per mode: "init scaffolds a tiered docs setup", "update detects drift (dead @imports, renamed commands, stale narrative) and incrementally refreshes via a Placement Resolver", "readme writes or audits a README against the standard-readme spec", "audit produces a documentation health report" — comprehensive coverage across all four modes with named targets. Not 4: no meaningful gap in action coverage; every mode's capability is stated concretely rather than generically.

5 / 5

Completeness

Explicitly answers both questions: what ("Authors, audits, and maintains project documentation across CLAUDE.md / .claude/rules/, AGENTS.md, README.md, and Diátaxis docs/ trees", plus per-mode capabilities and routing rules) and when ("Triggers on 'init claude', 'bootstrap docs', …"). Not 4: the 'when' is not merely present but enumerated with concrete trigger phrases, matching the anchor-5 example pattern exactly.

5 / 5

Trigger Term Quality

Comprehensive natural trigger phrases with synonym variations: "init claude", "bootstrap docs", "scaffold CLAUDE.md", "update docs", "sync CLAUDE.md", "docs drift", "write a README", "audit our docs", "review the README", "Diátaxis", "/docs". Not 4: coverage includes both verb-form and noun-form phrasings users would naturally say, plus the slash-command form; nothing obvious is missing.

5 / 5

Distinctiveness Conflict Risk

Clear niche — agent-facing docs architecture (CLAUDE.md tiering, .claude/rules/ placement, Diátaxis docs trees) — with distinctive triggers like "sync CLAUDE.md", "scaffold CLAUDE.md", and "Diátaxis" that no generic documentation or README skill would claim. Not 4: overlap risk is minimal; even the broadest trigger ("write a README") is disambiguated by the surrounding spec-based readme mode context.

5 / 5

Total

20

/

20

Passed

Validation

81%

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

Validation — 13 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

metadata_field

'metadata' should map string keys to string values

Warning

frontmatter_unknown_keys

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

Warning

relative_links

Relative link issues: 29 missing

Warning

Total

13

/

16

Passed

Repository
mthines/agent-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.