C# Tutor Skills

Current version: 0.6.0

C# Tutor is a Codex skill collection for developers learning C# and improving C#/.NET code. It gives Codex focused instructions for docs-grounded explanations, code review, debugging help, refactoring guidance, architecture feedback, practice exercises, and project inspection.

The project is built around one main skill, csharp-tutor, plus focused companion skills such as csharp-debug, csharp-async, csharp-oop, csharp-performance, and csharp-security. Broad review, docs-grounded, and style-only requests are handled as csharp-tutor modes rather than separate wrapper skills.

What This Project Does

• Explains C# and .NET concepts with examples matched to the learner's level.
• Reviews snippets, files, projects, and repositories for correctness, maintainability, scalability, security, performance, tests, and modernization opportunities.
• Helps with OOP, SOLID, clean code, design patterns, architecture, API design, dependency injection, async, concurrency, LINQ, generics, collections, exceptions, nullable reference types, build tooling, logging, NuGet packaging, NativeAOT/trimming, analyzers, JSON, ASP.NET Core, EF Core, and testing.
• Prefers official Microsoft documentation for language rules, .NET APIs, framework behavior, compatibility, security, and performance-sensitive claims.
• Provides learner support through practice exercises, debugging labs, cheat sheets, interview prep, mini projects, and learning plans.
• Includes shared catalogs for code smells/refactor choices and common compiler/runtime error triage.
• Includes a project inspection helper for .csproj, .sln, target frameworks, package references, analyzer settings, nullable settings, language version, and related project metadata.

Requirements

• Codex with local skill support.
• Python 3 if you want to run validation or the C# project inspection helper.
• PowerShell if you want to use the Windows install/update helper script.
• Bash, curl, and unzip if you want to use the Linux/macOS install/update helper script.
• Git if you want to clone, version, or contribute to this repository.

Installation

Install or update directly from GitHub with one pasteable PowerShell command:

irm https://raw.githubusercontent.com/yappologistic/CSharp-Tutor/master/scripts/install-latest.ps1 | iex

That command downloads the latest repository archive, backs up existing installed csharp-* skill folders, validates the source skills when Codex's validator is available, and copies the skills into your Codex skills directory. When a release retires wrapper skills, the installer removes the retired package-owned folders listed in csharp-tutor-manifest.json after backing them up unless backup is disabled.

On Linux or macOS, use the Bash installer:

curl -fsSL https://raw.githubusercontent.com/yappologistic/CSharp-Tutor/master/scripts/install-latest.sh | bash

Preview the Bash install without copying files:

curl -fsSL https://raw.githubusercontent.com/yappologistic/CSharp-Tutor/master/scripts/install-latest.sh | bash -s -- --dry-run

To preview the install without copying files:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/yappologistic/CSharp-Tutor/master/scripts/install-latest.ps1))) -DryRun

If you already cloned the repository, use the local install/update helper:

.\scripts\install-csharp-tutor.ps1 -Validate -Backup

Useful options:

• -DryRun: show what would be installed or updated without copying files.
• -Backup: back up existing installed csharp-* skill folders before overwriting them.
• -Validate: run Codex skill validation on the source skill folders before copying.
• -DestinationRoot: install to a non-default skills directory.
• For the one-command GitHub installer, use -NoBackup or -NoValidate to opt out of the default backup or validation behavior.
• For the one-command GitHub installer, use -Ref to install a branch, tag, or commit archive.
• Use -ListInstalled to print installed C# Tutor skill folders.
• Use -Uninstall -Backup to remove installed C# Tutor skill folders after creating a backup.

Install a pinned release:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/yappologistic/CSharp-Tutor/master/scripts/install-latest.ps1))) -Ref v0.6.0

For installation problems, see INSTALL-TROUBLESHOOTING.md.

For the generated skill catalog, see SKILLS.md. For topic routing, see TOPICS.md. For releases, see RELEASE.md. For the quality checklist, see QUALITY-RUBRIC.md. For representative maintenance prompts, see EXAMPLE-PROMPTS.md. For project boundaries, see KNOWN-LIMITATIONS.md.

On Windows, the usual Codex skills directory is:

%USERPROFILE%\.codex\skills

From this repository, copy all csharp-* folders into that directory:

Copy-Item -Path "D:\CSharp-Tutor\csharp-*" -Destination "$env:USERPROFILE\.codex\skills" -Recurse -Force

If you cloned the repository somewhere else, run the command from the repository root:

Copy-Item -Path ".\csharp-*" -Destination "$env:USERPROFILE\.codex\skills" -Recurse -Force

After installing or copying the folders, restart Codex or start a new thread if the skill picker does not refresh immediately.

Verifying Installation

After installation, the Codex skill picker should show entries such as:

• C# Tutor
• Csharp Debug
• Csharp Project
• Csharp Async
• Csharp Oop
• Csharp Performance
• Csharp Security

You can also type skill triggers in a prompt, for example:

$csharp-tutor explain async and await in C#
$csharp-tutor mode=review review this class for clean code and maintainability
$csharp-debug help me understand this compiler error

How To Use

Use csharp-tutor when you want the general tutor behavior:

$csharp-tutor explain LINQ deferred execution with examples
$csharp-tutor review this code for OOP design and scalability
$csharp-tutor create a beginner practice exercise about generics
$csharp-tutor make me a 4-week plan for learning ASP.NET Core

Use focused skills when you know the type of help you want:

$csharp-tutor mode=review review this service class for maintainability
$csharp-refactor improve this code using clean code principles
$csharp-debug explain why this NullReferenceException is happening
$csharp-async check this async code for cancellation and deadlock risks
$csharp-performance review this method for allocations and scalability
$csharp-security review this controller for security issues
$csharp-tests help me write unit tests for this class

For code review, paste the code directly into the prompt or work inside a project folder and point Codex at the relevant files.

Command Hints

The main tutor skill supports lightweight command-style hints:

$csharp-tutor q topic=LINQ
$csharp-tutor cs topic=async
$csharp-tutor quiz topic=generics level=beginner
$csharp-tutor lab topic=nullability reveal=false
$csharp-tutor review scope=security format=findings
$csharp-tutor cheatsheet topic=LINQ format=table depth=quick
$csharp-tutor project summary=risks path="D:\Projects\App\App.csproj"

Common controls:

• depth=quick|normal|deep
• format=findings|before-after|checklist|mentor|table
• scope=correctness|security|performance|architecture|tests|all
• difficulty=easy|medium|hard
• reveal=true|false
• pasteable=true|false
• profile=beginner|production|architecture|security|performance|interview

These hints are not a separate CLI. They are prompt conventions that help the skill choose the right response style.

Skill List

Main skill:

• csharp-tutor: Core tutoring, routing, docs grounding, and shared references.

Focused companion skills:

• csharp-api-design: Public API design and compatibility.
• csharp-analyzers: Roslyn analyzers, .editorconfig, and CI quality gates.
• csharp-aot: NativeAOT, trimming, linker warnings, and publish constraints.
• csharp-architecture: Application architecture guidance.
• csharp-aspnet: ASP.NET Core applications.
• csharp-async: Async, cancellation, and async API design.
• csharp-blazor: Blazor components, lifecycle, state, rendering, forms, auth, interop, and performance.
• csharp-build: .NET build, restore, SDK, project-file, and CI failures.
• csharp-cheatsheets: Compact topic cheat sheets.
• csharp-collections: Collections and data structures.
• csharp-concurrency: Thread safety and CPU-bound parallelism.
• csharp-containers: Dockerfiles, multi-stage builds, image size, health checks, and Kubernetes patterns.
• csharp-debug: Compiler errors, exceptions, failing tests, and unexpected behavior.
• csharp-debug-lab: Diagnosis-first debugging exercises.
• csharp-design-patterns: Pattern selection without overengineering.
• csharp-di: Dependency injection.
• csharp-efcore: Entity Framework Core.
• csharp-errors: Exceptions, validation, and failure handling.
• csharp-explain: Concept explanations.
• csharp-generics: Generic types, methods, constraints, and variance.
• csharp-grpc: gRPC services, clients, proto contracts, streaming, deadlines, auth, and diagnostics.
• csharp-help: Concise usage help.
• csharp-interview: Mock interviews and answer review.
• csharp-json: JSON serialization and persistence.
• csharp-linq: LINQ and deferred execution.
• csharp-logging: ILogger, structured logging, scopes, and safe logs.
• csharp-maui: .NET MAUI, XAML, MVVM, binding, navigation, platform code, and packaging.
• csharp-migration: .NET Framework, .NET Core, and modern .NET migration planning.
• csharp-modernize: Version-aware modernization.
• csharp-nullability: Nullable reference types and null-safety.
• csharp-nuget: NuGet packaging, versioning, and publishing safety.
• csharp-oop: Object-oriented design.
• csharp-performance: Performance and scalability review.
• csharp-plan: Learning plans and roadmaps.
• csharp-practice: Exercises, drills, and assignments.
• csharp-project: Project and repository inspection.
• csharp-quickfix: Smallest fix for one C# error, warning, or exception.
• csharp-regex: Regex patterns, escaping, captures, replacements, timeouts, and performance.
• csharp-refactor: Clean code and design-focused refactoring.
• csharp-security: Secure coding review.
• csharp-signalr: SignalR hubs, clients, groups, reconnects, auth, streaming, and scale-out.
• csharp-sourcegen: Source generators, incremental generators, diagnostics, testing, and AOT-friendly generation.
• csharp-tests: Test design and testability.
• csharp-versioning: C# and .NET compatibility checks.

Project Layout

D:\CSharp-Tutor
├── README.md
├── .gitignore
├── CHANGELOG.md
├── VERSION
├── csharp-tutor-manifest.json
├── scripts
│   ├── install-csharp-tutor.ps1
│   ├── install-latest.ps1
│   ├── install-latest.sh
│   ├── release.ps1
│   ├── restore-backup.ps1
│   └── test-csharp-tutor.ps1
├── csharp-tutor
│   ├── SKILL.md
│   ├── agents
│   ├── references
│   └── scripts
└── csharp-*
    ├── SKILL.md
    └── agents

Most focused skills are thin adapters. Shared guidance lives in csharp-tutor/references so the skill family stays consistent. High-use references include the code smell catalog, compiler/runtime error library, review checklist, source citation rules, and project inspection guidance.

Validation

Validate one skill with Codex's skill validator:

python "$env:USERPROFILE\.codex\skills\.system\skill-creator\scripts\quick_validate.py" ".\csharp-tutor"

Validate every C# skill from the repository root:

Get-ChildItem . -Directory -Filter "csharp*" |
  ForEach-Object {
    python "$env:USERPROFILE\.codex\skills\.system\skill-creator\scripts\quick_validate.py" $_.FullName
  }

Successful validation should report each skill as valid.

Run the full repository health check:

.\scripts\test-csharp-tutor.ps1

The health check validates skill structure, manifest consistency, README drift, markdown links, reference targets, golden output-quality prompts, skill validation, and installer dry-run behavior.

Run only the output-quality golden prompt check:

.\scripts\test-output-quality.ps1

To score captured model answers, save them as tests\answers\<case-id>.md and rerun the same script. The check validates required key points and forbidden claims, while tests\golden-qa.json keeps the human review rubric beside each representative prompt.

Regenerate the checked-in skill catalog after changing skill frontmatter or the manifest:

.\scripts\generate-skills-catalog.ps1

Print the maintenance dashboard:

.\scripts\get-maintenance-dashboard.ps1

Versioning

C# Tutor uses semantic versioning while it remains pre-1.0:

• PATCH: typo fixes, wording tweaks, docs link updates, and non-behavioral maintenance.
• MINOR: new references, new scripts, new command modes, new skills, and backward-compatible behavior improvements.
• MAJOR: renamed or removed skills, incompatible install layout changes, or intentionally breaking command/behavior changes.

Version metadata lives in:

• VERSION: the current package version.
• CHANGELOG.md: notable changes by version.
• csharp-tutor-manifest.json: package metadata, skill list, repository, and installer paths.

When cutting a release:

git tag v0.6.0
git push origin v0.6.0

The install scripts print the source ref and package version so users can see what they installed.

To update version metadata and prepare a changelog section:

.\scripts\release.ps1 -Version 0.6.1

To create and push a release tag after health checks pass:

.\scripts\release.ps1 -Version 0.6.1 -CreateTag -PushTag

To tag the currently checked-in VERSION after health checks pass:

.\scripts\release.ps1 -UseCurrentVersion -CreateTag -PushTag

To also create a draft GitHub Release from the matching CHANGELOG.md section:

.\scripts\release.ps1 -UseCurrentVersion -CreateTag -PushTag -CreateGitHubRelease -Draft

Project Inspection Helper

csharp-tutor/scripts/inspect_csharp_project.py inventories C# project metadata such as solutions, project files, target frameworks, nullable settings, language version, package references, and likely test projects.

Example:

python .\csharp-tutor\scripts\inspect_csharp_project.py "D:\Projects\MyApp" --pretty

This helper is useful when asking Codex to review a C# project because it gives the tutor a compact summary of the project structure before making recommendations.

Documentation Policy

This repository contains skill instructions and references. It does not vendor Microsoft documentation.

The skills are designed to prefer official sources for:

• C# language behavior.
• .NET API behavior.
• ASP.NET Core and EF Core guidance.
• Version compatibility.
• Security-sensitive recommendations.
• Performance-sensitive recommendations.

External resources can be used when helpful, but official documentation should be treated as the primary source for claims that depend on current framework behavior.

Contributing

When changing or adding a skill:

1. Keep focused skills small and route shared behavior through csharp-tutor/references. If a focused skill only repeats a csharp-tutor mode with no independent guidance, prefer a csharp-tutor mode=... entry instead of a standalone skill.
2. Prefer official Microsoft documentation for technical claims. Use csharp-tutor/references/official-docs-map.md for common canonical links.
3. Validate every changed skill before committing.
4. Avoid committing local paths, private project names, secrets, tokens, credentials, or machine-specific configuration.
5. Keep examples practical for developers who are learning C# and trying to write production-quality code.

See CONTRIBUTING.md for the full maintenance checklist.