dotnet-production-agent-skills 0.1.0 → 0.2.0

package/README.md

@@ -277,10 +277,32 @@ External consumers are never assumed absent just because no internal repository
 
 ## TypeScript CLI Reference
 
-The installer CLI is written in TypeScript and compiles to dependency-free Node.js ESM (requiring Node.js >= 18).
+### How guidance is applied
+
+| Concern | Mechanism | When it applies |
+| :--- | :--- | :--- |
+| Universal engineering rules | Managed section in project `.github/copilot-instructions.md` | Every Copilot coding task in that project |
+| Specialized .NET knowledge | Individual `SKILL.md` files | The coding agent selects relevant skills from their descriptions and the request |
+| Deterministic command enforcement | Optional host hooks/guardrails | Only when a supported host integration and policy are explicitly enabled |
+
+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. Hook installation is currently an extension point in `src/copilot/hooks.ts`; no command hook is installed because a portable supported Copilot hook configuration has not been established.
+
+Copilot project installs manage only the text between `<!-- dotnet-production-agent-skills:start -->` and `<!-- dotnet-production-agent-skills:end -->`. 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.
+
+```sh
+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.
 
 ```text
-dotnet-agent-skills <command> [options]
+dotnet-production-agent-skills <command> [options]
 
 Commands:
   install      Install canonical skills into agent discovery paths

package/copilot/production-instructions.md

@@ -0,0 +1,8 @@
+Understand the existing implementation before changing code. Follow its architecture and conventions.
+Reuse existing helpers and services; avoid duplicated logic and keep new code maintainable under repository analyzers and SonarCloud.
+Preserve compatibility and public API contracts unless a change is explicitly requested. Avoid unrelated refactors.
+Never expose stack traces, credentials, tokens, secrets, connection strings, internal URLs, or database details through customer-facing APIs.
+Never log secrets or sensitive payloads. Add operationally useful logs, and limit noise in high-traffic APIs.
+Do not introduce retries automatically. Add them only when requested or required by existing architecture, and only for safe transient operations.
+When behavior changes, check whether existing tests need updating. Avoid redundant tests that slow CI.
+Run the smallest appropriate validation, build, or test command after changing code.

package/dist/src/cli.js

@@ -1,18 +1,19 @@
 #!/usr/bin/env node
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync } from "node:fs";
 import { cp, lstat, mkdir, readFile, readdir, readlink, realpath, rename, rm, symlink, writeFile, } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 import { createInterface } from "node:readline/promises";
+import { changeInstructions, inspectInstructions } from "./copilot/instructions.js";
+import { validateSkills } from "./skills/validation.js";
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 const SKILLS_ROOT = path.join(PACKAGE_ROOT, "skills");
 const MANIFEST_NAME = ".dotnet-agent-skills.json";
 const SUPPORTED_TARGETS = new Set(["all", "shared", "codex", "copilot", "claude", "cursor"]);
 function usage() {
-    return `Usage: dotnet-agent-skills <command> [options]
+    return `Usage: dotnet-production-agent-skills <command> [options]
 
 Commands:
   install      Install canonical skills
@@ -226,16 +227,28 @@ async function moveToBackup(destination, name, target) {
 }
 async function installOrUpdate(options, command) {
     const skills = await packagedSkills();
+    const validationErrors = await validateCanonical();
+    if (validationErrors.length)
+        throw new Error(`invalid packaged skills: ${validationErrors.join("; ")}`);
+    if ((options.target === "copilot" || options.target === "all") && options.scope === "project") {
+        const instructions = await inspectInstructions(options.project);
+        if (instructions.state === "malformed")
+            throw new Error(`malformed managed Copilot instructions: ${instructions.path}`);
+    }
     const packaged = new Set(skills);
     const packageJson = JSON.parse(await readFile(path.join(PACKAGE_ROOT, "package.json"), "utf8"));
     const destinationPlans = [];
+    const digests = new Map(await Promise.all(skills.map(async (name) => [name, await digestDirectory(path.join(SKILLS_ROOT, name))])));
     for (const destination of destinations(options)) {
         const manifest = await readManifest(destination.directory);
         const plans = [];
         for (const name of skills) {
             const state = await currentState(destination.directory, name, manifest.skills[name]);
-            const action = state.state === "missing" ? "install" : state.state === "unchanged" ? "replace" : "conflict";
-            plans.push({ name, state, action });
+            const digest = digests.get(name);
+            const action = state.state === "missing" ? "install" : state.state === "unchanged"
+                ? manifest.skills[name]?.digest === digest && manifest.skills[name]?.mode === options.mode ? "skip" : "replace"
+                : "conflict";
+            plans.push({ name, state, action, digest });
         }
         const retirements = [];
         if (command === "update") {
@@ -259,6 +272,10 @@ async function installOrUpdate(options, command) {
         if (!options.dryRun)
             await mkdir(destination.directory, { recursive: true });
         for (const plan of plans) {
+            if (plan.action === "skip") {
+                console.log(`skip       ${plan.state.installedPath}`);
+                continue;
+            }
             const source = path.join(SKILLS_ROOT, plan.name);
             const target = plan.state.installedPath;
             if (plan.action !== "install") {
@@ -281,7 +298,7 @@ async function installOrUpdate(options, command) {
                     await cp(source, target, { recursive: true, errorOnExist: true });
             }
             manifest.skills[plan.name] = {
-                digest: await digestDirectory(source),
+                digest: plan.digest,
                 mode: options.mode,
                 source: options.mode === "link" ? await realpath(source) : null,
             };
@@ -305,8 +322,19 @@ async function installOrUpdate(options, command) {
         manifest.target = destination.target;
         await writeManifest(destination.directory, manifest, options.dryRun);
     }
+    if ((options.target === "copilot" || options.target === "all") && options.scope === "project") {
+        const action = await changeInstructions(options.project, "install", options.dryRun);
+        console.log(`${action === "skip" ? "skip" : options.dryRun ? `would ${action}` : action} Copilot production instructions`);
+        if (!options.dryRun)
+            console.log("Copilot CLI: /skills list | /skills reload | /skills info <skill-name>");
+    }
 }
 async function uninstall(options) {
+    if ((options.target === "copilot" || options.target === "all") && options.scope === "project") {
+        const instructions = await inspectInstructions(options.project);
+        if (instructions.state === "malformed")
+            throw new Error(`malformed managed Copilot instructions: ${instructions.path}`);
+    }
     const destinationPlans = [];
     for (const destination of destinations(options)) {
         const manifest = await readManifest(destination.directory);
@@ -329,8 +357,14 @@ async function uninstall(options) {
     for (const { destination, manifest, skills: plans } of destinationPlans) {
         for (const plan of plans) {
             console.log(`${options.dryRun ? "would remove" : "remove"}   ${plan.state.installedPath}`);
-            if (!options.dryRun)
-                await rm(plan.state.installedPath, { recursive: true, force: true });
+            if (!options.dryRun) {
+                if (plan.state.state === "modified") {
+                    const backup = await moveToBackup(destination.directory, plan.name, plan.state.installedPath);
+                    console.log(`backup     ${backup}`);
+                }
+                else
+                    await rm(plan.state.installedPath, { recursive: true, force: true });
+            }
             delete manifest.skills[plan.name];
         }
         if (!options.dryRun) {
@@ -341,48 +375,40 @@ async function uninstall(options) {
                 await writeManifest(destination.directory, manifest, false);
         }
     }
+    if ((options.target === "copilot" || options.target === "all") && options.scope === "project") {
+        const action = await changeInstructions(options.project, "uninstall", options.dryRun);
+        if (action !== "skip")
+            console.log(`${options.dryRun ? "would remove" : "remove"} Copilot production instructions`);
+    }
 }
 async function inspect(options) {
     const skills = await packagedSkills();
     const packaged = new Set(skills);
+    const packageJson = JSON.parse(await readFile(path.join(PACKAGE_ROOT, "package.json"), "utf8"));
     const installations = [];
+    const digests = new Map(await Promise.all(skills.map(async (name) => [name, await digestDirectory(path.join(SKILLS_ROOT, name))])));
     for (const destination of destinations(options)) {
         const manifest = await readManifest(destination.directory);
         const states = [];
         for (const name of skills) {
             const state = await currentState(destination.directory, name, manifest.skills[name]);
-            states.push({ name, state: state.state, mode: manifest.skills[name]?.mode ?? null });
+            const record = manifest.skills[name];
+            states.push({ name, state: state.state, mode: record?.mode ?? null, packaged: record ? record.digest === digests.get(name) ? "current" : "outdated" : null });
         }
         for (const [name, record] of Object.entries(manifest.skills)) {
             if (!packaged.has(name))
-                states.push({ name, state: "stale", mode: record.mode });
+                states.push({ name, state: "stale", mode: record.mode, packaged: null });
         }
-        installations.push({ ...destination, packageVersion: manifest.packageVersion, skills: states });
+        installations.push({ ...destination, packageVersion: manifest.packageVersion,
+            packageVersionMismatch: manifest.packageVersion !== null && manifest.packageVersion !== packageJson.version,
+            skills: states });
     }
-    return { packagedSkills: skills, installations };
+    const copilotInstructions = (options.target === "copilot" || options.target === "all") && options.scope === "project"
+        ? await inspectInstructions(options.project) : undefined;
+    return { packagedSkills: skills, currentPackageVersion: packageJson.version, installations, ...(copilotInstructions ? { copilotInstructions } : {}) };
 }
 async function validateCanonical() {
-    const errors = [];
-    for (const name of await packagedSkills()) {
-        const skillFile = path.join(SKILLS_ROOT, name, "SKILL.md");
-        if (!existsSync(skillFile)) {
-            errors.push(`${name}: missing SKILL.md`);
-            continue;
-        }
-        const contents = await readFile(skillFile, "utf8");
-        const match = contents.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
-        if (!match?.[1])
-            errors.push(`${name}: invalid frontmatter delimiters`);
-        else {
-            const declaredName = match[1].match(/^name:\s*(.+)$/m)?.[1]?.trim();
-            const description = match[1].match(/^description:\s*(.+)$/m)?.[1]?.trim();
-            if (declaredName !== name)
-                errors.push(`${name}: frontmatter name does not match directory`);
-            if (!description)
-                errors.push(`${name}: missing description`);
-        }
-    }
-    return errors;
+    return validateSkills(SKILLS_ROOT, await packagedSkills());
 }
 function countStates(skills) {
     return skills.reduce((counts, entry) => {
@@ -414,8 +440,9 @@ async function main() {
             const report = await inspect(parsed.options);
             const validationErrors = command === "doctor" ? await validateCanonical() : [];
             const unhealthy = report.installations.flatMap((entry) => entry.skills)
-                .filter((entry) => entry.state !== "unchanged");
-            const output = { ...report, validationErrors, healthy: validationErrors.length === 0 && unhealthy.length === 0 };
+                .filter((entry) => entry.state !== "unchanged" || entry.packaged === "outdated");
+            const instructionsUnhealthy = report.copilotInstructions && !["unchanged", "unmanaged"].includes(report.copilotInstructions.state);
+            const output = { ...report, validationErrors, healthy: validationErrors.length === 0 && unhealthy.length === 0 && !instructionsUnhealthy };
             if (parsed.options.json)
                 console.log(JSON.stringify(output, null, 2));
             else {
@@ -424,7 +451,14 @@ async function main() {
                     const summary = Object.entries(countStates(installation.skills))
                         .map(([key, value]) => `${key}=${value}`).join(" ");
                     console.log(`${installation.target.padEnd(7)} ${installation.directory} ${summary}`);
+                    if (installation.packageVersionMismatch)
+                        console.log(`  installed package version: ${installation.packageVersion}; current: ${report.currentPackageVersion}`);
+                    const outdated = installation.skills.filter((skill) => skill.packaged === "outdated");
+                    if (outdated.length)
+                        console.log(`  packaged updates: ${outdated.map((skill) => skill.name).join(", ")}`);
                 }
+                if (report.copilotInstructions)
+                    console.log(`Copilot instructions: ${report.copilotInstructions.state} ${report.copilotInstructions.path}`);
                 validationErrors.forEach((error) => console.error(`error: ${error}`));
             }
             if (command === "doctor" && !output.healthy)

package/dist/src/copilot/hooks.js

@@ -0,0 +1 @@
+export {};

package/dist/src/copilot/instructions.js

@@ -0,0 +1,74 @@
+import { readFile, mkdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const start = "<!-- dotnet-production-agent-skills:start -->";
+const end = "<!-- dotnet-production-agent-skills:end -->";
+const source = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../copilot/production-instructions.md");
+export async function instructionsPath(base) {
+    return path.join(base, ".github", "copilot-instructions.md");
+}
+async function optionalRead(file) {
+    try {
+        return await readFile(file, "utf8");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function section(text) {
+    const from = text.indexOf(start);
+    const closing = text.indexOf(end);
+    if ((from < 0) !== (closing < 0) || (from >= 0 && (closing < from || text.indexOf(start, from + start.length) >= 0 || text.indexOf(end, closing + end.length) >= 0))) {
+        throw new Error("malformed managed Copilot instructions section");
+    }
+    return from < 0 ? null : { from, to: closing + end.length };
+}
+export async function inspectInstructions(base) {
+    const file = await instructionsPath(base);
+    const existing = await optionalRead(file);
+    if (existing === null)
+        return { path: file, state: "missing" };
+    let bounds;
+    try {
+        bounds = section(existing);
+    }
+    catch {
+        return { path: file, state: "malformed" };
+    }
+    if (!bounds)
+        return { path: file, state: "unmanaged" };
+    const canonical = (await readFile(source, "utf8")).trim();
+    const managed = existing.slice(bounds.from + start.length, bounds.to - end.length).trim();
+    return { path: file, state: managed === canonical ? "unchanged" : "outdated" };
+}
+export async function changeInstructions(base, operation, dryRun) {
+    const file = await instructionsPath(base);
+    const existing = await optionalRead(file);
+    const bounds = section(existing ?? "");
+    if (operation === "uninstall") {
+        if (!bounds || existing === null)
+            return "skip";
+        const remaining = `${existing.slice(0, bounds.from).trimEnd()}${existing.slice(bounds.to).trimStart()}`.trim();
+        if (!dryRun) {
+            if (remaining)
+                await writeFile(file, `${remaining}\n`, "utf8");
+            else
+                await rm(file);
+        }
+        return "remove";
+    }
+    const canonical = (await readFile(source, "utf8")).trim();
+    const managed = `${start}\n${canonical}\n${end}`;
+    const next = bounds && existing !== null
+        ? `${existing.slice(0, bounds.from)}${managed}${existing.slice(bounds.to)}`
+        : `${existing?.trimEnd() ? `${existing.trimEnd()}\n\n` : ""}${managed}\n`;
+    if (next === existing)
+        return "skip";
+    if (!dryRun) {
+        await mkdir(path.dirname(file), { recursive: true });
+        await writeFile(file, next, "utf8");
+    }
+    return bounds ? "update" : "install";
+}

package/dist/src/skills/validation.js

@@ -0,0 +1,65 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+const safeName = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export async function validateSkills(root, names) {
+    const errors = [];
+    const declared = new Set();
+    for (const name of names) {
+        if (!safeName.test(name) || name.length > 64) {
+            errors.push(`${name}: unsafe skill directory name`);
+            continue;
+        }
+        const directory = path.join(root, name);
+        let contents;
+        try {
+            contents = await readFile(path.join(directory, "SKILL.md"), "utf8");
+        }
+        catch {
+            errors.push(`${name}: missing or unreadable SKILL.md`);
+            continue;
+        }
+        const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(contents);
+        if (!match) {
+            errors.push(`${name}: invalid frontmatter delimiters`);
+            continue;
+        }
+        const document = YAML.parseDocument(match[1], { uniqueKeys: true });
+        if (document.errors.length) {
+            errors.push(`${name}: invalid YAML: ${document.errors[0].message}`);
+            continue;
+        }
+        const metadata = document.toJS();
+        if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+            errors.push(`${name}: frontmatter must be a mapping`);
+            continue;
+        }
+        const fields = metadata;
+        if (typeof fields.name !== "string" || fields.name !== name)
+            errors.push(`${name}: frontmatter name does not match directory`);
+        if (typeof fields.description !== "string" || !fields.description.trim())
+            errors.push(`${name}: missing description`);
+        if (typeof fields.name === "string") {
+            if (declared.has(fields.name))
+                errors.push(`${name}: duplicate skill name ${fields.name}`);
+            declared.add(fields.name);
+        }
+        for (const link of contents.matchAll(/\]\(([^)#]+)(?:#[^)]*)?\)/g)) {
+            const target = link[1];
+            if (/^[a-z]+:/i.test(target) || target.startsWith("/"))
+                continue;
+            const resolved = path.resolve(directory, target);
+            if (!resolved.startsWith(`${directory}${path.sep}`)) {
+                errors.push(`${name}: linked file escapes skill directory: ${target}`);
+                continue;
+            }
+            try {
+                await stat(resolved);
+            }
+            catch {
+                errors.push(`${name}: missing linked file: ${target}`);
+            }
+        }
+    }
+    return errors;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotnet-production-agent-skills",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Portable production .NET engineering skills for coding agents",
   "license": "MIT",
   "author": {
@@ -17,10 +17,11 @@
   },
   "type": "module",
   "bin": {
-    "dotnet-agent-skills": "dist/src/cli.js"
+    "dotnet-production-agent-skills": "dist/src/cli.js"
   },
   "files": [
     "dist/src",
+    "copilot",
     "skills",
     "README.md",
     "LICENSE"
@@ -49,5 +50,8 @@
     "copilot",
     "claude-code",
     "cursor"
-  ]
+  ],
+  "dependencies": {
+    "yaml": "^2.9.1"
+  }
 }

package/skills/api-contract-safety/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api-contract-safety
-description: Preserve and evolve ASP.NET Core API contracts safely. Use when changing routes, verbs, headers, parameters, DTOs, JSON, status/errors, enums, auth, versioning, or public interfaces.
+description: Use when changing or reviewing existing API routes, versions, verbs, headers, request/response DTOs, serialization, status codes, error shapes, authorization, or public interfaces.
 ---
 
 # API contract safety

package/skills/api-endpoint-deprecation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api-endpoint-deprecation
-description: Plan, implement, or review deprecation and eventual removal of a customer-facing API endpoint. Use for endpoint replacement, version retirement, deprecation metadata, migration windows, usage verification, or explicit removal work.
+description: Use when planning, implementing, or reviewing API deprecation, replacement versions, sunset headers, migration windows, consumer verification, or endpoint removal.
 ---
 
 # Safe API endpoint deprecation

package/skills/aspnet-core-api-development/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: aspnet-core-api-development
-description: Create a new customer-facing ASP.NET Core API endpoint or API surface. Use for new controllers/minimal endpoints and their request, validation, service, integration, response, and OpenAPI flow; not for small changes to an existing endpoint.
+description: Use when building a new ASP.NET Core customer-facing API endpoint or version, including routing, header and request validation, service boundaries, authorization, error responses, and OpenAPI. Use api-contract-safety when modifying an existing contract.
 ---
 
 # New customer-facing ASP.NET Core APIs

package/skills/code-quality/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-quality
-description: Improve or assess quality of changed C#/.NET code under Clean-as-You-Code and analyzer/Sonar expectations. Use for requested quality work or while polishing a substantive implementation; do not trigger repository-wide legacy cleanup.
+description: Use when improving or reviewing modified .NET code for SonarCloud/Roslyn findings, duplication, complexity, maintainability, or existing helper reuse. Avoid unrelated legacy cleanup.
 ---
 
 # .NET code quality

package/skills/distributed-workflows/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: distributed-workflows
-description: Design or change .NET message handlers, background services, retries, idempotent operations, and multi-system workflows. Use when work crosses process/service boundaries or can execute more than once.
+description: Use when designing or changing .NET message handlers, background workers, idempotency, duplicate delivery, partial failures, or existing retry behavior. Introduce new retries only when requested or required by existing architecture.
 ---
 
 # Distributed workflows

package/skills/exception-handling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: exception-handling
-description: Design or review .NET exception handling, including catch boundaries, recovery, translation, cancellation, and logging ownership. Use when adding or changing exception paths or centralized handlers; load the API reference only for customer-facing HTTP boundaries.
+description: Use when implementing, modifying, or reviewing .NET exception handling, customer-facing API error translation, recovery boundaries, cancellation, and safe logging. Prevent internal details and secrets from reaching callers.
 ---
 
 # .NET exception handling

package/skills/google-bigquery-dotnet/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: google-bigquery-dotnet
-description: Implement or review Google BigQuery access from .NET with Google.Cloud.BigQuery.V2. Use only for BigQuery queries, jobs, result mapping, authentication, performance, or query-cost concerns.
+description: Use when implementing, modifying, reviewing, troubleshooting, or optimizing Google BigQuery integrations in .NET, including BigQueryClient, authentication, parameterized queries, DATE/DATETIME/TIMESTAMP types, query costs, serialization, and result mapping.
 ---
 
 # Google BigQuery for .NET

package/skills/google-cloud-pubsub-dotnet/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: google-cloud-pubsub-dotnet
-description: Implement or review Google Cloud Pub/Sub publishers and pull subscribers in .NET. Use only for Google.Cloud.PubSub.V1 messaging, subscriber workers, acknowledgement behavior, or Pub/Sub delivery concerns.
+description: Use when implementing, modifying, reviewing, or troubleshooting Google Cloud Pub/Sub publishers, subscribers, pull workers, acknowledgements, concurrency, flow control, dead-letter handling, ordering, or BackgroundService integration in .NET.
 ---
 
 # Google Cloud Pub/Sub for .NET

package/skills/google-firestore-dotnet/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: google-firestore-dotnet
-description: Implement or review Google Cloud Firestore persistence in .NET. Use only for Google.Cloud.Firestore document models, reads/writes, queries, transactions, batches, indexes, or Firestore cost/modeling decisions.
+description: Use when implementing, reviewing, or troubleshooting .NET Firestore document models, queries, transactions, batched writes, indexes, optimistic concurrency, or read/write costs.
 ---
 
 # Google Cloud Firestore for .NET

package/skills/production-logging/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: production-logging
-description: Design or review structured .NET logging for production and high-volume APIs. Use when adding/changing logs, defining logging ownership, reducing noise/cost, or protecting sensitive observability data.
+description: Use when adding, reviewing, or reducing .NET structured logs, exception telemetry, correlation IDs, sensitive-data exposure, or high-traffic API logging costs.
 ---
 
 # Production logging for .NET

package/skills/relational-database-dotnet/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: relational-database-dotnet
-description: Implement or review relational database access from .NET for PostgreSQL or Oracle. Use for ADO.NET/provider SQL, connections, transactions, commands, provider-specific mapping, or database retry decisions; compose with ef-core-safety when EF Core behavior is involved.
+description: Use when implementing, reviewing, or troubleshooting .NET PostgreSQL or Oracle SQL, ADO.NET providers, parameterized queries, connections, transactions, mapping, or database performance. Compose with ef-core-safety for EF Core.
 ---
 
 # Relational database access for .NET

package/skills/retry-resilience/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: retry-resilience
+description: >
+  Use when the user explicitly requests retry behavior or when reviewing existing
+  retry and resilience logic for transient HTTP, database, Pub/Sub, or cloud API
+  dependencies. Do not introduce new retries unless requested or required by
+  existing architecture.
+---
+
+# Retry and resilience in .NET
+
+Inspect existing policies, timeouts, cancellation, and failure semantics first. Retry only transient failures on operations safe to repeat, or operations with a reliable idempotency key. Bound attempts, total time, and concurrency; use backoff with jitter where appropriate. Honor server retry guidance when supported.
+
+Never retry validation failures or permanent authorization errors. Avoid layered retries that multiply calls and costs. Account for duplicate messages and ambiguous outcomes. Test the retry boundary with representative transient and permanent failures, and report the operational tradeoff.

package/skills/task-router/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: task-router
-description: Classify a software request just enough to select a safe, proportionate workflow. Use at the start of implementation, investigation, review, testing, or Git work when the needed workflow is not already obvious.
+description: Use only when the user explicitly requests help selecting a workflow or skill for a complex software task; choose relevant skills from their descriptions without implementing a custom skill router.
 ---
 
 # Task router

package/skills/unit-testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: unit-testing
-description: Add or improve focused automated tests for production .NET behavior. Use for new or materially changed testable business logic and regression fixes; optional for explicitly identified POCs.
+description: Use when adding or improving focused .NET unit tests for changed business behavior or regression fixes. Prefer parameterized cases and avoid trivial redundant tests that increase CI time.
 ---
 
 # .NET unit testing