CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

docs

Authors, audits, and maintains project docs — CLAUDE.md / .claude/rules/, AGENTS.md, README.md, and Diátaxis docs/ trees — in modes init, update, readme, and audit. Triggers on "init claude", "update docs", "docs drift", "write a README", "/docs".

Quality

75%

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

Fix and improve this skill with Tessl

tessl review fix ./skills/authoring/docs/SKILL.md
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 is a well-organized, prescriptive thin index with clear mode routing, sequenced phases, and validation gates — genuinely strong instructional design. Its critical defect is that the entire detail layer it indexes into (rules/ and templates/) is absent from the bundle, so most references dangle and the executable substance is unreachable, while the only other bundled reference is orphaned.

Suggestions

Ship the referenced detail layer: add the 11 missing files under rules/ (content-routing, placement-resolver, writing-style, claude-md, drift-detection, readme, docs-folder, maintenance, auto-update-loop) and templates/ (claude-md.md, readme.md), or inline the per-mode essentials into SKILL.md so the thin-index design actually resolves.

Inline the minimal executable specifics currently deferred to missing files — e.g., the git diff commands for change detection, the drift-check list, and the README audit rubric items — so update/audit runs are actionable from the body alone.

Reference references/research-sources.md from the body (it is currently an orphan) and state the CLAUDE.md ≤ 200-line threshold once instead of three times across hard rules, the Definition of Done, and anti-patterns.

DimensionReasoningScore

Conciseness

The body is a lean thin-index — mode-routing tables, phase lists, and one-liner anti-patterns with a prescriptive-not-descriptive principle, assuming Claude's competence. Minor trimmable padding remains: the "CLAUDE.md ≤ 200 lines / Anthropic's own threshold" rationale is repeated in the init hard rules, the init checklist, and the anti-patterns list, and the AGENTS.md intro explains a spec Claude largely knows. Not 5 because of that duplication; not 3 because the body is otherwise efficient.

4 / 5

Actionability

The body gives concrete decision tables (mode detection, disambiguation, argument parsing) but defers all executable specifics to files that do not exist in the bundle — "see rules/drift-detection.md §1 for git diff commands", "Run the README audit rubric in rules/readme.md §4", "Use templates/claude-md.md" — so no actual command, rubric, or template is reachable. Structurally it matches the 4 anchor's shape, but with the target files missing the guidance never resolves to executable steps, leaving it at the 3 anchor's incomplete-guidance level.

3 / 5

Workflow Clarity

Each mode has a numbered phase sequence with explicit gates: an overwrite confirmation (AskUserQuestion: Overwrite/Merge/Skip-Abort) during init, a dry-run option for update, and per-mode Definition-of-Done checklists ("Treat any unchecked item as a defect") plus P0/P1/P2 priority tiers. Not 5 because several checkpoints delegate their actual procedure to missing rule files (e.g., drift §1 diff commands, readme §4 audit rubric); comfortably above the 3 anchor since checkpoints themselves are explicit.

4 / 5

Progressive Disclosure

The design is the ideal thin-index pattern — one-level-deep, well-signaled references with per-mode loading tables — but scored against the actual bundle, 11 of the 12 referenced paths (all of rules/*.md and templates/*.md) do not exist; only references/archetypes.md ships, and references/research-sources.md is an orphan never cited in the body. Navigation is therefore non-functional as delivered, which drops it below the 3 anchor despite the good on-page structure.

2 / 5

Total

13

/

20

Passed

Description

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

The description is a strong third-person statement that explicitly covers what (four modes over five named doc surfaces) and when (five concrete trigger phrases). Its only weaknesses are generic action verbs and a few missing natural trigger variations like "documentation" or "sync docs".

DimensionReasoningScore

Specificity

"Authors, audits, and maintains project docs — CLAUDE.md / .claude/rules/, AGENTS.md, README.md, and Diátaxis docs/ trees — in modes init, update, readme, and audit" names several concrete surfaces and four distinct modes. It falls short of the 5 anchor because the actions themselves are three generic verbs — the operational detail per mode is not stated.

4 / 5

Completeness

Clearly answers both what ("Authors, audits, and maintains project docs" with enumerated surfaces and modes) and when ("Triggers on 'init claude', 'update docs', 'docs drift', 'write a README', '/docs'"), which is an explicit trigger clause with concrete phrases matching the 5 anchor. It is not the 4 anchor because the 'when' is fully explicit rather than improvable.

5 / 5

Trigger Term Quality

Triggers on "init claude", "update docs", "docs drift", "write a README", "/docs" — good natural-phrase coverage including the command form. Missing common variations like "documentation", "sync docs", "refresh docs", or "audit the documentation", so it does not reach the comprehensive-synonym level of the 5 anchor.

4 / 5

Distinctiveness Conflict Risk

The docs-tooling niche (CLAUDE.md/.claude/rules/ maintenance, README authoring, drift audits) with triggers like "docs drift" and "write a README" is mostly distinct with only minor overlap risk against generic documentation or bootstrap skills. Not 5 because "init claude" and "update docs" could still collide with other setup/doc-sync skills.

4 / 5

Total

17

/

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

Path

skills/authoring/docs/SKILL.md

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.