architecture
Architecture decision framework — tradeoffs, criteria, anti-patterns, and escalation rules
64
55%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./dot_config/opencode/skill/architecture/SKILL.mdQuality
Discovery
32%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 identifies a domain (architecture decisions) and lists related concepts but fails to specify concrete actions the skill performs and entirely lacks a 'Use when...' clause. It reads more like a topic label than a functional skill description, making it difficult for Claude to reliably select this skill over others in a large skill set.
Suggestions
Add an explicit 'Use when...' clause with trigger scenarios, e.g., 'Use when the user asks about architecture decisions, design tradeoffs, choosing between technical approaches, or needs help writing ADRs.'
Replace abstract nouns with concrete actions, e.g., 'Evaluates architecture options, documents trade-off analyses, identifies anti-patterns in system design, and recommends escalation paths for unresolved decisions.'
Include common user-facing trigger terms and synonyms like 'ADR', 'design decision', 'system design', 'technical choice', 'architecture review' to improve matching.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain ('architecture decision') and lists some relevant concepts ('tradeoffs, criteria, anti-patterns, escalation rules'), but these are abstract nouns rather than concrete actions. It doesn't specify what the skill actually does (e.g., 'evaluates architecture options', 'documents decisions in ADRs'). | 2 / 3 |
Completeness | Describes a loose 'what' (architecture decision framework) but has no 'when' clause or explicit trigger guidance. Per the rubric, a missing 'Use when...' clause caps completeness at 2, and the 'what' itself is weak enough to warrant a 1. | 1 / 3 |
Trigger Term Quality | Contains some relevant keywords like 'architecture decision', 'tradeoffs', 'anti-patterns', and 'escalation rules' that a user might mention, but misses common variations like 'ADR', 'design decisions', 'system design', 'technical decisions', or 'architecture review'. | 2 / 3 |
Distinctiveness Conflict Risk | The term 'architecture decision framework' provides some specificity, but 'tradeoffs' and 'criteria' are generic enough to overlap with other decision-making or design skills. It's somewhat distinguishable but not clearly carved out. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured architecture decision skill with strong actionability — the agent prompt template is concrete, specific, and immediately usable. The workflow is clear with appropriate escalation gates. The main weakness is that the inline prompt template is quite long, and the content could benefit from splitting reference tables (criteria, anti-patterns) into separate files to improve token efficiency and progressive disclosure.
Suggestions
Consider moving the decision criteria table and anti-patterns table to a separate reference file (e.g., CRITERIA.md) and linking to it from the prompt template to reduce token cost when the skill is loaded.
Trim the 'When to Load This Skill' section — Claude can infer most of these triggers from the skill description; keep only the non-obvious signals.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is reasonably efficient but includes some content that could be tightened — the decision criteria table and anti-patterns table are useful reference material but make the prompt template quite long. The 'When to Load This Skill' section is helpful but slightly verbose for Claude's capabilities. | 2 / 3 |
Actionability | The skill provides a fully concrete, copy-paste-ready agent prompt template with specific tables, criteria, anti-patterns, and output format. The workflow steps are explicit (gather context, spawn agent, present output, handle escalation), and the prompt includes specific tools to use (webfetch, context7, linear). | 3 / 3 |
Workflow Clarity | The 4-step workflow is clearly sequenced with an explicit escalation checkpoint (step 4). The agent prompt itself has a clear output format (4 ordered sections) and explicit escalation criteria that serve as validation gates before proceeding with a recommendation. | 3 / 3 |
Progressive Disclosure | The skill is a single file with all content inline, including a lengthy prompt template. The decision criteria table, anti-patterns table, and escalation rules could be referenced from separate files to keep the SKILL.md leaner. However, the content is well-organized with clear sections and headers. | 2 / 3 |
Total | 10 / 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
- athal7/dotfiles
- Commit
07d79b6
- 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.