Best Claude Code Skills for Existing Codebases: Pick by Failure Mode

The best Claude Code skills for an existing codebase are the ones that preserve its behavior while solving a specific problem. Start with repository discovery, use a debugging procedure when the cause is unknown, add a behavior-level regression test, and keep the resulting diff focused.

This is a selection guide for maintenance work: bug fixes, refactors, fragile tests and review. Recommendations come from inspecting the linked procedures, not from comparative execution or a performance benchmark. For the broader collection catalogue, use best Claude Code skills.

Choose by the failure you need to prevent

What goes wrong	Procedure to consider	Evidence to request
The agent invents patterns or misses a shared helper	Addy Osmani's context-engineering	Relevant rules, canonical implementation and nearby tests
Fixes accumulate without proving the cause	Superpowers systematic-debugging	Reproduction, hypothesis and a test that distinguishes it
A difficult bug lacks a reliable feedback loop	Matt Pocock's diagnosing-bugs	A repeatable signal that fails on this bug
Tests lock down internals and break during cleanup	Matt Pocock's tdd	Agreed public seam and independent expected behavior
A cleanup becomes a rewrite	Addy's code-simplification	Preserved contract and a focused comparison diff
Review misses requirements or architectural drift	Matt's code-review or Addy's code-review-and-quality	Findings tied to the spec, rules, callers and tests
“Done” arrives without fresh evidence	Superpowers verification-before-completion	Actual commands, exit results and remaining gaps

These procedures overlap. Select a clear owner for each phase rather than asking several collections to direct the same task simultaneously.

First, make the repository legible

Before installing another skill, give the agent a bounded discovery task:

Read the repository instructions and contribution guidance. Locate the public entry point, its callers, the existing helper we should reuse, and tests for this behavior. Identify the required verification commands. Report baseline failures and uncertainties before editing.

Addy's context-engineering addresses context starvation, irrelevant context and missing examples. Its practical value here is supplying the relevant rules and an existing pattern before asking for implementation.

For example, “update the date formatter” is incomplete if one caller renders a user's locale and another creates an external API payload. Find both contracts first. A helper that looks redundant in one file may preserve an integration requirement elsewhere.

Capture the starting branch and comparison base. Run the relevant existing checks before editing when feasible, so a later failure can be classified. If a required service or fixture is unavailable, record that limitation. An unavailable integration test does not become a passing check because the unit tests are green.

Keep discovery focused on the affected path. Reading every directory can bury the one rule or caller that changes the decision.

For an unknown cause, choose debugging before refactoring

Superpowers systematic-debugging organizes investigation around root cause, pattern analysis, hypothesis testing and implementation. It is a useful choice when the agent's habit is to make plausible edits after reading an error message.

A concrete prompt is:

The saved filter disappears after refreshing the issue list. Reproduce it, trace the state across the URL parser and persistence boundary, and test one hypothesis at a time. Do not change unrelated state handling.

Ask what observation would disprove the hypothesis. “It might be a race” is insufficient; a trace or controlled reproduction should distinguish the suspected race from a stale cache or invalid filter serialization.

Matt's diagnosing-bugs puts particular emphasis on building a tight feedback loop. It offers alternatives when a failing test is difficult: HTTP requests, fixture-driven CLI output, browser scripts, captured traces, differential runs and bisection harnesses.

Choose it when the immediate obstacle is “we cannot reliably tell whether the bug happened.” Preserve the smallest useful reproduction as a regression check where appropriate. Redact credentials from diagnostic artifacts, as the procedure requires.

For fragile tests, agree on observable behavior

Matt's tdd favors public interfaces, agreed test seams and one test-to-implementation slice at a time. It explicitly rejects implementation-coupled tests and expected values that merely recompute the production algorithm.

In a legacy discount calculation, a useful test might assert the documented total for a fixed basket through the checkout boundary. A test that asserts a private helper ran three times protects the current implementation instead of the customer contract.

Before a refactor, characterize the behavior you intend to preserve. Include awkward cases the business depends on: rounding, ordering, empty values and externally consumed error shapes. Characterization is a recommendation for maintenance work here; it does not mean every existing quirk is desirable. If a quirk is a bug, agree on the changed expectation separately.

Have the human confirm what the chosen seam catches and misses. An API test may protect response compatibility while missing keyboard behavior in the frontend. That gap should determine the additional verification, rather than an arbitrary target for test count.

For a focused refactor, preserve the contract

Addy's code-simplification is a candidate when behavior is understood and the task is to reduce complexity. Apply it to a named boundary with explicit constraints:

Simplify the duplicated filter parsing in these callers. Preserve accepted query parameters, default values and error responses. Reuse the canonical parser if it already satisfies both callers. Keep dependency upgrades and unrelated formatting outside this change.

The review question is whether the change removes concepts or branches a maintainer must understand. Moving the same complexity into another file may improve navigation, but it does not establish simpler behavior.

Prefer the smallest coherent diff, which may include several files if callers and tests must change together. A one-line patch is not inherently safer if it introduces a special case that hides the real invariant.

Keep intentional behavior changes separate from broad cleanup where practical. That makes regressions easier to attribute and gives the reviewer a stable compatibility contract. For larger process choices, compare best Superpowers alternatives and GSD vs Superpowers.

For review, check both requirements and repository fit

Matt's code-review uses separate standards and spec reviews against a supplied fixed point. It is useful when “looks clean” has been masking a missing requirement. Supply the originating issue or acceptance contract and the repository's actual standards.

Addy's code-review-and-quality examines correctness, readability, architecture, security and performance. Its procedure asks reviewers to check findings against callers, guards and tests, and distinguish pre-existing defects from introduced regressions.

For either choice, request a concrete failure path for a blocking finding. The reviewer should identify the input, affected behavior and relevant evidence. Label an unrelated legacy defect separately so the current patch does not quietly expand into a system-wide rewrite.

Finish with verification-before-completion. A completion claim needs fresh evidence for the relevant checks. Preserve manual verification gaps in the handoff; do not turn an agent's confidence into a test result.

When a local skill is the better choice

If the same repository-specific mistake recurs, a short local procedure may help more than another broad collection. For example: identify the canonical serializer, verify the public response fixture and prohibit changing its error shape during cleanup.

Anthropic's skill template provides a SKILL.md starting structure with a name and description. Write a precise trigger and link the repository's maintained sources. Avoid copying an entire architecture document into the skill, where it can drift.

The source snapshots in this guide were inspected November 6, 2026. Review the linked revisions before adopting them, and recheck upstream when updating your procedures. For a complete feature example rather than maintenance selection, follow the Matt Pocock skills walkthrough.

FAQ

Which skill should I add first to a legacy repository?

Start with the failure you observe most often. Missing conventions call for context discovery; an unknown cause calls for debugging. Establish the baseline before asking for code changes.

Can skills guarantee that a refactor preserves behavior?

No. They guide the agent's procedure. Representative tests, real verification and human review supply the evidence for your repository.

Should I install Superpowers and Matt Pocock skills together?

They can overlap in debugging, testing and review. Decide which procedure governs the current phase, and inspect how your installation invokes it. Avoid ambiguous instructions from multiple owners.

Does “best” mean these won a benchmark?

No. These are source-based recommendations for specific maintenance failure modes. This guide makes no claim about comparative speed, cost or success rates.