CtrlK
BlogDocsLog inGet started
Tessl Logo

architectural-review

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

60

Quality

70%

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

Quality

Content

82%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 strong, well-structured instruction skill: every pattern is grounded in concrete project invariants, the examples demonstrate real decisions, and the output format is fully specified. The only gaps are minor — a couple of statements restating common knowledge, no explicit ordering across the eight checks, and everything inlined in a single long file.

DimensionReasoningScore

Conciseness

The body is efficient and almost every token carries project-specific knowledge Claude cannot know (the protected-file table, dependency direction rules, template locations, the .squad/ leakage policy), with no padding of generic concepts. It sits at 4 rather than 5 because of minor trimmable over-explanation, e.g. 'Barrel files define the public API of a package' and 'Removing an export is a breaking change', which restate things Claude already knows.

4 / 5

Actionability

Guidance is fully concrete and executable: exact file paths in the protected-files table, the literal dependency direction to check ('squad-cli → depends on → squad-sdk'), a 5-step sweeping-refactor checklist with the exact marker string to scan for ('— zero dependencies'), five worked review examples with verdicts and recommendations, and a copy-paste output format template. This matches the top anchor of specific examples covering the common cases; as an instruction-only skill, absence of runnable code is not penalized.

5 / 5

Workflow Clarity

The eight patterns are each framed as explicit checklists ('Check every new import statement'), the sweeping-refactor pattern has a sequenced 5-step verification checklist, the examples demonstrate the reject/approve decision loop, and the Review Output Format section specifies verdicts, severities, and required fields. It does not reach 5 because there is no explicit ordering or triage flow connecting the eight checks into a single review pass (which check runs when, and what to do first when a PR matches several patterns).

4 / 5

Progressive Disclosure

No bundle files exist (no references/, scripts/, or assets/ directories), and the body is organized into well-labeled sections (Context, Patterns 1–8, Examples, Review Output Format, Anti-Patterns) with the one cross-reference — 'see architectural-proposals/SKILL.md' — clearly signaled and one level deep. It stays at 4 rather than 5 because the ~200-line body inlines everything, including the examples block and the protected-files table, some of which could be split into a reference file to keep the main file a leaner overview.

4 / 5

Total

17

/

20

Passed

Description

58%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 has a solid, concrete 'what' with four well-chosen architectural dimensions, but completely lacks an explicit 'when to use' trigger clause and offers a narrow set of natural trigger phrases. Adding a 'Use when...' sentence with common synonyms (pull request, code review, refactoring) would raise both completeness and trigger-term quality.

Suggestions

Append an explicit trigger clause, e.g. 'Use when reviewing pull requests that add modules, change imports across package boundaries, modify barrel-file exports, or perform sweeping refactors.'

Add natural synonyms users would say — 'pull request', 'code review', 'refactoring', 'dependency changes' — so the skill triggers on phrasings other than 'PRs for architectural quality'.

Sharpen distinctiveness from general code-review skills by naming the signals that select this skill over them (e.g. 'structural changes like new abstractions or cross-package imports').

DimensionReasoningScore

Specificity

The description names the domain ("review PRs for architectural quality") and lists several concrete focus areas — "module boundaries, dependency direction, export surface, pattern consistency" — which matches the anchor for several specific actions with minor gaps. It falls short of a 5 because it presents one action (review) with dimensions rather than the comprehensive multi-action coverage of the top anchor, and is above a 3 because the dimensions listed are concrete, not generic.

4 / 5

Completeness

The 'what' is clear (review PRs for architectural quality across four named dimensions) but there is no 'Use when...' clause or equivalent explicit trigger guidance anywhere in the description, which caps completeness at 3 per the judging guidelines. It is above a 2 because the 'what' half is concrete and multi-part, not vague.

3 / 5

Trigger Term Quality

Relevant keywords like "review PRs" and "architectural quality" are present, but common variations users would naturally say — "pull request", "code review", "refactor", "dependencies" as a standalone trigger — are missing, matching the 'some relevant keywords but missing common variations or synonyms' anchor. It is above a 2 because the terms present are natural, not jargon, and below a 4 because the vocabulary is narrow for such a broad trigger surface.

3 / 5

Distinctiveness Conflict Risk

The scope is mostly distinct — architectural review (boundaries, dependency direction, export surface) is distinguishable from general code-review, testing, or security-review skills, and the named dimensions narrow the niche. It does not reach 5 because 'review PRs' overlaps with any general PR-review skill and the description does not include trigger phrasing that would disambiguate which skill should fire for a routine PR review.

4 / 5

Total

14

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

15

/

16

Passed

Repository
bradygaster/squad
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.