CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

83

1.71x
Quality

76%

Does it follow best practices?

Impact

91%

1.71x

Average score across 3 eval scenarios

SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

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

Quality

Content

77%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 well-structured, highly actionable instruction skill with an exemplary phased workflow and explicit verification steps. Its weaknesses are the dangling reference to a nonexistent quota-limit-style-guide.md file, the large inlined style guide that could live in references/, and minor redundancy and self-inconsistency (the body uses 'e.g.' while its own rules forbid it).

Suggestions

Add the missing `quota-limit-style-guide.md` to `references/` (or remove the pointer) — the body directs the reader to a resource file that does not exist in the bundle.

Move the ~120-line Phase 1 style guide into a `references/style-guide.md` file and keep a short summary of the highest-impact rules in SKILL.md.

Fix internal inconsistencies: the grammatically broken 'Adhering to these principles...' opening line and the body's own use of 'e.g.' / 'foo' examples that violate the skill's abbreviation and placeholder rules.

DimensionReasoningScore

Conciseness

The body is a dense, mostly project-specific style guide (prettier-ignore placement, relative-link rules, callout syntax, Gemini CLI naming) — exactly what Claude does not already know — with concrete inline examples rather than padding. Minor over-explanation of basic grammar mechanics (serial comma, 'Address the reader as "you"') and slight redundancy (callout formatting stated in both 'Formatting and syntax' and 'Structure') keep it below anchor 5 but well above the verbose anchors.

4 / 5

Actionability

Concrete, executable guidance throughout: exact prettier-ignore comment syntax for .md and .mdx, a literal callout example, specific file paths (`docs/sidebar.json`, `packages/`, `CONTRIBUTING.md`), and the `npm run format` / `npm install` recovery step. Not a 5 because it directs the reader to a `quota-limit-style-guide.md` resource file that does not exist in the bundle, and the named tools `replace`/`write_file` are not the actual file-editing tool names — minor gaps in an otherwise executable instruction set.

4 / 5

Workflow Clarity

Four clearly sequenced phases (standards → preparation → execution → verification), with numbered sub-steps in Phase 2 (clarify, investigate, audit, connect, plan) and a dedicated Phase 4 verification: accuracy check, self-review, link check, and a format step with an explicit error-recovery loop ('If `npm run format` fails... run `npm install` first'). This matches anchor 5's clear sequence, explicit validation steps, and feedback loops for error recovery.

5 / 5

Progressive Disclosure

The bundle has one reference file (`references/docs-auditing.md`) and it is properly signaled with a markdown link from Phase 2 step 6 — but the body also points to a `quota-limit-style-guide.md` 'resource file' that does not exist anywhere in the bundle, and ~120 lines of style-guide standards are inlined in SKILL.md rather than split out. Broken navigation plus inline content that belongs in a reference file matches anchor 3 ('references present but not clearly signaled; content that should be separate is inline') better than anchor 4's 'minor organization gaps'.

3 / 5

Total

16

/

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 crisp, trigger-first description with fully explicit when-guidance and reasonable natural keywords, but the what-side is thin (generic verbs, no mention of the standards/audit capabilities) and the any-.md-file scope creates overlap risk. Solid but not exemplary.

Suggestions

Lead with a what-clause stating concrete capabilities (e.g., 'Writes, reviews, and edits Gemini CLI documentation to project style standards — voice, formatting, links, and quotas') before the 'Always use when...' trigger.

Add natural trigger synonyms users would say: 'documentation', 'markdown', 'README' alongside '/docs' and '.md files'.

Tie the trigger to the Gemini CLI project specifically to reduce conflict with generic markdown-editing skills.

DimensionReasoningScore

Specificity

The description names the domain ("files in the `/docs` directory or any `.md` files") and the actions "writing, reviewing, or editing", but these are three generic verbs rather than the concrete, distinctive operations of an anchor-4/5 description (e.g., enforcing project style standards, auditing the docset, checking links). Not a 2 because the domain and multiple actions are explicitly named; not a 4 because the actions are generic and coverage has gaps (auditing, formatting enforcement are unstated).

3 / 5

Completeness

Both what and when are explicitly and concretely answered in one sentence: "Always use this skill when the task involves writing, reviewing, or editing files in the `/docs` directory or any `.md` files" — the trigger could not be more explicit, and the capabilities (write, review, edit docs) are stated with concrete trigger surfaces. Matches anchor 5's pattern of explicit what + when with concrete trigger phrases.

5 / 5

Trigger Term Quality

Natural trigger terms are present: "docs", "`.md` files", "writing, reviewing, or editing" — phrases users would plausibly say. A few common variations are missing ("documentation", "markdown", "README", "changelog"), which keeps it just below anchor 5's comprehensive synonym/extension coverage but above anchor 3's single-keyword example.

4 / 5

Distinctiveness Conflict Risk

The scope "any `.md` files in the repository" is fairly broad and would overlap with general markdown/README/changelog-editing skills; it does not mention the project (Gemini CLI) or the standards-enforcement purpose that would give it a distinct niche. Not a 2 because the /docs and .md targeting is more specific than generic 'document files'; not a 4 because the any-markdown-file scope carries real overlap risk with closely related skills.

3 / 5

Total

15

/

20

Passed

Validation

100%

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