architecture-decision-records
Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes.
78
66%
Does it follow best practices?
Impact
100%
1.61xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./tests/ext_conformance/artifacts/agents-wshobson/documentation-generation/skills/architecture-decision-records/SKILL.mdQuality
Discovery
89%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 solid description that clearly communicates both purpose and trigger conditions. Its main weakness is that the 'what' portion could be more specific about the concrete actions performed (e.g., creating new ADRs from templates, updating statuses, generating ADR indexes). The trigger terms and completeness are strong, and the niche focus on ADRs makes it highly distinctive.
Suggestions
Expand the capability list with more specific actions, e.g., 'Write and maintain Architecture Decision Records (ADRs): create new ADRs from templates, update decision statuses, link related decisions, and generate ADR indexes.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (ADRs) and some actions ('write and maintain'), but doesn't list multiple specific concrete actions like creating templates, linking related decisions, tracking status changes, or generating indexes. | 2 / 3 |
Completeness | Clearly answers both what ('Write and maintain Architecture Decision Records following best practices') and when ('Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes') with explicit trigger guidance. | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms: 'Architecture Decision Records', 'ADRs', 'technical decisions', 'architectural choices', 'decision documentation', 'decision processes' — these cover the terms users would naturally use when needing this skill. | 3 / 3 |
Distinctiveness Conflict Risk | ADRs are a very specific niche within technical documentation. The description clearly targets architectural decision records specifically, making it unlikely to conflict with general documentation, code review, or other technical writing skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
42%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill is highly actionable with excellent concrete templates and examples, but is severely bloated for a SKILL.md file. It explains concepts Claude already understands, includes five full-length template examples inline when one or two would suffice, and fails to use progressive disclosure to manage its substantial content. The token cost is very high relative to the unique value added.
Suggestions
Reduce to one primary template inline with brief descriptions of alternative formats, moving full template examples to a separate TEMPLATES.md file
Remove the 'Core Concepts' section entirely — Claude knows what ADRs are, when to write them, and their lifecycle states
Split content into SKILL.md (overview + quick start + one template) with references to separate files for templates, review checklists, and management/tooling details
Add an explicit end-to-end workflow with validation steps: e.g., draft → self-check against checklist → submit PR → review → update index
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~300+ lines. Explains basic concepts Claude already knows (what an ADR is, when to write one, lifecycle states). Five full template examples with extensive fictional content is excessive — one template with brief variations would suffice. The 'Core Concepts' section is entirely unnecessary for Claude. | 1 / 3 |
Actionability | Provides fully concrete, copy-paste-ready templates with realistic examples, specific bash commands for adr-tools, complete directory structures, and detailed checklists. Every section contains actionable content rather than abstract descriptions. | 3 / 3 |
Workflow Clarity | The review checklist provides a clear before/during/after sequence, and the 'Creating a New ADR' steps are clear. However, the overall workflow for actually writing an ADR (from identifying the need to final acceptance) lacks explicit validation checkpoints — there's no feedback loop for draft quality or completeness verification before submission. | 2 / 3 |
Progressive Disclosure | Monolithic wall of content with five full templates inlined, each containing extensive example text. The templates, review process, and management sections should be split into separate referenced files. Everything is dumped into a single document with no references to external files for detailed content. | 1 / 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
- Dicklesworthstone/pi_agent_rust
- Commit
47823e3
- 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.