CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

docs-writing

Load to write, rewrite, or review repository markdown or documentation HTML: README, DEVELOPMENT, architecture docs, reference docs, SKILL.md and AGENTS.md.

Quality

73%

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/docs-writing/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

65%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 dense, disciplined instruction-only skill: it assumes the reader's competence, gives concrete per-file-type standards and decision procedures, and structures its references one level deep. Its main weaknesses are that the examples and rewrite workflow it depends on are not shipped in this bundle, breaking most of its links and leaving the core rewrite procedure external, plus minor repetition between the layout table and the per-file-type sections.

Suggestions

Ship the referenced bundle files (examples/ directory, workflows/rewrite.md) or inline the minimal rewrite steps so every link resolves; the body currently directs the reader to files that are not present.

Inline a short, explicit rewrite workflow with validation checkpoints (verify each claim, stop on unread source, owner approval for departures) rather than delegating entirely to the missing workflows/rewrite.md.

Remove the duplication between the § Layout table's reader/holds columns and the "Read by..." lines in § Per file type, honoring the skill's own rule to "State each fact once. Point at the first statement instead of repeating it."

DimensionReasoningScore

Conciseness

The body is lean and rule-per-line ("Write short sentences. Put one idea in each sentence.", "Delete sales language, quips, metaphors, and hedges.") and explains nothing Claude already knows; every contrast table teaches a rule. It falls short of anchor 5 only through minor repetition: the Layout table's reader/holds columns restate the "Read by..." lines of the § Per file type sections.

4 / 5

Actionability

Concrete, specific guidance throughout: an ordered eight-section README structure, per-type "Never:" lists, a numbered stop-at-first-yes decision tree in "One home per fact", and named tools ("decisions search", "kendex apply"). Not anchor 5 because the worked examples it directs the reader to read first ("read it before writing one", 12+ links to examples/) are absent from the bundle, so that step cannot be executed as shipped.

4 / 5

Workflow Clarity

The multi-step rewrite process is sequenced at a high level ("follows workflows/rewrite.md at the scope asked for... extracts what is unique, then writes each file in scope from a blank page") with a verification rule ("verifies each claim against its owning source", "An unread source leaves verification unresolved") and an owner-approval gate for departures. Not anchor 5 because the step-by-step procedure itself, including error-recovery checkpoints for a batch rewrite, lives in workflows/rewrite.md, which is not present in this bundle, leaving the in-body checkpoints implicit.

4 / 5

Progressive Disclosure

The link structure is well designed: one level deep, per-section, clearly signaled ("Example: [examples/readme.md](examples/readme.md)", [workflows/rewrite.md](workflows/rewrite.md), [references/assistant-home.md](references/assistant-home.md)). But scored against the actual bundle, only references/assistant-home.md exists; examples/ (12+ links), workflows/rewrite.md, and ../decider/SKILL.md are missing, so most navigation does not resolve — violating the skill's own rule that "Relative links in Markdown must resolve." Anchor 3 (structure present, but organization undermined by unresolved references) rather than 4.

3 / 5

Total

15

/

20

Passed

Description

75%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 concise, specific description that names concrete actions, the target medium, and the main file types, with usable load-trigger guidance. It falls just short of the top anchors by omitting several file types the skill covers, common synonyms like "docs"/"changelog", and an explicit "Use when..." clause.

Suggestions

Add an explicit trigger clause, e.g. "Use when writing, rewriting, or reviewing repository docs: a README, AGENTS.md, architecture or reference doc, or a changelog.", to raise completeness and trigger-term coverage.

Name the remaining governed file types (CHANGELOG/changelog.d, decision records, runbook, human architecture pages) so the description's coverage matches the skill body.

Include natural synonyms users say ("docs", "documentation", "changelog") to broaden trigger-term matching without adding length.

DimensionReasoningScore

Specificity

The description gives three concrete actions ("write, rewrite, or review") and six named file types ("README, DEVELOPMENT, architecture docs, reference docs, SKILL.md and AGENTS.md"), but omits file types the skill itself governs (CHANGELOG/changelog.d, decision records, runbook, human pages), so coverage has minor gaps. Anchor 4 (several specific actions, minor gaps) fits better than anchor 5's comprehensive coverage.

4 / 5

Completeness

The "what" is clear ("write, rewrite, or review repository markdown or documentation HTML") and the "when" is present as purpose-style trigger guidance ("Load to write, rewrite, or review..."), which functions as an explicit load condition. Not 3, because trigger guidance is explicit rather than weakly implied; not 5, because there is no dedicated "Use when the user asks to..." clause with concrete trigger phrases.

4 / 5

Trigger Term Quality

Natural terms a user would say are present ("README", "AGENTS.md", "SKILL.md", "markdown", "documentation"), giving good keyword coverage, but common synonyms such as "docs", "changelog", or "CLAUDE.md" and file extensions are missing. Anchor 4 (good coverage, a few natural terms missing) rather than 5 (comprehensive synonyms and extensions).

4 / 5

Distinctiveness Conflict Risk

A clear niche (repository markdown and documentation HTML) with distinct file-name triggers (README, AGENTS.md, SKILL.md) makes confusion unlikely. Minor overlap risk remains with generic writing or review skills triggered by the broad verb "review". Anchor 4 (mostly distinct, minor overlap) rather than 5.

4 / 5

Total

16

/

20

Passed

Validation

75%

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

Validation — 12 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

metadata_version

'metadata.version' is missing

Warning

frontmatter_unknown_keys

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

Warning

relative_links

Relative link issues: 29 missing, 1 suspicious

Warning

referenced_paths_exist

Referenced path issues: 2 missing

Warning

Total

12

/

16

Passed

Repository

vanillagreencom/kendex

Path

skills/docs-writing/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.