dotnet-production-agent-skills

v0.3.1

Published

3 days ago

Portable production .NET engineering skills for coding agents

0High
0Medium
0Low

dprakash2101

agent-skills dotnet codex copilot claude-code cursor antigravity

.NET Production Agent Skills

Practical .NET guidance for coding agents

A focused collection of SKILL.md guidance built to reduce repeated prompting, unnecessary token use, and avoidable rework when developing production .NET software with AI coding tools.

Browse the skills catalog · Build an install command · Release notes · Report an issue

Overview & Core Philosophy

dotnet-production-agent-skills captures reusable production guidance for coding agents working on modern .NET and ASP.NET Core codebases. It maintains one canonical source of truth and uses a small TypeScript installer to adapt that content to supported agent discovery locations.

The repository maintains one canonical source of truth:

skills/ (canonical portable Agent Skills)
  ├── focused SKILL.md specifications
  └── targeted references/ (deep dive technical guides)
         │
         ▼
  TypeScript Adapter (dist/src/cli.js)
         │
         ├── Codex         →  .agents/skills
         ├── GitHub Copilot →  .github/skills | .copilot/skills
         ├── Claude Code   →  .claude/skills
         ├── Cursor        →  .cursor/skills | .agents/skills
         └── Antigravity   →  .agents/skills + .agents/hooks.json

Core Engineering Invariant

Implement the requested behavior without changing unrelated behavior.
Task size changes investigation depth and validation rigor — never baseline safety standards.

No Hallucinated Edits: Narrow, intentional changes that preserve existing patterns.
Progressive Context Disclosure: Prevents token waste by loading comprehensive reference guides only when the specific scenario demands it.
Vendor Agnostic: Adheres to the portable Agent Skills specification. Guidance is maintained in one place rather than duplicated across agent ecosystems.

Architecture & Progressive Disclosure

Agents initially ingest only skill names and descriptions. When a task activates a skill, its concise SKILL.md is loaded. Specialized references (e.g. ADO.NET connection pools, BigQuery cost minimization, or API boundary error handling) are pulled into context only on demand:

flowchart TD
    subgraph Discovery ["1. Host Discovery (Zero Context Overhead)"]
        D1["Scan Skill Names & Descriptions"]
    end

    subgraph Activation ["2. Scenario Matching"]
        D1 -->|User Request Matches Scenario| S1["Load canonical SKILL.md"]
    end

    subgraph References ["3. Progressive Disclosure (On Demand Only)"]
        S1 -->|Cloud / Complex Task| R1["references/client-patterns.md"]
        S1 -->|Relational Database| R2["references/postgresql.md OR oracle.md"]
        S1 -->|HTTP Error Boundaries| R3["references/api-boundaries.md"]
    end

This layout ensures an ordinary controller edit does not saturate the agent's context window with Pub/Sub, BigQuery, Firestore, and Oracle rules.

Quick Start

Choose the smallest command that matches how you work. Copy mode is the recommended default because it is portable and easy to inspect.

# Recommended: install for supported agents on this machine
npx dotnet-production-agent-skills install --target all

# Keep the installation inside the current repository
npx dotnet-production-agent-skills install --target all --scope project

# Install for one agent only
npx dotnet-production-agent-skills install --target copilot

From Local Checkout

# Clone and build
git clone https://github.com/dprakash2101/dotnet-production-agent-skills.git
cd dotnet-production-agent-skills
npm install
npm run build

# Run health check & dry run
node dist/src/cli.js doctor --target all
node dist/src/cli.js install --target all --dry-run

# Perform installation
node dist/src/cli.js install --target all

Shell and PowerShell scripts are also provided:

# POSIX (Linux / macOS)
./scripts/install-skills.sh --target all

# Windows PowerShell
./scripts/install-skills.ps1 -Target all

Skills Catalog

The catalog is grouped by task so agents can load only the guidance relevant to the current work. Use the interactive catalog to search by technology, workflow, or engineering concern.

1. 🧭 Workflow & Orientation

2. 🏗️ Architecture & Core Implementation

3. 🛡️ API Contracts & Boundaries

4. 🧪 Quality, Testing & Review

5. ☁️ Cloud & Database Engineering

6. ⚡ Distributed Resilience & Security

7. 🔍 Incident Response & Diagnosis

Composition Workflows

Rather than bloating single skills, skills are composed to form seamless end-to-end engineering pipelines:

flowchart LR
    subgraph DefectWorkflow ["Fixing a Production Defect"]
        BI["bug-investigation"] --> DI["dotnet-implementation"]
        DI --> UT["unit-testing"]
        UT --> TV["targeted-validation"]
        TV --> DR["diff-review"]
    end

flowchart LR
    subgraph ApiWorkflow ["Building a Customer-Facing API"]
        AD["aspnet-core-api-development"] --> CS["api-contract-safety"]
        CS --> EH["exception-handling"]
        EH --> PL["production-logging"]
        PL --> CQ["code-quality"]
    end

flowchart LR
    subgraph CloudWorker ["Building an Event-Driven Worker"]
        PS["google-cloud-pubsub-dotnet"] --> DW["distributed-workflows"]
        DW --> EF["ef-core-safety / relational-database"]
        EF --> PL2["production-logging"]
    end

Quality Policies & Standards

Sonar & Clean-as-You-Code

Automatically inspects .editorconfig, repository analyzers, Roslyn rules, and SonarCloud settings before writing C#.
Adheres to Clean as You Code: fixes new defects and complexity in modified code without derailing tasks into massive legacy cleanups.

Targeted Unit-Test Coverage (90–100%)

Focuses on 90–100% meaningful coverage of new or modified business logic.
Avoids redundant test counts and brittle implementation testing; prioritizes framework-native parameterized tests ([Theory], [TestCase]) and real observable outcomes.

Formal API Deprecation Lifecycle

Endpoints follow an explicit, multi-step deprecation cycle before removal:

$$\text{ACTIVE} \longrightarrow \text{DEPRECATED} \longrightarrow \text{MIGRATION WINDOW} \longrightarrow \text{USAGE VERIFIED} \longrightarrow \text{REMOVAL APPROVED} \longrightarrow \text{REMOVED}$$

External consumers are never assumed absent just because no internal repository reference is found.

TypeScript CLI Reference

How guidance is applied

The CLI installs and manages guidance; it does not route prompts or load every skill for every task. Clear skill descriptions help the coding agent select relevant knowledge. Universal rules belong in repository instructions. Command blocking belongs in host-supported hooks. Project installs now configure native hooks for every supported coding agent using one shared, dependency-free guard script. Existing unrelated hook entries are preserved.

The initial policy blocks force-push, destructive Git reset/clean/branch deletion, broad recursive deletion, and direct access to common credential-bearing files. Safe commands continue normally. Host configuration is written to .codex/hooks.json, .github/hooks/dotnet-production-agent-skills.json, .claude/settings.json, .cursor/hooks.json, or .agents/hooks.json for Antigravity.

Copilot project installs manage only the text between  and . Existing team instructions outside those markers remain intact. Uninstall removes only the managed section. User-scope Copilot installs install skills into ~/.copilot/skills; repository instructions apply only to project scope.

dotnet-production-agent-skills install --target copilot --scope project
dotnet-production-agent-skills install --target copilot --scope user
dotnet-production-agent-skills update --target copilot --scope project
dotnet-production-agent-skills doctor --target copilot --scope project
dotnet-production-agent-skills list --target copilot --scope project

--mode copy installs portable snapshots, while --mode link creates links to the installed npm package and depends on that package remaining at the same location. Use --dry-run to preview changes without writing. Repeated installs skip unchanged snapshots; updates replace snapshots only when the packaged skill changes. Forced replacement or removal backs up locally modified skills.

The installer CLI is written in TypeScript and compiles to Node.js ESM (requiring Node.js >= 18). The runtime uses the small yaml dependency to validate skill metadata.

dotnet-production-agent-skills <command> [options]

Commands:
  install      Install canonical skills into agent discovery paths
  update       Refresh managed skills and retire stale/removed skills
  list         Display available skills and current installation status
  doctor       Validate skill metadata and report host installation health
  uninstall    Safely remove only skills tracked by this package

Options & Flags

Installation Targets & Paths

Safety & Conflict Handling

State Manifest: Managed installations are tracked in .dotnet-agent-skills.json with cryptographic content digests.
Conflict Protection: If a destination file was manually modified or belongs to another tool, the CLI aborts and refuses to overwrite.
Safe Backups: When --force is authorized, conflicting skills are backed up to timestamped archives before replacement.
Surgical Uninstallation: uninstall only removes files explicitly tracked by the manifest, leaving custom user skills untouched.

Host Compatibility

Publishing to npm

GitHub Actions publishes the package from .github/workflows/publish-npm.yml.

Configure repository settings:
- Secret PACKAGE_MANAGER_TOKEN — npm automation token that can publish dotnet-production-agent-skills (used as NODE_AUTH_TOKEN)
- Variable RELEASE_GIT_NAME — git author name for version-bump commits (example: Devi Prakash)
- Variable RELEASE_GIT_EMAIL — git author email for version-bump commits (example: [email protected])
Choose a versioning path:
- GitHub Release: create a release whose tag is semver (v1.2.3 or 1.2.3). The workflow aligns package.json to that version, refuses to republish an existing npm version, validates, then publishes.
- Workflow dispatch: choose keep to publish the current package.json version as-is, or patch / minor / major / prerelease to bump first. Optionally override the npm dist-tag, and optionally commit/tag changes back to the branch before publish.
Dist-tags default from the version (latest for stable, beta / next / alpha / rc for matching prereleases) unless you override them on dispatch.

For GitHub release events, the semver release tag is authoritative and both package files are aligned to it before the npm availability check. For manual workflow runs, package.json remains the version source of truth. If package-lock.json drifts, the workflow aligns it without inventing another semver. keep does not bump; it only publishes the current version after lock synchronization. Republishing the resolved version is still rejected.

Successful publishes are recorded under the repository npm environment (Deployments on the GitHub repo page) and link to the published package version on npmjs.com.

The workflow runs version resolution, an npm uniqueness check, and npm run validate before npm publish --access public --provenance.

Validation & Development

Verify all canonical skills against the Agent Skills specification and run the automated test suite:

# Validate skill markdown, frontmatter, links, and line-length limits
python3 scripts/validate_skills.py

# Run TypeScript build and node:test suite
npm test

# Run complete validation pipeline
npm run validate

# Dry-run package artifact creation
npm pack --dry-run

Release Notes

See release notes or the documentation page for changes, compatibility notes, and publication status.

Why I built this

I created dotnet-production-agent-skills after repeatedly explaining the same production expectations to GitHub Copilot—then spending more tokens correcting and reworking the result. This project captures those lessons as focused, reusable guidance so coding agents can start with better context and produce safer .NET code the first time.

Created and maintained by Devi Prakash. Contributions and practical feedback are welcome through GitHub issues.

License

Distributed under the MIT License. See LICENSE for complete terms.