architecture

Create or evaluate an architecture decision record (ADR). Use when choosing between technologies (e.g., Kafka vs SQS), documenting a design decision with trade-offs and consequences, reviewing a system design proposal, or designing a new component from requirements and constraints.

Quality

77%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./engineering/skills/architecture/SKILL.md

Quality

Content

68%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 well structured around a concrete, copy-paste-ready ADR template with sensible connector integration and a good hand-off to the system-design skill. Its weakest point is workflow clarity: the process is implicit in the output format rather than stated as steps, with no checkpoint to validate constraints or option coverage before drafting the ADR.

Suggestions

Add a short numbered workflow before the output format (e.g., 1. Extract constraints and non-functional requirements, 2. Confirm them with the user, 3. Enumerate 2-3 named options, 4. Assess each against the option table, 5. Draft the ADR) so the sequence is explicit rather than implied by the template.

Include a brief filled-in example of the Trade-off Analysis and Consequences sections, since those placeholders currently give no signal of expected depth or reasoning style.

Trim the Tips section to the one genuinely non-obvious item (stating constraints upfront) and drop restatements of knowledge Claude already has, such as the value of non-functional requirements.

Dimension	Reasoning	Score
Conciseness	The body is lean and template-driven, but the Tips section includes advisory filler ("Even if you're leaning one way, I'll give a more balanced analysis") and restates knowledge Claude already has about non-functional requirements.	4 / 5
Actionability	The full ADR markdown template and the concrete mode examples are directly usable, but placeholder sections like "[Key trade-offs between options with clear reasoning]" lack a worked example showing what good output looks like.	4 / 5
Workflow Clarity	No explicit step sequence exists (constraints gathering, option enumeration, assessment, drafting); sequence is only implicit in the template's section order, and there are no validation checkpoints such as confirming constraints with the user before recommending an option.	3 / 5
Progressive Disclosure	Sections are well organized and the detailed frameworks are correctly deferred one level to the system-design skill, but the ~80-line body exceeds the simple-skill exception and the external skill pointer is a single brief mention rather than clearly signposted navigation.	4 / 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.

A strong description with an explicit what-and-when structure and natural trigger phrases covering the main use modes. Its main limitation is thin capability enumeration — only 'create or evaluate' — which leaves the skill's concrete outputs undersold relative to its clear triggering.

Suggestions

Enumerate the concrete deliverables (e.g., 'produce a structured ADR with options-considered tables, trade-off analysis, consequences, and action items') instead of stopping at 'create or evaluate'.

Add common trigger synonyms such as 'architecture review', 'tech selection', or 'design proposal' alongside the existing scenario phrases.

Dimension	Reasoning	Score
Specificity	"Create or evaluate an architecture decision record (ADR)" names the domain plus exactly two concrete actions, but lists no further specific capabilities, matching the '1-2 concrete actions, not comprehensive' anchor rather than the 'several specific actions' anchor.	3 / 5
Completeness	A clear 'what' (create or evaluate an ADR) is paired with an explicit "Use when..." clause containing four concrete trigger scenarios, matching the top anchor exactly.	5 / 5
Trigger Term Quality	Natural user phrases like "choosing between technologies (e.g., Kafka vs SQS)", "reviewing a system design proposal", and "designing a new component from requirements and constraints" give good coverage, though common variants like "architecture review" or "tech selection" are missing.	4 / 5
Distinctiveness Conflict Risk	The ADR/design-decision niche has distinct triggers, but "designing a new component from requirements and constraints" overlaps with the system-design domain the skill body itself defers to, so minor overlap risk remains.	4 / 5
	Total	16 / 20 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
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning
relative_links	Relative link issues: 1 suspicious	Warning

	Total	14 / 16 Passed

Repository: anthropics/knowledge-work-plugins
Path: engineering/skills/architecture/SKILL.md
Commit: 8444efc

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