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.

Quality

83%

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

SKILL.md
Quality
Evals
Security

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.

The body is a disciplined, well-sequenced process specification with explicit gates, feedback loops, and verification steps — exemplary workflow clarity for an instruction-only skill. Its main defects are the missing DESIGN-DOC-TEMPLATE.md referenced at step 7, which undermines both progressive disclosure and executability of the drafting phase, and a handful of directives that lack a worked example.

Suggestions

Add the referenced DESIGN-DOC-TEMPLATE.md to the skill bundle (or inline its essential section structure), since step 7 depends on it but the file is absent from the skill directory.

Move the drafting style rules in step 7 (heading depth, table/diagram/list usage, link hygiene) into a short reference file or the template itself, slimming the SKILL.md body.

Include one compact worked example of a frontier question round or a skeletal design tree, so the step-5 directives ("trace", "assign ownership") have a concrete model to follow.

DimensionReasoningScore

Conciseness

The body is dense and directive throughout — it assumes competence, never explains general concepts, and avoids padding (e.g., "A heading labels a topic; the body makes the argument"). It earns 4 rather than 5 because a few sections carry layered qualifications that could be tightened, such as the repeated gating language in step 5 and the multi-clause edge-case rules in step 4.

4 / 5

Actionability

Guidance is unusually concrete for a process skill: a default artifact path (`docs/design/<descriptive-slug>.md`), a copy-paste question format block, an exact sub-agent dispatch prompt, and a verification command (`git diff --check -- <document-path>`). It stays at 4 rather than 5 because several core directives remain directional rather than executable — "Trace the production path end to end" and "Assign one clear owner to every concern" describe outcomes without a worked example showing the expected artifact.

4 / 5

Workflow Clarity

Nine explicitly sequenced phases with a hard gate ("Do not write the implementation plan or draft the design until this gate is complete"), explicit feedback loops (return to step 5 on unresolved decisions and on new findings from the adversarial pass), a re-validation loop ("repeat it only when the resulting revisions materially change the proposal"), and an 8-item pre-handoff checklist. This matches the anchor of clear sequence with explicit validation steps and error-recovery loops.

5 / 5

Progressive Disclosure

Section structure is good and the sole external reference is clearly signaled and one level deep ("Read `DESIGN-DOC-TEMPLATE.md` from this skill directory before drafting"), but that file does not exist in the skill bundle — no references/, scripts/, or assets/ directories are present — so the primary progressive-disclosure mechanism is a broken reference. Additionally, the ~220-line body inlines substantial drafting style rules and checklists that could partially live in reference files.

3 / 5

Total

16

/

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 that explicitly states what the skill produces and when to use it, with a concrete enumerated trigger list and a clearly bounded niche. Its weaknesses are minor: some trigger vocabulary is internal jargon, and it does not disambiguate against the closely related ADR skill within the description itself.

DimensionReasoningScore

Specificity

Concrete actions are explicit — "Create or update implementation-ready design proposals for Mistral Vibe under docs/design, including a bounded design-tree decision review before drafting" names the deliverable, destination, and a distinct pre-drafting activity. It stays at 4 rather than 5 because the action list is short (create/update/review) and details like the adversarial review or validation plan live only in the body, leaving minor coverage gaps.

4 / 5

Completeness

Both halves are explicitly answered: the "what" is "Create or update implementation-ready design proposals for Mistral Vibe under docs/design" and the "when" is the concrete "Use before implementing a substantial Vibe feature, migration, protocol or API change..." clause listing specific trigger situations. This matches the anchor for clearly and explicitly answering both with concrete trigger phrases.

5 / 5

Trigger Term Quality

The trigger clause uses naturally spoken terms — "substantial Vibe feature, migration, protocol or API change, runtime or persistence change, cross-component workflow, compatibility plan" — which users would plausibly say. It falls short of 5 because phrases like "failure semantics" and "bounded design-tree decision review" are internal jargon rather than user vocabulary, and common phrasings like "design doc" or "write a proposal" are absent from the trigger.

4 / 5

Distinctiveness Conflict Risk

The description carves a clear niche (implementation-ready design proposals for Mistral Vibe) with triggers tied to pre-implementation review, so it is mostly distinct. It is not a 5 because a closely related sibling skill (`write-vibe-adr`) exists — the body explicitly disambiguates against it — but the description itself never mentions ADRs, leaving minor overlap risk when a user asks for an architecture decision record.

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.