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. This should trigger for requests such as Generate UML diagram; Create sequence diagram; Create class diagram; Create state machine diagram; Create C4 diagram. Part of cursor-rules-java project
64
75%
Does it follow best practices?
Impact
—
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 enumerates supported diagram types, provides explicit trigger phrases, and answers both what and when. The only minor issue is the use of second person ('your specific visualization needs') which the rubric penalizes, but the description is otherwise well-constructed with clear niche positioning and natural trigger terms.
| 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 the modular, step-based interactive process. | 3 / 3 |
Completeness | Clearly answers both 'what' (generate various Java project diagrams through a modular interactive process) and 'when' ('Use when you need to generate Java project diagrams', 'This should trigger for requests such as...'). Has explicit trigger guidance. | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms users would say: 'Generate UML diagram', 'Create sequence diagram', 'Create class diagram', 'Create state machine diagram', 'Create C4 diagram'. Covers multiple diagram types explicitly. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive — scoped specifically to Java project diagrams with named diagram types (UML, C4, ER). The Java-specific context and enumerated diagram types make it unlikely to conflict with other skills. | 3 / 3 |
Total | 12 / 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 workflow structure for an interactive diagram generation process but suffers from redundancy across sections and lacks concrete, actionable guidance in the skill body itself. The actual diagram generation knowledge is entirely deferred to a reference file, making the SKILL.md more of a routing document than a useful guide. The validation step is well-defined but the core generation steps are too abstract to be independently useful.
Suggestions
Add at least one concrete PlantUML code example (e.g., a minimal sequence diagram) to make the skill actionable without requiring the reference file for basic usage.
Consolidate the duplicated content — the 'What is covered' list, 'Constraints' section, and workflow steps all repeat the same information about diagram types and C4 restrictions. Merge into a single authoritative location.
Specify how to validate PlantUML syntax in step 4 — provide a concrete command or tool (e.g., `java -jar plantuml.jar -syntax diagram.puml`) rather than the vague 'check for syntax correctness'.
Remove the 'What is covered in this Skill?' section entirely — it adds no value beyond what the workflow and constraints already convey, and Claude doesn't need a table of contents for a short document.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill has some unnecessary verbosity — the 'What is covered' section largely duplicates the 'When to use this skill' section and the workflow steps. The repeated mention of C4 Level 4 restriction (appears 3 times) and the explanatory parentheticals (e.g., 'levels 1–3; Code/Level 4 not generated') add redundancy. However, it's not egregiously padded. | 2 / 3 |
Actionability | The skill provides concrete commands for validation (`./mvnw validate`) but the actual diagram generation steps are vague — 'Create requested diagrams in PlantUML syntax' gives no executable guidance, no code examples, no PlantUML syntax snippets. All substantive content is deferred to the reference file, making the skill itself more of a pointer than actionable guidance. | 2 / 3 |
Workflow Clarity | The workflow has a clear 4-step sequence with validation at the start and end, and includes a feedback loop for validation failure. However, step 3 ('Generate PlantUML diagrams') is too vague — it doesn't describe how to generate diagrams, what inputs to use, or what the output should look like. The final validation step (step 4) says 'check for syntax correctness' but doesn't specify how (no tool or command provided). | 2 / 3 |
Progressive Disclosure | The skill references a single detailed file (`references/033-architecture-diagrams.md`) which is appropriate one-level-deep disclosure. However, since no bundle files were provided, we can't verify the reference exists or is well-structured. The main skill itself contains too much duplicated content (coverage list, constraints, workflow all repeat the same information) rather than being a clean overview pointing to the reference. | 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
- jabrena/cursor-rules-java
- Commit
26e9744
- 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.