How to Build a Code Review Agent Skill: From Skeleton to Cost‑Effective Localization (Part 2)

Localizing the Skill

The skeleton consists of SKILL.md, reference.md, and .mdc. Localization binds three elements: architecture conventions, coding standards, and context routing. The first two decide what to check; the third decides which files to load at runtime.

1. Deriving Architecture Checks

Using the COLA rule adapter → application → domain ← infrastructure, combine with real team pitfalls to produce executable checks.

Dependency direction: enforce one‑way layer dependencies; scan imports to detect reverse dependencies.

Gateway abstraction: flag direct injection of Mapper implementations in services.

Domain zero‑dependency: ensure domain packages do not import Spring framework packages.

Entity usage: verify write operations use Entity methods; avoid creating Entity classes for pure queries.

Layer data transfer: check method signatures use the correct data objects per layer.

2. Deriving Coding‑Standard Checks

Prohibit field injection with @Autowired or @Resource.

Require @Transactional to specify rollbackFor = Exception.class.

In MapStruct converters, mark audit fields ( id, createTime, updateTime) as ignore.

Enforce naming conventions: class names PascalCase, DTO suffix uppercase, URLs kebab‑case, JSON keys snake_case.

Controller exception handling: avoid unnecessary try‑catch; Service exceptions must carry business semantics.

Log policy: ensure critical operations are logged and sensitive data is not logged.

3. Business‑Logic Implementation Checks

Monetary fields must use BigDecimal with a defined RoundingMode; forbid double/float.

Write APIs that affect funds must be idempotent (business key or token).

State changes must go through Entity methods; direct field assignment is prohibited.

Multi‑tenant queries must filter by tenantId; full‑table queries without tenant filter are forbidden.

Concurrent updates to shared resources require optimistic lock (version) or distributed lock.

External API calls must have timeout, retry, and fallback policies and must not be invoked inside a transaction.

4. Unit‑Test Requirements and Quality Gates

Core service methods need unit tests named should_ExpectedBehavior_when_Precondition, each testing a single behavior.

Each test contains a single assertion; avoid multiple assertions in one @Test.

Mock only external dependencies (Gateway, external API); do not mock the class under test.

Use AssertJ for fluent assertions; avoid plain assert without exception checks.

Coverage: ≥70% for core modules, ≥80% for new code.

SonarQube must report no Blocker or Critical issues.

All changes must pass the code-review Skill without unresolved Critical items.

5. Context Routing: File Loading Order

Step 1: Load reference.md (project‑level quick‑lookup).
Step 2: Load layer‑specific .mdc files based on package path (e.g., adapter-web.mdc, application-service.mdc, domain-layer.mdc, infrastructure-impl.mdc, mapstruct-convertor.mdc, unit-test.mdc).
Step 3: Load common rules (cola-architecture.mdc + java-coding-style.mdc).

This selective loading reduces token consumption.

Token Consumption Breakdown

Input tokens (≈75‑85%): SKILL.md ≈ 3.5 K tokens. reference.md ≈ 1.5‑2 K tokens (loaded every review).

Code under review: 5‑10 K tokens for 3‑5 files.

Relevant .mdc files: 3‑6 K tokens.

Automatically read module context: 2‑4 K tokens.

System prompt and history: 2‑2.5 K tokens.

Output tokens (≈15‑25%): structured review report ≈ 3‑5 K tokens.

A medium‑size review (3‑5 files, 500‑800 lines) totals roughly 20 K‑34 K tokens.

Cost Estimate

Using mainstream models, a single review costs about $0.10‑$0.15 (≈ ¥0.5‑¥1). Ten reviews per day over 22 workdays yields a monthly expense of roughly ¥150‑¥230.

Cost‑Optimization Keys

Do not simplify checks merely to save tokens; vague checks reduce output quality and raise overall cost.

Prioritize context routing – load only the .mdc files relevant to the code layer.

Keep reference.md concise; it is loaded every time.

Limit the review scope to the Git diff rather than the whole module.

Extending the Pattern to Other Skills

The skeleton ( SKILL.md, reference.md, .mdc) remains identical; only the content changes. For example, a write‑prd skill replaces trigger words (“CR”, “review”) with “PRD”, “需求文档” and adjusts step definitions accordingly.

Common Pitfalls When Writing Skills

Listing only a name without a concrete violation signal (e.g., “check dependency injection”) is ineffective; the Agent needs the exact annotation to look for.

Putting everything into SKILL.md – keep process and dimensions there, layer‑specific rules in .mdc, and project‑specific patterns in reference.md.

Omitting severity principles causes the Agent to flag every suspicion as Critical.

Missing an output template leads to inconsistent report formats.

Attempting to cover all dimensions in the first version; start with 3‑4 core checks and expand gradually.

Conclusion

A Code Review Skill consists of three cooperating files ( SKILL.md, reference.md, .mdc) and follows a four‑step localization process: derive checks from architecture, coding, and business constraints; map them to team‑specific pitfalls; encode executable signals; and route context efficiently. Starting with the code‑review skill forces teams to formalize architecture and coding standards, creating lasting, maintainable assets.