**Verdict: your skill is not wrong, it is inert. Almost all 3,500 words describe what Claude was already going to do, which is why deleting it would change very little — and you have already noticed that.** That is the finding, and the fix is not editing. Let me show you why, then what to do instead. ## The Deletion Test, Section By Section The only question worth asking of any section: **if it were gone, would the review come out different?** | Section | Verdict | Why | |---|---|---| | ROLE | **CUT** | Assigning a persona does not add knowledge or change behavior on a task where the real instruction is specific | | PRINCIPLES | **CUT** | SOLID, DRY, KISS, "clean and maintainable" — already applied without being asked | | WHAT TO LOOK FOR | **CUT** | This is the list of categories a code review already covers. It is length, not instruction | | SEVERITY LEVELS | **KEEP, trimmed** | Only if your definitions are yours. If "critical means production is down" is your team's line, that is real. If they are the generic four, cut them | | OUTPUT FORMAT | **KEEP** | A required output shape is one of the few things that genuinely constrains behavior. Keep it and make it exact | | GLOSSARY | **CUT** | Claude knows what cyclomatic complexity and a race condition are | So: one section survives outright, one survives conditionally, and roughly 3,000 words come out. ## The Generic Lines, Quoted Back Here is the test to apply yourself. **Could this sentence appear unchanged in a skill for a completely different project?** - *"Write clean, maintainable code"* — fits every project ever written. Inert. - *"Follow SOLID, DRY, KISS"* — same. - *"Look for bugs, security vulnerabilities, performance issues"* — this is what "review this code" means. - *"You are a senior engineer with 15 years of experience"* — fits any codebase in any language. Every one passes that test, which means none of them is doing work. **A skill earns its place only by encoding something the model would not otherwise do.** ## What's Actually Missing — And It's The Whole Thing Your skill contains nothing that is true of *your Python monolith* specifically. That is the entire problem, and no amount of rewriting fixes it, because the material is not in the file — it is in your head and in your pull request history. Five kinds of content would genuinely change the output. Go and collect them: 1. **House conventions where several approaches are valid and you have picked one.** Do you use `logging` or a wrapper? Are type hints required on public functions? Do you allow bare `except`? Is it Pydantic models or dataclasses at boundaries? Claude cannot guess which you chose — that is exactly what a skill is for. 2. **Traps specific to your codebase.** Every monolith has them. Modules that look importable but create a cycle. The ORM call that silently issues a query per row. The config object that must not be touched at import time. The "just add a column" migration that locks a table nobody expects. **These are the highest-value sentences you can write** and none of them is in the file. 3. **The comments you find yourself writing repeatedly in reviews.** Open your last twenty pull requests. Anything you have said more than twice is a skill rule, already validated, in your own words. 4. **What the review should refuse or skip.** Generated files, vendored code, the legacy package everyone agreed not to touch, a directory pending deletion. Your skill currently has no boundaries at all, so it applies itself everywhere with equal confidence. 5. **Instructions someone could check.** "Be thorough" is unfalsifiable. "Report the count of public functions missing type hints" is an instruction with an observable result. ## Your Rewritten SKILL.md This is the shape. The bracketed parts are yours to fill — **and it is deliberately short.** A short skill that changes behavior beats a long one that does not. ```markdown --- name: code-reviewer description: Use when reviewing a pull request, diff, or file in this Python monolith, before approving. Applies this repo's conventions and known traps. --- # Code Review — This Repo Standard review practice is assumed. This file covers only what is specific to this codebase. ## House conventions - [Logging: which library, which level, what must never be logged] - [Typing: required where?] - [Error handling: which exceptions may be caught bare, if any] - [Data at boundaries: Pydantic / dataclasses / dicts] ## Known traps in this codebase - [The import cycle] - [The N+1 query] - [The migration that locks] ## Do not review - [Generated files, vendored paths, the legacy package] ## Output [Your exact table, columns named, severity values enumerated] ``` ## One Note On Your Description `"Expert code review skill. Reviews code for quality, bugs, and best practices."` describes **what the skill is**. A description's job is to say **when to use it**, because that is what determines whether it is ever consulted. The version above names the trigger — a pull request, a diff, this repo, before approving. I have kept this short on purpose: your problem is the body, not the trigger. If firing turns out to be the real issue, there are tools built specifically for trigger analysis and they will go deeper than I will here. ## The One Thing To Do First **Open your last twenty pull requests and write down every review comment you have made more than twice.** That list is your actual skill. It will probably be under 300 words, and it will change more about Claude's reviews than the 3,500 words you have now — because it is the only part nobody else could have written.