CtrlK
BlogDocsLog inGet started
Tessl Logo

docs-writer

Write, review, and edit documentation files with consistent structure, tone, and technical accuracy. Use when creating docs, reviewing markdown files, writing READMEs, updating `/docs` directories, or when user says "write documentation", "review this doc", "improve this README", "create a guide", or "edit markdown". Do NOT use for code comments, inline JSDoc, or API reference generation.

71

Quality

86%

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

78%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 well-structured, mostly lean instruction skill: clear stepwise workflow, concrete paths and tools, proper deferral of the style guide to a real one-level reference, and verification checkpoints. The main headroom is tightening minor padding and adding an explicit fix-and-retry loop around the verification step.

Suggestions

Trim redundant phrasing (e.g., replace "**Clarify the request:** Fully understand the user's documentation request" with a single actionable instruction like "Restate the request and identify the feature, command, or concept to document").

Add an explicit feedback loop to Step 4, e.g., "If re-reading reveals issues or links are broken, fix them and re-verify before offering to run `npm run format`".

Include one short worked example of a doc edit (before/after snippet) to make the editing sub-step copy-paste-concrete rather than directional.

DimensionReasoningScore

Conciseness

The body is lean and prescriptive — "Differentiate the task", "Check for connections", "Use `replace` and `write_file`" — with no explanations of concepts Claude already knows, matching anchor 4. It misses anchor 5 because a few items are padded or redundant (e.g., "**Clarify the request:** Fully understand the user's documentation request" restates the heading; "Always read the latest version of a file before you begin work" and the Step-1 plan/Step-4 review pairing could be tightened).

4 / 5

Actionability

Concrete, executable guidance dominates: specific paths ("`packages/` directory", "`docs/` directory", "`docs/sidebar.json`", "`references/style-guide.md`"), specific tool choices ("For small edits, `replace` is preferred. For new files or large rewrites, `write_file`"), and a copy-paste command ("`npm run format`"). As an instruction-only skill this fits anchor 4; it stops short of anchor 5 because several steps remain directional rather than executable ("Consider related documentation", "Create a clear, step-by-step plan") and no worked example of a well-formed edit is given.

4 / 5

Workflow Clarity

A clear four-step sequence (understand → investigate → write/edit → verify) with checkpoints in Step 4 ("re-read the files", "Verify the validity of all links") matches anchor 4's clear sequence with most checkpoints present. It is not 5 because there is no explicit error-recovery feedback loop (e.g., what to do when link verification fails) — validation is stated but the fix-and-retry cycle is left implicit. The batch/destructive cap does not apply since verification steps are present and doc editing is not a destructive operation.

4 / 5

Progressive Disclosure

The body is a concise workflow overview with well-organized sections, and the single bundle reference ("Adhere to the rules in `references/style-guide.md`") is clearly signaled, one level deep, and verified to exist with the bulk style detail appropriately split out (72 lines of standards). This matches anchor 5's clear overview with well-signaled one-level-deep references; nothing that belongs in a separate file is inlined.

5 / 5

Total

17

/

20

Passed

Description

95%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 strong description: concrete actions, explicit and well-phrased triggers covering both scenarios and verbatim user phrases, clear what/when answers, and an explicit negative boundary. The only minor gap is that the action verbs are somewhat generic relative to the skill's full capability set.

DimensionReasoningScore

Specificity

"Write, review, and edit documentation files" names the domain plus three concrete actions, with "with consistent structure, tone, and technical accuracy" adding quality dimensions — matching anchor 4 (several specific actions, minor gaps). It falls short of anchor 5 because the verbs are generic ("write, review, edit") rather than the fine-grained technical operations of the anchor-5 example, and it omits auxiliary actions the body actually covers (link verification, formatting).

4 / 5

Completeness

It explicitly answers what ("Write, review, and edit documentation files with consistent structure, tone, and technical accuracy") and when ("Use when creating docs, reviewing markdown files... or when user says..."), with concrete quoted trigger phrases — exactly the anchor-5 pattern. Not 4, because the 'when' clause is fully explicit rather than only partially specific.

5 / 5

Trigger Term Quality

Triggers cover scenarios ("creating docs, reviewing markdown files, writing READMEs, updating `/docs` directories") and quoted natural phrases ("write documentation", "review this doc", "improve this README", "create a guide", "edit markdown") — comprehensive coverage with synonyms and format terms, matching anchor 5; anchor 4 would require noticeably missing natural terms, which is not the case.

5 / 5

Distinctiveness Conflict Risk

A clear documentation niche with distinct triggers (READMEs, `/docs`, markdown) plus an explicit exclusion ("Do NOT use for code comments, inline JSDoc, or API reference generation") that sharply reduces overlap with code-commenting and API-doc skills — matching anchor 5's clear niche and minimal conflict risk.

5 / 5

Total

19

/

20

Passed

Validation

100%

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

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository
tech-leads-club/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.