Index of every page on this site: llms.txt
All skills
paulrberg avatar

/code-polish

@c9e5a34
by Paul Bergpaulrberg/agent-skills106 stars
11
Run it yourself

Polish 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.

Use this Skill: https://skilld.dev/gh/paulrberg/agent-skills/code-polish

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈46 tokens for metadata: the name and description. ≈1.6k when used: this file. ≈6.1k more on demand in 13 files.

Description uses 2.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈185 characters, or 2.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Code Polish

Resolve scope once. Make only high-confidence simplifications. Fix defects supported by evidence according to their risk. Verify the final state.

Modes

  • --simplify: simplify only.
  • --review: review and fix only.
  • Neither or both: simplify, then review the simplified result.
  • --with-profile <name> / --skip-profile <name>: add or suppress review profiles. Skip wins.

Fixed Scope

  1. Require a Git repository.
  2. Use explicit paths, patterns, ranges, natural-language targets, or a supplied resolved-scope block when present. Otherwise, use only files modified in this session. If session history is unavailable, use all uncommitted tracked and untracked files.
  3. Exclude lockfiles, generated outputs, vendored code, minified bundles, and large data snapshots from manual review unless explicitly requested. Validate relevant excluded outputs through their generator, schema, or invariants.
  4. Resolve and retain one authoritative scope set and optional exclusions for execution. Do not broaden or recompute scope later. Stop if it is empty.

Simplify

Preserve public contracts, inputs, outputs, side effects, error behavior, performance-sensitive characteristics, telemetry, and operational guards. Apply only changes with a concrete comprehension or defect-risk benefit:

  • flatten avoidable control-flow nesting.
  • clarify misleading names or dense transforms.
  • remove real duplication when the abstraction reduces total complexity.
  • tighten local types and contracts without broad churn.
  • remove only dead code caused by this session's edits.

Do not split by line count, perform architecture cleanup, convert sync/async APIs, add speculative configurability, or replace readable duplication with a one-use abstraction. A no-op is a valid result.

Review and Fix

Judge the diff against the user's request. Prioritize CRITICAL → HIGH → MEDIUM → LOW:

  • CRITICAL: exploitable security, data loss, or critical outage path.
  • HIGH: behavior, error-path, boundary, or performance defect affecting core behavior.
  • MEDIUM: resource leak, complexity hotspot, test gap, over-scoped change, speculative complexity, or weak success criterion likely to cause defects.
  • LOW: localized clarity or style issue with a real maintenance cost.

Every finding must cite a verified location, triggering input/state, failure mode, blast radius, and evidence in the changed code. Merge duplicates and apply the smallest defensible fix. Resolve ambiguous intent from the request and repository first. State routine assumptions. Ask only when the answer changes behavior or scope. While that item waits, continue independent in-scope fixes.

Select every applicable profile and read it once. Read all selected profiles together in one parallel turn:

Surface Profile
auth, secrets, crypto, external input/network, unsafe parsing security
env, config, timeouts, retries, pools, limits configuration
Go behavior, concurrency, context, errors go
Rust, Cargo/workspaces, async/concurrency, unsafe/FFI rust
Swift, iOS/macOS, SwiftUI/UIKit/AppKit, SwiftPM/Xcode targets swift
Kotlin, Android, coroutines/Flow, Compose, Gradle/manifest kotlin
TypeScript types, modules, packages, async behavior typescript
Python services, scripts, async, packaging, data IO python
shell, CI, deploy, installers, quoting shell
CSV/JSON/YAML/binary, schemas, migrations, generated data data-formats
human-facing numbers, money, percentages, rates, units number-formatting
naming and intent clarity naming unless skipped

Profiles live at references/profiles/<name>.md. Missing selected profiles are a stop condition.

Verification and Report

Run the narrowest formatter/lint, targeted tests, typecheck, and invariant checks that prove the final touched behavior. Broaden only for shared contracts. Name skipped checks and why.

Summarize scope with the file count and smallest useful repository-relative roots, globs, ranges, or user-supplied targets. Do not enumerate every file merely to prove scope. Name individual paths only for a small explicit scope or to clarify exceptions and findings.

Findings include severity, location, impact, evidence, fix, and confidence. A residual risk states the assumption, consequence if wrong, and how to check it.

Under Issues and caveats, group verified fixes with evidence as Resolved, and remaining problems, limitations, or unverified assumptions as Open, with their impact and next step. Omit empty groups. Report each item once. Put neutral context and agreed decisions under changes or scope.

Reserve blocker for something preventing required work and risk for a specific potential adverse outcome. A workaround leaves an item open when the underlying issue still affects the result. Completion requires fixed scope, traceable edits/findings, and validation evidence.

Lead a successful report with ### ✨ Code polish — ✅ complete, then summarize scope, meaningful changes, and verification. For small results, use short prose. Add tables or sections only when they clarify multiple changes or findings. Honor the user's requested format.

When review ran and found no defects, state ✅ No verified review findings. If a stop condition below prevents completion, lead with ### ✨ Code polish — ⛔ blocked and report the evidence and required decision. Keep severity tokens, profile IDs, commands, locations, reproduction inputs, and security evidence exact and undecorated.

Stop when behavior parity or required high-risk validation cannot be established, or a fix requires an unrequested public-contract change or larger redesign.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning10d5 checks · Risk SAFE
  • Gen Agent Trust Hub12d

    The skill is a comprehensive code review and refactoring framework that guides an agent through simplifying and verifying code across multiple programming languages. It implements structured security and quality checks through specialized profiles and uses standard development tools for validation.

  • Socket10d

    No alerts

  • Snyk12d

    Risk: LOW · No issues

  • Runlayer9mo

    1/1 file flagged

  • ZeroLeaks7mo

    1 finding · Score: 86/100

Signed by skilld at c9e5a34. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 2 weeks ago
argument-hint
[paths] [--simplify] [--review] [--with-profile <name>] [--skip-profile <name>]

README badge

README badge for paulrberg/agent-skills/code-polish