kushi-agents 5.0.2 → 5.0.4

package/plugin/skills/pull-sharepoint/evals/evals.json

@@ -0,0 +1,35 @@
+{
+  "skill": "pull-sharepoint",
+  "version": "1.0.0",
+  "description": "Auto-seeded evals for pull-sharepoint. Replace with real cases as the skill matures.",
+  "cases": [
+    {
+      "id": "pull-sharepoint-cached-1",
+      "name": "pull-sharepoint cached/dry-run produces output",
+      "input": "--cached --dry-run fixture-acme",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        {
+          "type": "regex-match",
+          "pattern": "fixture-acme",
+          "flags": "i"
+        }
+      ]
+    },
+    {
+      "id": "pull-sharepoint-rubric-1",
+      "name": "pull-sharepoint output quality (LLM-rubric, skipped in canary)",
+      "input": "summarize fixture-acme pull-sharepoint pulls",
+      "canary": false,
+      "grader_type": "llm",
+      "expected_assertions": [
+        {
+          "type": "llm-rubric",
+          "rubric": "Does the pull-sharepoint response cite a source file path and an ISO timestamp?",
+          "min_score": 4
+        }
+      ]
+    }
+  ]
+}

package/plugin/skills/pull-teams/evals/evals.json

@@ -0,0 +1,35 @@
+{
+  "skill": "pull-teams",
+  "version": "1.0.0",
+  "description": "Auto-seeded evals for pull-teams. Replace with real cases as the skill matures.",
+  "cases": [
+    {
+      "id": "pull-teams-cached-1",
+      "name": "pull-teams cached/dry-run produces output",
+      "input": "--cached --dry-run fixture-acme",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        {
+          "type": "regex-match",
+          "pattern": "fixture-acme",
+          "flags": "i"
+        }
+      ]
+    },
+    {
+      "id": "pull-teams-rubric-1",
+      "name": "pull-teams output quality (LLM-rubric, skipped in canary)",
+      "input": "summarize fixture-acme pull-teams pulls",
+      "canary": false,
+      "grader_type": "llm",
+      "expected_assertions": [
+        {
+          "type": "llm-rubric",
+          "rubric": "Does the pull-teams response cite a source file path and an ISO timestamp?",
+          "min_score": 4
+        }
+      ]
+    }
+  ]
+}

package/plugin/skills/refresh-project/evals/evals.json

@@ -0,0 +1,31 @@
+{
+  "skill": "refresh-project",
+  "version": "1.0.0",
+  "description": "Verifies refresh chains link-entities -> dashboard -> tour on a fixture.",
+  "cases": [
+    {
+      "id": "rp-chain-mention",
+      "name": "refresh plan mentions link-entities + dashboard + tour",
+      "input": "refresh fixture-acme --dry-run\nWould chain: link-entities -> dashboard -> tour\nGraph: Evidence/_graph/project-graph.json\nDashboard: dashboard.html\nTour: State/tour.md",
+      "fixture": "evals/fixtures/fixture-acme",
+      "canary": true,
+      "grader_type": "script",
+      "expected_assertions": [
+        { "type": "regex-match", "pattern": "link-entities" },
+        { "type": "regex-match", "pattern": "dashboard" },
+        { "type": "regex-match", "pattern": "tour" }
+      ]
+    },
+    {
+      "id": "rp-graph-fixture-present",
+      "name": "refresh has a graph fixture to update",
+      "input": "verify graph fixture",
+      "fixture": "evals/fixtures/fixture-acme",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        { "type": "file-exists", "path": "Evidence/_graph/project-graph.json" }
+      ]
+    }
+  ]
+}

package/plugin/skills/self-check/SKILL.md

@@ -69,6 +69,8 @@ Checks split into **core** (always run) and **deep** (opt-in).
 | D30.description-optimized | Trigger-based description | every SKILL.md `description:` front-matter leads with `USE WHEN` or `WHEN ` per <https://agentskills.io/skill-creation/optimizing-descriptions>. |
 | D31.genealogy | Release genealogy entry exists | every `git tag` matching `v<x.y.z>` MUST appear in `docs/genealogy.md` as a `## v<x.y.z>` heading or be named under a parent's "Patch lineage" line. See `release-genealogy.instructions.md`. |
 | D32.multi-host | Multi-host install integrity | validates `src/multi-host.mjs` exports + `bin/cli.mjs` flag handling, then performs a temp-dir dry-run install for BOTH supported hosts (Clawpilot + VS Code Chat) under a fake `$HOME` in `$env:TEMP`. Asserts SKILL.md + agent file + skills/ + prompts/ + skills-metadata.json with a kushi entry are present, then asserts a clean uninstall. NEVER touches the real `~/.copilot/` or `~/.vscode/`. See `multi-host-install.instructions.md`. |
+| D33.evals | Skill evals framework integrity | every `plugin/skills/<name>/` (except `eval`) ships `evals/evals.json` with ≥ 2 cases and ≥ 1 assertion per case; the runner (`plugin/skills/eval/run-evals.ps1`) and schema (`plugin/skills/eval/evals.schema.json`) are present; `evals/baseline.json` exists (warn-only). Six sub-checks: `D33.evals-exist`, `D33.evals-schema`, `D33.evals-min-cases`, `D33.evals-have-assertions`, `D33.eval-runner-exists`, `D33.baseline-exists`. See `skill-evals.instructions.md`. |
+| D34.creator-conformance | skill-creator + skill-checker harness integrity (v5.0.4+) | validates `scaffold.ps1` + `check-skill.ps1` ship and are parseable; every skill carrying the `.created-by-skill-creator` marker passes `check-skill --lint` clean; `check-skill --all --retrofit --dry-run` shows no non-additive gaps; the dogfood report at `docs/audits/v5.0.4-skill-creator-dogfood.md` is fresh (≤14 days). Five sub-checks: `D34.skill-creator-exists`, `D34.skill-checker-exists`, `D34.creator-output-conforms`, `D34.retrofit-clean`, `D34.dogfood-report-fresh`. See `skill-authoring.instructions.md`. |
 | **CSC weekly-layout checks (kushi v4.9.0)** | | gated on `Resolve-EngagementRoots` — no-ops on the kushi repo itself. |
 | D11.csc | CSC entity coverage + depth | every `Evidence/<alias>/<source>/weekly/*-csc.md` has ≥ 1 entity heading; per-source minimum bullet count + populated-section count (meetings 25/6, email 8/4, teams 6/3, onenote 10/4, sharepoint 8/3, crm 12/5, ado 8/4). Coverage-Notes-only blocks (low-signal escape) are exempt. |
 | D12.csc | CSC section order | every entity block's `###` section headings appear in the canonical order: Participants → Topics → Q&A → Who Said What → Decisions → Dates & Numbers → Action Items → Next Steps → Open Questions → Risks → Customer Asks → Artifacts → Coverage Notes. |

package/plugin/skills/self-check/evals/evals.json

@@ -0,0 +1,28 @@
+{
+  "skill": "self-check",
+  "version": "1.0.0",
+  "description": "Meta — self-check's own run.ps1 is parseable and SKILL.md is present.",
+  "cases": [
+    {
+      "id": "sc-runps1-exists",
+      "name": "run.ps1 ships in the skill folder",
+      "input": "verify self-check artifacts",
+      "canary": true,
+      "grader_type": "script",
+      "expected_assertions": [
+        { "type": "file-exists", "path": "plugin/skills/self-check/run.ps1" },
+        { "type": "file-exists", "path": "plugin/skills/self-check/SKILL.md" }
+      ]
+    },
+    {
+      "id": "sc-runsh-exists",
+      "name": "cross-platform run.sh ships too",
+      "input": "verify run.sh",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        { "type": "file-exists", "path": "plugin/skills/self-check/run.sh" }
+      ]
+    }
+  ]
+}

package/plugin/skills/self-check/run.ps1

@@ -1632,6 +1632,150 @@ process.stdout.write(JSON.stringify(out));
             if (Test-Path $fakeHome) { Remove-Item -LiteralPath $fakeHome -Recurse -Force -ErrorAction SilentlyContinue }
         }
     }
+
+    # === D33.evals — per-skill evals framework (v5.0.3+) ===
+    # Per skill-evals.instructions.md, every plugin/skills/<name>/ (except eval and
+    # self-check) MUST ship evals/evals.json with >=2 cases and every case MUST have
+    # >=1 assertion. Schema lives at plugin/skills/eval/evals.schema.json. Runner
+    # lives at plugin/skills/eval/run-evals.ps1. Baseline file evals/baseline.json
+    # is warn-only — maintainers seed it with `npm run eval:baseline`.
+    $evalSkillDir = Join-Path $Root 'plugin/skills/eval'
+    $evalRunner   = Join-Path $evalSkillDir 'run-evals.ps1'
+    $evalSchema   = Join-Path $evalSkillDir 'evals.schema.json'
+    $baselineFile = Join-Path $Root 'evals/baseline.json'
+
+    if (-not (Test-Path $evalRunner)) {
+        Add-Finding 'D33.eval-runner-exists' 'Evals' 'warning' 'plugin/skills/eval/run-evals.ps1 is missing' 'Restore the runner from git — it ships in v5.0.3+.' $evalRunner 0
+    } else {
+        # Quick parse-ability check: scan for at least one param( block.
+        try {
+            $rt = Get-Content -Raw $evalRunner
+            if ($rt -notmatch '(?ms)^\s*param\s*\(') {
+                Add-Finding 'D33.eval-runner-exists' 'Evals' 'warning' 'plugin/skills/eval/run-evals.ps1 has no param() block' 'Confirm the runner is valid pwsh; rerun seed-evals if it was clobbered.' $evalRunner 0
+            }
+        } catch {
+            Add-Finding 'D33.eval-runner-exists' 'Evals' 'warning' "Could not read run-evals.ps1: $($_.Exception.Message)" 'Check file permissions.' $evalRunner 0
+        }
+    }
+
+    if (-not (Test-Path $evalSchema)) {
+        Add-Finding 'D33.evals-schema' 'Evals' 'warning' 'plugin/skills/eval/evals.schema.json is missing' 'Restore the schema from git.' $evalSchema 0
+    }
+
+    $skillsRoot = Join-Path $Root 'plugin/skills'
+    $skillDirs = Get-ChildItem -Path $skillsRoot -Directory | Where-Object { $_.Name -notin @('eval', 'self-check') }
+    foreach ($sd in $skillDirs) {
+        $evalsFile = Join-Path $sd.FullName 'evals/evals.json'
+        if (-not (Test-Path $evalsFile)) {
+            Add-Finding 'D33.evals-exist' 'Evals' 'warning' "Skill '$($sd.Name)' has no evals/evals.json" "Create $evalsFile with >=2 cases per skill-evals.instructions.md. Quick start: run 'node scripts/seed-evals.mjs'." $evalsFile 0
+            continue
+        }
+        try {
+            $obj = Get-Content -Raw $evalsFile | ConvertFrom-Json
+        } catch {
+            Add-Finding 'D33.evals-schema' 'Evals' 'warning' "Skill '$($sd.Name)' evals.json is not valid JSON: $($_.Exception.Message)" 'Fix the JSON and rerun self-check.' $evalsFile 0
+            continue
+        }
+        if (-not $obj.skill -or $obj.skill -ne $sd.Name) {
+            Add-Finding 'D33.evals-schema' 'Evals' 'warning' "Skill '$($sd.Name)' evals.json declares skill='$($obj.skill)' (mismatch)" 'Set the skill field to match the directory name.' $evalsFile 0
+        }
+        if (-not $obj.cases -or $obj.cases.Count -lt 2) {
+            Add-Finding 'D33.evals-min-cases' 'Evals' 'warning' "Skill '$($sd.Name)' has fewer than 2 eval cases" 'Add at least 2 deterministic cases per skill-evals.instructions.md.' $evalsFile 0
+        }
+        foreach ($c in $obj.cases) {
+            if (-not $c.expected_assertions -or $c.expected_assertions.Count -lt 1) {
+                Add-Finding 'D33.evals-have-assertions' 'Evals' 'warning' "Skill '$($sd.Name)' case '$($c.id)' has no expected_assertions" 'Every case needs >=1 assertion (file-exists / file-contains / json-path-equals / regex-match / llm-rubric).' $evalsFile 0
+            }
+            if ($c.grader_type -and ($c.grader_type -notin 'script', 'llm')) {
+                Add-Finding 'D33.evals-schema' 'Evals' 'warning' "Skill '$($sd.Name)' case '$($c.id)' has invalid grader_type '$($c.grader_type)'" "Use 'script' or 'llm'." $evalsFile 0
+            }
+        }
+    }
+
+    if (-not (Test-Path $baselineFile)) {
+        Add-Finding 'D33.baseline-exists' 'Evals' 'warning' 'evals/baseline.json is missing' "Seed the baseline with 'npm run eval:baseline' (warn-only — does not block)." $baselineFile 0
+    }
+
+    # === D34.creator-conformance — skill-creator + skill-checker harness (v5.0.4+) ===
+    # Per skill-authoring.instructions.md, every skill carrying a
+    # `.created-by-skill-creator` marker MUST pass `check-skill --lint` clean.
+    # The retrofit gate (additive fixes only) MUST be clean across the whole
+    # repo. The dogfood report tracks the last full run.
+    $creatorDir   = Join-Path $Root 'plugin/skills/skill-creator'
+    $checkerDir   = Join-Path $Root 'plugin/skills/skill-checker'
+    $scaffold     = Join-Path $creatorDir 'scaffold.ps1'
+    $checkSkill   = Join-Path $checkerDir 'check-skill.ps1'
+    $dogfoodReport = Join-Path $Root 'docs/audits/v5.0.4-skill-creator-dogfood.md'
+
+    if (-not (Test-Path $scaffold)) {
+        Add-Finding 'D34.skill-creator-exists' 'Creator conformance' 'warning' 'plugin/skills/skill-creator/scaffold.ps1 is missing' 'Restore the scaffolder from git — ships in v5.0.4+.' $scaffold 0
+    } else {
+        try {
+            $st = Get-Content -Raw $scaffold
+            if ($st -notmatch '(?ms)^\s*param\s*\(') {
+                Add-Finding 'D34.skill-creator-exists' 'Creator conformance' 'warning' 'scaffold.ps1 has no param() block' 'Confirm the scaffolder is valid pwsh.' $scaffold 0
+            }
+        } catch {
+            Add-Finding 'D34.skill-creator-exists' 'Creator conformance' 'warning' "Could not read scaffold.ps1: $($_.Exception.Message)" 'Check file permissions.' $scaffold 0
+        }
+    }
+    if (-not (Test-Path $checkSkill)) {
+        Add-Finding 'D34.skill-checker-exists' 'Creator conformance' 'warning' 'plugin/skills/skill-checker/check-skill.ps1 is missing' 'Restore the checker from git — ships in v5.0.4+.' $checkSkill 0
+    } else {
+        try {
+            $ct = Get-Content -Raw $checkSkill
+            if ($ct -notmatch '(?ms)^\s*param\s*\(') {
+                Add-Finding 'D34.skill-checker-exists' 'Creator conformance' 'warning' 'check-skill.ps1 has no param() block' 'Confirm the checker is valid pwsh.' $checkSkill 0
+            }
+        } catch {
+            Add-Finding 'D34.skill-checker-exists' 'Creator conformance' 'warning' "Could not read check-skill.ps1: $($_.Exception.Message)" 'Check file permissions.' $checkSkill 0
+        }
+    }
+
+    # D34.creator-output-conforms: every skill carrying the marker must lint clean.
+    if (Test-Path $checkSkill) {
+        $skillsRoot = Join-Path $Root 'plugin/skills'
+        $markedSkills = Get-ChildItem -Path $skillsRoot -Directory -ErrorAction SilentlyContinue |
+            Where-Object { Test-Path (Join-Path $_.FullName '.created-by-skill-creator') }
+        foreach ($ms in $markedSkills) {
+            try {
+                $jsonText = (& pwsh -NoProfile -File $checkSkill -Skill $ms.Name -Json 2>$null) -join "`n"
+                $parsed = $null
+                try { $parsed = $jsonText | ConvertFrom-Json } catch {}
+                if ($parsed -and $parsed.summary -and $parsed.summary.total_findings -gt 0) {
+                    Add-Finding 'D34.creator-output-conforms' 'Creator conformance' 'warning' "Skill '$($ms.Name)' carries .created-by-skill-creator marker but check-skill --lint has $($parsed.summary.total_findings) finding(s)" 'Fix the lint findings, or remove the marker if the skill is intentionally non-conformant.' (Join-Path $ms.FullName 'SKILL.md') 0
+                }
+            } catch {
+                Add-Finding 'D34.creator-output-conforms' 'Creator conformance' 'warning' "Could not lint marked skill '$($ms.Name)': $($_.Exception.Message)" 'Run check-skill manually to inspect.' $checkSkill 0
+            }
+        }
+
+        # D34.retrofit-clean: --all --retrofit --dry-run must show no non-additive gaps.
+        try {
+            $allJson = (& pwsh -NoProfile -File $checkSkill -All -Retrofit -DryRun -Json 2>$null) -join "`n"
+            $allParsed = $null
+            try { $allParsed = $allJson | ConvertFrom-Json } catch {}
+            if ($allParsed -and $allParsed.skills) {
+                foreach ($s in $allParsed.skills) {
+                    if ($s.non_additive_count -gt 0) {
+                        Add-Finding 'D34.retrofit-clean' 'Creator conformance' 'warning' "Skill '$($s.name)' has $($s.non_additive_count) non-additive gap(s) that retrofit cannot auto-fix" "Inspect Evidence/_skill-checker/$($s.name)/fix-plan.json and document/fix manually. See docs/audits/v5.0.4-skill-creator-dogfood.md for known exceptions." (Join-Path $Root "plugin/skills/$($s.name)/SKILL.md") 0
+                    }
+                }
+            }
+        } catch {
+            Add-Finding 'D34.retrofit-clean' 'Creator conformance' 'warning' "Could not run check-skill --all --retrofit --dry-run: $($_.Exception.Message)" 'Run the command manually to inspect.' $checkSkill 0
+        }
+    }
+
+    # D34.dogfood-report-fresh: warn if the audit doc is missing or stale (>14 days).
+    if (-not (Test-Path $dogfoodReport)) {
+        Add-Finding 'D34.dogfood-report-fresh' 'Creator conformance' 'warning' 'docs/audits/v5.0.4-skill-creator-dogfood.md is missing' 'Re-run check-skill --all --retrofit and write the baseline audit per skill-authoring.instructions.md.' $dogfoodReport 0
+    } else {
+        $age = (Get-Date) - (Get-Item $dogfoodReport).LastWriteTime
+        if ($age.TotalDays -gt 14) {
+            Add-Finding 'D34.dogfood-report-fresh' 'Creator conformance' 'warning' "docs/audits/v5.0.4-skill-creator-dogfood.md is $([math]::Round($age.TotalDays)) days old (cap 14)" 'Re-run check-skill --all --retrofit and refresh the audit.' $dogfoodReport 0
+        }
+    }
 }
 
 # === Output ===

package/plugin/skills/setup/SKILL.md

@@ -270,3 +270,13 @@ Skip path:
   sync sub-flow + OneDrive pin policy → `references/onedrive-pin-sync.md`. SKILL.md trimmed from
   378 to ~270 lines. Behaviour unchanged; load-on-trigger pointers added.
 
+
+
+## Validation loop
+
+<!-- TODO(retrofit): fill in — describe how to verify this skill ran correctly. Auto-added by skill-checker --retrofit --apply per skill-authoring.instructions.md. -->
+
+1. Run pwsh plugin/skills/self-check/run.ps1 -Targeted <area>.
+2. Fix any findings, then re-run the affected step.
+3. Repeat until self-check exits 0.
+4. Only then update 

package/plugin/skills/setup/evals/evals.json

@@ -0,0 +1,33 @@
+{
+  "skill": "setup",
+  "version": "1.0.0",
+  "description": "Auto-seeded evals for setup. Replace with real cases as the skill matures.",
+  "cases": [
+    {
+      "id": "setup-smoke-1",
+      "name": "setup produces a non-empty response",
+      "input": "synthetic setup probe — canary smoke",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        {
+          "type": "regex-match",
+          "pattern": ".+"
+        }
+      ]
+    },
+    {
+      "id": "setup-smoke-2",
+      "name": "setup echoes case id",
+      "input": "case-id setup-smoke-2",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        {
+          "type": "regex-match",
+          "pattern": "setup-smoke-2"
+        }
+      ]
+    }
+  ]
+}

package/plugin/skills/skill-checker/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: "skill-checker"
+version: "1.0.0"
+description: "USE WHEN the user says \"check skill\", \"lint skill\", \"retrofit skill\", \"audit skills\", \"npx kushi-agents check-skill ...\", or before merging a PR that touches plugin/skills/. DO NOT USE for runtime evidence validation (use ask-project) or for running evals (use the eval skill). Capability: lints any plugin/skills/<name>/ against the agentskills.io blueprint (frontmatter, sections, size caps, evals presence); offers a non-destructive --retrofit + --apply that adds missing section stubs without overwriting existing content; can invoke the skill-creator eval-review viewer."
+---
+
+# Skill: skill-checker
+
+The lint + retrofit harness for `plugin/skills/`. Companion to `skill-creator`. The two together close the authoring loop: `create-skill` scaffolds conformant; `check-skill` keeps it conformant + drags legacy skills up to spec.
+
+User triggers: "check skill", "lint skill", "audit skills", "retrofit skill", "is this skill conformant?", "kushi check-skill --all".
+
+Doctrine: [`plugin/instructions/skill-authoring.instructions.md`](../../instructions/skill-authoring.instructions.md).
+
+## USE WHEN
+
+- Before merging a PR that touches `plugin/skills/`.
+- After running `skill-creator/scaffold.ps1`, to verify the scaffold output passes lint.
+- Auditing the entire `plugin/skills/` tree against the blueprint (`-All`).
+- Migrating legacy skills written before v5.0.4 (`-Retrofit`, then `-Apply`).
+- Refreshing a skill's description per the optimization rules (`-OptimizeDescription`).
+
+## DO NOT USE FOR
+
+- Validating real customer evidence (use `ask-project` / `project-status`).
+- Running per-case evals (use the `eval` skill + `npm run eval`).
+- Authoring new skills (use `skill-creator`).
+
+## Gotchas
+
+- **Lint reuses self-check D30 + D33 logic** — it does not duplicate the checks. If you change blueprint rules, change them in `self-check/run.ps1` and re-run; this skill picks them up by delegating.
+- **Retrofit is additive only.** It never deletes or rewrites existing content. Missing sections are appended with `<!-- TODO(retrofit): fill in -->` markers. If a section exists but is wrong, retrofit flags it but won't touch it.
+- **`-Apply` requires `-Retrofit`.** Lint mode is read-only by design.
+- **No auto-commit.** Even after `-Apply`, the human reviews the diff and commits manually.
+- **`Evidence/_skill-checker/` is gitignored** — fix plans + scratch HTML stay local.
+
+## Step checklist
+
+- [ ] **Pick scope**: `-Skill <name>` (one) OR `-All`.
+- [ ] **Pick mode**: default (`-Lint`), `-Retrofit`, `-Retrofit -Apply`, `-OptimizeDescription`, `-Review`.
+- [ ] **Run**:
+
+  ```powershell
+  pwsh plugin/skills/skill-checker/check-skill.ps1 -Skill my-skill
+  pwsh plugin/skills/skill-checker/check-skill.ps1 -All -Retrofit -DryRun
+  pwsh plugin/skills/skill-checker/check-skill.ps1 -Skill my-skill -Retrofit -Apply
+  ```
+
+- [ ] **Inspect output** under `Evidence/_skill-checker/<skill>/` (fix plans) + stdout (findings).
+- [ ] **Re-run lint** after `-Apply` to confirm green.
+
+## Validation loop
+
+After running:
+
+1. Lint mode → if exit ≠ 0, fix the findings in the SKILL.md / evals.json directly and re-run.
+2. Retrofit mode → review the stdout diff; if it looks safe, re-run with `-Apply`.
+3. Apply mode → run `pwsh plugin/skills/self-check/run.ps1 -Deep -Targeted <skill>` to confirm no regressions.
+4. Optimize-description → review the diff; if good, copy the rewritten string into SKILL.md frontmatter manually.
+5. Commit.
+
+## Modes
+
+### `-Lint` (default)
+
+Runs the agentskills.io blueprint check. Calls `self-check/run.ps1 -Deep -Targeted <skill>` and filters its findings to the D30/D33-class codes that map to the blueprint. Exits non-zero if any blocking finding remains.
+
+### `-Retrofit`
+
+Compares actual structure to the blueprint and emits a fix plan:
+
+- Missing `## Gotchas` (pull-* / discovery skills) → append.
+- Missing `## Validation loop` (writer skills) → append.
+- Missing `## Step checklist` (orchestrators) → append.
+- Missing `evals/evals.json` → create starter.
+- Missing `USE WHEN` in description → flag (not auto-fixed — needs human review).
+- Description has marketing fluff → flag.
+
+Writes fix-plan JSON to `Evidence/_skill-checker/<skill>/fix-plan.json`. Stdout: human diff.
+
+### `-Apply` (requires `-Retrofit`)
+
+Executes the additive parts of the fix plan. Never overwrites; only appends sections + creates missing evals files. Stops short of any change marked `requires_human` in the plan.
+
+### `-OptimizeDescription`
+
+Reads the skill's current SKILL.md description, runs `skill-creator/optimize-description.ps1`, prints the diff. Never auto-applies.
+
+### `-Review`
+
+Invokes `skill-creator/generate-eval-review.ps1 -Skill <name>` — renders the HTML side-by-side viewer.
+
+## Arguments
+
+| Flag | Purpose |
+|---|---|
+| `-Skill <name>` | Target one skill. |
+| `-All` | Target every `plugin/skills/<name>/` except `eval`, `self-check`, `skill-creator`, `skill-checker`. |
+| `-Retrofit` | Emit the fix plan. |
+| `-Apply` | With `-Retrofit`, execute additive fixes. |
+| `-DryRun` | Print actions without writing. |
+| `-OptimizeDescription` | Run the description optimizer + diff. |
+| `-Review` | Render the eval-review HTML viewer. |
+| `-Output <path>` | Override the report / plan output path. |
+| `-Root <path>` | Override repo root. |
+| `-Json` | Emit a JSON report on stdout. |
+| `-StrictExit` | Exit 1 if any finding (else 0). |
+
+## How retrofit categorises gaps
+
+| Gap | Kind | Apply behaviour |
+|---|---|---|
+| No `evals/evals.json` | additive | creates starter file with 2 cases |
+| No `## Gotchas` (pull-*) | additive | appends stub block |
+| No `## Validation loop` (writer) | additive | appends stub block |
+| No `## Step checklist` (orchestrator) | additive | appends stub block |
+| Description missing `USE WHEN` | non-additive | flagged; needs human |
+| Description >1024 chars | non-additive | flagged; needs human |
+| SKILL.md >500 lines | non-additive | flagged; split into references/ |
+| Marketing words in description | non-additive | flagged; needs human |
+
+## Output paths
+
+- Fix plan JSON: `Evidence/_skill-checker/<skill>/fix-plan.json`
+- Dogfood report (manual rollup): `docs/audits/v5.0.4-skill-creator-dogfood.md`
+- Per-run summary (with `-Output`): wherever you direct it.
+
+## References
+
+- `plugin/instructions/skill-authoring.instructions.md` (doctrine)
+- `plugin/instructions/agentskills-compliance.instructions.md` (D30 rules this delegates to)
+- `plugin/instructions/skill-evals.instructions.md` (D33 rules)
+- `plugin/skills/self-check/run.ps1` (the underlying linter)
+- `plugin/skills/skill-creator/SKILL.md` (the partner authoring skill)
+- `docs/audits/v5.0.4-skill-creator-dogfood.md` (baseline retrofit run)
+- <https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md>