writing-user-docs

House style for user-facing documentation — voice, scope, structure, and what to leave out. Use this skill whenever writing, editing, or reviewing anything a user reads to learn how to use a tool — help center articles, getting-started guides, tutorials, feature docs, README usage sections, in-app help, release notes, or FAQ entries. Trigger it even when the request is phrased plainly — "document this feature", "write docs for X", "explain this to users", "write a README for this library", "turn these notes into a guide" — and even when no style guidelines are mentioned. Also use it to review existing docs for tone, bloat, or leaked implementation detail. Do not use it for internal engineering docs, architecture write-ups, RFCs, or code comments.

Quality

94%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

93%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 tight, highly actionable instruction-only style guide that assumes Claude's competence and gives concrete do/don't examples plus a publishing checklist. The only mild gap is the absence of an explicit feedback/retry loop, which is largely inapplicable to a non-destructive style skill.

Dimension	Reasoning	Score
Conciseness	Lean and opinionated with no padding; it never explains concepts Claude already knows and every line earns its place ("Formality doesn't add authority, it just adds distance and words").	5 / 5
Actionability	Concrete, specific guidance with do/don't examples throughout ("You tap Save," not "the Save button should be tapped"; cut "just/simply/easy"; if the button says Workspace, never say "project") and a copy-applicable publishing checklist.	5 / 5
Workflow Clarity	The "Before publishing" numbered checklist serves as a clear validation checkpoint, but as a style guide rather than a destructive/batch operation it has no explicit retry or error-recovery loop, so it sits just below a 5.	4 / 5
Progressive Disclosure	A self-contained, under-60-line skill with no need for external references, organized into clear, well-signaled sections (Voice, Scope, Structure, Cover the unhappy path, Keep it from rotting, Before publishing).	5 / 5
	Total	19 / 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, well-targeted description that clearly states what the skill is, when to use it with concrete natural trigger phrases, and where it does not apply. It uses third-person imperative voice and avoids fluff, with only minor room to sharpen the action verbs beyond generic writing/editing/reviewing.

Dimension	Reasoning	Score
Specificity	Names the domain (user-facing documentation) and concrete actions (writing, editing, reviewing) plus a comprehensive enumeration of doc types, but the core verbs are generic writing actions rather than many distinct concrete operations, so it sits below a 5.	4 / 5
Completeness	Explicitly answers both what ("House style for user-facing documentation — voice, scope, structure, and what to leave out") and when ("Use this skill whenever writing, editing, or reviewing..." with concrete trigger phrases and a negative-scope boundary).	5 / 5
Trigger Term Quality	Comprehensive coverage of natural trigger phrases users actually say — quoted examples like "document this feature", "write docs for X", "explain this to users", "write a README for this library", "turn these notes into a guide" — plus doc-type synonyms (help center articles, tutorials, release notes, FAQ).	5 / 5
Distinctiveness Conflict Risk	Clear niche (user-facing docs house style) with distinct triggers and an explicit negative-scope boundary ("Do not use it for internal engineering docs, architecture write-ups, RFCs, or code comments") that minimizes overlap with adjacent skills.	5 / 5
	Total	19 / 20 Passed

Validation

100%

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: callstackincubator/agent-skills
Path: skills/writing-user-docs/SKILL.md
Commit: 61e6e7d

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.