CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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.

Quality

79%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/architecture-decision-records/SKILL.md

The canonical home for this skill is architecture-decision-records in rmyndharis/antigravity-skills

SKILL.md
Quality
Evals
Security

Quality

Content

71%Weight 40%Scale 1-5

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

The content is highly actionable, with complete templates, executable tooling commands, and concrete checklists that leave no ambiguity about how to produce and manage ADRs. Its weaknesses are length (fully-worked example ADRs that could be skeletal) and the absence of any progressive disclosure: everything is packed into a single long file instead of splitting templates into referenced files. The core workflow steps are also terser than the detailed review guidance around them.

Suggestions

Move the five ADR templates into separate reference files (e.g., references/templates/madr.md) and keep one short annotated skeleton plus per-template pointers in SKILL.md, cutting context load to the overview level.

Reduce Templates 1 and 5 to skeletal structures with brief inline placeholders, preserving the format demonstration without ~90 lines of project-specific example content.

Expand the 'Instructions' section into a sequenced workflow with explicit checkpoints (e.g., draft from template -> verify options/cons sections are balanced -> PR review per checklist -> update index), mirroring the validation detail already present in the Review Process.

DimensionReasoningScore

Conciseness

The body runs ~437 lines with two fully-worked ~90-line example ADRs (PostgreSQL and event-sourcing RFC) whose project-specific detail (PgBouncer, migration phases, event schemas) goes beyond demonstrating the format. There is little explanation of concepts Claude doesn't need, but the templates could be tightened to skeletal structures, matching 'mostly efficient but could be tightened' rather than the minor-trim profile of a 4.

3 / 5

Actionability

Five complete, copy-paste-ready templates (MADR, lightweight, Y-statement, deprecation, RFC), executable adr-tools commands ("adr init docs/adr", "adr new -s 3 ..."), a concrete directory layout, an index table format, and a filled-in review checklist. Guidance is fully executable and covers the common cases, matching the top anchor; a 4 would imply gaps in the concrete material, which are not present.

5 / 5

Workflow Clarity

The creation workflow ("Copy template.md to NNNN-title-with-dashes.md... Submit PR... Update this index") and the three-phase Review Checklist give clear sequences with checkpoints, and no destructive/batch cap applies. However, the main 'Instructions' section is a terse 4-step list whose steps are more abstract than sequenced, leaving minor validation gaps versus the explicit validate/fix/retry profile of a 5.

4 / 5

Progressive Disclosure

There are no bundle files at all; all five templates, management, review, and best-practices content are inlined in one 437-line SKILL.md under clear headers. Structure is good, but ~250 lines of template content that clearly belongs in separate reference files (e.g., templates/madr.md, templates/rfc.md) is inlined, matching 'content that should be separate is inline' rather than the mostly-appropriate placement of a 4.

3 / 5

Total

15

/

20

Passed

Description

78%Weight 40%Scale 1-5

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

The description is well-constructed with an explicit 'Use when...' clause covering multiple trigger scenarios and a clear statement of what the skill does. Its main weaknesses are limited action specificity (only 'write and maintain') and a small amount of generic phrasing ('following best practices'). Trigger term coverage is good though not exhaustive of natural synonyms.

Suggestions

Replace the generic phrase 'following best practices for technical decision documentation' with 1-2 more concrete capabilities, e.g., 'from templates like MADR, Nygard, and Y-statement formats, including lifecycle management and indexing'.

Add common user synonyms to the trigger clause, such as 'design decisions', 'decision records', or 'documenting rationale/trade-offs', to broaden natural-term coverage.

Clarify the boundary against general documentation skills by scoping triggers to architecture-level decisions (e.g., 'Use when a decision will shape system structure or be hard to reverse').

DimensionReasoningScore

Specificity

"Write and maintain Architecture Decision Records (ADRs)" names the domain and two concrete actions (write, maintain), but "following best practices for technical decision documentation" is generic filler and no further specific capabilities are listed. This matches the anchor for 1-2 concrete actions without comprehensive coverage; it does not reach 4, which requires several specific actions with only minor gaps.

3 / 5

Completeness

Clearly answers 'what' ("Write and maintain Architecture Decision Records (ADRs)") and explicitly answers 'when' with concrete trigger phrases ("Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes"). Both halves are explicit with multiple triggers, matching the top anchor; a 4 would require the 'when' to be less explicit or specific than it is here.

5 / 5

Trigger Term Quality

Includes strong natural terms users would say: "Architecture Decision Records (ADRs)", "technical decisions", "architectural choices", "decision processes". A few common variations are missing (e.g., "design decisions", "decision record", "rationale"), so it fits 'good keyword coverage; a few natural terms missing' rather than the comprehensive-synonym coverage of a 5.

4 / 5

Distinctiveness Conflict Risk

The ADR/decision-record niche with its explicit acronym is largely distinct, but "documenting significant technical decisions" and "establishing decision processes" leave minor overlap risk with general documentation and process-design skills. It is more distinct than the 'somewhat specific but could still overlap' anchor (3), yet not the minimal-conflict clarity of a 5.

4 / 5

Total

16

/

20

Passed

Validation

93%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

relative_links

Relative link issues: 4 missing

Warning

Total

15

/

16

Passed

Repository

agent-skills-hub/agent-skills-hub

Path

skills/architecture-decision-records/SKILL.md

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.