write-docs

Use when writing or editing documentation pages (concept pages, how-to guides, API reference prose, tutorials) under docs/. Provides the writing style, voice, and structural rules for Agenta docs. Apply this skill before drafting any new docs page, and include it in the brief for any subagent tasked with writing docs.

Quality

88%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Medium

Suggest reviewing before use

Quality

Content

77%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

An exceptionally actionable, well-sequenced style guide with concrete examples and validation checkpoints, but it is a monolithic single file whose length and inline templates keep it from being lean or progressively disclosed.

Suggestions

Move the subagent brief template and the §0 BAD/GOOD example catalog into reference files under ./references/ and link to them from SKILL.md to reduce inline bulk and improve progressive disclosure.

Tighten multi-line BAD examples to one-line illustrations where the contrast is already clear, cutting tokens without losing the point.

Consider condensing §0's prose rules into a compact checklist, since several paragraphs restate the four-beats structure already shown as a list.

Dimension	Reasoning	Score
Conciseness	It assumes Claude's competence (no padding explaining what docs or Diátaxis are) and each rule earns its place, but at ~250 lines with multi-line BAD/GOOD blocks and a full subagent brief it is comprehensive rather than lean and could be tightened in places.	2 / 3
Actionability	Highly actionable throughout: concrete BAD/GOOD contrast pairs, exact commands ('pnpm update-api-docs', 'ruff format', 'gh pr create --draft', 'git checkout origin/<base> -- docs/docs/reference/api/'), specific paths, and a copy-paste subagent brief template.	3 / 3
Workflow Clarity	Sequenced workflows carry explicit validation checkpoints — §9 'Before you ship' (run build, fix errors, ruff format/check), §4 verify request/response shapes against the live API, and §8's exact revert command for auto-generated MDX.	3 / 3
Progressive Disclosure	Well-organized into numbered sections with clear headings, but it is monolithic: no bundle files exist and content that could live in references (the subagent brief template, the extensive §0 example catalog) is inline in a single 250-line file.	2 / 3
	Total	10 / 12 Passed

Description

100%

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 'Use when' triggers covering natural terms, both what and when answered, and a distinct docs-writing niche. Third-person voice is maintained throughout with no first/second-person slips.

Dimension	Reasoning	Score
Specificity	Names concrete actions ('writing or editing documentation pages', 'drafting any new docs page') on concrete artifacts enumerated by type ('concept pages, how-to guides, API reference prose, tutorials'), plus what it supplies ('writing style, voice, and structural rules').	3 / 3
Completeness	Explicitly answers both what ('Provides the writing style, voice, and structural rules for Agenta docs') and when ('Use when writing or editing documentation pages... under docs/', 'Apply this skill before drafting any new docs page').	3 / 3
Trigger Term Quality	Covers natural terms a user would actually say — 'documentation pages', 'how-to guides', 'tutorials', 'API reference', 'docs' — alongside the explicit 'Use when' trigger clause.	3 / 3
Distinctiveness Conflict Risk	Scoped narrowly to 'Agenta docs' under 'docs/' with doc-type-specific triggers, giving it a clear niche unlikely to fire for unrelated writing or coding skills.	3 / 3
	Total	12 / 12 Passed

Validation

93%

Warnings & errors only

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

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning

	Total	15 / 16 Passed

Repository: Agenta-AI/agenta
Path: .agents/skills/write-docs/SKILL.md
Commit: 93872a6

Reviewed: 5 days ago

Table of Contents

Discovery Implementation Validation

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.