CtrlK
BlogDocsLog inGet started
Tessl Logo

architecture-decision

Create an ADR documenting a technical decision: context, alternatives considered, consequences.

60

Quality

75%

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 ./.claude/skills/architecture-decision/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

77%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 body is an exceptionally actionable, rigorously validated workflow with copy-paste tool calls, explicit gates, refusal paths, and feedback loops at every risky step. Its weaknesses are structural: a monolithic 660-line SKILL.md with the ADR template and mode procedures inlined rather than in reference files, plus repeated design-rationale passages that pad the token budget.

Suggestions

Move the full ADR markdown template (Step 5) into a references/ file (e.g., references/adr-template.md) and keep only the section list and key rules inline; do the same for the retrofit and acceptance mode procedures to cut SKILL.md's inline weight.

State each guard's rationale once and reference it afterward — e.g., write the 'silent pass is indistinguishable from a check that never ran' / NOT-ASSESSED rule in one place and have the engine-validation, GDD-sync, and dependency checks cite it, trimming the repeated persuasive asides.

Fix the step numbering so "Write approval" and "Update Architecture Registry" are unambiguous sub-steps (e.g., 5.8/5.9) or top-level steps, rather than list items that visually collide with '## 5' and '## 6'.

DimensionReasoningScore

Conciseness

The body is dense with actionable directives but noticeably padded in its justificatory asides: "a silent pass is indistinguishable from a check that never ran" is argued separately at the engine-validation (5.5), GDD-sync (5.7), and dependency (Phase 0 step 3) sections, and the UNKNOWN-vs-None rationale appears in both acceptance mode and Step 4. It does not explain concepts Claude already knows, so it sits above the verbose anchor, but several rationale blocks could be halved without losing the guard.

3 / 5

Actionability

Guidance is copy-paste ready throughout: exact tool invocations (`Grep pattern="^## " path="docs/architecture/[adr-file].md" output_mode="content" -n`, the blocked-story Grep with glob and output_mode), verbatim AskUserQuestion prompts with option lists, concrete size thresholds (`Bash: wc -c`, ~50KB read policy), a full ADR markdown template, and exact registry append anchoring logic. Nearly every instruction names the tool, path, and expected output.

5 / 5

Workflow Clarity

Phases are explicitly sequenced (argument parse → engine context → numbering → registry-gated context gathering → collaborative design → generation → validation → write approval → registry update → closing) with validation checkpoints at every risky point: BLOCKING gates, refusal conditions (unaccepted dependencies, superseded ADRs, ambiguous glob matches), a three-outcome reporting rule for checks, revise-then-confirm feedback loops for specialist/TD reviews, and explicit user approval before any registry or file write. The only blemish is the confusing sub-numbering (a list-item "5. Write approval" and "6. Update Architecture Registry" nested inside section 5), which is cosmetic.

5 / 5

Progressive Disclosure

No bundle files exist (references/, scripts/, assets/ are all absent), and the ~660-line SKILL.md inlines substantial content that belongs in separate reference files — most notably the ~120-line ADR template and the full retrofit/acceptance procedures. Internal sectioning is good and external doc references (`.claude/docs/director-gates.md`, `workflow-modes.md`, `automation-modes.md`) are clearly signaled, but major content that should be split out is inline.

3 / 5

Total

16

/

20

Passed

Description

66%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 specific, third-person, and concrete about what the skill produces, with a distinct ADR niche and natural trigger terms. Its main flaw is the complete absence of any 'when to use' guidance, and secondarily the missing spelled-out form 'architecture decision record' for users who don't know the abbreviation.

Suggestions

Append a 'when' clause, e.g., 'Use when documenting an architecture decision, choosing between technical approaches, or when the user mentions ADRs, decision records, or trade-off documents.'

Spell out 'architecture decision record (ADR)' once and add synonyms like 'design decision' or 'technical trade-off' so the description triggers for users unfamiliar with the abbreviation.

Optionally mention the retrofit and accept modes (e.g., 'retrofit existing ADRs with missing sections; move ADRs from Proposed to Accepted') so the description covers all three of the skill's capabilities.

DimensionReasoningScore

Specificity

"Create an ADR documenting a technical decision: context, alternatives considered, consequences" names several concrete deliverables (the ADR itself plus its three content sections), matching the 'lists several specific actions; minor gaps' anchor. It falls short of 5 because the skill's retrofit and acceptance modes, engine-compatibility validation, and registry updates are entirely uncovered.

4 / 5

Completeness

The 'what' is clear and concrete — create an ADR capturing context, alternatives, and consequences — but there is no 'Use when...' clause or equivalent trigger guidance anywhere, so per the judging guideline completeness is capped at 3. It is not 2 because the 'what' half is fully explicit rather than vague.

3 / 5

Trigger Term Quality

"ADR", "technical decision", and "alternatives considered" are terms users would naturally say, giving good keyword coverage per the score-4 anchor. Not 5: it never spells out "architecture decision record" or offers synonyms like "design decision" or "trade-offs", so users who don't know the ADR abbreviation have weak trigger surface.

4 / 5

Distinctiveness Conflict Risk

ADR authorship is a distinct niche with dedicated terminology, and the description would not plausibly trigger general document or code skills — matching 'mostly distinct; minor overlap risk'. Not 5: it overlaps mildly with generic decision-documentation and architecture-review skills, and without trigger phrases the boundary relies on the ADR term alone.

4 / 5

Total

15

/

20

Passed

Validation

81%

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

Validation — 13 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

skill_md_line_count

SKILL.md is long (661 lines); consider splitting into references/ and linking

Warning

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

13

/

16

Passed

Repository
Donchitos/Claude-Code-Game-Studios
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.