Many teams still run background services on older .NET versions: Windows-only, tied to hard-coded server paths, logging every step straight to disk, and guarding against overlapping runs with a plain bool. Migrating them by hand often takes a sprint per service, because each one has its own history. We moved a group of them to .NET 10 worker services in two days. The speed didn't come from the agent typing faster. It came from skill files that told the coding agent exactly what "done" looks like.

#1. Why Agents Alone Weren't Enough

Ask a coding agent to "upgrade this worker to .NET 10" and you get a tutorial answer: a fresh BackgroundService, a generic logger, maybe a new ORM. It compiles, and it looks nothing like the rest of the solution. Pulling that output back in line with your conventions takes longer than doing the migration yourself.

A migration at this scale needs three things the model doesn't have:

  • The target shape: how your layers, logging, configuration and data access are meant to look.
  • The migration traps: what breaks when old code meets .NET 10 and Linux.
  • A definition of done: a checklist the agent verifies before it says it's finished.

A skill is how you hand an agent all three, once, instead of re-typing them in every prompt.

#2. Two Skills, Stacked

Diagram
House-style skill  (how we write .NET)
  layering, naming, DI style, logging, data access,
  response and error conventions, review checklist
        │  reused by
        ▼
Worker migration skill  (how we move a worker to .NET 10)
  target framework + runtimes, hosting, scheduling,
  logging adapter, paths, deployment, checklist
        │
        ▼
Coding agent: orient → convert → build → checklist → PR

The house-style skill came first. It describes how a .NET service is written in your codebase: which layers exist and what each may do, how dependencies are registered, which logger to inject, how data access is done, and how errors are handled. Most teams already have these rules. They just live in people's heads and in old pull-request comments.

The migration skill builds on it. A worker is the same layered code with a timer instead of an HTTP request, so it reuses the house rules and adds only what's specific to background services and to the upgrade itself.

Distil skills from real code

Write the skill from your best existing service, not from documentation. "This is how our best service does it" is something an agent can copy faithfully. "Follow best practices" isn't.

#3. Step Zero: Orient Before Editing

The most useful section of a migration skill is the first one. Before touching a file, the agent answers a fixed set of questions about the project in front of it:

  • Does the service depend on shared library projects? If other services still use those libraries, they need to target both frameworks for a while.
  • Which packages does it use? System.Data.SqlClient is deprecated in favour of Microsoft.Data.SqlClient, and Microsoft.Extensions.* packages move to 10.x.
  • Does anything use System.Drawing.Common? Since .NET 7 it's Windows-only, so image or document rendering has to move to a cross-platform library or sit behind an OS check.
  • Where are the hard-coded Windows paths, the schedule interval, and any loop over tenants or sites?

This stops the agent assuming every service matches the reference one. It also means each pull request opens with a short inventory, so review starts with what the agent found rather than with a diff.

#4. What the Migration Changes

#One project file for every platform

Each service targets net10.0 with the worker SDK and declares the runtimes it can be published for:

xml
<Project Sdk="Microsoft.NET.Sdk.Worker">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <RuntimeIdentifiers>win-x64;win-x86;win-arm64;linux-x64;linux-arm64;linux-arm</RuntimeIdentifiers>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Hosting.WindowsServices" Version="10.0.0" />
    <PackageReference Include="Microsoft.Extensions.Hosting.Systemd" Version="10.0.0" />
    <PackageReference Include="Microsoft.Data.SqlClient" Version="5.2.2" />
  </ItemGroup>
</Project>

#A host that knows where it's running

Program.cs moves to Host.CreateApplicationBuilder and picks the right service integration at startup, so the same build runs as a Windows Service or a systemd daemon:

C#
var builder = Host.CreateApplicationBuilder(args);

if (OperatingSystem.IsWindows())
{
    builder.Services.AddWindowsService(o => o.ServiceName = "ReportWorker");
}
else if (OperatingSystem.IsLinux())
{
    builder.Services.AddSystemd();
}

builder.Services.Configure<WorkerOptions>(builder.Configuration.GetSection("Worker"));
builder.Services.AddScoped<ReportJob>();
builder.Services.AddHostedService<Worker>();

var host = builder.Build();
host.Services.GetRequiredService<ILogger<Program>>().LogInformation(
    "Starting on {OS} [{Arch}], .NET {Runtime}",
    RuntimeInformation.OSDescription, RuntimeInformation.ProcessArchitecture, Environment.Version);
await host.RunAsync();

That startup line seems minor until a service is quietly running as x86 on a 64-bit machine. It answers "what is this actually running on?" from the first log line.

#PeriodicTimer and a real reentrancy guard

Older workers often use a timer callback plus a bool isRunning flag to skip a tick while the previous run is still going. That flag isn't thread-safe. The migrated Worker uses PeriodicTimer, a SemaphoreSlim and a fresh DI scope per tick:

C#
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
    using var timer = new PeriodicTimer(_options.Interval);

    await RunOnceAsync(stoppingToken);                   // run once at start
    while (await timer.WaitForNextTickAsync(stoppingToken))
    {
        await RunOnceAsync(stoppingToken);
    }
}

private async Task RunOnceAsync(CancellationToken token)
{
    if (!await _gate.WaitAsync(0, token))                // previous run still going
    {
        _logger.LogWarning("Previous run still in progress, skipping this tick.");
        return;
    }
    try
    {
        using var scope = _scopeFactory.CreateScope();     // fresh services per tick
        await scope.ServiceProvider.GetRequiredService<ReportJob>().RunAsync(token);
    }
    catch (Exception ex) when (ex is not OperationCanceledException)
    {
        _logger.LogError(ex, "Run failed");
    }
    finally
    {
        _gate.Release();
    }
}

Stopping the service now cancels the wait instead of waiting for the next tick, and a slow run can never overlap the next one.

#One bad item doesn't stop the batch

If a worker loops over tenants, customers or files, the skill requires each one to run inside its own try/catch. One tenant's bad data logs an error and the loop moves on to the next.

#5. The Logging Trick: Adapt, Don't Rewrite

Legacy services often have dozens of calls to an old logging helper, each one writing a line to disk synchronously. In a loop that runs every few seconds, that's a lot of I/O for logs nobody reads unless something fails.

Rewriting every call site is the slow, risky part of a migration. Instead, the skill tells the agent to change only the helper's body and route it to a buffered step logger:

C#
// The old helper keeps its signature, so no caller changes.
public void LogStep(string message, string method)
{
    _steps.Add(method, message);   // in memory: no disk write on the happy path
}

The step logger keeps a bounded list of steps (say, the last 100) for the current run. On success they're discarded. When something throws, the error log includes the whole chain of steps that led to the failure, in order. The happy path stops writing to disk, a failure gets a more complete log than before, and none of the existing callers changed.

This is where stacking skills pays off

If the house-style skill already defines how services log, the migration skill just points to it. The agent doesn't invent yet another logging approach, and API and worker logs read the same way.

#6. Cross-Platform Paths and Deployment

Old configuration files are often full of absolute Windows paths like D:\Logs\MyService\. On Linux these don't fail loudly: they create a folder literally named D:\Logs\MyService\ next to the binary. The rule is simple: no drive letters or backslashes in code, build paths with Path.Combine from AppContext.BaseDirectory, and override them per environment:

Text
Worker__LogPath=/var/log/report-worker/

The skill also includes the deployment recipes, so the agent finishes each service with all three ready:

  • Windows Service via sc.exe create, as before.
  • systemd unit with Type=notify and Restart=always, which works because of AddSystemd().
  • Multi-arch Dockerfile using --platform=$BUILDPLATFORM and TARGETARCH, so one build produces AMD64 and ARM64 images.
Text
dotnet publish -c Release -r linux-arm64 --self-contained true -p:PublishSingleFile=true -o ./publish/linux-arm64

#7. The Checklist Is the Definition of Done

Each skill ends with a checklist, and the agent is told to go through it before calling a service finished. A typical migration checklist:

  • Targets net10.0, declares runtime identifiers, and no deprecated data-access package is left.
  • The host registers Windows Service and systemd support and logs OS, architecture and runtime at startup.
  • No hard-coded Windows paths remain.
  • PeriodicTimer plus SemaphoreSlim, with no unsynchronised "is running" flag.
  • Every tenant or item in a batch has its own error boundary.
  • The code follows the house-style skill's checklist too.
  • Publishes for every target runtime.

The checklist is what made review fast. Instead of reading every diff from scratch, a reviewer confirms the agent's checklist against the code and spends their attention on the business logic, which is the part only someone who knows the system can judge.

#8. The Loop

  1. Write the skills from the best existing code. Start with your house style, then the migration on top of it.
  2. Migrate one service with the agent and watch closely. Every place the agent guessed becomes a new rule in the skill.
  3. Run the agent across the remaining services, one branch each: orient, convert, build, publish for each runtime, run the checklist.
  4. Review against the checklist, then run each service side by side with the old one before switching over.
  5. Feed corrections back into the skill, so the next service needs fewer of them.
Fast doesn't mean unreviewed

The agent did the repetitive work: project files, hosting, timers, logging adapters, paths and deployment files. People still reviewed every pull request and checked each service against the one it replaced. Two days was possible because the review was focused, not because there wasn't one.

#9. Takeaways

  • Agents are fast but generic. A skill turns "upgrade to .NET 10" into "upgrade to .NET 10 the way this codebase does things".
  • Stack skills. A migration skill that reuses your house-style skill keeps every service consistent.
  • Make orientation the first step, so the agent inventories each project before changing it.
  • Adapt legacy call sites instead of rewriting them. One method body change beats hundreds of edits.
  • End every skill with a checklist. It's the agent's definition of done and the reviewer's map.
  • Every correction belongs in the skill, not in the next prompt.

For the wider workflow these skills belong to, see how I use an Obsidian vault, MCP and Skills, and for the worker basics, the dynamic background service manager in .NET 8.