Designing a SKILL.md-Driven Code Review Agent

AI-assisted coding has transformed development speed. But it's created an unexpected problem: as implementation velocity skyrockets, code review workload explodes. Without automated review support, human reviewers can't keep pace with PR volume.

This article walks you through building a code review agent centered on SKILL.md—a practical automation that actually understands your team's design principles, not just generic linting rules. You'll learn to structure a review system that catches real problems while earning team trust.

The Growing Code Review Bottleneck

Before AI assistance became mainstream, code review and implementation were roughly equal efforts. Today, that balance has shattered. A developer using GitHub Copilot or Claude Code can write 5–10x more code, faster.

Yet existing automated review tools (GitHub Copilot Review, GitLab Duo) hit a wall:

• They don't know your project's rules — Class naming conventions, responsibility separation philosophy, your team's approach to type safety—all invisible to generic tools
• They can't judge design — Why you chose a particular architecture, where you're willing to trade off performance for clarity—lost
• Knowledge disappears — The same code smell gets flagged again and again, because lessons aren't captured anywhere

A SKILL.md-driven code review agent solves this. It externalizes team knowledge into a living document, making review decisions reproducible, auditable, and scalable.

Architecture Built Around SKILL.md

SKILL.md is Cowork's (Anthropic's official CLI) standard format for capturing team workflows and decision frameworks in Markdown. Apply it to code review, and you gain:

Folder Structure

.github/
├── instructions/
│   ├── CODE_REVIEW_PRINCIPLES.md     ← Core design philosophy
│   ├── NAMING_CONVENTIONS.md         ← Naming and structure rules
│   └── ARCHITECTURE_RULES.md         ← Architectural constraints
├── skills/
│   └── code-review/
│       ├── SKILL.md                  ← Review agent workflow
│       ├── good-review.md            ← Quality review examples
│       └── bad-review.md             ← Anti-patterns to avoid
└── agents/
    └── code-reviewer.agent.md        ← Agent definition (orchestration)

Why Center on SKILL.md?

1. Readability — Plain Markdown is approachable for non-engineers
2. Version control — Git tracks changes; commit messages explain why
3. Team onboarding — New members see exactly how the team reviews code
4. Reusability — The same guide can power PR reviews, architecture reviews, security audits, and more

A Nine-Step Review Process

Production-quality code review follows a structured pipeline. Each step owns a specific concern; together they build confidence in the code.

Step 1: Diff Detection

Input: PR metadata (files, line counts, change summary)
Task: Extract git diff; identify significant changes
Output: List of changed files and scope

Step 2: Load Context

Task: Read .github/instructions/CODE_REVIEW_PRINCIPLES.md
Goal: Understand project constraints, team philosophy, known risks

Step 3–4: Logic Review & Bug Detection

Step 3: Implementation Review
  ✓ Is the logic sound?
  ✓ Are edge cases handled?
  ✓ Is the type safety appropriate?

Step 4: Bug Hunting
  ✓ Null reference risks?
  ✓ Resource leaks?
  ✓ Race conditions?

Step 5–6: Integrity & Impact Analysis

Step 5: File Integrity
  ✓ Import/export consistency
  ✓ No circular dependencies?

Step 6: Blast Radius
  ✓ What other modules might break?
  ✓ Is test coverage adequate?

Step 7–9: Compliance, Quality, Reporting

Step 7: Requirement Fit
  ✓ Does code match PR description?
  ✓ Do tests cover the spec?

Step 8: Quality Checks
  ✓ Performance implications?
  ✓ Security concerns?

Step 9: Report & Communicate
  ✓ Organize findings by severity
  ✓ Post comments to PR
  ✓ Highlight actionable items

The Critical Constraint: Read-Only

Your agent suggests fixes, but never auto-commits them. Why?

• Unreviewed changes introduce risk
• Developers miss learning opportunities
• Code ownership becomes fuzzy
• Trust erodes if the bot makes mistakes

Designing Quality Guides

To keep suggestions sharp and helpful, define "good feedback" and "bad feedback" explicitly.

Inside good-review.md

## Anatomy of a Good Review Comment

1. **The Problem** — What's wrong (concisely)
2. **The Impact** — What breaks if left unfixed
3. **The Rationale** — Why (cite ARCHITECTURE_RULES.md)
4. **The Fix** — Concrete alternative code

## Example: Type Safety

**Problem**: `productId` is `string | number` when passed to the function

**Impact**: Database queries become vulnerable to injection attacks.
         Type checker can't guarantee correctness, risking runtime errors.

**Rationale**: ARCHITECTURE_RULES.md #3—"All external inputs must be
             explicitly type-narrowed before use."

**Suggested Fix**:
```typescript
const productId = parseProductId(req.query.id);
function parseProductId(input: unknown): ProductId {
  if (typeof input !== 'string') throw new Error('Invalid product ID');
  return new ProductId(input);
}

### Inside bad-review.md

What Kills Feedback Credibility

❌ Personal Preference "I don't like how you wrote this"

❌ Vague Complaints "This logic is complicated" (What's complicated? How would you improve it?)

❌ Unmeasured Claims "Performance is bad" (Compared to what? How slow?)

❌ Out of Scope Flagging unrelated code that wasn't changed

✅ Concrete Grounding "ARCHITECTURE_RULES.md #7 requires..."

✅ Measurable Impact "This loop queries the DB once per item (N+1). At current scale: 500ms → 5 seconds latency."

## Custom Instructions: Injecting Team Knowledge

In SKILL.md's custom checklist, enumerate project-specific review items.

```markdown
## Custom Checklist

### Class Design

- [ ] Class name is a **noun only** (no verbs)
  - ✅ `UserRepository`, `PaymentProcessor`
  - ❌ `UserHandler`, `ProcessPayment`

- [ ] One responsibility per class (SOLID)
  - Does the PR description explain why, if it breaks this rule?

- [ ] Public methods ≤ 3
  - Overly broad interfaces invite misuse

### Type Safety

- [ ] No `any` type (use `@ts-ignore` comment if unavoidable)
- [ ] Leverage `??` and `?.` for nullish values
- [ ] External API calls must validate response shape

### Testing

- [ ] Logic changes include new or modified tests
- [ ] Complex branches (3+ levels of nesting) are tested

### Documentation

- [ ] Public APIs have JSDoc (params, return, throws)
- [ ] Non-obvious implementations have comments explaining intent

Feed these checklist items into your agent's system prompt, and you've transferred team judgment into automation.

Looking back and Next Steps

A SKILL.md-driven code review agent is the scalable answer to the AI implementation explosion. By making team knowledge explicit, you gain:

• Consistency — Same criteria, every PR
• Transparency — Rules are visible; pushback is easy
• Growth — Feedback patterns feed back into SKILL.md for the next cycle

The next frontier is CI/CD integration: PR created → agent reviews automatically → severity-ranked suggestions posted as comments. That requires careful handling of severity definitions, false positive management, and clear human-AI roles.

That's what the second article covers—moving from architecture to production quality.