architecture-decision

Creates an Architecture Decision Record (ADR) documenting a significant technical decision, its context, alternatives considered, and consequences. Every major technical choice should have an ADR.

Quality

72%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

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

Quality

Content

77%

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

The body is highly actionable with a clear, well-validated multi-step workflow, but it is a long monolithic file that could benefit from splitting large templates into reference files and tightening verbose mockup blocks.

Suggestions

Move the full ADR markdown template (Step 5) and the reusable warning-block scaffolds into a references/ file (e.g. references/adr-template.md) referenced one level deep, reducing SKILL.md to an overview.

Tighten or condense the repeated ⚠️ mockup blocks and AskUserQuestion scaffolding to cut tokens without losing the operational detail.

Confirm the referenced project paths (e.g. .claude/docs/director-gates.md, docs/engine-reference/) are real, or mark them as expected project layout so the navigation is clearly signaled.

Dimension	Reasoning	Score
Conciseness	The skill is mostly operational guidance rather than concepts Claude already knows, but at ~450 lines it includes verbose mockup/warning blocks and repeated prompt scaffolding that could be tightened, fitting the "mostly efficient but could be tightened" anchor.	2 / 3
Actionability	Provides concrete file paths (e.g. docs/registry/architecture.yaml), a full ADR markdown template, exact AskUserQuestion prompts, and specific spawn instructions — fully executable and copy-paste ready.	3 / 3
Workflow Clarity	Steps 0–6 are clearly sequenced with explicit validation checkpoints (BLOCKING gates, review-mode checks, GDD sync check, write approval, registry-append logic), including feedback loops for the destructive write operations the guidelines call out.	3 / 3
Progressive Disclosure	No bundle files exist (references/scripts/assets all absent) and SKILL.md is monolithic; the large inline ADR template and warning-block scaffolding could be split into signaled one-level-deep reference files, fitting the "some structure but content that should be separate is inline" anchor.	2 / 3
	Total	10 / 12 Passed

Description

67%

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 clearly states what the skill does and names a distinct, well-scoped niche, but it lacks an explicit "Use when..." trigger clause and natural trigger-term coverage, which caps completeness and trigger quality.

Suggestions

Add an explicit trigger clause such as "Use when making or documenting a significant technical decision, or when the user asks for an ADR / architecture decision record."

Include natural trigger variations users would say (e.g., "ADR", "architecture decision record", "document a technical decision", "record a design decision") to improve trigger-term coverage.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — "documenting a significant technical decision, its context, alternatives considered, and consequences" — matching the anchor for naming several specific actions rather than vague language.	3 / 3
Completeness	The "what" is clear, but the "when" is only implied by "Every major technical choice should have an ADR" rather than an explicit "Use when..." clause, which the guidelines cap at 2.	2 / 3
Trigger Term Quality	Contains relevant keywords ("Architecture Decision Record (ADR)", "technical decision") but misses common natural variations and lacks an explicit trigger phrase, fitting the "some relevant keywords but missing common variations" anchor.	2 / 3
Distinctiveness Conflict Risk	"Architecture Decision Record (ADR)" is a distinct niche with clear triggers unlikely to overlap with other skills, matching the clear-niche anchor.	3 / 3
	Total	10 / 12 Passed

Validation

87%

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 — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	14 / 16 Passed

Repository: Donchitos/Claude-Code-Game-Studios
Path: .claude/skills/architecture-decision/SKILL.md
Commit: 984023d

Reviewed: 3 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.