CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

architecture-decision

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

Quality

68%

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

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 body is a well-structured orchestrator skill: a clear 0–6 phase sequence with per-phase delegation to real, well-signaled one-level-deep reference files, concrete output templates, and thoughtful guards (no-argument guard, compaction re-reads, never-unblock-stories rule). Its main weakness is verbosity in a few policy-explanation passages that could be trimmed or pushed into references.

Suggestions

Move the docs.density prose-depth detail (terse/balanced/thorough definitions) into references/5-generate.md, keeping only a one-line pointer in the body since that is where prose is actually written.

Trim the closing rationale parenthetical and the /architecture-review explanation to one imperative line each — the rule is what matters, not the justification.

DimensionReasoningScore

Conciseness

The body is project-specific rather than explaining known concepts, but several passages could be tightened or moved to references: the six-line docs.density prose-depth explanation, the closing rationale parenthetical ('Acceptance has consequences enforced across many skills...'), and the explanatory expansion of the /architecture-review warning.

3 / 5

Actionability

Guidance is mostly executable — exact reference paths per step, exact quoted user-facing messages, a copy-paste widget format block, and explicit gate-file routing — with only minor gaps such as 'Scan docs/architecture/' lacking a specific command and executable detail living in the reference files.

4 / 5

Workflow Clarity

Steps 0–6 are clearly sequenced with explicit mode detection, a no-argument guard, compaction re-read instructions, and a closing checklist (required ADRs, prerequisites, all remaining options); validation/feedback loops are present but delegated to reference files rather than restated in the body.

4 / 5

Progressive Disclosure

The body is a clean orchestrator: all six cited references/*.md files exist in the bundle, each is signaled with 'Read X now and follow it' plus the condition for when to read it, and references are one level deep (they point to project docs, not to further skill files).

5 / 5

Total

16

/

20

Passed

Description

53%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 communicates a clear, bounded capability (ADR authoring with a defined section structure) in concise third-person form, but it omits any 'when to use' trigger guidance and ignores two of the skill's three modes (retrofit, accept). Trigger-term coverage relies on a single insider term ('ADR') with no synonyms.

Suggestions

Add a 'Use when...' clause with concrete triggers, e.g. 'Use when the user asks to document a technical or architecture decision, record trade-offs, or write an ADR.'

Include natural synonyms and variations users might say — 'architecture decision record', 'design decision', 'technical trade-off' — alongside 'ADR'.

Mention the retrofit and accept capabilities (e.g. '...or retrofit an existing decision from code, or record acceptance of a proposed ADR') so the description covers all three invocation modes.

DimensionReasoningScore

Specificity

Names the domain ('ADR documenting a technical decision') and its content components ('context, alternatives considered, consequences'), but the only action stated is 'Create' — the retrofit and accept modes the skill supports are absent, so coverage is not comprehensive.

3 / 5

Completeness

The 'what' is clear (create an ADR covering context, alternatives, consequences) but there is no 'Use when...' clause or equivalent trigger guidance, which caps completeness at 3 per the judging guidelines.

3 / 5

Trigger Term Quality

'ADR' and 'technical decision' are relevant keywords, but there are no common variations or synonyms such as 'architecture decision record', 'design decision', or 'trade-off', matching the anchor for some relevant keywords with missing variations.

3 / 5

Distinctiveness Conflict Risk

'Create an ADR' occupies a clear niche with minimal overlap risk against other skills, but without any trigger clause the description relies on the user already knowing the term ADR, so it is not fully at the distinct-triggers level.

4 / 5

Total

13

/

20

Passed

Validation

87%

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

CriteriaDescriptionResult

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

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.