Name: visual-plan
Rating: 56.8 (1 reviews)
Author: BuilderIO

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

71%

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 ./.agents/plugins/agent-native-visual-plans/skills/visual-plan/SKILL.md

The canonical home for this skill is visual-plan in BuilderIO/skills

Quality

Content

73%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 dense, highly prescriptive instruction skill with an exceptionally well-instrumented workflow — explicit validation checkpoints, concurrency fences, and feedback-resolution ordering rival the best rubric exemplars. Its weaknesses are repetition across sections and a body that carries reference-grade detail inline.

Suggestions

Consolidate repeated rules — the standalone-plan/revision-language rule, the expectedUpdatedAt fence, and the design-mode promotion guidance each appear 2-3 times across Plan Discipline, Core Workflow, Visual Surface Choice, and Tool Guidance — into one authoritative section with brief cross-references.

Move low-frequency detail sections (Setup & Authentication, Visibility & Sharing, Interpreting comment anchors) into references/ files, keeping one summary line each in the body, to cut main-file token load.

Vary the boilerplate 'READ references/X.md — it is the single source of truth... Do not author from memory' phrasing, which repeats nearly verbatim for four different files and reads as padding.

Dimension	Reasoning	Score
Conciseness	Nearly every sentence carries non-obvious domain guidance rather than explanations of things Claude already knows, but the body is noticeably repetitive — the revision-language rule, the expectedUpdatedAt fence, and the 'single source of truth / do not author from memory' pattern are each restated across multiple sections, which could be consolidated.	3 / 5
Actionability	Guidance is highly concrete — exact tool names, parameters, patch operations, expectedUpdatedAt fencing, and copy-paste commands ('npx @agent-native/core@latest skills add visual-plans') — but no worked example is inline; examples are delegated to references/exemplar.md and the live get-plan-blocks catalog.	4 / 5
Workflow Clarity	The 8-step Core Workflow is explicitly sequenced with hard validation checkpoints: re-read-after-write comparison of persisted text and block IDs, concurrency fencing via expectedUpdatedAt from a fresh read, verification-before-resolve ordering for feedback, and auth-failure stop-and-reconnect recovery, plus an adversarial self-review pass.	5 / 5
Progressive Disclosure	All six referenced files exist and are one level deep, each with a dedicated, clearly-signaled section directing the agent to read it before authoring; however, some body content (Setup & Authentication, Visibility & Sharing, Interpreting comment anchors) is detailed enough that it could itself move to a reference file.	4 / 5
	Total	16 / 20 Passed

Description

58%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.

The description clearly states what the skill produces but lacks an explicit trigger ('Use when...') clause and natural synonym coverage, so it will not reliably surface for relevant requests. It sits solidly at the middle of the rubric scale with concrete artifact naming as its main strength.

Suggestions

Add an explicit 'Use when...' clause with concrete triggers, e.g. 'Use when the user asks for a visual plan, wireframes, mockups, or wants to review a plan before implementation.'

Include natural synonyms and variations users would say — wireframes, mockups, storyboards, before/after comparison, plan review — alongside 'diagrams' and 'visual plans'.

Add one or two more concrete verbs (e.g. 'compose', 'annotate', 'convert') so the action list reads as multiple specific capabilities rather than one verb plus artifacts.

Dimension	Reasoning	Score
Specificity	Names the domain plus several concrete artifacts — 'diagrams, file maps, annotated code, open questions, and UI/prototype review' — but a single verb ('Turn...into') covers them all, so coverage is slightly short of the comprehensive multi-action anchor.	4 / 5
Completeness	The 'what' is clear, but the 'when' is only weakly implied by 'when useful'; there is no explicit 'Use when...' clause, which caps completeness at 3 per the judging guidelines.	3 / 5
Trigger Term Quality	Relevant keywords exist ('text plans', 'visual plans', 'diagrams', 'UI/prototype'), but common natural variations users would actually say — wireframes, mockups, storyboards, 'planning', 'before/after' — are missing, matching the 'some relevant keywords but missing variations' anchor.	3 / 5
Distinctiveness Conflict Risk	'Turn ordinary text plans into rich interactive visual plans' carves a fairly distinct niche, though broad terms like 'diagrams' and 'plans' leave minor overlap risk with general diagramming or design-review skills — mostly distinct rather than a clear isolated niche.	4 / 5
	Total	14 / 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
skill_md_line_count	SKILL.md is long (537 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: a941a2e

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