kushi-agents 5.0.2 → 5.0.4

package/plugin/skills/skill-checker/check-skill.ps1

@@ -0,0 +1,416 @@
+<#
+.SYNOPSIS
+skill-checker — lint, retrofit, apply, optimize-description, and review for
+plugin/skills/<name>/ trees.
+
+.DESCRIPTION
+Default mode is -Lint: reuses self-check D30 + D33 logic to validate that a
+skill matches the agentskills.io blueprint as codified in
+plugin/instructions/skill-authoring.instructions.md.
+
+-Retrofit emits a non-destructive fix plan; -Apply executes only the additive
+parts. -OptimizeDescription runs the description optimizer; -Review renders the
+HTML eval-review viewer.
+
+The skill blueprint:
+  - YAML frontmatter with `name:` matching the directory.
+  - `description:` containing "USE WHEN" in the first 160 chars.
+  - At least one of: ## Gotchas / ## Validation loop / ## Step checklist.
+  - For pull-* skills: ## Gotchas REQUIRED.
+  - For writer skills: ## Validation loop REQUIRED.
+  - For orchestrators: ## Step checklist REQUIRED.
+  - SKILL.md size: <=500 lines, <=5000 tokens.
+  - evals/evals.json present with >=2 cases.
+
+The "writer" + "orchestrator" lists below mirror self-check/run.ps1.
+#>
+[CmdletBinding(DefaultParameterSetName='Lint')]
+param(
+    [string]$Skill,
+    [switch]$All,
+    [switch]$Retrofit,
+    [switch]$Apply,
+    [switch]$DryRun,
+    [switch]$OptimizeDescription,
+    [switch]$Review,
+    [string]$Output,
+    [switch]$Json,
+    [switch]$StrictExit,
+    [string]$Root = (Resolve-Path (Join-Path $PSScriptRoot "..\..\..")).Path
+)
+
+$ErrorActionPreference = 'Stop'
+
+# ---- helpers ---------------------------------------------------------------
+
+$writerSkills = @(
+    'bootstrap-project', 'refresh-project', 'build-state', 'consolidate-evidence',
+    'link-entities', 'dashboard', 'tour', 'aggregate-project', 'project-status',
+    'fde-intake', 'fde-report', 'fde-triage', 'emit-vertex', 'vertex-link',
+    'propose-ado-update', 'apply-ado-update'
+)
+$orchestratorSkills = @(
+    'bootstrap-project', 'refresh-project', 'build-state', 'link-entities',
+    'dashboard', 'tour'
+)
+$excludeFromAll = @('eval', 'self-check', 'skill-creator', 'skill-checker')
+
+function Get-Frontmatter {
+    param([string]$Path)
+    $text = Get-Content -Raw -Path $Path
+    if ($text -notmatch '^(?s)---\r?\n(.*?)\r?\n---') { return @{} }
+    $yaml = $Matches[1]
+    $fm = @{}
+    foreach ($line in $yaml -split "`n") {
+        if ($line -match '^\s*([a-zA-Z0-9_-]+)\s*:\s*(.+?)\s*$') {
+            $key = $Matches[1]
+            $val = $Matches[2].Trim('"', "'", ' ')
+            $fm[$key] = $val
+        }
+    }
+    return $fm
+}
+
+function Get-SkillType {
+    param([string]$Name)
+    if ($Name -like 'pull-*') { return 'pull' }
+    if ($orchestratorSkills -contains $Name) { return 'orchestrator' }
+    if ($writerSkills -contains $Name) { return 'writer' }
+    return 'other'
+}
+
+function Get-TargetSkills {
+    param([string]$Root, [string]$Skill, [switch]$All)
+    $skillsRoot = Join-Path $Root 'plugin/skills'
+    if ($Skill) {
+        $d = Join-Path $skillsRoot $Skill
+        if (-not (Test-Path $d)) { throw "No such skill: $Skill (looked at $d)" }
+        return @(Get-Item -LiteralPath $d)
+    }
+    if ($All) {
+        return Get-ChildItem -Path $skillsRoot -Directory | Where-Object { $excludeFromAll -notcontains $_.Name }
+    }
+    throw "Specify -Skill <name> or -All."
+}
+
+function Lint-Skill {
+    param([System.IO.DirectoryInfo]$Dir)
+    $findings = New-Object System.Collections.Generic.List[object]
+    $skillMd = Join-Path $Dir.FullName 'SKILL.md'
+    if (-not (Test-Path $skillMd)) {
+        $findings.Add([pscustomobject]@{ code='SC1.no-skill-md'; severity='error'; message="SKILL.md missing in $($Dir.Name)/"; kind='non-additive' })
+        return $findings
+    }
+    $text = Get-Content -Raw $skillMd
+    $lines = (Get-Content $skillMd).Count
+    $tokens = [math]::Round($text.Length / 4)
+    $fm = Get-Frontmatter $skillMd
+    $type = Get-SkillType -Name $Dir.Name
+
+    # Frontmatter name match.
+    if ($fm['name'] -and $fm['name'] -ne $Dir.Name) {
+        $findings.Add([pscustomobject]@{ code='SC2.name-mismatch'; severity='error'; message="frontmatter name '$($fm['name'])' != directory '$($Dir.Name)'"; kind='non-additive' })
+    }
+    if (-not $fm['name']) {
+        $findings.Add([pscustomobject]@{ code='SC2.no-name'; severity='error'; message="frontmatter missing 'name:'"; kind='non-additive' })
+    }
+
+    # Description shape.
+    $desc = $fm['description']
+    if (-not $desc) {
+        $findings.Add([pscustomobject]@{ code='SC3.no-description'; severity='error'; message="frontmatter missing 'description:'"; kind='non-additive' })
+    } else {
+        $head = $desc.Substring(0, [Math]::Min(160, $desc.Length))
+        if ($head -notmatch '\bUSE WHEN\b') {
+            $findings.Add([pscustomobject]@{ code='SC3.description-no-use-when'; severity='warning'; message="description does not lead with 'USE WHEN' in first 160 chars"; kind='non-additive' })
+        }
+        if ($desc.Length -gt 1024) {
+            $findings.Add([pscustomobject]@{ code='SC3.description-too-long'; severity='warning'; message="description is $($desc.Length) chars (cap 1024)"; kind='non-additive' })
+        }
+        # Marketing-word check: case-sensitive lowercase only so title-cased
+        # proper nouns (e.g. "Comprehensive Structured Capture") are not flagged.
+        $marketing = @('powerful', 'comprehensive', 'blazing', 'seamless', 'effortless', 'cutting-edge', 'world-class')
+        foreach ($w in $marketing) {
+            if ($desc -cmatch "\b$w\b") {
+                $findings.Add([pscustomobject]@{ code='SC3.description-marketing'; severity='warning'; message="description contains marketing word '$w'"; kind='non-additive' })
+            }
+        }
+    }
+
+    # Size caps.
+    if ($lines -gt 500) {
+        $findings.Add([pscustomobject]@{ code='SC4.skill-too-long'; severity='warning'; message="SKILL.md is $lines lines (cap 500)"; kind='non-additive' })
+    }
+    if ($tokens -gt 5000) {
+        $findings.Add([pscustomobject]@{ code='SC4.skill-too-many-tokens'; severity='warning'; message="SKILL.md is ~$tokens tokens (cap 5000)"; kind='non-additive' })
+    }
+
+    # Section presence per type.
+    $hasGotchas    = $text -match '(?m)^##\s+Gotchas\b'
+    $hasValidation = $text -match '(?m)^##\s+Validation loop\b'
+    $hasChecklist  = ($text -match '(?m)^##\s+Step checklist\b') -or ($text -match '(?m)^\s*-\s+\[ \]')
+
+    if ($type -eq 'pull' -and -not $hasGotchas) {
+        $findings.Add([pscustomobject]@{ code='SC5.missing-gotchas'; severity='warning'; message="pull-* skill missing '## Gotchas' section"; kind='additive'; fix='append-gotchas' })
+    }
+    if ($type -eq 'writer' -and -not $hasValidation) {
+        $findings.Add([pscustomobject]@{ code='SC5.missing-validation-loop'; severity='warning'; message="writer skill missing '## Validation loop' section"; kind='additive'; fix='append-validation' })
+    }
+    if ($type -eq 'orchestrator' -and -not $hasChecklist) {
+        $findings.Add([pscustomobject]@{ code='SC5.missing-checklist'; severity='warning'; message="orchestrator missing '## Step checklist' (or '- [ ]' items)"; kind='additive'; fix='append-checklist' })
+    }
+    if ($type -eq 'other' -and -not ($hasGotchas -or $hasValidation -or $hasChecklist)) {
+        $findings.Add([pscustomobject]@{ code='SC5.missing-procedure-section'; severity='warning'; message="skill needs at least one of '## Gotchas' / '## Validation loop' / '## Step checklist'"; kind='additive'; fix='append-validation' })
+    }
+
+    # Evals presence.
+    $evalsFile = Join-Path $Dir.FullName 'evals/evals.json'
+    if (-not (Test-Path $evalsFile)) {
+        $findings.Add([pscustomobject]@{ code='SC6.no-evals'; severity='warning'; message="evals/evals.json missing"; kind='additive'; fix='create-evals' })
+    } else {
+        try {
+            $obj = Get-Content -Raw $evalsFile | ConvertFrom-Json
+            if (-not $obj.cases -or $obj.cases.Count -lt 2) {
+                $findings.Add([pscustomobject]@{ code='SC6.evals-fewer-than-2'; severity='warning'; message="evals.json has fewer than 2 cases"; kind='non-additive' })
+            }
+            if ($obj.skill -ne $Dir.Name) {
+                $findings.Add([pscustomobject]@{ code='SC6.evals-skill-mismatch'; severity='warning'; message="evals.json declares skill='$($obj.skill)' (expected '$($Dir.Name)')"; kind='non-additive' })
+            }
+        } catch {
+            $findings.Add([pscustomobject]@{ code='SC6.evals-invalid-json'; severity='error'; message="evals.json is not valid JSON: $($_.Exception.Message)"; kind='non-additive' })
+        }
+    }
+
+    # References load-on-trigger.
+    $refsDir = Join-Path $Dir.FullName 'references'
+    if (Test-Path $refsDir) {
+        if ($text -notmatch 'references/[A-Za-z0-9_\-]+\.md') {
+            $findings.Add([pscustomobject]@{ code='SC7.references-no-trigger'; severity='warning'; message="references/ folder present but SKILL.md never cites 'references/<file>.md'"; kind='non-additive' })
+        }
+    }
+
+    return $findings
+}
+
+function Get-AppendBlock {
+    param([string]$Fix)
+    switch ($Fix) {
+        'append-gotchas' {
+            return @"
+
+
+## Gotchas
+
+<!-- TODO(retrofit): fill in — top-5 failure modes for this skill. Each bullet starts with the concrete failure mode, then the correction. Auto-added by skill-checker --retrofit --apply per skill-authoring.instructions.md. -->
+
+- **<failure mode 1>** — <correction>
+- **<failure mode 2>** — <correction>
+- **<failure mode 3>** — <correction>
+- **<failure mode 4>** — <correction>
+- **<failure mode 5>** — <correction>
+"@
+        }
+        'append-validation' {
+            return @"
+
+
+## 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 `run-log.yml` with success status.
+"@
+        }
+        'append-checklist' {
+            return @"
+
+
+## Step checklist
+
+<!-- TODO(retrofit): fill in — convert the procedure into GitHub checkbox syntax. Auto-added by skill-checker --retrofit --apply per skill-authoring.instructions.md. -->
+
+- [ ] Step 1 — <first concrete action>
+- [ ] Step 2 — <second concrete action>
+- [ ] Step 3 — <third concrete action>
+- [ ] Final  — Run self-check + evals; only commit on green.
+"@
+        }
+    }
+    return ''
+}
+
+function Get-StarterEvals {
+    param([string]$Name)
+    $slug = ($Name -replace '[^a-z0-9-]', '-')
+    return @"
+{
+  "skill": "$Name",
+  "version": "0.1.0",
+  "description": "Starter evals auto-added by skill-checker --retrofit --apply. Replace as soon as the skill has real behavior to assert.",
+  "cases": [
+    {
+      "id": "$slug-skillmd-exists",
+      "name": "SKILL.md exists for $Name",
+      "input": "verify $Name skill artifacts",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        { "type": "file-exists", "path": "plugin/skills/$Name/SKILL.md" }
+      ]
+    },
+    {
+      "id": "$slug-description-shape",
+      "name": "SKILL.md description leads with USE WHEN",
+      "input": "verify $Name description shape",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        { "type": "file-contains", "path": "plugin/skills/$Name/SKILL.md", "value": "USE WHEN" }
+      ]
+    }
+  ]
+}
+"@
+}
+
+function Apply-Fixes {
+    param([System.IO.DirectoryInfo]$Dir, $Findings)
+    $applied = New-Object System.Collections.Generic.List[string]
+    $skillMd = Join-Path $Dir.FullName 'SKILL.md'
+    foreach ($f in $Findings) {
+        if ($f.kind -ne 'additive') { continue }
+        switch ($f.fix) {
+            'create-evals' {
+                $evalsDir = Join-Path $Dir.FullName 'evals'
+                $evalsFile = Join-Path $evalsDir 'evals.json'
+                if (-not (Test-Path $evalsFile)) {
+                    if (-not $DryRun) {
+                        New-Item -ItemType Directory -Force -Path $evalsDir | Out-Null
+                        Set-Content -LiteralPath $evalsFile -Value (Get-StarterEvals -Name $Dir.Name) -Encoding UTF8
+                    }
+                    [void]$applied.Add("create $evalsFile")
+                }
+            }
+            { $_ -in 'append-gotchas','append-validation','append-checklist' } {
+                $block = Get-AppendBlock -Fix $f.fix
+                if (-not $DryRun) {
+                    Add-Content -LiteralPath $skillMd -Value $block -Encoding UTF8
+                }
+                [void]$applied.Add("append $($f.fix) to $skillMd")
+            }
+        }
+    }
+    return $applied
+}
+
+# ---- main ------------------------------------------------------------------
+
+# Review mode delegates to skill-creator.
+if ($Review) {
+    if (-not $Skill) { throw "-Review requires -Skill <name>." }
+    $reviewer = Join-Path $Root 'plugin/skills/skill-creator/generate-eval-review.ps1'
+    & pwsh -NoProfile -File $reviewer -Skill $Skill -Root $Root
+    exit $LASTEXITCODE
+}
+
+# OptimizeDescription mode delegates to skill-creator.
+if ($OptimizeDescription) {
+    if (-not $Skill) { throw "-OptimizeDescription requires -Skill <name>." }
+    $skillMd = Join-Path $Root "plugin/skills/$Skill/SKILL.md"
+    if (-not (Test-Path $skillMd)) { throw "No SKILL.md for '$Skill' at $skillMd" }
+    $fm = Get-Frontmatter $skillMd
+    $current = $fm['description']
+    if (-not $current) { throw "No description: in $skillMd frontmatter." }
+    $optimizer = Join-Path $Root 'plugin/skills/skill-creator/optimize-description.ps1'
+    & pwsh -NoProfile -File $optimizer -Description $current
+    exit $LASTEXITCODE
+}
+
+# Apply requires Retrofit.
+if ($Apply -and -not $Retrofit) {
+    throw "-Apply requires -Retrofit."
+}
+
+$targets = Get-TargetSkills -Root $Root -Skill $Skill -All:$All
+$report = [ordered]@{
+    mode      = if ($Apply) { 'apply' } elseif ($Retrofit) { 'retrofit' } else { 'lint' }
+    root      = $Root
+    timestamp = (Get-Date -Format o)
+    skills    = @()
+}
+
+$totalFindings = 0
+$totalApplied  = 0
+$totalSkillsClean = 0
+$skillsNeedManual = New-Object System.Collections.Generic.List[string]
+
+foreach ($d in $targets) {
+    $findings = Lint-Skill -Dir $d
+    $applied  = @()
+    if ($Apply -and ($findings | Where-Object { $_.kind -eq 'additive' })) {
+        $applied = Apply-Fixes -Dir $d -Findings $findings
+        # Re-lint after apply.
+        $findings = Lint-Skill -Dir $d
+    }
+    $nonAdditive = @($findings | Where-Object { $_.kind -eq 'non-additive' })
+    if ($findings.Count -eq 0) { $totalSkillsClean++ }
+    if ($nonAdditive.Count -gt 0) { [void]$skillsNeedManual.Add($d.Name) }
+    $totalFindings += $findings.Count
+    $totalApplied  += $applied.Count
+    $report.skills += [ordered]@{
+        name        = $d.Name
+        type        = Get-SkillType -Name $d.Name
+        findings    = @($findings)
+        applied     = @($applied)
+        non_additive_count = $nonAdditive.Count
+    }
+
+    # Write per-skill fix plan during retrofit.
+    if ($Retrofit) {
+        $planDir  = Join-Path $Root "Evidence/_skill-checker/$($d.Name)"
+        $planFile = Join-Path $planDir 'fix-plan.json'
+        if (-not $DryRun) {
+            New-Item -ItemType Directory -Force -Path $planDir | Out-Null
+            ($findings | ConvertTo-Json -Depth 6) | Set-Content -LiteralPath $planFile -Encoding UTF8
+        }
+    }
+}
+
+$report.summary = [ordered]@{
+    total_skills      = $targets.Count
+    total_findings    = $totalFindings
+    skills_clean      = $totalSkillsClean
+    skills_with_manual_work = $skillsNeedManual.Count
+    skills_needing_manual   = @($skillsNeedManual)
+    applied           = $totalApplied
+}
+
+if ($Output) {
+    $report | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $Output -Encoding UTF8
+}
+
+if ($Json) {
+    $report | ConvertTo-Json -Depth 8
+} else {
+    Write-Host ""
+    Write-Host "### skill-checker ($($report.mode)) — $($targets.Count) skill(s) scanned"
+    Write-Host ""
+    foreach ($s in $report.skills) {
+        $tag = if ($s.findings.Count -eq 0) { 'OK ' } else { '!! ' }
+        Write-Host "$tag $($s.name) [type=$($s.type)] — findings=$($s.findings.Count) applied=$($s.applied.Count)"
+        foreach ($f in $s.findings) {
+            Write-Host "      [$($f.code)] $($f.message)  ($($f.kind))"
+        }
+        foreach ($a in $s.applied) {
+            Write-Host "      + $a"
+        }
+    }
+    Write-Host ""
+    Write-Host "summary: $($report.summary.skills_clean)/$($report.summary.total_skills) clean; $($report.summary.applied) fix(es) applied; $($report.summary.skills_with_manual_work) skill(s) need manual review."
+}
+
+if ($StrictExit -and $totalFindings -gt 0) { exit 1 }
+exit 0

package/plugin/skills/skill-checker/evals/evals.json

@@ -0,0 +1,41 @@
+{
+  "skill": "skill-checker",
+  "version": "1.0.0",
+  "description": "Meta — skill-checker runner ships and is parseable; SKILL.md description leads with USE WHEN.",
+  "cases": [
+    {
+      "id": "check-skill-exists",
+      "name": "check-skill.ps1 ships in the skill folder",
+      "input": "verify skill-checker artifacts",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        { "type": "file-exists", "path": "plugin/skills/skill-checker/check-skill.ps1" },
+        { "type": "file-exists", "path": "plugin/skills/skill-checker/SKILL.md" }
+      ]
+    },
+    {
+      "id": "description-leads-use-when",
+      "name": "skill-checker description leads with USE WHEN",
+      "input": "verify SKILL.md description shape",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        { "type": "file-contains", "path": "plugin/skills/skill-checker/SKILL.md", "value": "USE WHEN" }
+      ]
+    },
+    {
+      "id": "modes-documented",
+      "name": "all four operating modes are documented",
+      "input": "verify SKILL.md mode coverage",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        { "type": "file-contains", "path": "plugin/skills/skill-checker/SKILL.md", "value": "-Retrofit" },
+        { "type": "file-contains", "path": "plugin/skills/skill-checker/SKILL.md", "value": "-Apply" },
+        { "type": "file-contains", "path": "plugin/skills/skill-checker/SKILL.md", "value": "-OptimizeDescription" },
+        { "type": "file-contains", "path": "plugin/skills/skill-checker/SKILL.md", "value": "-Review" }
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,134 @@
+---
+name: "skill-creator"
+version: "1.0.0"
+description: "USE WHEN the user says \"create skill\", \"new skill\", \"scaffold a skill\", \"npx kushi-agents create-skill ...\", or wants to author a new kushi skill that conforms to the agentskills.io blueprint. DO NOT USE for editing existing skills (use skill-checker --retrofit). Capability: scaffolds plugin/skills/<name>/ with SKILL.md, evals/evals.json, optional references/, and a .created-by-skill-creator marker; provides description-optimization and an HTML eval-review viewer. Inspired by Anthropic's skill-creator."
+---
+
+# Skill: skill-creator
+
+The meta-skill that authors NEW kushi skills. Adapted from Anthropic's [skill-creator](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md) to kushi's PowerShell-first stack + 2-host install matrix.
+
+User triggers: "create skill", "new skill", "scaffold a skill", "kushi create-skill", "make me a pull-something skill".
+
+Doctrine: [`plugin/instructions/skill-authoring.instructions.md`](../../instructions/skill-authoring.instructions.md).
+
+## USE WHEN
+
+- The user wants to add a new skill to `plugin/skills/`.
+- A new evidence source / orchestrator / utility needs a skill home and you want it conformant on day one.
+- Bootstrapping the SKILL.md + evals/evals.json + optional references/ tree from a single prompt.
+
+## DO NOT USE FOR
+
+- Editing an existing skill (use `skill-checker --retrofit`).
+- Authoring `*.instructions.md` doctrine (write those by hand; they have their own front-matter rules).
+- Producing release docs (CHANGELOG, genealogy) — those are human-curated.
+
+## Gotchas
+
+- **Type selection matters.** `pull` → forces `## Gotchas`; `writer` → forces `## Validation loop`; `orchestrator` → forces `## Step checklist`; `other` → at least one of the three. Picking the wrong type ships a non-conformant skill that `check-skill --lint` will immediately flag.
+- **Description must lead with `USE WHEN`** in the first 160 chars or `D30.description-optimized` fails. The scaffold inserts this for you; if you replace it, run `optimize-description.ps1` afterward.
+- **Marker file is the strict-gate opt-in.** `.created-by-skill-creator` is written by `scaffold.ps1`. `D34.creator-output-conforms` requires every marked skill to be lint-clean. Don't add the marker to half-built skills.
+- **Templates are starter content, not boilerplate to ignore.** Every `TODO(skill-creator)` must be replaced before the first PR.
+- **`Evidence/_skill-creator/` is gitignored** — eval-review HTML stays local.
+
+## Step checklist
+
+- [ ] **Pick a name** (kebab-case, verb-led: `pull-foo`, `apply-foo`, `consolidate-foo`).
+- [ ] **Pick a type** (`pull` | `writer` | `orchestrator` | `other`).
+- [ ] **Run scaffold**:
+
+  ```powershell
+  pwsh plugin/skills/skill-creator/scaffold.ps1 `
+       -Name my-new-skill `
+       -Type other `
+       -Description "USE WHEN ... DO NOT USE FOR ..."
+  ```
+
+- [ ] **Optimize the description** if you handcrafted it:
+
+  ```powershell
+  pwsh plugin/skills/skill-creator/optimize-description.ps1 `
+       -Description "<your draft>"
+  ```
+
+- [ ] **Fill placeholders** (grep `TODO(skill-creator)`).
+- [ ] **Lint**: `npx kushi-agents check-skill my-new-skill`
+- [ ] **Run evals**: `npm run eval -- my-new-skill`
+- [ ] **Self-check targeted**: `pwsh plugin/skills/self-check/run.ps1 -Deep -Targeted my-new-skill`
+- [ ] **Commit**.
+
+## Validation loop
+
+After scaffolding (or running any sub-command):
+
+1. Run `check-skill --lint <name>` — must be clean.
+2. Run `npm run eval -- <name>` — must pass (the starter evals exercise file-exists + regex-match).
+3. Run `pwsh plugin/skills/self-check/run.ps1 -Targeted <name>` — only known-allowed findings.
+4. If any of the above fails, fix in-place and re-run from step 1.
+5. Only then add `.created-by-skill-creator` (the scaffold does this for you).
+
+## What `scaffold.ps1` does
+
+1. Validates `-Name` is kebab-case and doesn't already exist (unless `-Force`).
+2. Creates `plugin/skills/<name>/`.
+3. Renders `templates/skill-skeleton.template.md` → `SKILL.md`, picking the right type-specific section.
+4. Renders `templates/evals-starter.template.json` → `evals/evals.json` with 2 starter cases.
+5. If `pull` or `writer`, renders `templates/gotchas-stub.template.md` → into `SKILL.md`.
+6. Writes the `.created-by-skill-creator` marker.
+7. Prints next-step guidance.
+
+`-Force` overwrites an existing skill folder (use carefully). `-DryRun` prints actions without writing.
+
+## What `optimize-description.ps1` does
+
+Applies the agentskills.io description-optimization rules:
+
+- Lead with `USE WHEN`.
+- Append `DO NOT USE FOR` if missing.
+- Strip marketing words (`powerful`, `comprehensive`, `blazing`, `seamless`, `simple`).
+- Hard-cap 1024 chars.
+- Returns the rewritten string on stdout. Idempotent.
+
+Can be invoked standalone (just to test a draft) or via `skill-checker --optimize-description <name>` (compares against the current SKILL.md description).
+
+## What `generate-eval-review.ps1` does
+
+Takes an eval workspace (`Evidence/_evals/<skill>/iterations/`) and renders a static HTML side-by-side viewer at `Evidence/_skill-creator/<skill>/review.html`. Helps a maintainer compare two eval runs (e.g. before/after a prompt change) without spinning up infra. Output is gitignored.
+
+## Arguments
+
+### `scaffold.ps1`
+
+| Flag | Purpose |
+|---|---|
+| `-Name <kebab>` | REQUIRED — skill directory + front-matter `name`. |
+| `-Type <pull\|writer\|orchestrator\|other>` | REQUIRED — picks template sections. |
+| `-Description <string>` | REQUIRED — front-matter `description` (will be auto-optimized). |
+| `-Force` | Overwrite existing folder. |
+| `-DryRun` | Print actions only. |
+| `-Root <path>` | Override repo root (default: 3 levels above the script). |
+
+### `optimize-description.ps1`
+
+| Flag | Purpose |
+|---|---|
+| `-Description <string>` | REQUIRED — string to rewrite. |
+| `-Quiet` | Suppress diff output; print only the rewritten string. |
+
+### `generate-eval-review.ps1`
+
+| Flag | Purpose |
+|---|---|
+| `-Skill <name>` | REQUIRED — skill whose eval iterations to review. |
+| `-Output <path>` | Override output path. Default `Evidence/_skill-creator/<skill>/review.html`. |
+| `-Root <path>` | Override repo root. |
+
+## References
+
+- `plugin/instructions/skill-authoring.instructions.md` — the doctrine this skill enforces.
+- `plugin/instructions/agentskills-compliance.instructions.md` — section/size rules.
+- `plugin/instructions/skill-evals.instructions.md` — evals schema.
+- `plugin/skills/skill-checker/SKILL.md` — the linter that validates scaffold output.
+- `plugin/skills/skill-creator/templates/` — load templates from here when filling.
+- <https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md>

package/plugin/skills/skill-creator/evals/evals.json

@@ -0,0 +1,40 @@
+{
+  "skill": "skill-creator",
+  "version": "1.0.0",
+  "description": "Meta — skill-creator scripts ship, are parseable, and templates are present.",
+  "cases": [
+    {
+      "id": "scaffold-exists",
+      "name": "scaffold.ps1 ships in the skill folder",
+      "input": "verify skill-creator artifacts",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        { "type": "file-exists", "path": "plugin/skills/skill-creator/scaffold.ps1" },
+        { "type": "file-exists", "path": "plugin/skills/skill-creator/SKILL.md" }
+      ]
+    },
+    {
+      "id": "templates-exist",
+      "name": "all three templates ship",
+      "input": "verify templates folder",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        { "type": "file-exists", "path": "plugin/skills/skill-creator/templates/skill-skeleton.template.md" },
+        { "type": "file-exists", "path": "plugin/skills/skill-creator/templates/evals-starter.template.json" },
+        { "type": "file-exists", "path": "plugin/skills/skill-creator/templates/gotchas-stub.template.md" }
+      ]
+    },
+    {
+      "id": "description-leads-use-when",
+      "name": "skill-creator description leads with USE WHEN",
+      "input": "verify SKILL.md description shape",
+      "canary": false,
+      "grader_type": "script",
+      "expected_assertions": [
+        { "type": "file-contains", "path": "plugin/skills/skill-creator/SKILL.md", "value": "USE WHEN" }
+      ]
+    }
+  ]
+}