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 Plinth Toolkit

Quality

—

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Quality

Content

57%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-structured, lean instruction-only skill body with excellent progressive disclosure via a single real one-level-deep reference. It is held back by redundant trigger listings, ADR template details delegated entirely to the reference, and validation steps that appear in the reference rather than the workflow body.

Suggestions

Trim or consolidate the "When to use this skill" list to avoid duplicating triggers already in the frontmatter description.

Include a brief inline MADR template skeleton or a short example ADR output so the body is actionable without forcing a context switch to the reference.

Surface the key validation step (e.g. `mvn validate` / `./mvnw validate`) directly in the workflow body, not only in the reference, so the feedback loop is visible at the point of action.

Dimension	Reasoning	Score
Conciseness	The body is lean and avoids explaining concepts Claude already knows, but the 16-item "When to use this skill" list largely duplicates and expands triggers already present in the frontmatter description, so it could be tightened.	2 / 3
Actionability	Guidance is concrete (load a named reference file, elicit specific inputs, produce a MADR-style document, confirm before creating), but the actual MADR template structure and an example ADR output are delegated to the reference rather than shown, leaving key details incomplete in the body.	2 / 3
Workflow Clarity	A clear three-step sequence with a confirm-alignment checkpoint in step 2, but validation specifics (the reference's MANDATORY `mvn validate`) live in the reference file and the body's checkpoints are otherwise limited to the confirmation step.	2 / 3
Progressive Disclosure	A lean overview that points to a single, clearly signaled, one-level-deep reference (references/030-architecture-adr-general.md, verified to exist with no chained references), with content appropriately split between overview and detail.	3 / 3
	Total	9 / 12 Passed

Description

90%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, specific description with explicit "Use when" triggers and good natural keyword coverage, clearly scoped to ADR generation for Java. The only notable issue is the second-person voice ("you need"), which costs it a specificity point under the rubric.

Suggestions

Rewrite in third person to avoid the second-person penalty, e.g. "Use when generating Architecture Decision Records (ADRs) for a Java project..." instead of "Use when you need to generate...".

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions ("generate Architecture Decision Records", "systematically gathers context, stakeholders, options, and outcomes", "produce well-structured ADR documents") which would anchor at 3, but the second-person phrasing "Use when you need to generate" triggers the rubric's mandated 1-point specificity penalty.	2 / 3
Completeness	Explicitly answers both what (interactive conversational ADR generation gathering context, stakeholders, options, outcomes) and when ("Use when..." plus "This should trigger for requests such as...").	3 / 3
Trigger Term Quality	Natural trigger phrases users would say ("Generate ADR; Create Architecture Decision Record; Document architecture decision; Architecture Decision Record for Java") give good coverage of common variations.	3 / 3
Distinctiveness Conflict Risk	Scoped to ADRs for Java projects with distinct, domain-specific triggers, making it unlikely to fire for the wrong skill.	3 / 3
	Total	11 / 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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: jabrena/plinth
Commit: aaee915

Reviewed: 1 day 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.