csharp-async

An AI agent skill for designing, implementing, reviewing, and debugging asynchronous C# code.

Tested against .NET 9 and .NET 10. Initially built for OpenAI Codex 5.3; the SKILL.md frontmatter is spec-compliant, so it also loads in Claude Code and other Agent Skills runtimes. You may need to adjust agents/openai.yaml for other hosts.

What it does

Most async bugs are not syntax bugs — they are contract bugs at boundaries. This skill pushes the agent to settle ownership of cancellation, timeout, retry, disposal, and duplicate-work protection before it starts moving await keywords around.

It covers:

• Choosing between Task, ValueTask, IAsyncEnumerable<T>, Channel<T>, TaskCompletionSource<T>, and SemaphoreSlim
• Cancellation token propagation into the real await, not just checks between awaits
• The difference between bounding a wait (WaitAsync), cancelling the work (CancelAfter on a linked CTS), and racing (Task.WhenAny)
• Idle timeout vs. total timeout for streaming and SSE workloads
• IAsyncDisposable ownership, repeated/concurrent disposal, and lifecycle state
• ConfigureAwait(false) and what it actually affects (SynchronizationContext / TaskScheduler capture — not ExecutionContext or AsyncLocal flow)
• Idempotency and duplicate-start protection for visible, persisted, or billable work
• Observability fields and an incident triage playbook

Layout

Path	Purpose
csharp-async/SKILL.md	Entry point. Workflow, decision matrix, correctness rules, review modes.
csharp-async/references/async-reference.md	Deep reference with patterns, anti-patterns, symptom-to-suspect mapping, and official sources.
csharp-async/agents/openai.yaml	Display metadata for Codex.

The reference is loaded on demand — SKILL.md points to it when the task involves stream readers, ValueTask, Channel<T>, TaskCompletionSource<T>, async disposal, or ambient context.

Install

Clone or copy the csharp-async/ directory into your agent's skills folder.

For Claude Code:

git clone https://github.com/coro-bot/csharp-async.git
cp -r csharp-async/csharp-async ~/.claude/skills/

For Codex, place it wherever your skills are configured to load from.

Usage

The skill triggers on async work automatically. You can also invoke it directly:

• "Review this service for sync-over-async and missing token propagation."
• "This SSE reader hangs on disconnect — triage it."
• "Should this hot-path method return ValueTask?"

It has three modes: implementation (writing or patching), review (auditing existing code), and triage (production failure already in progress).

Modifying it

The guidance is deliberately opinionated. If your codebase has a stronger documented policy, say so in your project instructions — SKILL.md defers to documented codebase policy over its own defaults.

License

CORO License — see LICENSE.

Free to use and modify. If distributed beyond personal use, including non-profit or commercial packaging, please include the license and cite https://github.com/coro-bot