dotnet-production-agent-skills 0.1.1 → 0.2.1

package/README.md

@@ -10,7 +10,7 @@
 
 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](https://dprakash2101.github.io/dotnet-production-agent-skills/#skills) · [Build an install command](https://dprakash2101.github.io/dotnet-production-agent-skills/#install) · [Report an issue](https://github.com/dprakash2101/dotnet-production-agent-skills/issues)
+[Browse the skills catalog](https://dprakash2101.github.io/dotnet-production-agent-skills/#skills) · [Build an install command](https://dprakash2101.github.io/dotnet-production-agent-skills/#install) · [Release notes](RELEASE_NOTES.md) · [Report an issue](https://github.com/dprakash2101/dotnet-production-agent-skills/issues)
 
 </div>
 
@@ -36,6 +36,7 @@ A focused collection of `SKILL.md` guidance built to reduce repeated prompting,
   - [Safety & Conflict Handling](#safety--conflict-handling)
 - [Host Compatibility](#host-compatibility)
 - [Validation & Development](#validation--development)
+- [Release Notes](#release-notes)
 - [Why I built this](#why-i-built-this)
 - [License](#license)
 
@@ -201,12 +202,14 @@ The catalog is grouped by task so agents can load only the guidance relevant to
 | [`google-cloud-pubsub-dotnet`](skills/google-cloud-pubsub-dotnet/SKILL.md) | Implement robust Google Cloud Pub/Sub publishers and pull subscribers with proper ack/nack semantics. | [client-patterns](skills/google-cloud-pubsub-dotnet/references/client-patterns.md) |
 | [`google-bigquery-dotnet`](skills/google-bigquery-dotnet/SKILL.md) | Query BigQuery with parameterization, pagination, streaming buffers, and strict query-cost awareness. | [query-safety](skills/google-bigquery-dotnet/references/query-safety.md) |
 | [`google-firestore-dotnet`](skills/google-firestore-dotnet/SKILL.md) | Model Firestore documents, transactions, and batched writes with concurrency and read-cost awareness. | — |
+| [`redis-dotnet`](skills/redis-dotnet/SKILL.md) | Design secure .NET Redis caches, expiration, invalidation, and token protection. | — |
 
 ### 6. ⚡ Distributed Resilience & Security
 
 | Skill | Focus & Trigger | Progressive References |
 | :--- | :--- | :--- |
 | [`distributed-workflows`](skills/distributed-workflows/SKILL.md) | Build idempotent consumers, handle partial failures, manage distributed retries, and design background workers. | — |
+| [`retry-resilience`](skills/retry-resilience/SKILL.md) | Add explicitly requested retries or review existing transient failure policies; avoid automatic retries. | — |
 | [`dotnet-security`](skills/dotnet-security/SKILL.md) | Threat-model .NET boundaries, protect against SSRF/XSS/SQLi, enforce authorization, and handle secrets safely. | — |
 | [`production-logging`](skills/production-logging/SKILL.md) | Produce structured, high-signal, sensitive-data-masked, and cost-efficient Serilog/ILogger production logs. | — |
 
@@ -277,10 +280,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
@@ -374,6 +399,10 @@ npm pack --dry-run
 
 ---
 
+## Release Notes
+
+See [release notes](RELEASE_NOTES.md) or the [documentation page](https://dprakash2101.github.io/dotnet-production-agent-skills/release-notes.html) 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.

package/RELEASE_NOTES.md

@@ -0,0 +1,40 @@
+# Release notes
+
+## Unreleased — Redis caching skill
+
+Proposed in [PR #6](https://github.com/dprakash2101/dotnet-production-agent-skills/pull/6); this change is not yet published to npm.
+
+### New
+
+- Added `redis-dotnet` guidance for .NET and ASP.NET Core Redis caching: key design, expiration, invalidation, concurrency, failure handling, and targeted validation.
+- The skill prohibits plaintext credentials in Redis. Credential ciphertext must be bound to the cache key, trusted tenant/account, and credential purpose using authenticated associated data or equivalent purpose isolation, with encryption keys outside Redis. Tests must reject ciphertext copied to another key, tenant/account, or purpose.
+- Added the skill to the README and website catalog.
+
+## v0.2.0 — Copilot instructions and safer skill management
+
+The implementation was merged in [PR #4](https://github.com/dprakash2101/dotnet-production-agent-skills/pull/4) and published as [`dotnet-production-agent-skills@0.2.0`](https://www.npmjs.com/package/dotnet-production-agent-skills/v/0.2.0). These notes document that release; the release notes page is a follow-up documentation change.
+
+### New
+
+- Copilot project installs manage an always-on engineering section in `.github/copilot-instructions.md`. Existing team instructions outside the managed markers remain intact; uninstall removes only the managed section.
+- A `retry-resilience` skill covers explicitly requested retries and reviews of existing retry policies. Its guidance avoids introducing retries automatically.
+- The CLI has a separate Copilot hooks interface for future command guardrails. No hooks are installed by this change.
+
+### Improved
+
+- Repeated installs skip unchanged managed skills. An updated packaged skill replaces an unchanged installed copy.
+- Forced uninstall backs up locally edited managed skills and reports the backup path.
+- `doctor` parses YAML frontmatter, accepts multiline descriptions, checks skill metadata and local references, reports packaged updates and Copilot instruction state, and exits nonzero for installation or validation errors.
+- Skill descriptions now give agents clearer cues for selecting task-specific guidance. Copilot installation output includes skill discovery commands.
+- CLI help displays the published executable name, `dotnet-production-agent-skills`.
+
+### Compatibility and upgrade
+
+- Targets (`all`, `shared`, `codex`, `copilot`, `claude`, `cursor`), user and project scopes, copy and link modes, and existing CLI flags remain supported.
+- Copilot instructions are added only for project-scope Copilot installs (including `--target all --scope project`). User-scope Copilot installs continue to install skills in `~/.copilot/skills`.
+- Review any local skill edits before updating. The CLI still requires `--force --yes` for noninteractive replacement of conflicts, with a backup of the replaced content.
+- The CLI now depends on the `yaml` npm package. Install the package normally so npm resolves its runtime dependency.
+
+### Validation
+
+`npm run validate` passed: 30 packaged skills validated and 14 CLI tests passed. The CLI help, Copilot install dry run, doctor output, package dry run, and `git diff --check` were also exercised.

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.1",
+  "version": "0.2.1",
   "description": "Portable production .NET engineering skills for coding agents",
   "license": "MIT",
   "author": {
@@ -21,7 +21,9 @@
   },
   "files": [
     "dist/src",
+    "copilot",
     "skills",
+    "RELEASE_NOTES.md",
     "README.md",
     "LICENSE"
   ],
@@ -49,5 +51,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/redis-dotnet/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: redis-dotnet
+description: Implement, review, or troubleshoot Redis caching in .NET and ASP.NET Core, including StackExchange.Redis, IDistributedCache, key design, expiration, cache invalidation, performance, and secure handling of cached tokens or secrets.
+---
+
+# Redis caching for .NET
+
+Inspect the application's existing cache abstraction, Redis client registration, serializers, and failure policy before changing code. Reuse established helpers and avoid adding a second connection or serialization scheme without a reason.
+
+- Choose a stable namespaced key with environment and tenant/customer isolation where needed. Do not place access tokens, secret keys, passwords, or sensitive personal data in key names; keys appear in diagnostics and operational tools.
+- Set an explicit TTL from the data's real validity. For access tokens, expire the cache entry before the token's expiry with a small safety margin, and handle refresh races across instances. Define invalidation when source data changes. Avoid unbounded or permanently cached entries by default.
+- Keep values small and version serialized payloads when schemas can change. Do not cache null/error responses without a deliberate short-lived policy. Avoid large scans, blocking commands, and per-request connection creation; bound timeouts and concurrency.
+- **Never store access tokens, refresh tokens, API keys, secret keys, passwords, or other credentials in Redis as plaintext values.** Prefer caching a non-sensitive reference when possible. If a credential must be cached, encrypt before writing and decrypt only after reading. Require the established, vetted helper to authenticate the intended cache key, trusted tenant/account identity, and credential purpose as associated data (AAD), or provide equivalent purpose isolation for that exact context. Derive the same unambiguous, versioned context independently from the authorized request and computed key on both paths; never accept tenant or purpose solely from Redis or the ciphertext. Reject a mismatch without returning or using the credential. If the helper cannot bind this context, extend or wrap it safely before caching credentials. Keep encryption keys outside Redis in the existing secret-management system and support key rotation; do not invent cryptography.
+- Protect Redis transport with TLS and restrict access using the deployment's network and least-privilege authentication controls. Encryption in transit or at rest does not replace application-level protection of sensitive cached values. Do not log cache values, credentials, connection strings, or decrypted payloads.
+- Decide whether a Redis miss or outage should fall back to the source, fail closed, or surface an error based on the flow. Avoid a thundering herd on misses and keep any lock or refresh mechanism bounded. Add retries only when requested or required by existing architecture.
+- Test expiration, invalidation, tenant isolation, concurrent cache misses, serialization changes, and Redis failure behavior where relevant. For credential caching, verify plaintext secrecy, decrypt failures, and key rotation. Copy a valid ciphertext to another cache key, tenant/account, or credential purpose and verify decryption or use fails closed in each case.

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