architectural-review

How to review PRs for architectural quality — module boundaries, dependency direction, export surface, pattern consistency

Quality

72%

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 ./.copilot/skills/architectural-review/SKILL.md

Quality

Content

85%

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 and well-sequenced with concrete checklists, worked examples, and a copy-paste output format. Its main weakness is length and redundancy between the Patterns and Anti-Patterns sections.

Dimension	Reasoning	Score
Conciseness	The body assumes Claude's knowledge (no concept explanations) but runs long with redundancy — the protected-files table and its checklist repeat, and the Anti-Patterns section restates the Patterns — fitting the score-2 anchor of mostly efficient but could be tightened.	2 / 3
Actionability	It gives concrete rules ('SDK files must NEVER import from CLI'), specific file paths, a numbered 5-step refactor checklist, a copy-paste review output format, and worked example findings, matching the score-3 anchor of specific, copy-paste-ready guidance for an instruction-only skill.	3 / 3
Workflow Clarity	Review steps are sequenced (check patterns → findings → verdict) with explicit checklists and validation checkpoints such as the 5-step refactor list and the >20-file deletion red flag, matching the score-3 anchor of clear sequence with validation steps and checklists.	3 / 3
Progressive Disclosure	It is a single cohesive file with clearly organized sections (Context, Patterns, Examples, Output Format, Anti-Patterns), no deep nested references, and one appropriate pointer to the sibling proposals skill, matching the score-3 anchor of clear organization with easy navigation for a self-contained instruction skill.	3 / 3
	Total	11 / 12 Passed

Description

60%

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 about what architectural aspects to check but omits any explicit 'Use when' trigger and uses only a narrow set of natural keywords. Adding a trigger clause and broader trigger terms would raise completeness and trigger quality.

Suggestions

Add an explicit 'Use when reviewing PRs that...' trigger clause naming concrete PR signals (new modules, barrel-file changes, cross-package imports) so Claude knows when to invoke it.

Broaden trigger terms to include natural phrases like 'code review', 'architecture review', and 'dependency direction check' alongside the current technical terms.

Sharpen distinctiveness by contrasting with the sibling proposals skill inline (e.g., 'for reviewing existing PRs, not writing proposals') to reduce overlap with general review skills.

Dimension	Reasoning	Score
Specificity	The description enumerates four concrete review actions — 'module boundaries, dependency direction, export surface, pattern consistency' — matching the score-3 anchor that lists multiple specific concrete actions, rather than just naming the domain.	3 / 3
Completeness	It clearly states what the skill does but lacks any 'Use when...' trigger clause, so per the judging guideline completeness is capped at 2 (what present, when missing or only implied).	2 / 3
Trigger Term Quality	It includes some natural terms a user might say ('review PRs', 'architectural quality') but misses common variations like 'code review' or 'architecture review', fitting the score-2 anchor of some relevant keywords missing common variations.	2 / 3
Distinctiveness Conflict Risk	The architectural niche is reasonably specific, but 'review PRs' could overlap with a general PR/code-review skill and there is no trigger narrowing to prevent that, matching the score-2 anchor of somewhat specific but still overlapping.	2 / 3
	Total	9 / 12 Passed

Validation

93%

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

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: bradygaster/squad
Path: .copilot/skills/architectural-review/SKILL.md
Commit: e23dd92

Reviewed: 1 day 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.