docs-write

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

Quality

70%

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

71%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, actionable writing-process skill with a clear sequence and concrete examples. Its main weakness is a broken external reference that undermines progressive disclosure.

Suggestions

Fix or remove the dangling @./../_shared/metabase-style-guide.md reference so navigation actually resolves.

Add an explicit validation/re-read checkpoint (e.g., 'Re-read aloud; if a step is unclear, rewrite it') to strengthen the feedback loop.

Tighten filler sentences like 'This ensures consistent formatting across all documentation' to lift conciseness toward 5.

Dimension	Reasoning	Score
Conciseness	Mostly lean prescriptive guidance with no padding about basic concepts, but a few sentences are explanatory filler ('This ensures consistent formatting...', 'you don't know the reader's context').	4 / 5
Actionability	Provides concrete do/don't examples, a real command (yarn prettier --write), and a quick-reference table; minor gaps include an awkward escaped-backtick code block and mostly illustrative rather than copy-paste examples.	4 / 5
Workflow Clarity	Clear Draft→Edit→Polish→Format sequence with light checkpoints ('Verify examples actually work', prettier); non-destructive skill so no hard validation cap applies, but no real re-validation feedback loop.	4 / 5
Progressive Disclosure	Well-organized sections, but the sole one-level-deep reference (@./../_shared/metabase-style-guide.md) does not exist on disk, so the signaled navigation is broken.	3 / 5
	Total	15 / 20 Passed

Description

70%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 solid description that states what the skill does and when to use it with concrete trigger terms and a brand-scoped niche. It stops short of enumerating multiple specific capabilities, which keeps it from the top tier.

Suggestions

Add 1-2 more concrete actions (e.g., 'proofread, restructure, and format') to lift specificity toward 5.

Broaden trigger terms with synonyms like 'docs', 'guide', 'tutorial', or '.md' for fuller natural-language coverage.

Tighten the 'when' clause with a more specific trigger phrase (e.g., 'Use when writing or revising any Metabase-facing doc').

Dimension	Reasoning	Score
Specificity	Names the documentation domain and the concrete write/edit action with a stated style, but lists only one primary action rather than several specific ones.	3 / 5
Completeness	Explicitly answers both what ('Write documentation following Metabase's... style') and when ('Use when creating or editing documentation files'), though the when clause is moderately generic.	4 / 5
Trigger Term Quality	Includes natural trigger phrases ('creating or editing documentation files') plus file-type keywords (markdown, MDX), with only minor synonym coverage gaps.	4 / 5
Distinctiveness Conflict Risk	Scoping to 'Metabase's... style' gives a clear niche with mostly distinct triggers, though generic 'documentation files' terms retain minor overlap with general writing skills.	4 / 5
	Total	15 / 20 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: d5ae560

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.