Content
35%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill provides a reasonable multi-step workflow for updating visualizations but suffers from significant verbosity, particularly around the Excalidraw opt-in path which is repeated in multiple places. Actionability is weakened by the lack of concrete Mermaid examples/templates and reliance on vague heuristics. The workflow would benefit from validation checkpoints and better content organization through external references.
Suggestions
Add a concrete Mermaid diagram example showing the expected output format, style conventions, and classDef palette — this would dramatically improve actionability.
Add validation steps: verify Mermaid syntax renders correctly before committing, and add error handling for missing config or failed git operations.
Extract the Excalidraw branching logic into a separate reference file (e.g., EXCALIDRAW.md) and the devflow-specific file-to-visualization mappings into another file, keeping SKILL.md focused on the core mermaid workflow.
Remove redundant Excalidraw reminders (appears in Steps 1b, 5, and the complexity callout) — state it once with a clear cross-reference.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is very verbose with extensive explanations Claude doesn't need (e.g., explaining what heuristics to use for mapping files to visualizations, explaining what config keys mean, lengthy Excalidraw branching logic). The Excalidraw opt-in path alone adds significant token overhead and is repeated multiple times. Much of the content reads as documentation rather than lean instructions. | 1 / 3 |
Actionability | Some concrete commands are provided (git diff, git add/commit), but much of the guidance is heuristic-based and vague ('determine which visualization(s) it might affect', 'infer from the project type'). No concrete Mermaid diagram examples or templates are given, and the Excalidraw path references an external skill without showing exact invocation syntax. | 2 / 3 |
Workflow Clarity | Steps are clearly numbered and sequenced (Steps 1-8), which is good. However, there are no validation checkpoints — no step to verify the Mermaid syntax is valid, no verification that the commit succeeded, and no error recovery for cases like malformed diagrams or missing config files. For a workflow involving file creation and git commits, this is a notable gap. | 2 / 3 |
Progressive Disclosure | The content is a monolithic wall of text with no references to external files for detailed content (e.g., the style guide template, the devflow-specific heuristic mappings, or the default visualization templates could all be in separate files). The Excalidraw branching logic bloats the main file when it could be a separate reference. No bundle files are provided to support progressive disclosure. | 2 / 3 |
Total | 7 / 12 Passed |