030-architecture-adr-general
Use when you need to generate Architecture Decision Records (ADRs) for a Java project through an interactive, conversational process that systematically gathers context, stakeholders, options, and outcomes to produce well-structured ADR documents. This should trigger for requests such as Generate ADR; Create Architecture Decision Record; Document architecture decision; Architecture Decision Record for Java. Part of cursor-rules-java project
59
67%
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/030-architecture-adr-general/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 skill description that clearly communicates what the skill does (generates ADRs through an interactive process gathering context, stakeholders, options, and outcomes), when to use it (with explicit trigger phrases), and its specific domain (Java projects). The description is well-structured with both a 'Use when' clause and explicit trigger examples, making it easy for Claude to select appropriately.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description lists multiple specific concrete actions: 'generate Architecture Decision Records (ADRs)', 'interactive, conversational process', 'gathers context, stakeholders, options, and outcomes', 'produce well-structured ADR documents'. These are concrete and specific capabilities. | 3 / 3 |
Completeness | Clearly answers both 'what' (generate ADRs through an interactive process that gathers context, stakeholders, options, and outcomes) and 'when' (explicit 'Use when' clause at the start, plus 'This should trigger for' with specific example phrases). | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms: 'Generate ADR', 'Create Architecture Decision Record', 'Document architecture decision', 'Architecture Decision Record for Java', plus the acronym 'ADR' and full form. These cover the natural variations a user would say. | 3 / 3 |
Distinctiveness Conflict Risk | Very clear niche: Architecture Decision Records specifically for Java projects. The combination of ADR + Java + interactive process makes it highly distinctive and unlikely to conflict with other documentation or architecture skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
35%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 structure for an interactive ADR generation workflow but lacks the concrete, actionable content needed to be useful. It contains no ADR template, no example questions for the conversational gathering phase, no sample output, and no executable commands. Nearly all substance is deferred to a reference file that isn't available for evaluation, leaving the SKILL.md as essentially a table of contents rather than an instructional document.
Suggestions
Include the MADR template directly in the skill or as an inline example so Claude knows the exact output format without depending solely on the reference file.
Add specific questions or a structured checklist for the conversational information-gathering phase (e.g., 'What problem are you solving?', 'What are the constraints?', 'What alternatives did you consider?').
Provide a concrete example showing a sample input scenario and the resulting ADR output to make the skill actionable and copy-paste ready.
Trim the 'When to use this skill' section to 4-5 representative triggers instead of 17 overlapping phrases.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The 'When to use this skill' section is excessively long with 17 trigger phrases that are largely redundant and could be condensed. The constraints section is reasonable but the 'What is covered' bullet list partially duplicates the workflow. Overall mostly efficient but could be tightened. | 2 / 3 |
Actionability | The skill provides no concrete code, commands, templates, or examples. The workflow steps are abstract descriptions ('collect context through conversation', 'create a MADR-style ADR document') without showing what the ADR template looks like, what questions to ask, or what the output format should be. Everything actionable is deferred to a reference file that isn't provided. | 1 / 3 |
Workflow Clarity | The three workflow steps provide a reasonable sequence (gather → confirm → generate), and step 2 includes a confirmation checkpoint before generating output. However, the steps lack specificity—there's no detail on what questions to ask, no validation criteria for the output, and no feedback loop if the user rejects the summary in step 2. | 2 / 3 |
Progressive Disclosure | The skill references a single external file (references/030-architecture-adr-general.md) which is appropriate one-level-deep disclosure. However, since no bundle files were provided, we cannot verify the reference exists or contains the promised detailed guidance. The SKILL.md itself is too thin—it defers almost all actionable content to the reference, making the main file insufficient on its own. | 2 / 3 |
Total | 7 / 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.