docs-write

Write documentation following Metabase's conversational, clear, and user-focused style. Use when creating or editing documentation files (markdown, MDX, etc.).

Quality

77%

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 ./bundled/skills/docs-write/SKILL.md

Quality

Content

65%

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

A well-organized, highly actionable style guide with concrete examples and a clear Draft/Edit/Polish/Format process. It loses points for some advisory prose, a light validation loop, and a shared-guide @-import whose target file is missing from the bundle.

Suggestions

Tighten the 'Start here' rhetorical questions and editorial asides (e.g. 'Nobody wants to be in docs longer than necessary') into direct imperatives to improve conciseness.

Add an explicit verify→fix→retry checkpoint in the writing process (e.g. after 'Verify examples actually work', state 'if an example errors, fix it and re-verify before moving on') to strengthen the workflow loop.

Ensure the @./../_shared/metabase-style-guide.md import resolves to a real bundled file, or inline the essential style rules so the skill is self-contained.

Dimension	Reasoning	Score
Conciseness	Mostly efficient bullet/table format with no padding about concepts Claude already knows, but editorial asides like "Nobody wants to be in docs longer than necessary" and the three rhetorical "Start here" questions could be tightened. Not 3 because some prose is advisory filler rather than direct guidance; not 1 because it is lean and un-padded overall.	2 / 3
Actionability	Concrete do/don't pairs throughout — headings ("Set SAML before adding users" ✅ vs "Environment variables" ❌), link examples, a copy-paste command ("yarn prettier --write <file-path>"), and a Write-This/Not-This quick-reference table. Fully specific, actionable guidance matching anchor 3.	3 / 3
Workflow Clarity	A clear Draft → Edit → Polish → Format sequence is present, with a light checkpoint ("Verify examples actually work") and a final prettier step. Not 3 because validation is implicit/light with no validate→fix→retry feedback loop; not 1 because the ordered stages are unambiguous.	2 / 3
Progressive Disclosure	Uses a single well-signaled one-level @-import ("@./../_shared/metabase-style-guide.md") and the body is well-sectioned, but the referenced file is not present in the bundle (no references/scripts/assets dirs, file not found), so navigation to the detailed material fails. Not 3 because the referenced path is not a real, verifiable file; not 1 because the structure is clean and only one level deep rather than a nested chain.	2 / 3
	Total	9 / 12 Passed

Description

90%

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-formed description: it states what the skill does, when to use it, and is anchored to a distinctive Metabase style. The only soft spot is specificity, since 'write/create/edit documentation' is a single action cluster rather than a list of distinct concrete actions.

Dimension	Reasoning	Score
Specificity	Quotes "Write documentation" and "creating or editing documentation files" — it names the domain and a couple of actions but does not list multiple distinct concrete actions (cf. anchor 3 'extract text, fill forms, merge documents'). It is above anchor 1's vague 'Helps with documents' because concrete writing/editing actions are named.	2 / 3
Completeness	Quotes both the what ("Write documentation following Metabase's conversational, clear, and user-focused style") and an explicit when ("Use when creating or editing documentation files (markdown, MDX, etc.)"), matching the anchor 3 example exactly. Not 2 because the 'Use when' trigger is explicit, not merely implied.	3 / 3
Trigger Term Quality	Quotes "documentation files (markdown, MDX, etc.)" — natural terms a user would say when needing docs written or edited. Matches anchor 3's 'good coverage of natural terms' rather than anchor 2's partial coverage.	3 / 3
Distinctiveness Conflict Risk	The Metabase-style qualifier ("following Metabase's conversational, clear, and user-focused style") carves a clear niche unlikely to trigger for a generic docs skill. Not 2 because the branded style + markdown/MDX triggers make overlap unlikely.	3 / 3
	Total	11 / 12 Passed

Validation

87%

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

Validation for skill structure

Criteria	Description	Result
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning
relative_links	Relative link issues: 4 missing	Warning

	Total	14 / 16 Passed

Repository: foryourhealth111-pixel/Vibe-Skills
Path: bundled/skills/docs-write/SKILL.md
Commit: f627ab5

Reviewed: about 8 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.