update-visualizations

Analyze recent changes and update affected architecture visualizations

Quality

—

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Quality

Content

72%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The content is a well-structured, actionable workflow with concrete commands and clear sequencing. Its main weaknesses are missing validation checkpoints before committing and some repetition of the Excalidraw branching instructions.

Suggestions

Add an explicit verification step before Step 8 (Commit), e.g. re-read each updated diagram to confirm it reflects the diff and that mermaid syntax is valid.

Consolidate the Excalidraw substitution guidance into one place (Step 1b) and reference it from Step 5 instead of restating the full instructions.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient and avoids explaining basic concepts, but the Excalidraw substitution instructions are repeated nearly verbatim in Step 1b, again as a Step 5 callout, and referenced once more, which could be tightened.	2 / 3
Actionability	It provides fully executable, copy-paste-ready commands ('git diff HEAD~1', 'git add <viz-path>/', 'git commit -m "..."', 'devflow visualizations render <file>.excalidraw') plus specific file-to-diagram heuristic mappings.	3 / 3
Workflow Clarity	The eight steps are clearly sequenced, but there is no validation or verification checkpoint (e.g. confirm the diagram reflects the diff or that mermaid syntax is valid) before the destructive batch commit, which caps workflow clarity at 2.	2 / 3
Progressive Disclosure	The body is well-organized into clearly numbered sections with explicitly signaled one-level-deep references (the render-diagram skill and the <viz-path>/README.md style guide) and no nested reference chains.	3 / 3
	Total	10 / 12 Passed

Description

50%

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 communicates the skill's purpose but is held back by the absence of any 'when to use' trigger guidance and only generic action verbs. It is competent but not exemplary.

Suggestions

Add an explicit 'Use when...' trigger clause, e.g. 'Use when updating architecture diagrams after code changes, or when the user mentions visualizations, mermaid diagrams, or architecture overviews.'

Replace generic verbs with more specific concrete actions, e.g. 'Analyze git diffs, map changed files to affected diagrams, and update or create mermaid architecture visualizations.'

Include natural trigger term variations users would actually say, such as 'diagrams', 'mermaid', 'architecture diagrams', and 'viz'.

Dimension	Reasoning	Score
Specificity	It names the domain ('architecture visualizations') and two actions ('Analyze recent changes', 'update affected architecture visualizations'), but the verbs are generic rather than multiple specific concrete actions as required for a 3.	2 / 3
Completeness	It clearly states what the skill does but provides no 'Use when...' clause or equivalent explicit trigger guidance, which per the guidelines caps completeness at 2.	2 / 3
Trigger Term Quality	It includes relevant terms ('recent changes', 'architecture visualizations') but misses common natural variations a user would say such as 'diagrams', 'mermaid diagrams', or 'architecture diagrams'.	2 / 3
Distinctiveness Conflict Risk	'architecture visualizations' is a recognizable niche, but without explicit triggers it could still overlap with general documentation or diagram-updating skills.	2 / 3
	Total	8 / 12 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
relative_links	Relative link issues: 2 missing	Warning

	Total	15 / 16 Passed

Repository: AndreJorgeLopes/devflow
Commit: 9556c94

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