code-polish
installsforks
How to install code-polish?
paulrberg/agent-skills/code-polish
$npx -y skills add PaulRBerg/agent-skills --skill code-polishPolish changed code when the user explicitly asks, or when an active workflow requests post-implementation simplification and risk-profiled review over a fixed file scope.
SKILL.md
| 1 | # Code Polish |
| 2 | |
| 3 | Resolve scope once, make only high-confidence simplifications, fix evidenced defects by risk, and verify the final |
| 4 | state. |
| 5 | |
| 6 | ## Modes |
| 7 | |
| 8 | - `--simplify`: simplify only. |
| 9 | - `--review`: review and fix only. |
| 10 | - Neither or both: simplify, then review the simplified result. |
| 11 | - `--with-profile <name>` / `--skip-profile <name>`: add or suppress review profiles; skip wins. |
| 12 | |
| 13 | ## Fixed Scope |
| 14 | |
| 15 | 1. Require a Git repository. |
| 16 | 2. Use explicit paths, patterns, ranges, natural-language targets, or a supplied `resolved-scope` block when present. |
| 17 | Otherwise use only files modified in this session; if session history is unavailable, use all uncommitted tracked and |
| 18 | untracked files. |
| 19 | 3. Exclude lockfiles, generated outputs, vendored code, minified bundles, and large data snapshots from manual review |
| 20 | unless explicitly requested. Validate relevant excluded outputs through their generator, schema, or invariants. |
| 21 | 4. Emit one authoritative `resolved-scope` block and optional `excluded-scope` block. Do not broaden or recompute scope |
| 22 | later. Stop if it is empty. |
| 23 | |
| 24 | ## Simplify |
| 25 | |
| 26 | Preserve public contracts, inputs, outputs, side effects, error behavior, performance-sensitive characteristics, |
| 27 | telemetry, and operational guards. Apply only changes with a concrete comprehension or defect-risk benefit: |
| 28 | |
| 29 | - flatten avoidable control-flow nesting; |
| 30 | - clarify misleading names or dense transforms; |
| 31 | - remove real duplication when the abstraction reduces total complexity; |
| 32 | - tighten local types and contracts without broad churn; |
| 33 | - remove only dead code caused by this session's edits. |
| 34 | |
| 35 | Do not split by line count, perform architecture cleanup, convert sync/async APIs, add speculative configurability, or |
| 36 | replace readable duplication with a one-use abstraction. A no-op is a valid result. |
| 37 | |
| 38 | ## Review and Fix |
| 39 | |
| 40 | Judge the diff against the user's request. Prioritize `CRITICAL → HIGH → MEDIUM → LOW`: |
| 41 | |
| 42 | - **CRITICAL**: exploitable security, data loss, or critical outage path. |
| 43 | - **HIGH**: behavior, error-path, boundary, or performance defect affecting core behavior. |
| 44 | - **MEDIUM**: resource leak, complexity hotspot, test gap, over-scoped change, speculative complexity, or weak success |
| 45 | criterion likely to cause defects. |
| 46 | - **LOW**: localized clarity or style issue with a real maintenance cost. |
| 47 | |
| 48 | Every finding must cite a verified location, triggering input/state, failure mode, blast radius, and evidence in the |
| 49 | changed code. Merge duplicates and apply the smallest defensible fix. When intent is ambiguous, stop or record the |
| 50 | assumption instead of guessing. |
| 51 | |
| 52 | Select every applicable profile and read it once: |
| 53 | |
| 54 | | Surface | Profile | |
| 55 | | ------------------------------------------------------------- | ----------------------- | |
| 56 | | auth, secrets, crypto, external input/network, unsafe parsing | `security` | |
| 57 | | env, config, timeouts, retries, pools, limits | `configuration` | |
| 58 | | Go behavior, concurrency, context, errors | `go` | |
| 59 | | TypeScript types, modules, packages, async behavior | `typescript` | |
| 60 | | Python services, scripts, async, packaging, data IO | `python` | |
| 61 | | shell, CI, deploy, installers, quoting | `shell` | |
| 62 | | CSV/JSON/YAML/binary, schemas, migrations, generated data | `data-formats` | |
| 63 | | naming and intent clarity | `naming` unless skipped | |
| 64 | |
| 65 | Profiles live at `references/profiles/<name>.md`. Missing selected profiles are a stop condition. |
| 66 | |
| 67 | ## Verification and Report |
| 68 | |
| 69 | Run the narrowest formatter/lint, targeted tests, typecheck, and invariant checks that prove the final touched behavior. |
| 70 | Broaden only for shared contracts. Name skipped checks and why. |
| 71 | |
| 72 | Report `Scope`, `Simplifications` when run, `Review Findings and Fixes` when run, `Verification`, and `Residual Risks`. |
| 73 | Findings include severity, location, impact, evidence, fix, and confidence. A residual risk states the assumption, |
| 74 | consequence if wrong, and how to check it. Completion requires fixed scope, traceable edits/findings, and validation |
| 75 | evidence. |
| 76 | |
| 77 | Render a successful report as `### ✨ Code polish — ✅ complete`, a small summary-count table, the exact |
| 78 | `resolved-scope` block, `### ✨ Simplifications`, `### 🔎 Review findings and fixes`, `### 🧪 Verification`, and |
| 79 | `### ⚠️ Residual risks`, omitting inapplicable sections. When review is clean, state `✅ No verified review findings.` |
| 80 | If a stop condition below prevents completion, lead with `### ✨ Code polish — ⛔ blocked` and report t |
People who liked this also viewed
6 picksType
- find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 2026
- grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026
- vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026
- improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026
- setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026
- triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026
