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

Quality

67%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/030-architecture-adr-general/SKILL.md

Quality

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), when to use it (explicit trigger phrases and use-when clause), and its specific domain (Java projects). The description is well-structured with good trigger term coverage and a clear niche that minimizes conflict risk with other skills.

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 detailed.	3 / 3
Completeness	Clearly answers both 'what' (generate ADRs through an interactive process gathering context, stakeholders, options, 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 common variations a user would naturally say.	3 / 3
Distinctiveness Conflict Risk	Very distinct niche: Architecture Decision Records specifically for Java projects, with a conversational/interactive approach. The combination of ADR + Java + interactive process makes it highly unlikely to conflict with other 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 effective. The workflow steps are abstract descriptions without templates, example outputs, or specific conversational prompts. Nearly all useful content appears to be deferred to a reference file that wasn't provided for evaluation, leaving the SKILL.md as essentially a pointer rather than a functional guide.

Suggestions

Include the MADR template directly in the skill or show a concrete example ADR output so Claude knows the exact format to generate

Add specific questions or a structured interview script for the conversational gathering phase (e.g., 'Ask: What is the architectural context? What are the quality attributes at stake?')

Specify the file naming convention and storage location for generated ADRs (e.g., 'Save as docs/adr/NNNN-title-with-dashes.md')

Condense the 17 trigger phrases in 'When to use this skill' to 4-5 representative examples

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 edge case formatting adds some verbosity. The 'What is covered' bullet list partially restates the workflow.	2 / 3
Actionability	The skill provides no concrete code, commands, templates, or executable examples. The workflow steps are abstract descriptions ('collect context through conversation', 'create a MADR-style ADR document') without showing the actual MADR template format, example ADR output, specific questions to ask, or file naming conventions. Everything actionable is deferred to the reference file.	1 / 3
Workflow Clarity	The three workflow steps provide a reasonable sequence (read reference → synthesize → generate), and step 2 includes a confirmation checkpoint before generating output. However, the steps lack specificity—there's no guidance on what questions to ask, how to structure the conversation, where to save the file, or what to do if the user disagrees with the recommendation.	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 assess its quality. The SKILL.md itself defers almost all actionable content to this reference, making the main file too thin to be useful on its own.	2 / 3
	Total	7 / 12 Passed

Validation

100%

Warnings & errors only

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: 762cb86

Reviewed: 2 days ago

Table of Contents

Discovery Implementation Validation

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.