CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

docs-writing

Load when creating or editing any Markdown file or documentation HTML, such as README, DEVELOPMENT, architecture docs, reference docs, SKILL.md and AGENTS.md, and when rewriting or reviewing one.

Quality

72%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/docs-writing/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

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

An exceptionally disciplined instruction-only skill: terse rule-dense prose, concrete routing tables, named checkers, and explicit validation checkpoints. Its main weaknesses are the large set of referenced files (examples/, workflows/rewrite.md) missing from the bundle — which breaks both navigation and the 'read the example' steps — and a few opaque jargon-heavy passages in the project-instructions block.

Suggestions

Ship the examples/ files and workflows/rewrite.md referenced by the per-file-type route table and § Writing, or remove/inline those links, so every navigation target resolves within the bundle.

Restate the rewrite workflow's core validation steps (extract what is unique, write each file from a blank page, verify claims against owning sources) in the body so the batch process has visible checkpoints even without the workflow file.

Tighten the kendex project-instructions block at the top of the body — its refresh-owner sentences are convoluted and only loosely related to the documentation-writing core.

DimensionReasoningScore

Conciseness

The body is dense, rule-per-sentence prose that assumes Claude's competence (no explanation of what Markdown or docs are) and pairs each standard with a compact before/after table — efficient with only minor trims needed. It falls short of anchor 5 because the kendex project-instructions block ("After an authorized documentation rewrite changes kendex-owned inputs, use the repository refresh and verification route...") and several baroque compound sentences in § Writing require re-reading and could be tightened.

4 / 5

Actionability

Concrete, executable guidance throughout: a first-match-wins routing table ("The first row whose path matches wins; `*` matches across `/`"), exact path tables, a before/after rewrite table, and named commands and checkers ("kendex report", "decisions search", "md-reflow --check", "the doc-limits check"). Not anchor 5 because key steps route to files absent from the bundle — "read its section and its example" and "follows workflows/rewrite.md" cannot be executed as shipped.

4 / 5

Workflow Clarity

Multi-step processes are clearly sequenced (find the file type in the table, then read its section and example; the one-home-per-fact ordered questions with "stop at the first yes") with explicit validation checkpoints ("verifies each claim against its owning source", "An unread source leaves verification unresolved", checkers named per rule). Not anchor 5 because the batch rewrite workflow's own validation steps are delegated entirely to a workflows/rewrite.md file that is not in the bundle.

4 / 5

Progressive Disclosure

The body is a genuine overview with well-signaled, one-level-deep references, and all 8 references/*.md files exist with real content; however, the 13 example files in the route table's Example column, workflows/rewrite.md, and ../decider/SKILL.md are referenced but absent from the bundle, so a large share of navigation targets do not resolve. That is more than the 'minor organization gaps' of anchor 4, while the structure that does exist is far better organized than anchor 3's inline-bulk example.

3 / 5

Total

15

/

20

Passed

Description

62%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 trigger-focused description with strong, natural when-terms and named documentation artifacts, but it omits any statement of what the skill provides (a writing standard, repository layout, and per-file-type guidance). Adding a one-clause capability statement before the trigger clause would lift both completeness and specificity to the top anchors.

Suggestions

Open with a what-clause, e.g., "Applies a repository documentation standard: writing rules, file layout, and per-file-type guidance" before the existing "Load when..." trigger clause.

Add common natural terms users say — "docs", "documentation", "CHANGELOG", "CONTRIBUTING" — to the trigger list to widen keyword coverage.

Narrow "any Markdown file" toward the skill's actual niche (repository design documentation) to reduce overlap with README/AGENTS generator and code-review skills.

DimensionReasoningScore

Specificity

Names several concrete actions ("creating or editing", "rewriting or reviewing") and specific artifact types ("README, DEVELOPMENT, architecture docs, reference docs, SKILL.md and AGENTS.md", "documentation HTML"), matching the 'several specific actions; minor gaps' anchor. Not 5 because it never states what the skill actually does to those files (apply a writing standard, layout, examples), leaving capability coverage incomplete.

4 / 5

Completeness

The 'when' is fully explicit ("Load when creating or editing any Markdown file ... and when rewriting or reviewing one") but the 'what' — what the skill does — is never stated, only weakly implied by the trigger activities. This is the inverse of anchor 3 (clear what, weak when); it sits above anchor 2's bare 'only when, no what' because the trigger specification is detailed and names the domain's artifacts.

3 / 5

Trigger Term Quality

Good natural keyword coverage — "Markdown", "README", "DEVELOPMENT", "architecture docs", "SKILL.md", "AGENTS.md", "rewriting", "reviewing" are terms users would naturally say. A few natural terms are missing ("docs", "documentation" unqualified, "CHANGELOG", "CONTRIBUTING", ".md"), so it falls short of the comprehensive-with-synonyms anchor 5.

4 / 5

Distinctiveness Conflict Risk

"any Markdown file" is broad and would overlap with doc-adjacent skills (e.g., README/AGENTS generators or code-review skills touching docs), matching 'somewhat specific but could still overlap with similar skills'. The enumerated documentation types give it a recognizable niche, keeping it above anchor 2's high-overlap generic examples.

3 / 5

Total

14

/

20

Passed

Validation

87%

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

Validation — 14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

metadata_version

'metadata.version' is missing

Warning

relative_links

Relative link issues: 15 possibly missing (examples/, examples/HIW-tasks.md, examples/architecture-design-system.md, examples/architecture-plugins.md, examples/behaviour-spec.md, +10 more), 1 suspicious

Warning

Total

14

/

16

Passed

Repository

vanillagreencom/kendex

Path

.agents/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.