update-visualizations

Analyze recent changes and update affected architecture visualizations

Quality

65%

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 ./skills/update-visualizations/SKILL.md

Quality

Content

61%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 content is a well-sequenced, actionable guide with concrete commands and clear heuristics, but it repeats the Excalidraw path and lacks a validation checkpoint before the batch commit. Splitting devflow-specific heuristics into a reference would improve token efficiency.

Suggestions

Add a validation step before Step 8 (e.g. 'Verify each updated mermaid block renders; fix syntax errors before committing') to introduce a feedback loop for the batch operation.

De-duplicate the Excalidraw instructions: keep the full explanation in Step 1b and replace the Step 5 blockquote with a short back-reference.

Consider moving the devflow-specific file-mapping heuristics (Step 4) into a references/ file to slim the main body and aid discoverability.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient with step-by-step structure, but the Excalidraw substitution is explained in full in Step 1b and then repeated as a blockquote in Step 5, adding redundancy that could be tightened.	3 / 5
Actionability	Provides concrete, executable commands (`git diff HEAD~1`, `devflow visualizations render <file>.excalidraw`, `git add`/`git commit`) and specific file-to-visualization heuristics, with only minor placeholder gaps.	4 / 5
Workflow Clarity	An explicit 8-step sequence exists, but the batch commit step has no validation/verification checkpoint (e.g. confirm diagrams render or mermaid syntax is valid) and no error-feedback loop, which caps workflow clarity at 3 for a batch/destructive operation.	3 / 5
Progressive Disclosure	The single-file skill is well-organized into clearly numbered steps and sub-steps with no nested references; not a 5 because it exceeds ~50 lines and a couple of sections (devflow heuristics, style conventions) could optionally live in a reference file.	4 / 5
	Total	14 / 20 Passed

Description

53%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 states a clear purpose and domain but lacks an explicit 'when to use' trigger clause and natural synonyms like 'diagrams' or 'mermaid'. It is reasonably distinct from sibling skills yet would benefit from concrete trigger phrases.

Suggestions

Add a 'Use when...' clause with concrete triggers, e.g. 'Use when updating architecture diagrams or mermaid visualizations after code changes'.

Include natural synonyms users actually say — 'diagrams', 'mermaid', 'architecture diagrams' — alongside 'visualizations'.

Optionally name the concrete actions more specifically (e.g. 'locate affected diagrams, update mermaid blocks, and commit').

Dimension	Reasoning	Score
Specificity	Names the domain ('architecture visualizations') and two concrete actions ('Analyze recent changes' and 'update affected'), matching the anchor for 1-2 concrete actions without comprehensive coverage.	3 / 5
Completeness	The 'what' is clear (analyze changes and update visualizations) but there is no 'Use when...' clause or equivalent explicit trigger guidance, which caps completeness at 3 per the rubric guideline.	3 / 5
Trigger Term Quality	Includes some natural terms ('recent changes', 'architecture visualizations') but omits common synonyms a user would say such as 'diagrams', 'mermaid', or 'architecture diagrams'.	3 / 5
Distinctiveness Conflict Risk	The niche (updating architecture visualizations from recent code changes) is mostly distinct with only minor overlap risk against generic doc-update skills; not a 5 because trigger phrasing is not explicit enough to fully eliminate conflict.	4 / 5
	Total	13 / 20 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
Path: skills/update-visualizations/SKILL.md
Commit: bd4b70c

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