@zalom/plastic 1.0.0-alpha.9 → 1.0.0-beta.2

package/skills/dashboard/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: plastic-dashboard
+description: Use when the user wants an overview of intents, asks "where are we", "what's next", "what should I work on", "show the dashboard", or invokes /plastic-dashboard. Renders a deterministic Value×Effort work cockpit as Markdown across the global store and all projects, and emits a machine-readable queue that auto mode consumes.
+---
+
+# Dashboard — Plastic Work Cockpit
+
+A deterministic overview of the intent store(s). It answers three questions at a glance:
+**where we are** (recently worked), **where we go next** (a Value×Effort matrix), and
+**how to conduct it** (a disposition per intent). The human-facing surface is **Markdown**,
+because the user's UI renders Markdown natively but collapses raw tool-call stdout.
+
+The script does all the data work. The agent fills a Markdown template from the script's
+payload with near-zero reasoning and **presents the filled board in its reply**. Same store
+state → byte-identical payload, regardless of model. Do NOT hand-summarize intents.
+
+## When to Use
+
+- User invokes `/plastic-dashboard`
+- User asks "where are we", "what's next", "what should I work on", "show me the intents"
+- `plastic-continuing` lands on the board on resume
+- `plastic-auto` reads `--json` to choose the next dispatchable intent
+
+## Procedure (the Markdown board — default human surface)
+
+### Step 1 — Get the data payload
+
+```bash
+ruby ~/.plastic/scripts/dashboard.rb [continue|project <slug>] --data
+```
+
+- `continue` (default) → the **global** board payload (`mode: "global"`).
+- `project <slug>` → that **project** board payload (`mode: "project"`).
+
+The payload is read-only JSON. Global-board fields: `date`, `store_health`, `recently_worked`,
+`matrix` (`quick_win`/`next_big`/`defer`/`triage`/`research`, each a list of `{line, bullet, ...}`),
+`counts`, `projects`, `project_totals`. Project-board fields: `slug`, `store_health`,
+`description`, `recently_worked`, `matrix`, `counts`, `active`, `future`.
+
+Each board load runs the scoped store check (`doctor --store <scope>`): the global board runs
+`--store global` and a project board runs `--store <slug>`. The result rides in the payload as
+`store_health` (`{scope, status, summary, failing_checks}`). Surface it as a one-line
+store-health note on the board (for example `store health: pass (3/3)` or
+`store health: warn (orphaned_intents)`). It is non-fatal: a warn or fail is shown as data and
+never blocks the board.
+
+### Step 2 — Fill the matching template
+
+Templates live in this skill's `templates/` directory:
+`~/.claude/skills/plastic-dashboard/templates/dashboard-global.md` and
+`dashboard-project.md`.
+
+Fill mechanically — no rewriting, no re-sorting:
+- `{{a.b.count}}` → the integer (e.g. `matrix.quick_win.count` = that list's length).
+- `{{...lines}}` → join the list's `.line` strings with **real newlines** (one per line).
+  These lines are already glyph-led (the glyph is the bullet — never add `-`, never emit
+  `<br>`). If a matrix quadrant list is empty, render `_(none)_`.
+- `projects.lines` → one line per project:
+  `- **{slug}** — {description} · active {active} · done {done} · future {future} · last accessed {last_accessed_at[0,10]}`.
+- Scalars (`{{date}}`, `{{slug}}`, `{{description}}`) → substitute verbatim.
+
+### Step 3 — Present it (mandatory, every invocation)
+
+**Paste the filled Markdown into your reply.** This is non-optional: the board only reaches
+the user when it is in the chat reply, not in tool-call stdout. Never describe the board
+instead of showing it.
+
+### Step 4 — Entry flow (the board is the menu)
+
+The board lists everything; the user navigates by free prose (no capped picker):
+- On the **global** board, the user replies with an **intent id** (work it), a **project
+  name** (re-run `project <slug> --data` and present that board), or **"new"** (start a new
+  intent in global via `plastic-creating-intent`).
+- On a **project** board, the user replies with an **intent id**, or **"global"** to return.
+
+## Auto-mode contract (`--json`)
+
+`plastic-auto` consumes a separate machine-readable manifest (unchanged):
+
+```bash
+ruby ~/.plastic/scripts/dashboard.rb [continue|project <slug>|all] --json
+```
+
+```json
+{ "generated_for": "auto-mode", "scope": "<scope|all>",
+  "next_big_thing": "<id|null>",
+  "dispatchable_queue": [ {"id","scope","disposition","type","value","effort","flags","rank"} ],
+  "human_only": ["<id>", "..."] }
+```
+
+Work `dispatchable_queue` in `rank` order (`defer`/`research`); leave `human_only` for the user.
+
+## Text modes (terminal / legacy)
+
+`dashboard.rb [continue|project <slug>|all]` with no flag still prints the ASCII cockpit for
+a raw terminal. The Markdown board (`--data` + template) is the surface for the chat UI.
+
+## How classification works (deterministic)
+
+- **Effort** — small for `research`/`exploration`/`bugfix`, for already-scoped intents
+  (plan/checklist exists), or deep refinement branches; big otherwise.
+- **Value → high** when any of: explicit `value: high`; a human-authored **root** intent; an
+  intent with a non-empty `chain`; or an intent that is a `source` of ≥1 other intent. Else low.
+- **Flags** — `unblocked` only when a **future** intent has **all** its `sources` done;
+  `stale` only on future intents past the staleness threshold. Both kept low-noise by design.
+- **Override** — a `value: high|low` frontmatter field always wins (pre-stamped data, never
+  model judgment at render time).
+
+## Eval
+
+The eval is the payload + golden snapshots: run the engine against the fixture store and
+assert the `--data` payload shape/sorting/classification and the byte-identical `--json` +
+text goldens in `test/fixtures/dashboard/`. See `test/dashboard_test.rb`. Drift without an
+intentional change means the skill is broken.
+
+## Notes
+
+- Quadrant lists are **not** Markdown `-` bullets — the glyph is the bullet (the boards are
+  UI-only and may evolve, so they need not be valid Markdown lists). Never emit `<br>`.
+- Clusters (Zettelkasten grouping in INDEX.md) are intentionally not rendered.
+- Additive: changes no core lifecycle, gate, or cycle logic.

package/skills/dashboard/templates/dashboard-global.md

@@ -0,0 +1,31 @@
+# 🧩 Plastic · Global Board — {{date}}
+
+**Recently worked** · last 24h
+{{recently_worked.lines}}
+
+## Where we go next · Value × Effort  *(global intents only)*
+
+|  | Small effort | Big effort |
+|---|---|---|
+| **High value** | ⚡ **Quick win** · {{matrix.quick_win.count}} | ★ **Next big thing** · {{matrix.next_big.count}} |
+| **Low value** | → **Defer (agent)** · {{matrix.defer.count}} | ⚑ **Triage** · {{matrix.triage.count}} |
+
+**⚡ Quick win** — small effort, high value
+{{matrix.quick_win.lines}}
+
+**★ Next big thing** — big effort, high value
+{{matrix.next_big.lines}}
+
+**→ Defer (agent)** — small effort, low value
+{{matrix.defer.lines}}
+
+**⚑ Triage** — big effort, low value
+{{matrix.triage.lines}}
+
+🔬 **Research → agent**
+{{matrix.research.lines}}
+
+## Projects · active {{project_totals.active}} · done {{project_totals.done}} · future {{project_totals.future}}
+{{projects.lines}}
+
+**What would you like to work on next?** (type an **intent id**, a **project name**, or anything **new** you'd like to start)

package/skills/dashboard/templates/dashboard-project.md

@@ -0,0 +1,40 @@
+# 📦 {{slug}} · Project Board — {{date}}
+
+{{description}}
+
+**Recently worked** · last 24h
+{{recently_worked.lines}}
+
+## Where we go next · Value × Effort
+
+|  | Small effort | Big effort |
+|---|---|---|
+| **High value** | ⚡ **Quick win** · {{matrix.quick_win.count}} | ★ **Next big thing** · {{matrix.next_big.count}} |
+| **Low value** | → **Defer (agent)** · {{matrix.defer.count}} | ⚑ **Triage** · {{matrix.triage.count}} |
+
+**⚡ Quick win** — small effort, high value
+{{matrix.quick_win.lines}}
+
+**★ Next big thing** — big effort, high value
+{{matrix.next_big.lines}}
+
+**→ Defer (agent)** — small effort, low value
+{{matrix.defer.lines}}
+
+**⚑ Triage** — big effort, low value
+{{matrix.triage.lines}}
+
+🔬 **Research → agent**
+{{matrix.research.lines}}
+
+## Intents · active {{counts.active}} · done {{counts.done}} · future {{counts.future}}
+
+**Active**
+{{active.lines}}
+
+**Future**
+{{future.lines}}
+
+**Legend** · ○ What ◔ Why ◑ How ◕ Exec ● Done · ⚡ quick win ★ big → defer ⚑ triage 🔬 research
+
+**What would you like to work on next?** (type an **intent id**, or **global** to go back)

package/skills/doctor/SKILL.md

@@ -1,14 +1,55 @@
 ---
-name: doctor
+name: plastic-doctor
 description: Use when diagnosing Plastic installation health, after updates, or when something seems broken. Runs checks and reports findings with fix options.
 ---
 
 # Doctor — Plastic Health Check
 
+## Scopes
+
+Doctor has three scopes. Pick the right one for the situation:
+
+| Scope | Flag | When it runs | States |
+|-------|------|--------------|--------|
+| Core check | `--core` | SessionStart hook (automatic), also available on demand | Binary: pass or error |
+| Store check | `--store [global\|<slug>]` | Dashboard load, `plastic-continuing` | Three-state: pass / warn / fail |
+| Full check | (no flag) | After every update (automatic), or `/plastic-doctor` | Three-state: pass / warn / fail |
+
+### `--core` (binary, manifest-backed)
+
+Verifies that every core file is present and content-matches what the installed
+version shipped. It checks two install manifests:
+
+- `~/.plastic/manifest.json` (global manifest, covers PLASTIC.md and global scripts)
+- `~/.claude/plastic/manifest.json` (agent-side manifest, covers agent scripts and hooks)
+
+Each manifest maps a file path to its SHA256. The core check also confirms hooks
+are registered, scripts are present and executable, and the installed version
+matches. Result is binary: exit 0 on pass, non-zero on error. It never produces
+warnings.
+
+### `--store [global|<slug>]`
+
+Checks store state: intents are well-formed, INDEX sections are present, conventions
+are followed, and links are valid. Scope options:
+
+- No argument: checks all stores (global and all projects)
+- `global`: checks only the global store
+- A project slug (e.g. `--store plastic`): checks only that project's store
+
+Produces three-state results (pass / warn / fail) and is run per-scope at dashboard
+load time: the global board uses `--store global`, a project board uses `--store <slug>`.
+
+### Full doctor (no flag)
+
+Runs core plus all store checks plus deprecation checks. This is what `/plastic-doctor`
+invokes. It also runs automatically after every `plastic-update` (informational,
+does not block or revert the update).
+
 ## When to Use
 
-- User invokes `/plastic:doctor`
-- After `plastic:update` completes (automatically)
+- User invokes `/plastic-doctor` (full check)
+- After `plastic-update` completes (automatically, full check)
 - When hooks aren't firing, skills aren't loading, or something seems broken
 - When the user says "check plastic", "diagnose", "what's wrong with plastic"
 
@@ -75,6 +116,8 @@ Use the `fix_hint` value to determine the correct action:
 | "Create INDEX.md with required sections" | Write INDEX.md with the 5 sections: Active, Future, Clusters, Abandoned, Completed |
 | "Add missing entries to INDEX.md" | Add orphaned intents to the appropriate INDEX.md section |
 | "Remove stale references from INDEX.md" | Edit INDEX.md to remove ghost references |
+| "Inject the missing required frontmatter field(s)" | Edit the intent's `{ID}--{slug}.md` frontmatter to add the missing key (e.g. `chain: []`) without touching other keys |
+| "Run: provision-project-store {slug}" | Run `provision-project-store <slug>` (or invoke the `plastic-add-project-store` skill) to create the missing store |
 | "Re-run installer" | Run `npx @zalom/plastic@latest --agent` |
 
 For fixes the agent cannot handle automatically, explain what the user needs
@@ -95,7 +138,7 @@ Show the updated results.
 
 ## Post-Update Mode
 
-When invoked from `plastic:update` (not directly by the user):
+When invoked from `plastic-update` (not directly by the user):
 
 1. Run the diagnostic script as in Step 1.
 2. If all checks pass: show a single line — **"Health check: all clear."**
@@ -110,3 +153,7 @@ This keeps the update flow clean when nothing is wrong.
 - The script outputs JSON to stdout. Any diagnostic errors go to stderr.
 - Non-zero exit codes mean "issues found", not "script crashed".
   Always parse stdout regardless of exit code.
+
+## References
+
+- Read `references/gates-stuck-detection.md` for the full gate enforcement table, bridge file pattern, and stuck detection thresholds when diagnosing gate failures or stuck agents

package/skills/doctor/references/gates-stuck-detection.md

@@ -0,0 +1,38 @@
+# Gate Enforcement and Stuck Detection
+
+## Bridge File Pattern
+
+`/tmp/plastic-{session}.json` is the hot cache; the filesystem is the authority.
+SessionStart rebuilds the bridge file from the filesystem — the bridge is always disposable.
+
+## Gate Taxonomy
+
+| Gate type | Purpose |
+|---|---|
+| **Pre-flight** | Prerequisites exist? |
+| **Revision** | New info invalidated prior work? |
+| **Escalation** | Blocked items surface to user |
+| **Abort** | Inconsistent state detected |
+
+## Full Gate Enforcement
+
+| Gate | Blocked action | Required prerequisite |
+|---|---|---|
+| Pre-flight | Cannot write `plan.md` | `spec.md` must exist |
+| Pre-flight | Cannot create `actions/` | `spec.md` must exist |
+| Pre-flight | Cannot write `outcome.md` | `checklist.md` must exist with all items checked |
+| Revision | Cannot proceed to Exec | Context changed after spec.md — re-derive spec |
+| Abort | Cannot complete intent | `outcome.md` exists but checklist has unchecked items |
+
+Hard blocking — hooks exit with code 2 when gates fail.
+
+## Stuck Detection
+
+| Condition | Threshold | Action |
+|---|---|---|
+| Consecutive gate failures | 3+ | Warning |
+| Consecutive gate failures | 5+ | Force savepoint + escalate |
+| No activity | 5+ min | Warning |
+| No activity | 10+ min | Force savepoint + escalate |
+| Context pressure | 80% | Warning |
+| Context pressure | 90% | Force savepoint |

package/skills/doctor/report.md

@@ -7,6 +7,10 @@
   2. Replace every {{placeholder}} below with the corresponding JSON value.
   3. For the category sections: the template shows ONE example section.
      Repeat that pattern for each unique category in the checks array.
+     The scope determines which categories appear:
+       --core scope:      agent_registration, core_files (binary pass/error only)
+       --store scope:     global_store, conventions, project_stores
+       full (no flag):    all six categories below
      The six known categories and their display names are:
        global_store       -> "Global Store"
        conventions        -> "Conventions"

package/skills/evaluating-skills/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: plastic-evaluating-skills
+description: >
+  Evaluate Plastic skills for correctness, convention compliance, and
+  progressive disclosure. Use when testing whether a skill produces good
+  outputs, verifying convention compliance after changes, running evals
+  against skills or instructions, creating evals for a new or updated
+  skill, checking if a description triggers correctly, or assessing
+  whether a skill is still needed. Also use when the user says "evaluate",
+  "test the skill", "run evals", "check conventions", or "write evals".
+---
+
+# Evaluating Skills
+
+Eval methodology for Plastic skills, based on
+[agentskills.io](https://agentskills.io/skill-creation/evaluating-skills)
+and [Anthropic's eval guide](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents).
+
+## Gotchas
+
+- Assertions written before observing output are almost always wrong — run
+  the eval first, observe actual output, THEN write assertions
+- Near-miss negative test cases are the most valuable — prompts that share
+  keywords with should-trigger cases but need a different skill entirely
+- Select the best skill iteration by validation pass rate, not the last one
+- Grade outcomes, not execution paths — if the agent solved the task via an
+  unexpected route but produced correct output, that is a pass
+- Same skill can behave differently across agent frameworks — test on each
+  target agent (Claude Code, Hermes, OpenClaw, Codex)
+
+## Procedure
+
+### Step 1: Choose eval scope
+
+Determine what you are evaluating:
+
+- **Description triggering** — does the agent activate the right skill for
+  a given prompt? Tests the description field effectiveness.
+- **Output quality** — does the skill produce correct results when activated?
+  Tests the skill body and references.
+- **Convention compliance** — does the output follow Plastic conventions?
+  Read `references/convention-checks.md` for the full assertion library.
+
+Multiple scopes can apply to the same skill. Start with the scope that
+addresses your immediate concern, add others as needed.
+
+### Step 2: Design test cases
+
+Create `evals/evals.json` in the skill being evaluated. Copy the starter
+template from `assets/eval-template.json` in this skill.
+
+**For description triggering:**
+- Write ~20 queries: 8-10 should-trigger, 8-10 should-not-trigger
+- Split 60/40 into train and validation sets (proportional mix in each)
+- Include near-miss negatives that share keywords but need a different skill
+- In `expected_output`, describe whether the skill should or should not activate
+  and why
+
+**For output quality:**
+- Start with 2-3 test cases, expand after first results
+- Use realistic user prompts with varied phrasing, detail level, and formality
+- In `expected_output`, describe what correct output looks like — not exact text
+- Use `files` array for any input files the test needs
+
+**For convention compliance:**
+- Start with 2-3 test cases targeting specific convention areas
+- In `expected_output`, describe which conventions must be met
+- Read `references/convention-checks.md` for the full assertion library
+
+Leave `assertions` arrays empty. They are populated after Step 4.
+
+### Step 3: Run paired evals
+
+Dispatch a subagent per test case to ensure clean context — no leakage
+between test runs. Run each case twice:
+
+1. **With skill** — the skill is available and loaded
+2. **Without skill** — the skill is not available (baseline comparison)
+
+The delta between with-skill and without-skill measures what the skill adds.
+If the delta is negligible, the skill may not be adding value for that case.
+
+Grade outcomes, not paths. An unexpected tool-call sequence that produces
+correct output is still a pass.
+
+### Step 4: Write assertions after observing
+
+Review actual outputs from Step 3. Write specific, verifiable assertions
+based on what you observed — not what you expected beforehand.
+
+Choose the grader type that fits each assertion:
+- **Code-based** — structure, file existence, format validity, counts
+- **LLM-as-judge** — quality, completeness, tone, semantic correctness
+- **Human** — edge cases, calibration, judgment calls
+
+Read `references/eval-methodology.md` for the full grader taxonomy and
+LLM-judge calibration protocol.
+
+Good assertions are specific, verifiable, and countable:
+"Output includes at least 3 concrete recommendations."
+
+Weak assertions are vague: "Output is good."
+Brittle assertions use exact phrase matching.
+
+Require concrete evidence for PASS. No benefit of the doubt.
+
+### Step 5: Grade and iterate
+
+Compute pass rates per test case and aggregate across the eval suite.
+
+Track two metrics separately:
+- **pass@k** — succeeded at least once in k trials (capability)
+- **pass^k** — succeeded every time in k trials (reliability)
+
+Read `references/eval-methodology.md` for formulas and interpretation.
+
+Three signal sources for skill improvement:
+1. **Failed assertions** — specific gaps in the skill
+2. **Human feedback** — broader quality issues not captured by assertions
+3. **Execution transcripts** — reveals WHY things went wrong
+
+Feed all three plus the current SKILL.md to propose targeted changes.
+Iterate on the train set only. Check the validation set for generalization.
+5 iterations is usually enough. If not improving after 5, the test cases
+themselves may be the problem — revisit Step 2.
+
+### Step 6: Graduate and monitor
+
+Once a skill hits ~100% on capability evals (pass@k = 1.0 for 3+
+consecutive runs):
+
+1. **Graduate** capability evals into regression tests — run them on every
+   skill change to protect against backsliding
+2. **Monitor** the with/without delta over time — if it shrinks to zero
+   across 3+ runs, the model may have internalized the skill
+3. **Retire** cautiously — archive the skill, do not delete. Re-test after
+   model updates in case capabilities regress.
+
+Read `references/eval-methodology.md` for graduation criteria, retirement
+detection, and the three-layer eval taxonomy.

package/skills/evaluating-skills/assets/eval-template.json

@@ -0,0 +1,12 @@
+{
+  "skill_name": "",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "",
+      "expected_output": "",
+      "files": [],
+      "assertions": []
+    }
+  ]
+}

package/skills/evaluating-skills/evals/evals.json

@@ -0,0 +1,75 @@
+{
+  "skill_name": "evaluating-skills",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I want to evaluate whether my creating-intent skill follows Plastic conventions",
+      "expected_output": "The skill should activate and guide the user through convention compliance evaluation: choose eval scope, design test cases using convention-checks reference, run paired evals, write assertions after observing.",
+      "files": [],
+      "assertions": []
+    },
+    {
+      "id": 2,
+      "prompt": "Run evals on the brainstorming skill to see if the description triggers correctly",
+      "expected_output": "The skill should activate and guide through description triggering evaluation: design ~20 queries with should-trigger and near-miss negatives, 60/40 train/validation split, compute trigger rates.",
+      "files": [],
+      "assertions": []
+    },
+    {
+      "id": 3,
+      "prompt": "Create evals for a new skill I just wrote for database migrations",
+      "expected_output": "The skill should activate, help create evals/evals.json in the migration skill directory using the template, guide through choosing eval scope (likely output quality), and design initial test cases.",
+      "files": [],
+      "assertions": []
+    },
+    {
+      "id": 4,
+      "prompt": "Check if my SKILL.md is under the token budget and follows progressive disclosure",
+      "expected_output": "The skill should activate and guide through convention compliance evaluation focused on progressive disclosure checks: body under 500 lines/5000 tokens, references have conditional triggers, description under 1024 chars.",
+      "files": [],
+      "assertions": []
+    },
+    {
+      "id": 5,
+      "prompt": "My skill's description isn't triggering on the right prompts, how do I fix it?",
+      "expected_output": "The skill should activate and guide through description triggering evaluation: create should-trigger and should-not-trigger queries, run paired evals, measure trigger rate, iterate on description wording.",
+      "files": [],
+      "assertions": []
+    },
+    {
+      "id": 6,
+      "prompt": "Write unit tests for my Ruby model that validates email addresses",
+      "expected_output": "The skill should NOT trigger. This is a code testing task, not a skill evaluation task. Near-miss negative — shares 'test' keyword but needs a different skill.",
+      "files": [],
+      "assertions": []
+    },
+    {
+      "id": 7,
+      "prompt": "Fix the bug in my login controller where sessions aren't persisting",
+      "expected_output": "The skill should NOT trigger. This is a debugging task with no relation to skill evaluation.",
+      "files": [],
+      "assertions": []
+    },
+    {
+      "id": 8,
+      "prompt": "Review this pull request for code quality issues",
+      "expected_output": "The skill should NOT trigger. Code review is different from skill evaluation. Near-miss negative — shares 'review/evaluate' concept.",
+      "files": [],
+      "assertions": []
+    },
+    {
+      "id": 9,
+      "prompt": "I updated my skill and want to make sure it still works correctly",
+      "expected_output": "The skill should activate and guide through regression evaluation: run existing evals against the updated skill, compare pass rates with previous version, check for backsliding.",
+      "files": [],
+      "assertions": []
+    },
+    {
+      "id": 10,
+      "prompt": "How do I know if a skill is still needed or if the model has learned the behavior?",
+      "expected_output": "The skill should activate and guide through skill retirement detection: monitor with/without delta over time, if delta approaches zero the model has internalized the skill.",
+      "files": [],
+      "assertions": []
+    }
+  ]
+}

package/skills/evaluating-skills/references/convention-checks.md

@@ -0,0 +1,76 @@
+# Plastic Convention Checks
+
+Assertion library for convention compliance evals on Plastic skills.
+Load when running convention compliance evals on a Plastic skill.
+
+## Directory Structure
+
+| Check | Pass criteria |
+|-------|--------------|
+| SKILL.md exists | File present at skill root |
+| Name matches directory | `name` in frontmatter equals directory name |
+| Standard directories only | Only scripts/, references/, assets/, evals/ at root level (all optional) |
+| References one level deep | No nested directories inside references/ |
+| No orphan files | Every file in the skill dir is referenced from SKILL.md or another skill file |
+| evals/ has evals.json | If evals/ exists, it contains evals.json |
+
+## Frontmatter
+
+| Check | Pass criteria |
+|-------|--------------|
+| `name` present | Non-empty, 1-64 chars |
+| `name` format | Lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens |
+| `name` matches dir | Exact match with skill directory name |
+| `description` present | Non-empty, 1-1024 chars |
+| `description` phrasing | Starts with imperative verb or "Use when" pattern |
+| `description` triggers | Mentions at least one trigger context ("Use when...") |
+| `description` edge cases | Includes at least one indirect trigger (user doesn't name the domain) |
+| No unknown required fields | Only uses fields from agentskills.io spec: name, description, license, compatibility, metadata, allowed-tools |
+
+## Progressive Disclosure
+
+| Check | Pass criteria |
+|-------|--------------|
+| Body line count | SKILL.md body (excluding frontmatter) under 500 lines |
+| Body token count | SKILL.md body under 5000 tokens (estimate: lines * 10) |
+| Deep detail in references | Content exceeding activation budget lives in references/ |
+| Conditional reference triggers | Every reference file mentioned in SKILL.md has a "when" condition |
+| No generic references | No "see references/ for more" — each reference has specific load trigger |
+| Description token budget | Description stays under ~100 tokens for discovery stage |
+
+## Content Quality
+
+| Check | Pass criteria |
+|-------|--------------|
+| Gotchas are concrete | Each gotcha is a specific correction, not general advice |
+| Gotchas positioned early | Gotchas section appears before or near the top of procedures |
+| Defaults, not menus | Skill picks one approach; alternatives mentioned briefly if at all |
+| Procedures over declarations | Instructions teach HOW to approach, not WHAT to produce |
+| Reasoning over rigid directives | Uses "Do X because Y" pattern, not "ALWAYS/NEVER" without rationale |
+| No redundant knowledge | Every instruction passes "would the agent get this wrong without it?" |
+| No explaining basics | Does not explain HTTP, JSON, what a migration is, etc. |
+
+## Eval Quality (when evals/ exists)
+
+| Check | Pass criteria |
+|-------|--------------|
+| Standard format | evals.json follows agentskills.io eval structure |
+| Prompts are realistic | Each prompt reads like a real user message |
+| Varied phrasing | Prompts use different wording, detail levels, formality |
+| Near-miss negatives | At least 2 should-not-trigger cases that share keywords |
+| Expected output descriptive | expected_output describes success, not exact text |
+| Assertions (if populated) | Each assertion is specific, verifiable, and countable |
+
+## Intent Structure (when evaluating intent compliance)
+
+| Check | Pass criteria |
+|-------|--------------|
+| Intent file exists | `{ID}--{slug}.md` present in intent directory |
+| Frontmatter complete | id, intent, sources, chain, created, author, tags present |
+| ID format correct | Follows Luhmann alternating: digits and letters alternate |
+| Directory name matches | `{ID}--{slug}` format, 3-5 word slug |
+| Lifecycle artifacts | Present artifacts match the intent's lifecycle stage |
+| spec.md gate | plan.md only exists if spec.md exists |
+| plan.md gate | checklist.md only exists if plan.md exists |
+| outcome.md gate | outcome.md only exists if all checklist items checked |
+| Insights append-only | `## Insights` section only grows, never shrinks |