Claude Skill

code-polish

Imported from paulrberg/agent-skills/skills/code-polish.

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Virus-scanned Reviewed automatically before listing.

Full trust report

Download paulrberg-agent-skills-skills_code-polish-913232a.zip · 9 KB
Part of paulrberg/agent-skills — 42 skills

Install

skills CLI npx skills add https://github.com/PaulRBerg/agent-skills/tree/main/skills/code-polish
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install paulrberg-agent-skills@llmmart
Git git clone https://github.com/PaulRBerg/agent-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole paulrberg/agent-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Code Polish

Resolve scope once, make only high-confidence simplifications, fix evidenced defects by risk, and 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, and continue independent in-scope fixes while that item waits.

Select every applicable profile and read it once:

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
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
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 and 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. Use short prose for small results; add tables or sections only when they clarify multiple changes or findings, and 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.

Files (agent-skills)
  • agents
    • openai.yaml 42 B
      policy:
        allow_implicit_invocation: true
      
  • references
    • profiles
      • configuration.md 868 B
        # Configuration Profile
        
        Load when the diff touches config, infra limits, or rollout controls.
        
        ## Checks
        
        - `CFG-001` High-magnitude change (`HIGH`): significant value shift without baseline or justification.
        - `CFG-002` Timeout/retry inversion (`HIGH`): upstream/downstream timeout or retry hierarchy causes cascading failures.
        - `CFG-003` Pool/limit mismatch (`HIGH`): connection/thread/concurrency limits can starve or overload dependencies.
        - `CFG-004` Env drift (`MEDIUM`): prod values copied blindly from dev/staging without proportional scaling.
        - `CFG-005` Rollback gap (`MEDIUM`): risky change lacks an available rollback or rollout-control strategy.
        - `CFG-006` Observability gap (`MEDIUM`): no metric/alert to validate the change safely.
        
        ## Evidence Expectations
        
        - Compare new values against previous values.
        - Call out concrete failure mode under load.
        
      • data-formats.md 757 B
        # Data Formats Profile
        
        Load when the diff touches structured-data parsing or emission.
        
        ## Checks
        
        - `DF-001` CSV formula injection (`HIGH`): cells starting with formula tokens exported unsanitized.
        - `DF-002` Unsafe YAML handling (`CRITICAL`): unsafe loader on untrusted YAML.
        - `DF-003` Schema-free parsing (`HIGH`): JSON/YAML accepted without structural validation.
        - `DF-004` Numeric precision loss (`HIGH`): large identifiers/amounts coerced into unsafe number types.
        - `DF-005` Binary parser trust (`HIGH`): no length/magic-byte/offset validation.
        - `DF-006` Encoding ambiguity (`MEDIUM`): implicit charset assumptions can corrupt data or bypass checks.
        
        ## Evidence Expectations
        
        - Show malformed payload and resulting failure or exploit condition.
        
      • go.md 1.5 KB
        # Go Profile
        
        Load when the diff touches Go services, CLIs, concurrency, context propagation, error handling, modules, or tests.
        
        ## Checks
        
        - `GO-001` Context loss (`HIGH`): request-scoped, command-scoped, or shutdown work ignores cancellation, deadlines, or
          parent context.
        - `GO-002` Goroutine/channel leak (`HIGH`): goroutines, timers, tickers, readers, or channels can block or outlive their
          owner.
        - `GO-003` Error loss (`HIGH`): returned errors are ignored, wrapped without useful context, or replaced with unsafe
          zero values.
        - `GO-004` Nil/zero-value trap (`HIGH`): nil pointers, nil interfaces, nil maps/slices, or zero-value structs break
          valid inputs or error paths.
        - `GO-005` Loop/capture aliasing (`MEDIUM`): loop variables, pointer reuse, or shared buffers produce incorrect
          references for the module's Go version.
        - `GO-006` Interface bloat (`MEDIUM`): broad interfaces, package-level globals, or hard-coded dependencies make behavior
          hard to test or substitute.
        - `GO-007` Module/tool drift (`MEDIUM`): `go.mod`, `go.sum`, generated files, or tool versions change without a matching
          reason or reproducible command.
        - `GO-008` Test blind spot (`MEDIUM`): table tests, race-sensitive paths, or error branches do not cover changed
          behavior.
        
        ## Evidence Expectations
        
        - Show the failing input, cancellation path, concurrency schedule, or error branch.
        - Name the narrow Go command that proves the finding, such as `go test ./pkg/foo`, `go test -race ./pkg/foo`,
          `go test ./...`, or `go mod tidy`.
        
      • naming.md 1001 B
        # Naming Profile
        
        Load last, after correctness and security checks; optional — skip with `--skip-profile naming`.
        
        ## Checks
        
        - `NM-001` Generic function names (`MEDIUM`): names like `process`/`handle` hide intent.
        - `NM-002` Misleading identifiers (`MEDIUM`): name contradicts actual data shape or behavior.
        - `NM-003` Boolean ambiguity (`LOW`): a boolean name conceals the condition it represents.
        - `NM-004` File/export mismatch (`LOW`): filename and exported symbol diverge from project conventions.
        - `NM-005` Constant intent loss (`LOW`): magic values or value-based constant names.
        - `NM-006` Misleading filename (`LOW`): file's actual responsibility diverges from what its name implies (e.g.,
          `utils.ts` that only formats dates → `date-format.ts`). Suggest a rename with rationale; flag as `MEDIUM` when the
          mismatch is likely to cause incorrect usage or placement of new code.
        
        ## Guardrail
        
        Only raise naming findings when they materially reduce maintainability in the touched code.
        
      • python.md 805 B
        # Python Profile
        
        Load when the diff touches `*.py` or Python service code.
        
        ## Checks
        
        - `PY-001` Mutable defaults (`HIGH`): shared state across calls from mutable default args.
        - `PY-002` Async blocking (`HIGH`): blocking I/O in coroutine paths.
        - `PY-003` Dangerous execution (`CRITICAL`): `eval`/`exec`/unsafe deserialization on untrusted input.
        - `PY-004` Injection surfaces (`CRITICAL`): SQL string interpolation, `subprocess(..., shell=True)` with user input.
        - `PY-005` Iterator/lifecycle bugs (`MEDIUM`): exhausted iterators reused or context cleanup omitted.
        - `PY-006` Type-blind boundaries (`MEDIUM`): weakly validated external payloads.
        
        ## Evidence Expectations
        
        - Show exact call path where untrusted input crosses into dangerous API.
        - Include deterministic repro condition when possible.
        
      • rust.md 2.4 KB
        # Rust Profile
        
        Load when the diff touches Rust source, Cargo manifests or workspaces, build scripts, toolchain configuration,
        unsafe/FFI, async or concurrent code, or tests.
        
        ## Checks
        
        - `RS-001` Recoverable panic (`HIGH`): `unwrap`, `expect`, indexing, `panic!`, or `unreachable!` is reachable through
          valid input or fallible external state rather than a proven invariant.
        - `RS-002` Unsafe contract breach (`CRITICAL`): unsafe blocks or implementations, raw pointers, FFI, pinning, or layout
          code fail to uphold aliasing, lifetime, alignment, initialization, ownership, unwind, or `Send`/`Sync` invariants.
        - `RS-003` Error contract loss (`HIGH`): errors are discarded, flattened into the wrong class or exit behavior, stripped
          of actionable context, or masked by cleanup.
        - `RS-004` Async/concurrency lifecycle (`HIGH`): blocking work or lock guards cross an await, spawned work lacks
          ownership, or cancellation, panics, and channel closure can cause hangs, deadlocks, or lost failures.
        - `RS-005` State/cleanup atomicity (`HIGH`): filesystem or process updates, temporary files, locks, or guards can leave
          partial state, remove resources they do not own, or prevent safe retry after interruption.
        - `RS-006` OS/process boundary mismatch (`HIGH`): exit status, environment, or working directory assumptions go
          unchecked; path or byte handling forces UTF-8; or normalization and containment assumptions accept or reject the wrong
          target.
        - `RS-007` Cargo/toolchain drift (`MEDIUM`): manifests, lockfiles, features, workspace membership, resolver, edition,
          MSRV, toolchain, or build outputs change inconsistently or make dependency resolution irreproducible.
        - `RS-008` Test blind spot (`MEDIUM`): changed error paths, CLI or integration behavior, features, workspace members,
          targets, platforms, or concurrency behavior lack coverage.
        
        ## Evidence Expectations
        
        - Show the triggering input, error path, schedule, or interruption point. For unsafe code, name the required invariant
          and the safe caller that can violate it.
        - Do not flag panic-capable syntax alone; prove that the path is reachable without a programmer bug or broken invariant.
        - Use repository-provided validation when present. Otherwise name the narrow applicable command, such as
          `cargo fmt --all --check`, `cargo clippy --all-targets --locked -- --deny warnings`, or
          `cargo test --locked <filter>`; add workspace, feature, or target coverage only when the changed contract requires it.
        
      • security.md 1.2 KB
        # Security Profile
        
        Load when the diff touches trust boundaries.
        
        ## Checks
        
        - `SEC-001` Injection sink (`CRITICAL`): SQL/shell/template/path input reaches execution without safe binding.
        - `SEC-002` Broken auth/authz (`CRITICAL`): missing ownership checks, privilege escalation paths, or trust on
          client-only checks.
        - `SEC-003` Secret exposure (`HIGH`): credentials in source, logs, artifacts, or client bundles.
        - `SEC-004` Unsafe execution/parsing (`CRITICAL`): `eval`/unsafe deserialization/untrusted code execution.
        - `SEC-005` Session/token weakness (`HIGH`): missing validation/rotation/expiry constraints.
        - `SEC-006` Traversal or SSRF (`HIGH`): user-controlled paths/URLs can reach unintended resources.
        - `SEC-007` Missing abuse controls (`MEDIUM`): no throttling/lockout/rate limits on brute-force paths.
        
        ## Evidence Expectations
        
        - Show attacker-controlled input path to vulnerable sink.
        - State preconditions and realistic blast radius.
        
        ## Guardrail
        
        Do not flag GitHub Actions `uses:` steps for pinning third-party actions to a commit hash instead of a version tag (e.g.
        `actions/checkout@v4`). The user accepts the supply-chain risk of version tags; this is not a finding.
        
      • shell.md 732 B
        # Shell Profile
        
        Load when the diff touches shell scripts or shell-heavy CI blocks.
        
        ## Checks
        
        - `SH-001` Unquoted expansion (`HIGH`): word-splitting/globbing can alter command behavior.
        - `SH-002` Command injection (`CRITICAL`): `eval` or string-built commands with untrusted input.
        - `SH-003` Error masking (`HIGH`): missing `set -euo pipefail` or unchecked critical commands.
        - `SH-004` Tempfile race/leak (`MEDIUM`): insecure temp paths or missing cleanup traps.
        - `SH-005` Portability mismatch (`LOW`): shebang/syntax mismatch for target shell.
        - `SH-006` Secret leakage (`HIGH`): credentials exposed in args, logs, or traces.
        
        ## Evidence Expectations
        
        - Show exact expansion/injection vector and resulting command behavior.
        
      • typescript.md 871 B
        # TypeScript Profile
        
        Load when the diff touches TypeScript source, declarations, compiler config, package metadata, or generated types.
        
        ## Checks
        
        - `TS-001` Unsafe boundary typing (`HIGH`): `any`, assertions, or unchecked generics hide invalid external data.
        - `TS-002` Unhandled async failure (`HIGH`): missing `await`, `.catch`, `return`, or error propagation drops failures.
        - `TS-003` Async ordering bug (`HIGH`): concurrent operations can overwrite newer state or observe stale data.
        - `TS-004` Module/tool drift (`MEDIUM`): `tsconfig`, package metadata, generated types, or lockfiles change
          inconsistently.
        - `TS-005` Lifecycle leak (`MEDIUM`): timers, listeners, subscriptions, or caches outlive their owner.
        
        ## Evidence Expectations
        
        - Show the invalid input, async timeline, or ownership path.
        - Name the narrow TypeScript command that proves the finding.
        
  • SKILL.md 6 KB
    ---
    argument-hint: "[paths] [--simplify] [--review] [--with-profile <name>] [--skip-profile <name>]"
    name: code-polish
    description:
      "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."
    ---
    
    # Code Polish
    
    Resolve scope once, make only high-confidence simplifications, fix evidenced defects by risk, and 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, and continue
    independent in-scope fixes while that item waits.
    
    Select every applicable profile and read it once:
    
    | 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`                  |
    | 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`          |
    | 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 and 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. Use short prose for small results; add tables or sections only when they clarify multiple changes or
    findings, and 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.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.

Related