Official agent skill

C# Behavior-Preserving Refactoring

by dotnet in dotnet/skills

Refactors C# and .NET code without changing behavior, using binding-aware edits plus a build and tests, and separating out or declining anything that alters behavior.

OfficialMITAuto-check passedDevelopment

Install C# Behavior-Preserving Refactoring

skills CLI
$ npx skills add dotnet/skills --skill csharp-refactoring -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install dotnet/skills csharp-refactoring --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/dotnet/skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/plugins/dotnet/skills/csharp-refactoring .claude/skills/csharp-refactoring && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
csharp-refactoring
GitHub stars
5.6k
Used in
1 other repo
Token cost
~3.1k tokens
SKILL.md length
1,561 words
Files
2 (incl. references)
Skills in repo
91
Repo updated
First seen
Licence
MIT

At a glance

Refactors C# and .NET code without changing behavior, using binding-aware edits plus a build and tests, and separating out or declining anything that alters behavior.

  • Works in 3 steps: State: Not a behavior-preserving… → State: No files changed. → State: Next workflow: . Then stop. Do…
  • Renaming or moving C# types and members without changing behavior
  • SKILL.md covers Mandatory gate: classify…, Work only in the current…, Rename / move by bindings, not… and Consolidate toward the…, plus 6 more sections
  • Calls dotnet and git

What it does

A refactor changes structure and never observable behavior. Before restoring, building or editing, the agent classifies each requested operation. If at least one operation is a separable structural change, it does that work and explicitly defers the rest. If the structural and behavior-changing parts cannot be separated, or every operation falls outside refactoring, it gives a fixed three-line stop response stating the reason, that no files changed and which workflow comes next, and then stops without offering alternatives.

Requests dressed up as refactors are sorted out: a framework or NuGet version change is an upgrade handed to `dotnet-upgrade`, a new capability is a feature, a change to a threshold, rate or output is a behavior change, and tightening a shipped nullable annotation is a source-contract change. The covered operations include rename, move, extract, inline, merge, deduplicate, split and modernize, with care for partial and generated declarations, public APIs, serialization and reflection names, friend assemblies, conditional compilation and multi-targeted projects. `references/operation-catalog.md` is bundled, and effort scales with the size of the change.

When your agent uses it

  • Renaming or moving C# types and members without changing behavior
  • Extracting or inlining methods in a multi-targeted project
  • Sorting out a request that mixes a refactor with a bug fix or upgrade
  • Consolidating duplicated code behind a public API

Example prompts

  • “Rename OrderProcessor to OrderService across the solution without changing behavior.”
  • “Extract the discount logic from CheckoutController into its own class.”
  • “Refactor the invoice code and also change the rounding rule.”
  • “Merge the two near-identical repository classes and keep the public API stable.”

Requirements

  • A buildable C# solution with relevant tests

Workflow steps

3 steps, taken from the first numbered list in SKILL.md.

  1. State: Not a behavior-preserving refactor: .
  2. State: No files changed.
  3. State: Next workflow: . Then stop. Do not add manual implementation steps, alternatives,

What it can do on your machine

Read from SKILL.md and the folder at commit 8d670fa. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • dotnet
    • git

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use git, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

C# Behavior-Preserving Refactoring loads about 3.1k tokens when it runs, and up to ~3.8k if it reads all its reference files. Until then it costs about 186 tokens; SKILL.md has 1,561 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~186
When it runs · the whole SKILL.md, loaded when a task matches
~3.1k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~3.8k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from dotnet/skills at commit 8d670fa, republished under its MIT licence (© dotnet). 1,561 words, ~3,097 tokens.

Download SKILL.mdSave it as .claude/skills/csharp-refactoring/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
csharp-refactoring
description
Safely refactors C#/.NET code without changing behavior. USE FOR any request to refactor, rename, move, extract, inline, merge, consolidate, deduplicate, split, or modernize C# code, including partial/generated declarations, wrappers, public APIs, serialization/reflection/configuration names, friend assemblies, conditional compilation, and multi-targeted projects. Also use when a request calls a feature, bug fix, package/framework upgrade, or public nullability change a refactor and the behavior-changing part must be separated or declined. DO NOT USE FOR ordinary feature or bug fixes not presented as refactoring; standalone upgrades after reclassification (use dotnet-upgrade); adding tests; or formatting-only work.
license
MIT

C# Refactoring (behavior-preserving)

A refactor changes structure, never observable behavior. Do the edit with binding-aware tools, then confirm behavior held with a build + the relevant tests. Keep the effort proportional to the change: a one-line local rename does not need the ceremony a public multi-targeted change does.

Mandatory gate: classify before validation or editing

Read only enough repository context to classify each requested operation. Do this before restoring, building, or making an edit. Classification precedence is:

  • If the request explicitly asks for at least one separable behavior-preserving operation, complete that structural work and defer only the behavior-changing or contract-changing operations. Do not invent or infer structural work to avoid the stop response.
  • If the structural and behavior-changing parts cannot be separated, use the whole-request stop response and state why they are inseparable.
  • Otherwise, use the whole-request stop response only when every requested operation is outside behavior-preserving refactoring.

For a whole request that is outside behavior-preserving refactoring:

  1. State: Not a behavior-preserving refactor: <specific reason>.
  2. State: No files changed.
  3. State: Next workflow: <workflow>. Then stop. Do not add manual implementation steps, alternatives, an offer to proceed without the workflow, or a follow-up question — even when that workflow is unavailable.
Requested as a "refactor"Classification and action
Framework or NuGet version changeUpgrade. Do not edit or validate the upgrade here; hand off to dotnet-upgrade.
New capability, flag, endpoint, tier, or behaviorFeature. Do not implement it here; hand off to the repository's feature workflow.
Threshold, rate, output, or bug-result changeBehavior change. Defer it and hand off to the repository's bug-fix or behavior-change workflow; still complete any clearly separable structural operation.
Tighten or loosen a shipped/public nullable annotationSource-contract change. Leave the declaration and API record unchanged; hand off to the repository's API-contract workflow.

For a mixed request, never stop after classification. Perform the separable structural operation, explicitly defer the behavior/contract change, and never state No files changed. after completing structural work. Never modify tests to make an unauthorized behavior change appear preserved.

Work only in the current workspace

Use the current agent workspace as the boundary. If it is a Git checkout, resolve its repository root (git rev-parse --show-toplevel) and stay inside it. If Git metadata is absent, treat the current working directory and its subdirectories as the boundary, and use a solution or project named in the request inside it; Git is not a prerequisite for a refactor. Resolve prompt-provided relative paths inside that boundary.

Search and edit only that workspace. Never use filesystem-wide search or select a similarly named clone, another worktree, build output, or unrelated temporary directory because a file also exists there. If a named path is absent, stop and report the mismatch instead of guessing another workspace. If a tool rejects an in-workspace path for a mechanical reason such as path form or unsupported tool root, retry through another in-workspace mechanism. If the rejection is a permission or policy denial, report it instead of working around it. Never search outside the boundary.

Rename / move by bindings, not text

The #1 way a "rename" silently corrupts code is editing textual matches (comments, strings, unrelated overloads) instead of real bindings. Find every binding reference first, then edit semantically. Use the strongest tool available: an IDE/Roslyn workspace refactoring, then the C# LSP the dotnet plugin declares (findReferences, goToDefinition, incomingCalls, rename code action), then analyzer code-fixes / Roslynator, then compiler-validated edits (edit the true bindings, rebuild, let the compiler flag misses). Plain find/replace only when scope is provably tiny and every hit is verified. Include every partial declaration, and edit the generator input, never generated (*.g.cs) output.

For the operation → Roslyn-provider mapping and representative PRs, see references/operation-catalog.md.

Consolidate toward the existing source of truth

When de-duplicating, preserve the ownership direction stated by the code or request. If B duplicates an implementation already owned by A, keep A canonical and make B delegate to it; do not invert the dependency merely because either direction compiles. Preserve public compatibility wrappers when the duplicate surface is shipped, and migrate only in-repo callers that are safe to move.

Decisions that change the edit

Use the first matching row instead of applying the requested operation mechanically:

SituationDoNever
Inline an internal, unshipped pass-through wrapperMigrate every binding reference to the target, remove the wrapper, then compile to catch misses.Keep dead indirection "for compatibility" when no compatibility boundary exists.
Inline or remove a shipped/public wrapperMigrate ordinary in-repo callers, but retain an [Obsolete] forwarding entry point unless the request explicitly authorizes a breaking change.Delete a shipped API merely because all current source callers were migrated.
Rename a member reached by a string, reflection, DI, or configurationRename binding-based callers; preserve the observed external name with a forwarding shim or metadata, and exercise the old-name path.Rewrite an external/configured name just to make the new source name consistent.
Extract duplicated logic whose callers pass different valuesExtract the algorithm and pass each caller's existing inputs through unchanged.Collapse distinct inputs, evaluation order, rounding, or side effects into one caller's version.
Rename code compiled under #if or multiple TFMsUpdate every source branch and validate each target framework explicitly.Treat a green default-target build as evidence for unbuilt branches.
Merge near-identical typesParameterize only the values that differ, migrate every construction site, and preserve each old value exactly. If the old types are internal/unshipped and the request says to merge into one type, delete their declarations.Retain unnecessary aliases, static holders, factories, or wrapper types that leave the requested merge incomplete; introduce a new hierarchy or behavior.
Show full SKILL.md (637 more words)Show less

Preserve contracts beyond C# call sites

Compilation proves binding compatibility, not every external contract. Before renaming or moving a type/member, check whether its name or metadata is observed by serialization, reflection, dependency injection, configuration binding, source generators, P/Invoke, or dynamic.

BoundaryRequired decision
Serialized/configuration namePreserve the external name with the repository's existing mechanism (for example, JsonPropertyName) while migrating C# callers; run a focused round-trip or payload test.
Public nullable annotationThe mandatory classification gate applies: leave it unchanged and hand off as a source-contract change.
Uncovered reflection or runtime lookupDo not guess that a compile-clean rename is safe. Preserve the observed name or stop and report the unverified runtime boundary.

Verify proportionally

Confirm behavior is preserved after the edit — scaled to blast radius, not a fixed ceremony:

  • Local / private (method-local or private member, one file, single target framework, no public surface, no partial/generated/#if): skip a separate baseline unless the tree is already suspect. Make the edit, then run the narrowest build and relevant tests once. Let the compiler catch missed references.
  • Cross-boundary (public/shipped symbol, multi-targeted project, #if/platform branches, or partial/generated code): establish a baseline, then run an explicit build and the relevant tests for each target framework after the edit (a test command's implicit build is not separate build evidence; a green default build can hide a break on another TFM), and run the hazards check below.

Use the repo's own build/test workflow when it documents one (README/CONTRIBUTING, build.*, eng/, global.json, .github/workflows); its instructions win over any generic command.

Typical workflow (one operation)
  1. Choose one named refactoring operation and keep the step focused on that operation only.
  2. Find true binding references (findReferences/goToDefinition/rename) and include all partial declarations.
  3. Establish a baseline first only for a cross-boundary change or a tree not already known green.
  4. Apply the change via the most semantics-aware tool available; avoid blind find/replace when possible.
  5. Rebuild and run the relevant tests. If the gate goes red, report the failure and repair or reassess only your edit; never discard unrelated worktree changes.

Otherwise:

bash
dotnet build   # 0 errors
dotnet test    # stays green; same pass count as before

One operation per step; never mix a refactor and a behavior change in the same step. On red, stop and report the failure; repair only your edit without discarding unrelated worktree changes.

Final response contract

Keep the handoff concise and evidence-based:

  • Refactor: name the structural operation and the symbols/files changed.
  • Preserved: name the behavior or compatibility boundary and the mechanism that preserved it.
  • Validation: report the exact commands and observed result; never claim success after a failed restore, build, target framework, or test run.
  • Deferred: for a mixed request, name the behavior/contract change intentionally left undone and its correct next workflow. Omit this line when nothing was deferred.

Cross-boundary hazards (only when it touches a boundary)

If — and only if — the change touches a public symbol, a multi-targeted project, or partial/generated code, some breaks won't show up as a failing test. Search the repo for the surface that governs the symbol (don't assume): the public-API gate (PublicAPI.Shipped/Unshipped.txt for PublicApiAnalyzers, and/or ApiCompat/<EnablePackageValidation> — not interchangeable), <TargetFrameworks>/#if branches, and InternalsVisibleTo. Moving a public type to another assembly needs [TypeForwardedTo] in the original assembly; a move within one assembly does not. A public rename needs an [Obsolete] shim, not a forwarder. For a provably local/private change, skip these checks.

Stop an in-scope refactor when

  • The baseline is already red (you can't prove you preserved behavior).
  • The requested structural change would alter a public/shipped API and no compatibility shim or forwarder can preserve it. Report the boundary. Use the gate's handoff format when no structural work was completed; after separable work, put the incompatible operation on the Deferred: line instead. Do not ask to make the breaking change.
  • Equivalence depends on runtime behavior tests don't cover (reflection, DI, serialization, dynamic, P/Invoke) — report the unverified boundary instead of claiming behavior was preserved.

© dotnet, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file (references) in plugins/dotnet/skills/csharp-refactoring of dotnet/skills.

  • SKILL.md
  • references/operation-catalog.md

Open the folder on GitHubat commit 8d670fa

Used in 1 other repository

We found 2 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 1 other GitHub owner. This page covers the copy in dotnet/skills, which our catalogue first saw on October 7, 2026.

Compare with similar skills

C# Behavior-Preserving Refactoring next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

C# Behavior-Preserving Refactoring compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
C# Behavior-Preserving Refactoring this skilldotnet/skills5.6k1 repos~3.1kAutomated safety check: PassMIT
Dynamo Dotnet ExpertDynamoDS/Dynamo2k—~909Automated safety check: PassApache-2.0
Add Refactoringdotnet/roslynator3.5k—~946Automated safety check: PassCustom licence
Deprecate Analyzer Or Refactoringdotnet/roslynator3.5k—~511Automated safety check: PassCustom licence
Okojo Test262akeit0/okojo160—~742Automated safety check: PassMIT
Dotnet10 Featuresrunceel/ReactiveProperty944—~2.7kAutomated safety check: PassMIT

Similar skills

  • Dynamo Dotnet Expert

    DynamoDS/Dynamo

    Write and review C/.NET code in Dynamo following Dynamo coding standards, modern C patterns, and repo conventions.

    2k GitHub stars~909 tokensUpdated today
    DevelopmentAuto-check passed
  • Add Refactoring

    dotnet/roslynator

    Official

    A skill your agent uses when adding a new RR refactoring in roslynator, editing Refactorings.xml, registering in RefactoringContext, or when refactorings-testing.md shows XunitRefactoringVerifier —…

    3.5k GitHub stars~946 tokensUpdated 2 days ago
    DevelopmentAuto-check passed
  • Official

    A skill your agent uses when obsoleting or retiring RCS, RR, or RCF in roslynator, replacing an analyzer with another id, or when tempted to use IsObsolete on an Analyzer entry — analyzers use…

    3.5k GitHub stars~511 tokensUpdated 2 days ago
    DevelopmentAuto-check passed
  • Okojo Test262

    akeit0/okojo

    Run and continue Okojo Test262 compliance work. An agent skill from akeit0/okojo.

    160 GitHub stars~742 tokensUpdated 16 days ago
    DevelopmentAuto-check passed
  • Dotnet10 Features

    runceel/ReactiveProperty

    Reference for the .NET 10 / C 14 features that are relevant to the ReactiveProperty repository.

    944 GitHub stars~2.7k tokensUpdated 1 mo ago
    DevelopmentAuto-check passed
  • Refactor Analysis

    Samsung/TizenFX

    Automatically scans the TizenFX codebase on a rotating schedule to discover .NET 8 / C 12+ refactoring targets and register them as GitHub Issues.

    214 GitHub stars~2.6k tokensUpdated today
    DevelopmentAuto-check passed

More from dotnet/skills

All 91 skills in this repo
  • Official

    Resolves .NET runtime frames in Apple .ips crash logs to function names, source files and line numbers using dSYM symbols, atos and the Microsoft symbol server.

    5.6k GitHub starsUsed in 1 repo~2.4k tokens
    Auto-check passed
  • Official

    Resolves native crash frames from .NET Android tombstones to function names, source files and line numbers using BuildIds, Microsoft's symbol server and llvm-symbolizer.

    5.6k GitHub starsUsed in 1 repo~2.1k tokens
    Auto-check passed
  • Official

    Scans C# and .NET code for about 50 performance anti-patterns and reports prioritized findings with concrete fixes, at a scan depth you choose.

    5.6k GitHub starsUsed in 3 repos~3.1k tokens
    Auto-check passed
  • Official

    Statically pairs source files with test files to list code that no test references, using Roslyn for C# or tree-sitter for many languages, with no build.

    5.6k GitHub starsUsed in 1 repo~3.3k tokens
    Auto-check passed
  • Microbenchmarking

    dotnet/skills

    Official

    Activate this skill when BenchmarkDotNet (BDN) is involved in the task — creating, running, configuring, or reviewing BDN benchmarks.

    5.6k GitHub starsUsed in 3 repos~3.3k tokens
    Auto-check passed
  • Official

    Makes .NET projects compatible with Native AOT and trimming by resolving IL trim and AOT analyzer warnings through annotations rather than suppressions.

    5.6k GitHub starsUsed in 2 repos~4.2k tokens
    Auto-check passed

Works with

Categories

Questions about C# Behavior-Preserving Refactoring

What does C# Behavior-Preserving Refactoring do?

Refactors C# and .NET code without changing behavior, using binding-aware edits plus a build and tests, and separating out or declining anything that alters behavior. A refactor changes structure and never observable behavior. Before restoring, building or editing, the agent classifies each requested operation.

When should I use C# Behavior-Preserving Refactoring?

C# Behavior-Preserving Refactoring fits situations like: renaming or moving C# types and members without changing behavior; extracting or inlining methods in a multi-targeted project; sorting out a request that mixes a refactor with a bug fix or upgrade; consolidating duplicated code behind a public API.

How do I install C# Behavior-Preserving Refactoring in Claude Code?

Run `npx skills add dotnet/skills --skill csharp-refactoring -a claude-code`. Or copy the skill folder (plugins/dotnet/skills/csharp-refactoring in dotnet/skills) into .claude/skills/csharp-refactoring in your project. Claude Code loads it when a task matches its description.

How do I install C# Behavior-Preserving Refactoring in Codex?

Run `npx skills add dotnet/skills --skill csharp-refactoring -a codex`. Or copy the skill folder (plugins/dotnet/skills/csharp-refactoring in dotnet/skills) into .agents/skills/csharp-refactoring in your project. Codex loads it when a task matches its description.

Can I use C# Behavior-Preserving Refactoring in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add dotnet/skills --skill csharp-refactoring -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/csharp-refactoring, .gemini/skills/csharp-refactoring, .github/skills/csharp-refactoring and .opencode/skills/csharp-refactoring in your project.

What does C# Behavior-Preserving Refactoring need to run?

Going by SKILL.md and its folder, C# Behavior-Preserving Refactoring needs the command-line tools its instructions call (dotnet and git). Our summary lists: A buildable C# solution with relevant tests.

Does C# Behavior-Preserving Refactoring access the network?

SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is C# Behavior-Preserving Refactoring safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does C# Behavior-Preserving Refactoring use?

C# Behavior-Preserving Refactoring is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does C# Behavior-Preserving Refactoring use?

About 3.1k tokens (SKILL.md is roughly 12k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 719 tokens, read only when the agent opens those files.

What are the alternatives to C# Behavior-Preserving Refactoring?

Skills that share tags, products or a category with C# Behavior-Preserving Refactoring: Dynamo Dotnet Expert (DynamoDS/Dynamo, 2k stars), Add Refactoring (dotnet/roslynator, 3.5k stars), Deprecate Analyzer Or Refactoring (dotnet/roslynator, 3.5k stars) and Okojo Test262 (akeit0/okojo, 160 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains C# Behavior-Preserving Refactoring?

dotnet (a GitHub organization, an official publisher) maintains it in dotnet/skills, which has 5,568 GitHub stars. The repository holds 91 skills in this directory. The repository was last updated on October 7, 2026.

Source: dotnet/skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.