CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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.

64

Quality

80%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.vibe/skills/write-vibe-design-doc/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

70%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 skill lays out an unusually rigorous, well-gated workflow with explicit validation and feedback loops, written leanly for a competent reader. Its main defect is that step 7 depends on DESIGN-DOC-TEMPLATE.md, which is absent from the skill bundle, making the drafting step — the skill's core output — non-executable as written.

Suggestions

Add the missing DESIGN-DOC-TEMPLATE.md to the skill directory (or a references/ bundle file referenced from the body) so the step 7 instruction "Read DESIGN-DOC-TEMPLATE.md from this skill directory before drafting" is actually executable; alternatively inline a minimal section skeleton in the body.

Trim cross-step repetition: consolidate the "return to step 5 on unresolved material decisions" rule and the ownership/edge-case rules into single authoritative statements that later steps refer back to, as the skill itself instructs for the documents it produces.

State in the body (or the template) what the required reviewer-path sections are, so the absence of the template file would not leave the drafting step without its section structure.

DimensionReasoningScore

Conciseness

The body is dense, prescriptive, and assumes Claude's competence — no known concepts are re-taught — but there is minor restatement across steps ("If a material decision remains unresolved, return to step 5" in both steps 7 and 8, and the step 9 checklist re-lists step 4's edge-case and ownership rules) that could be trimmed. Efficient overall, so it sits above the 'some unnecessary explanation' anchor at 3 and below the every-token-earns-its-place anchor at 5.

4 / 5

Actionability

Mostly concrete — an exact question format template, the quoted adversarial-reviewer prompt, the default destination "docs/design/<descriptive-slug>.md", and the command "git diff --check -- <document-path>" — but the central drafting step (step 7) instructs "Read DESIGN-DOC-TEMPLATE.md from this skill directory before drafting" and that file does not exist in the bundle, leaving the core deliverable step non-executable. A missing key detail for the skill's primary output keeps this below the 'minor gaps' anchor at 4.

3 / 5

Workflow Clarity

Nine clearly sequenced steps with explicit gates and feedback loops: "Do not write the implementation plan or draft the design until this gate is complete" (step 5), reconciliation of adversarial findings with "return to step 5 and wait for confirmation" (step 8), and a final review checklist (step 9) that verifies links, commands, and unresolved blockers against the current checkout. Matches the anchor for clear sequence, explicit validation, error-recovery loops, and checklists.

5 / 5

Progressive Disclosure

The body itself is well sectioned and the reference is clearly signaled ("Read DESIGN-DOC-TEMPLATE.md from this skill directory"), but no bundle file exists — there is no references/ directory and no template file — so the intended one-level-deep split does not function and all drafting structure must be improvised. Structure is good, but the broken/absent reference and monolithic inline detail place this between the 'minimal structure' anchor at 2 and the 'good structure, clear references' anchor at 4.

3 / 5

Total

15

/

20

Passed

Description

83%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 description: it states concrete capabilities, an explicit "Use before..." trigger clause covering a broad range of change types, and product-scoped triggers that make misfiring unlikely. Its only weaknesses are a couple of missing natural synonyms and no disambiguation against the sibling ADR skill.

DimensionReasoningScore

Specificity

Names the domain and several concrete actions — "Create or update implementation-ready design proposals", "under docs/design", "a bounded design-tree decision review before drafting" — with only minor gaps (the doc's internal coverage is not enumerated). Fits the 'several specific actions; minor gaps' anchor rather than the 1-2-action anchor at 3.

4 / 5

Completeness

Clearly answers both halves: 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 — the explicit "Use before implementing..." clause with concrete trigger phrases. Not 4 because the 'when' is explicit and specific rather than merely present.

5 / 5

Trigger Term Quality

Good natural-term coverage: "substantial Vibe feature, migration, protocol or API change, runtime or persistence change, cross-component workflow, compatibility plan". A few natural phrases users might say are missing (e.g., "design doc", "spec", "proposal review"), so it falls short of the comprehensive-synonym anchor at 5.

4 / 5

Distinctiveness Conflict Risk

Scoping to "Mistral Vibe" and the distinctive decision-review framing give it a mostly distinct niche, but it does not disambiguate against the closely related ADR skill the body references, leaving minor overlap risk. Not 5 for that residual conflict with sibling documentation skills.

4 / 5

Total

17

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

metadata_version

'metadata.version' is missing

Warning

Total

15

/

16

Passed

Repository

mistralai/mistral-vibe

Path

.vibe/skills/write-vibe-design-doc/SKILL.md

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.