documentation

To write, design, review, simplify, restructure, or standardize OSS project documentation

Quality

58%

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

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/documentation/SKILL.md

Quality

Content

63%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 well-structured, actionable instruction skill with a clear reasoning workflow, but it is long and repeats principles across multiple sections, and everything is inlined with no progressive disclosure to reference files.

Suggestions

Consolidate the repeated 'minimize duplication / single job / scan-don't-read' guidance so it appears once, cutting roughly 30-50 lines.

Move 'Voice & Tone' and the 'Writing Constraints' banned-word tables into a referenced file (e.g., references/voice-and-style.md) to introduce one-level-deep progressive disclosure.

Add a short 'Quick start' section at the top that points to the thinking model and output structure, so the overview routes readers before the full principles.

Dimension	Reasoning	Score
Conciseness	The body assumes Claude's intelligence (no explanations of what documentation is) and is mostly efficient, but at ~285 lines it repeats the same themes (minimize duplication, scan-don't-read, single-job docs) across 'Operating rules', 'Core principle', 'Heuristics', and 'Hard constraints', matching anchor 3's 'could be tightened'.	3 / 5
Actionability	Provides concrete actionable guidance: an explicit file-responsibility map (README, OVERVIEW, QUICKSTART, CONTRIBUTING, etc.), a named banned-words list, and hard constraints, fitting anchor 4's 'mostly executable guidance' for an instruction-only skill.	4 / 5
Workflow Clarity	The ordered 'Documentation thinking model' (Audience -> Intent -> Time-to-value -> Placement -> Maintenance) is a clear sequenced workflow, and the 'Review tests' checklist plus default 'Output preferences' structure provide checkpoints, matching anchor 4.	4 / 5
Progressive Disclosure	The single SKILL.md is well-structured with clear section headers but inlines ~285 lines with no bundle references, and content like 'Voice & Tone' or the banned-word tables could live in separate files, matching anchor 3.	3 / 5
	Total	14 / 20 Passed

Description

53%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 clearly states the domain and lists several verbs describing scope, but it omits any explicit 'Use when' trigger guidance, which caps completeness and limits its usefulness for skill routing.

Suggestions

Add an explicit 'Use when...' clause naming concrete triggers (e.g., 'Use when writing, restructuring, or reviewing project docs, README, CONTRIBUTING, or ARCHITECTURE files').

Replace abstract verbs with more concrete actions (e.g., 'audit doc structure', 'split overloaded docs', 'trim duplication') to raise specificity.

Include natural synonyms users actually say ('docs', 'README', 'CONTRIBUTING.md') to improve trigger-term coverage.

Dimension	Reasoning	Score
Specificity	Names the domain ('OSS project documentation') and several actions ('write, design, review, simplify, restructure, or standardize'), but the actions are abstract generic verbs rather than concrete operations, matching anchor 3 and falling short of anchor 4's specific-action coverage.	3 / 5
Completeness	The 'what' is clear (writing/designing/reviewing OSS documentation) but there is no 'Use when...' trigger clause, so per the judging guideline a missing explicit trigger caps completeness at 3.	3 / 5
Trigger Term Quality	Relevant keywords like 'documentation', 'write', 'review', and 'standardize' are present, but common natural variations users say ('docs', 'README', 'CONTRIBUTING.md', 'restructure docs') are missing, fitting anchor 3.	3 / 5
Distinctiveness Conflict Risk	The 'OSS project documentation' niche is mostly distinct from general writing skills with only minor overlap risk, matching anchor 4 rather than the broader anchor 3.	4 / 5
	Total	13 / 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: griddynamics/rosetta
Path: .claude/skills/documentation/SKILL.md
Commit: 044d86c

Reviewed: 20 hours 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.