docs-writer

Always use this skill when the task involves writing, reviewing, or editing files in the `/docs` directory or any `.md` files in the repository.

1.71x

Quality

71%

Does it follow best practices?

Impact

91%

1.71x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.gemini/skills/docs-writer/SKILL.md

Quality

Content

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

The body is a dense, highly actionable docs-style guide with a clear phased workflow and a well-signaled single reference, scoring 4 on actionability, workflow clarity, and progressive disclosure. The main drag is conciseness: the voice/tone and language sections repeat general writing advice Claude already knows.

Suggestions

Trim the voice/tone and language sections to the project-specific deltas only (the quota/limit rule, the prettier-ignore convention, the Gemini CLI naming) and drop generic writing guidance Claude already follows.

Strengthen the verification phase into an explicit validate-fix-retry loop for link checks, not just the format/npm install hint.

Consider splitting the large formatting/standards block into a reference file referenced from a concise overview in SKILL.md to improve the overview-to-detail balance.

Dimension	Reasoning	Score
Conciseness	Most of the guide is genuinely project-specific (prettier-ignore syntax, sidebar.json, quota terminology, npm run format), but the voice/tone and language sections restate general writing principles Claude already knows (active voice, serial comma, avoid "foo"/"bar"), which is more than minor over-explanation and pulls it below a 4.	3 / 5
Actionability	Provides concrete, specific guidance throughout — exact prettier-ignore comments per file type, enumerated alert types, concrete paths (packages/, docs/sidebar.json), named tools (replace, write_file), and the npm run format command — with only minor gaps such as deferring auditing detail to a reference file.	4 / 5
Workflow Clarity	A clear four-phase sequence culminates in an explicit verification phase (self-review, link check, format) with a light recovery hint for format failures, but the feedback loops are thin (no retry loop for broken links), so it stops short of a 5.	4 / 5
Progressive Disclosure	Well-organized sections plus a clearly signaled, one-level-deep reference to the real file ./references/docs-auditing.md; the standards guide is largely inlined rather than split into multiple reference files, so it is not a 5.	4 / 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.

The description is concise, third-person, and provides an explicit, specific trigger clause with concrete actions and targets, scoring solidly at the 4 level across all dimensions. Its main gap is the absence of plain synonyms ("documentation", "markdown") and a separately framed capability statement that would push it to a 5.

Suggestions

Add plain-language synonyms to the trigger (e.g., "when working with documentation, docs, or markdown files") so users' natural phrasing matches more reliably.

Separate the "what" from the "when" with a brief capability lead-in (e.g., "Produces and maintains accurate, on-brand documentation. Use when...").

Mention the auditing/review capability hinted at in the body to make the action set more comprehensive and distinctive.

Dimension	Reasoning	Score
Specificity	Names the docs domain plus three concrete actions ("writing, reviewing, or editing") and concrete targets ("/docs directory", ".md files"), but the verbs are broad rather than a comprehensive set of distinct operations, so it falls short of a 5.	4 / 5
Completeness	An explicit "Always use this skill when..." trigger clause provides a clear, specific "when", and the verbs give an implicit "what"; the two are lightly merged rather than cleanly separated as in the anchor-5 example, so it is not a 5.	4 / 5
Trigger Term Quality	Includes natural user phrases ("writing, reviewing, or editing", "/docs directory", ".md files") but omits common synonyms a user might say such as "documentation", "docs", or "markdown", leaving it just below comprehensive.	4 / 5
Distinctiveness Conflict Risk	Scoping to the /docs directory gives a fairly distinct niche, but "any .md files in the repository" broadens it enough to risk overlap with a general markdown-writer skill, keeping it below a 5.	4 / 5
	Total	16 / 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: google-gemini/gemini-cli
Path: .gemini/skills/docs-writer/SKILL.md
Commit: 9a15c45

Reviewed: 1 day 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.