write-vibe-design-doc

Create or update implementation-ready design proposals for Mistral Vibe under docs/design, including a bounded design-tree decision review before drafting. Use before implementing a substantial Vibe feature, migration, protocol or API change, runtime or persistence change, cross-component workflow, compatibility plan, or other work whose ownership, behavior, failure semantics, rollout, and validation need review.

Quality

82%

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

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 design-doc workflow with excellent sequencing, gates, and a review checklist. The main defect is a missing referenced bundle file (DESIGN-DOC-TEMPLATE.md) that the workflow instructs Claude to read before drafting.

Suggestions

Add the missing DESIGN-DOC-TEMPLATE.md to the skill bundle (or move its essential structure inline) so the step-7 instruction to 'Read DESIGN-DOC-TEMPLATE.md from this skill directory' does not dead-end.

Tighten the repeated gating language across steps 5, 7, and 8 ('Do not write the implementation plan or draft the design until this gate is complete' appears in spirit multiple times) by stating the gate once and referring back to it.

Consider moving the detailed question-format template and the adversarial-review prompt into a reference file so the main workflow stays leaner, improving conciseness and progressive disclosure together.

Dimension	Reasoning	Score
Conciseness	Dense, instruction-only prose that assumes competence and never explains concepts Claude already knows; a few clauses (e.g. the repeated gating reminders in steps 5 and 8) could be trimmed without loss.	4 / 5
Actionability	Concrete and executable for a methodology skill: specific file paths (docs/design/<descriptive-slug>.md), files to read (README.md, AGENTS.md, ADRs), a command (git diff --check -- <document-path>), a literal question template, and a quoted sub-agent task; minor gaps only.	4 / 5
Workflow Clarity	A clearly sequenced 9-step workflow with explicit gates ('Do not write the implementation plan or draft the design until this gate is complete'), feedback loops ('return to step 5'), and a final review checklist — matching the anchor for explicit validation steps and checklists.	5 / 5
Progressive Disclosure	The body is well-sectioned and clearly signals a one-level-deep reference ('Read DESIGN-DOC-TEMPLATE.md from this skill directory before drafting'), but that referenced file is absent from the bundle — a load-bearing dangling reference that breaks navigation.	3 / 5
	Total	16 / 20 Passed

Description

87%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 strong, third-person description that clearly states both capability and explicit use-when triggers tied to a specific product niche. The only mild gap is action specificity, which names the high-level deliverables rather than the full document composition.

Dimension	Reasoning	Score
Specificity	Names concrete actions — 'Create or update implementation-ready design proposals', 'a bounded design-tree decision review before drafting' — in a specific domain, but stops short of enumerating the full set of doc sections it produces.	4 / 5
Completeness	Explicitly answers both what ('Create or update implementation-ready design proposals for Mistral Vibe under docs/design, including a bounded design-tree decision review before drafting') and when ('Use before implementing a substantial Vibe feature, migration, ...') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Covers natural trigger phrases users would say — 'feature', 'migration', 'protocol or API change', 'runtime or persistence change', 'cross-component workflow', 'compatibility plan' — with good but not exhaustive synonym coverage.	4 / 5
Distinctiveness Conflict Risk	Targets a clear niche — 'Mistral Vibe' design proposals under docs/design, distinct from the named sibling write-vibe-adr — with minimal overlap risk against other skills.	5 / 5
	Total	18 / 20 Passed

Validation

93%

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

Validation for skill structure

Criteria	Description	Result
metadata_version	'metadata.version' is missing	Warning

	Total	15 / 16 Passed

Repository: mistralai/mistral-vibe
Path: .vibe/skills/write-vibe-design-doc/SKILL.md
Commit: d4b3223

Reviewed: 6 days 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.