033-architecture-diagrams
Use when you need to generate Java project diagrams — including UML sequence diagrams, UML class diagrams, C4 model diagrams, UML state machine diagrams, and ER (Entity Relationship) diagrams — through a modular, step-based interactive process that adapts to your specific visualization needs. Part of the skills-for-java project
69
61%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/033-architecture-diagrams/SKILL.mdQuality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a strong description that clearly identifies the skill's purpose, lists specific diagram types as concrete capabilities, and opens with an explicit 'Use when' trigger clause. The main weakness is the use of second person ('your specific visualization needs') which violates the third-person voice guideline, and the trailing 'Part of the skills-for-java project' adds little selection value. The phrase 'modular, step-based interactive process that adapts to your specific visualization needs' is somewhat fluffy.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: UML sequence diagrams, UML class diagrams, C4 model diagrams, UML state machine diagrams, and ER diagrams. Also mentions 'modular, step-based interactive process' which describes the approach. | 3 / 3 |
Completeness | Clearly answers both what (generate various types of Java project diagrams through a modular interactive process) and when ('Use when you need to generate Java project diagrams'). The 'Use when' clause is explicit at the start. | 3 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'UML', 'sequence diagrams', 'class diagrams', 'C4 model', 'state machine diagrams', 'ER', 'Entity Relationship', 'Java project diagrams'. These cover common variations well. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive — scoped specifically to Java project diagram generation with explicit diagram types listed. The Java-specific focus and enumeration of diagram types (UML, C4, ER) make it unlikely to conflict with other skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
22%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is essentially a table of contents with a validation constraint, but lacks any actionable content for generating diagrams. It repeatedly lists the diagram types it covers without providing any concrete examples, PlantUML syntax, or step-by-step workflows. The entire substance is deferred to a single reference file, making the SKILL.md itself minimally useful.
Suggestions
Add at least one concrete, executable PlantUML example for the most common diagram type (e.g., a sequence diagram) so the skill is immediately actionable without reading the reference.
Define the actual step-based interactive workflow with numbered steps, decision points (e.g., 'which diagram type?'), and validation checkpoints — not just 'run validate first.'
Remove the redundant listing of diagram types (appears in the intro sentence, the 'What is covered' section, and the 'When to use' section) to improve conciseness.
Add a brief quick-start section showing the end-to-end flow for generating one diagram type, then point to the reference for additional types and advanced options.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content has some unnecessary repetition (e.g., listing all diagram types multiple times in the intro, 'What is covered', and 'When to use') and explains things that could be more tightly expressed. The bullet list of 'What is covered' largely restates the opening sentence. | 2 / 3 |
Actionability | The skill provides no concrete code, commands beyond `./mvnw validate`, no PlantUML syntax examples, no executable guidance for actually generating any of the diagram types. It describes what it covers but delegates all actual instructions to a reference file without providing any actionable content itself. | 1 / 3 |
Workflow Clarity | There is no clear step-by-step workflow despite claiming to be a 'step-based interactive process.' The only sequenced guidance is 'run validate first,' but the actual diagram generation steps, validation checkpoints for PlantUML syntax, and feedback loops are entirely absent from this file. | 1 / 3 |
Progressive Disclosure | There is a single reference link to a detailed file, which is good, but the SKILL.md itself contains almost no substantive quick-start content — it's essentially an empty shell pointing to one reference. The overview doesn't give enough to act on before needing the reference. | 2 / 3 |
Total | 6 / 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
- jabrena/cursor-rules-java
- Commit
1847adc
- 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.