CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

brooks-review

PR code review that surfaces decay risks, design smells, and maintainability issues with concrete Symptom → Source → Consequence → Remedy findings, drawing on twelve classic engineering books. Triggers when: user asks to review code, check a PR, shares a diff or pastes code asking...

Quality

73%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/brooks-review/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

60%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-organized, appropriately cautious about scope creep, and token-efficient, but it delegates its entire analytical substance to `pr-review-guide.md`, which is absent from the bundle. As shipped, the skill tells Claude to follow checks and named risks it cannot actually read.

Suggestions

Bundle `pr-review-guide.md` under `references/` (or inline its checks and named risks into SKILL.md) so the repeatedly referenced analysis content actually resolves — currently every mention of 'the guide' is a dangling pointer.

Replace the 'When to Use' section's verbatim copy of the frontmatter description with a short, distinct usage note; the duplication carries the description's mid-sentence truncation ('pastes code asking...') and a 'pR' typo into the body.

Spell out at least one concrete example check per category (change propagation, duplication, complexity) in the body so the skill remains actionable even before the guide is loaded.

DimensionReasoningScore

Conciseness

The body is lean and assumes Claude's competence ("A large diff or long function is a review lead, not by itself a demonstrated defect"), with no re-teaching of known concepts. The only waste is the "When to Use" section repeating the frontmatter description nearly verbatim, including its "pastes code asking..." truncation and the "pR" typo, so it is not a 5.

4 / 5

Actionability

Concrete elements exist — the finding record format ("Symptom (source location), Source (verified contract or principle), Consequence (reachable effect), and Remedy (small actionable fix)") and the report format ("mode `PR Review`, scope, findings by severity, checks actually run, limits and next action") — but the core analysis instructions are delegated to `pr-review-guide.md` ("the guide's change propagation, cognitive overload, duplication, complexity, dependency and domain checks"), and that file is not present in the bundle, so the actual checks cannot be executed as written. This is 'some concrete guidance but incomplete; missing key details', not the minimal-hints level of 2.

3 / 5

Workflow Clarity

Five clearly numbered steps with an epistemic checkpoint ("Separate confirmed findings from questions and unavailable evidence") and an explicit terminal condition ("No findings is a valid result"). Not 5 because there is no explicit verify/re-validate loop, and step 2's checks ("when applicable") depend on the missing guide, leaving a gap in what is actually run.

4 / 5

Progressive Disclosure

The body is cleanly sectioned and the one reference is clearly signaled ("Read `pr-review-guide.md` for the retained analysis process"), but the bundle contains no `references/` directory and no `pr-review-guide.md` — the reference is dangling, and the checks, named risks, and evidence the body repeatedly points to (four separate mentions of "the guide") have no home in the skill. The disclosure structure collapses to a broken pointer rather than a working overview-to-detail split.

2 / 5

Total

13

/

20

Passed

Description

75%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 specific, third-person description with an explicit trigger clause and a clearly differentiated maintainability-review niche. Its main defect is that it ends mid-sentence ('pastes code asking...'), truncating the trigger list and capping completeness and keyword coverage below the top anchors.

Suggestions

Complete the truncated trigger clause — 'pastes code asking...' cuts off mid-phrase; finish the list (e.g., 'pastes code asking for feedback, a review, or a sanity check').

Add natural synonyms and variations to the trigger list — 'code review', 'review my PR/pull request', 'look over these changes' — to broaden keyword coverage.

Replace the vague flavor phrase 'drawing on twelve classic engineering books' with what it concretely does (e.g., 'checks diffs against named design-smell and decay-risk rules').

DimensionReasoningScore

Specificity

It names the domain and several concrete actions with a structured output: "PR code review that surfaces decay risks, design smells, and maintainability issues with concrete Symptom → Source → Consequence → Remedy findings". Not 5 because "drawing on twelve classic engineering books" is flavor rather than a capability and the action coverage stops at 'surfacing findings'; not 3 because it lists more than 1-2 concrete actions.

4 / 5

Completeness

Both elements are explicit: a clear 'what' ("PR code review that surfaces decay risks, design smells, and maintainability issues...") and an explicit 'when' clause ("Triggers when: user asks to review code, check a PR, shares a diff or pastes code asking...") that qualifies as equivalent trigger guidance, so the missing-'Use when' cap does not apply. Not 5 because the 'when' clause is literally truncated mid-phrase with an ellipsis, leaving the trigger list incomplete.

4 / 5

Trigger Term Quality

Natural phrases users would actually say are present: "user asks to review code, check a PR, shares a diff or pastes code asking...". Not 5 because the trigger clause is cut off mid-sentence and common synonyms like 'code review', 'pull request', or 'look over my changes' are missing; clearly above 3's 'missing common variations'.

4 / 5

Distinctiveness Conflict Risk

The niche is distinct — decay-risk/maintainability review with a fixed Symptom → Source → Consequence → Remedy finding structure — but the triggers "review code" and "check a PR" are broad and would overlap with any general code-review skill, matching 'mostly distinct; minor overlap risk with closely related skills' rather than the minimal-conflict level of 5.

4 / 5

Total

16

/

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

BigSimmo/Communication

Path

.agents/skills/brooks-review/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.