visual-plan

Turn ordinary text plans into rich interactive visual plans with diagrams, file maps, annotated code, open questions, and UI/prototype review when useful.

Quality

72%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./.agents/plugins/agent-native-visual-plans/skills/visual-plan/SKILL.md

Quality

Content

85%

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 well-structured, actionable guide for a complex hosted-MCP workflow, with a clearly sequenced Core Workflow, explicit validation checkpoints, and clean one-level progressive disclosure into verified reference files. Its main weakness is verbosity from repeated emphasis and restated caveats.

Suggestions

Consolidate the repeated "READ references/X.md — do not author from memory" and "single source of truth" phrasings into a single shared directive to reduce token cost.

State the expectedUpdatedAt concurrency fence once in Core Workflow and reference it briefly elsewhere instead of re-explaining the full rationale multiple times.

Trim restated cross-references between sections (e.g., the Visual Surface Choice pointer and the wireframe/canvas sections overlap) to tighten the document.

Dimension	Reasoning	Score
Conciseness	The body avoids explaining concepts Claude already knows, but is long and repeats emphasis ("READ references/X.md — do not author from memory" and "single source of truth" each appear many times, and the expectedUpdatedAt fence is restated several times), so it could be tightened.	2 / 3
Actionability	It names exact tools, parameters, and operations (create-visual-plan, contentPatches, set-visual-render-mode with renderMode: "design", patch-visual-plan-source) and includes an executable install command, giving concrete copy-ready guidance rather than vague direction.	3 / 3
Workflow Clarity	The 8-step Core Workflow is clearly sequenced with an explicit verification checkpoint (step 7 re-reads and compares persisted text, block IDs/counts, canvas/prototype against intent) and a destructive-write concurrency fence, plus feedback loops via get-plan-feedback before editing.	3 / 3
Progressive Disclosure	The overview body points to six one-level-deep reference files (connection.md, canvas.md, document-quality.md, wireframe.md, exemplar.md, local-files.md), all verified present, each clearly signaled by a dedicated "## ... — read references/X.md" header with no nested reference chains.	3 / 3
	Total	11 / 12 Passed

Description

60%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description concretely names the skill's outputs but omits explicit trigger guidance, leaving the "when to use" dimension only implied. It is specific in capability yet generic enough to risk overlap with sibling planning skills.

Suggestions

Add an explicit "Use when..." clause naming natural user triggers (e.g., "Use when planning UI/product work, storyboards, wireframes, or when a text plan needs a reviewable visual surface").

Soften technical jargon ("file maps", "annotated code") in favor of terms users naturally say, or pair them with common synonyms.

Sharpen distinctiveness by foregrounding the unique value (interactive, reviewable visual plans with canvas/prototype tabs) over generic outputs like diagrams and open questions.

Dimension	Reasoning	Score
Specificity	The description enumerates multiple concrete outputs — "diagrams, file maps, annotated code, open questions, and UI/prototype review" — matching the anchor for listing several specific concrete actions rather than vague language.	3 / 3
Completeness	The "what" is clear (turn text plans into rich interactive visual plans), but the "when" is only weakly implied by "when useful" with no "Use when..." clause or equivalent explicit trigger, which per the judging guidelines caps completeness at 2.	2 / 3
Trigger Term Quality	It includes some natural terms ("visual plans", "diagrams", "prototype", "UI review") but mixes in technical phrasing ("file maps", "annotated code") and lacks common variations or an explicit trigger enumeration, placing it at "some relevant keywords but missing common variations."	2 / 3
Distinctiveness Conflict Risk	"Rich interactive visual plans" is a fairly distinct niche, but generic terms like "diagrams" and "open questions" plus the absence of explicit triggers mean it could still overlap with other planning or visualization skills.	2 / 3
	Total	9 / 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
skill_md_line_count	SKILL.md is long (510 lines); consider splitting into references/ and linking	Warning
metadata_version	'metadata.version' is missing	Warning

	Total	14 / 16 Passed

Repository: BuilderIO/agent-native
Path: .agents/plugins/agent-native-visual-plans/skills/visual-plan/SKILL.md
Commit: c1ee18b

Reviewed: 5 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.