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

77%

Does it follow best practices?

Impact

91%

1.71x

Average score across 3 eval scenarios

SecuritybySnyk

Passed

No known issues

Fix and improve this skill with Tessl

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

Quality

Content

77%

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

The skill body is well-structured and highly actionable with clear phased workflows and validation steps. Its main weaknesses are verbosity from restating general writing rules Claude already knows and limited use of progressive disclosure for the large inline style guide.

Suggestions

Move generic writing/grammar guidance (active voice, serial comma, contractions) out of the body or trim it, keeping only the Gemini-CLI-specific conventions Claude would not already know.

Consider externalizing the Phase 1 style-guide rules into a reference file so SKILL.md reads as an overview pointing to detailed materials, with the existing docs-auditing.md as the model.

DimensionReasoningScore

Conciseness

The body is mostly efficient and contains genuinely project-specific rules (Gemini CLI naming, prettier-ignore placement, quota/limit terminology), but large portions restate generic writing guidance Claude already knows (active voice, serial comma, avoid 'please', avoid Latin abbreviations), so it could be tightened.

2 / 3

Actionability

For an instruction-only skill the guidance is concrete and specific — exact conventions, executable examples for <details> and callouts, named alert types, and a real referenced procedure — satisfying the actionable-without-code criterion.

3 / 3

Workflow Clarity

The four-phase structure sequences work clearly (Preparation, Execution, Verification) and Phase 4 provides explicit validation checkpoints (accuracy, self-review, link check) plus a format-fail recovery loop ('If npm run format fails... run npm install first').

3 / 3

Progressive Disclosure

The single reference (docs-auditing.md) is real, one level deep, and clearly signaled, but SKILL.md itself is a large inline style guide rather than an overview pointing to detailed materials, so content that could be split remains inline.

2 / 3

Total

10

/

12

Passed

Description

77%

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 strong on completeness and specificity, with an explicit use-when trigger and concrete actions. It is weaker on trigger-term breadth and distinctiveness because of its reliance on a literal directory path and the broad '.md files in the repository' scope.

Suggestions

Add common natural trigger terms such as 'documentation', 'markdown', or 'README' so the description matches how users actually phrase doc-editing requests.

Tighten the scope from 'any .md files in the repository' to documentation-specific contexts to reduce overlap with general file-editing skills.

DimensionReasoningScore

Specificity

The description lists multiple concrete actions ('writing, reviewing, or editing') tied to a concrete domain ('/docs directory or any .md files'), matching the score-3 anchor that lists several specific concrete actions.

3 / 3

Completeness

It explicitly answers both what (write/review/edit docs and .md files) and when via an explicit 'Always use this skill when the task involves...' trigger clause.

3 / 3

Trigger Term Quality

'writing, reviewing, or editing' and 'docs'/'md files' are natural terms, but coverage is narrow and anchored to a literal directory path rather than common variations like 'documentation' or 'markdown' a user would actually say.

2 / 3

Distinctiveness Conflict Risk

The '/docs' scoping is distinctive, but 'any .md files in the repository' is broad and could overlap with general file-editing or README-editing skills.

2 / 3

Total

10

/

12

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.

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