update-visualizations
Analyze recent changes and update affected architecture visualizations
42
41%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/update-visualizations/SKILL.mdQuality
Discovery
32%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 is too terse and lacks both concrete action details and explicit trigger guidance. While it hints at a specific niche (updating architecture diagrams based on code changes), it doesn't provide enough information for Claude to reliably select this skill over similar documentation or diagramming skills. The absence of a 'Use when...' clause is a significant gap.
Suggestions
Add an explicit 'Use when...' clause with trigger terms like 'update architecture diagram,' 'code changed,' 'refactor,' 'dependency visualization,' or 'system diagram out of date.'
List specific concrete actions such as 'parses git diffs, identifies structural changes, updates Mermaid/PlantUML diagrams, regenerates dependency graphs.'
Specify the types of architecture visualizations supported (e.g., component diagrams, sequence diagrams, dependency graphs) and the formats involved (e.g., Mermaid, PlantUML, SVG).
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names a domain (architecture visualizations) and two actions (analyze recent changes, update visualizations), but lacks detail on what specific actions are performed—e.g., what kind of changes, what format of visualizations, what tools are used. | 2 / 3 |
Completeness | It partially describes what the skill does but has no explicit 'Use when...' clause or equivalent trigger guidance, and the 'what' is also vague. The absence of a 'when' clause caps this at 2 per the rubric, and the weak 'what' brings it to 1. | 1 / 3 |
Trigger Term Quality | Includes some relevant terms like 'architecture visualizations' and 'recent changes,' but misses common natural variations users might say such as 'diagrams,' 'architecture docs,' 'code changes,' 'dependency graph,' or 'update docs after refactor.' | 2 / 3 |
Distinctiveness Conflict Risk | The combination of 'architecture visualizations' and 'recent changes' provides some specificity, but it could overlap with general documentation update skills or diagram generation skills without clearer scoping. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
50%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides a reasonable high-level workflow for updating project visualizations but falls short on actionability and validation. The step sequence is logical, but the lack of concrete examples (sample mermaid output, config JSON schema, README template) means Claude must infer significant details. Adding validation steps for rendered diagrams and providing executable templates would substantially improve the skill.
Suggestions
Add a concrete example of `visualizations.json` config and a sample mermaid diagram output so Claude knows the exact expected format.
Add a validation checkpoint after Step 5 — e.g., verify mermaid syntax parses correctly before committing, with a retry loop if it fails.
Provide a template for the README.md index and the style guide (classDef palette, init block) rather than describing them abstractly.
Extract the heuristic mapping tables (Step 4) and default visualization templates (Step 6) into separate referenced files to improve progressive disclosure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is moderately efficient but includes some unnecessary verbosity. The heuristic mapping tables in Step 4 are useful but could be more compact. Some steps like 'Read the current file' and 'Identify what's outdated' are obvious to Claude and don't need explicit enumeration. | 2 / 3 |
Actionability | The skill provides a clear sequence of steps and some concrete commands (git diff, git add/commit), but most guidance is descriptive rather than executable. There are no concrete mermaid diagram examples, no sample visualization config JSON, and no template for the style guide or README structure. Claude would need to infer many details. | 2 / 3 |
Workflow Clarity | The 8-step sequence is clearly ordered and covers the full workflow from discovery to commit. However, there are no validation checkpoints — no step to verify the mermaid diagrams render correctly, no error handling if git diff returns nothing, and no feedback loop if the generated diagrams are malformed. For a workflow that modifies and commits files, this is a notable gap. | 2 / 3 |
Progressive Disclosure | The content is reasonably well-structured with numbered steps and bold subsections. However, it's a monolithic file with no references to external files for the detailed heuristic mappings, style guide templates, or example configs — all of which could benefit from being split out. No bundle files are provided to support the references made (visualizations.json schema, README template, style guide). | 2 / 3 |
Total | 8 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- AndreJorgeLopes/devflow
- Commit
b0b1bb6
- 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.