DEV Community: alapha888

Teach Your Coding Agent to Review Code Without the Style Nitpicks

alapha888 — Thu, 01 Oct 2026 18:57:31 +0000

I asked my coding agent to review a 120-line pull request last month. It came back with 23 comments. Eighteen were about quote style, line length, and import order. It missed the SQL query built by string concatenation. It missed the database call inside the loop.

The review was technically thorough and completely useless. The dangerous stuff sailed through while the agent graded my taste in quotation marks.

That was the day I wrote down how I actually want code reviewed — and turned it into a skill the agent follows every time.

The review that got it wrong

Here's the kind of diff I'm talking about — a small Python helper, the sort of thing that shows up in every PR:

def process_orders(orders, db):
    results = []
    for order in orders:
        user = db.query("SELECT * FROM users WHERE id = " + str(order.user_id))
        results.append({
            "id": order.id,
            "total": order.total,
            "processed_at": int(time.time()) + 86400,
        })
    return results[0]["total"]

A free-form agent review of this tends to produce: "consider using double quotes consistently," "this function could use a docstring," "line 4 exceeds 88 characters." Meanwhile results[0]["total"] throws an IndexError on an empty order list, the user id is concatenated into raw SQL, and db.query runs once per order inside the loop. The three things that would page someone at 2am get outvoted by formatting opinions.

The problem isn't that the agent can't review code. It's that "review this code" is a vibe, not a procedure. Every session invents its own definition of what matters. So I wrote the definition down.

That's what an agent skill is: a SKILL.md file — frontmatter plus a step-by-step workflow — that lives in your agent's skills directory. When you ask the agent to do a matching task, it reads the skill and follows it. No re-prompting, no drift. (If you want the full version of this idea, my first post walks through the same pattern for commit messages.)

Five axes, in order

The skill — code-review-checklist — reduces a review to one question: "Will this code become someone else's problem within three months?" Then it walks five axes in priority order:

Correctness — edge cases (null, empty, zero, negative, oversized), concurrency and timing assumptions, swallowed exceptions. The only axis that can block a merge.
Security — user input concatenated into SQL, shell, or HTML; hard-coded secrets; sensitive data in logs.
Readability — names that say what things are, one job per function, no magic numbers. Flag only what you genuinely can't understand — not "I'd write it differently."
Performance — repeated queries or recomputation inside loops, N+1 problems, avoidable copies of large objects. No data-free speculation: "this might get slow" is not a comment.
Test coverage — new logic has tests, edge cases have cases. All-green tests with the critical path uncovered still get sent back.

Three guardrails keep the review honest. Scope first: over ~400 changed lines, the agent asks for a split — review quality on huge diffs always collapses, and pretending otherwise produces theater. At most 10 comments: more than that means the code needs a rewrite, not fifty line-items of grading. No style policing: indentation, quotes, semicolons — that's the linter's job, and the skill says so explicitly.

Every comment has a fixed format — [axis] file:line problem → suggested fix — and every comment must cite a concrete line. A comment without a code reference is invalid by definition. Then triage: Must fix (correctness, security) blocks the merge; Should fix (readability, performance, tests) doesn't, but the agent says so out loud instead of leaving you to guess which is which.

The same diff, after

Run the skill over that process_orders function and you get something like this:

[Must fix][Correctness] orders.py:9  empty orders list triggers IndexError → guard for empty before taking [0]
[Must fix][Security] orders.py:4  user id concatenated into SQL string → use parameterized query
[Should fix][Performance] orders.py:4  db.query inside the loop (N+1) → batch-fetch users before the loop
[Should fix][Readability] orders.py:7  magic number 86400 → name it SECONDS_PER_DAY

Four comments, all actionable, all pointing at lines. No quote-style opinions. The merge-blocking ones are labeled as such. This is what I wanted from a review all along: not a second pair of eyes grading my style, but a checklist that catches the 2am-paging stuff before it merges.

Install and use

Same pattern as the other skills — a folder you copy:

git clone https://github.com/alapha888/agent-skills-en.git
cp -r agent-skills-en/skills/code-review-checklist ~/.claude/skills/

No dependencies, no network calls, no sign-up. Then: "Review this diff." The agent reads the skill and follows the axes. If you want the whole team on it, commit the folder to .claude/skills/ in the repo — now every review in the project runs the same checklist. The format is an open standard, so this isn't Claude-only; the same folder works in Codex, Cursor, Gemini CLI, and other hosts that support skills.

The copyable core

If you'd rather write your own, the heart of the skill is this checklist — the minimal executable version you can paste into your own SKILL.md:

## Code review checklist

- [ ] Correctness: edge cases (null/0/negative/oversized) handled, exceptions not swallowed
- [ ] Correctness: concurrency/timing assumptions hold, no races
- [ ] Security: no SQL/shell/HTML injection points, no hard-coded secrets, no sensitive data in logs
- [ ] Readability: names are descriptive, functions have a single responsibility, no magic numbers
- [ ] Performance: no repeated queries/computation in loops, no N+1, no evidence-free performance worries
- [ ] Tests: new logic is covered, edge cases have cases
- [ ] Scope: diff ≤ ~400 lines, otherwise split first

Plus the two rules that do most of the work: every comment cites a line, and style stays with the linter. Everything else is commentary.

What it can't fix

The skill won't save you from a 2,000-line diff — it will just ask you to split it, every time, until you do. It won't catch architectural mistakes, because a checklist reviews code, not design: if the whole approach is wrong, no axis flags it. And it inherits your tests' blind spots — if the critical path has no test and the reviewer (you) doesn't notice, the checklist can't notice for you. It's a mirror for your standards, not a replacement for judgment.

But for the everyday case — a normal-sized PR, written in a hurry, reviewed at the end of the day — it turns "review this" from a vibe into a procedure. The dangerous stuff gets caught, the nitpicks go to the linter, and the author gets four comments instead of twenty-three.

The code review skill is one of five I published — the set also covers commit messages, proofreading docs, meeting notes, and deep-research reports. All free, MIT licensed, same install pattern: github.com/alapha888/agent-skills-en

If you try it on a real PR, I'd like to know which axis fires most often for your codebase. Mine is readability, which tells me something about how I write code at 11pm.

Teach Your Coding Agent to Write Commit Messages Your Team Will Actually Read

alapha888 — Thu, 01 Oct 2026 06:45:19 +0000

Teach Your Coding Agent to Write Commit Messages Your Team Will Actually Read

Every team's git history has them. fix stuff. wip. update code. asdf. Messages that made sense at 11pm on a Friday and mean nothing by Monday.

I use Claude Code every day, and for months my fix was the same as everyone's: I'd sigh, type out my commit conventions again in the prompt — conventional commits, imperative mood, short subject, explain the why in the body — and hope the agent remembered. It mostly worked. Until it didn't, because every session started from zero and every phrasing of my instructions produced a slightly different result.

The actual problem isn't that agents can't write good commit messages. It's that my expectations lived in my head, re-typed slightly differently each time. What I needed was to write the workflow down once, in a form the agent would follow the same way every time.

I ended up writing five of these for the repetitive knowledge-work tasks I kept re-explaining (proofreading docs, commit messages, meeting notes, code review, research reports). This post is about one of them — the commit message skill — because it's the smallest one to install and the easiest to feel the difference from. Ten minutes, and your whole team gets consistent messages.

Why a skill, not a saved prompt?

You might wonder why this needs to be a "skill" at all instead of a text snippet you paste, or a paragraph in your project's CLAUDE.md. I tried all three, and they fail differently.

A pasted prompt works but resets every session. You're still the human linter, noticing when the agent drifted from your convention and correcting it. CLAUDE.md instructions are better — they're loaded automatically — but they compete with everything else in that file for the agent's attention, and they tend to grow into a junk drawer of project lore. A slash command is closer, but commands are usually about doing something specific ("run the deploy script"), not about how to think through a recurring judgment call.

A skill sits in the middle: it loads only when the task matches, it carries the full workflow (rules, examples, anti-patterns) instead of a one-line instruction, and it lives in a directory your whole team shares. The mental model that finally clicked for me: a saved prompt is a reminder to yourself; a skill is a checklist for the agent.

Step 1: Install the skill

The skill is a single folder. Clone the repo and copy that folder into your agent's skills directory:

git clone https://github.com/alapha888/agent-skills-en.git
mkdir -p ~/.claude/skills
cp -r agent-skills-en/skills/git-commit-message ~/.claude/skills/

That's the entire install. No dependencies, no network calls, no sign-up. The skill is a markdown file; the agent reads it like a human would read a checklist.

If you want the whole team on the same conventions, put it at the project level instead: copy the folder to .claude/skills/ in your repo and commit it. Now everyone who opens the project — and every agent session in it — follows the same workflow.

One line in your CONTRIBUTING.md and the convention is documented, versioned, and enforced by default rather than by nagging:

## Commit messages

Commit messages are written with the `git-commit-message` skill
(`.claude/skills/git-commit-message/`): `type: imperative subject` ≤ 50 chars,
body explains the *why*. Don't hand-write them from memory — let the agent do it.

The format is an open standard, so this isn't Claude-only. The same folder works in Codex, Cursor, Gemini CLI, and other hosts that support skills.

Step 2: Understand what the skill actually does

Before trusting it, read the workflow. It's short, and knowing what's inside is the difference between using a skill and cargo-culting one. Here's what the skill instructs the agent to do:

Look at the real changes first. Run git status --short and git diff --cached --stat. If the staging area is empty, stop and ask the user — never invent a commit message out of nothing.
Pick exactly one type prefix from feat, fix, docs, refactor, test, chore, based on the diff. If one commit mixes types, the agent asks you to split it instead of papering over the mess.
Write the subject as type: imperative phrase, 50 characters max, starting with a verb: "Add…", "Fix…", "Remove…", "Unify…". Empty subjects like "update code" or "fix bug" are banned by name.
Write the body (1–3 lines) explaining why, not how. Bug fixes must state the trigger conditions. The diff already shows what changed line by line; the body is for the person reading this in three months.
Output a ready-to-run command, not bare text you have to assemble yourself.

Two design decisions in there are worth noticing. First, the subject is for skimmers and the body is for future-you — the skill keeps those two jobs separate instead of blending them. Second, there's no meta-commentary allowed: no "generated by AI" footers, no praise. The message is about the change, nothing else.

Step 3: Use it on a real commit

Let's walk through a concrete example. Say you've staged a change that adds rate limiting to your login endpoint. With the skill installed, you just say:

Write a commit message for my staged changes.

The agent reads the staged diff, sees it's a new behavior (not a bug fix, not a refactor), and produces:

git commit -m "feat: add rate limiting to login endpoint" -m "Blocks brute-force attempts; limit is 5 tries per minute per IP, returns 429."

Type prefix, imperative subject under 50 characters, body that explains the why (brute-force protection) and the key behavior (5/min/IP, 429) — the two things you'd want to know without opening the diff.

Here's a bug-fix example, where the skill's "state the trigger conditions" rule earns its keep:

git commit -m "fix: keep order-list filters across pagination" -m "Trigger: filter first, then turn the page. Cause: page turns dropped the query params."

"Trigger: filter first, then turn the page" is the kind of sentence that saves someone twenty minutes of reproduction six months from now. Nobody writes that sentence unless a checklist tells them to.

Step 4: What it refuses to do (and why that matters)

A skill is as defined by its refusals as its instructions. This one has four I like:

Empty staging area? It stops and asks. It will not write a commit message from vibes.
Mixed commit? A feature plus a refactor becomes two commits. The skill won't let one feat: subject cover both.
Catch-all chore? Labeling everything chore until the type system means nothing is called out as an anti-pattern.
Novel-length subject? feat: add a really useful feature that greatly improves the user experience gets flagged — the subject says what, praise is the user's job.

These sound obvious written down. That's the point: obvious, written down, followed every time, beats clever, in-your-head, followed sometimes.

What the skill can't fix

Honest caveat: no skill fixes bad commit hygiene. If your habit is to git add -A the entire afternoon's work and ask for one message, the skill will correctly refuse to split it for you — it can ask you to stage things separately, but it can't decide what belonged together. The skill assumes you stage deliberately (per feature, per fix) and does the wording. Garbage in, slightly better-worded garbage out.

Similarly, the body explains why only if you can articulate why. When the agent asks "why did you make this change?", "because the ticket said so" is a sign the commit probably shouldn't exist in that form. The skill is a mirror for your process, not a replacement for it.

Where this goes from here

The commit message skill is the smallest of the five I published — the full set also covers proofreading technical docs (itemized checklist, never rewrites your voice), turning meeting notes into minutes (every action item gets an owner and a deadline), five-axis code review (capped at 10 actionable comments, no style nitpicks), and structuring deep-research reports (explicit uncertainty statements). All free, MIT licensed, same install pattern: copy a folder, use it.

They started as a Chinese-language pack I use daily; I rewrote every example for English workplace context rather than translating. If your team has the same five repetitive workflows I did, they're yours to take: github.com/alapha888/agent-skills-en

One last thing: the pattern generalizes. Any task you find yourself re-explaining to an agent weekly — a report format, a review checklist, a translation convention — is a skill waiting to be written down. A SKILL.md is just frontmatter (name, description) plus a workflow with one runnable example and a short anti-pattern list. Write the first one for the task that annoys you most; the rest get easier.

And if you try the commit message skill, I'd genuinely like to know where its workflow is wrong for your team. The fastest way to improve a checklist is to watch someone trip over it.