docs: tune skill eval cases and document how to write them

.claude/skills/board-ops/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: board-ops
-description: gh recipes for the Inspector project boards — add a card, move its Status, set or re-score its Priority, delete a card, and recover from a deleted single-select option. Covers board #28 (v2) and board #11 (v1), their node/field/option IDs, and the option-deletion hazard.
+description: "gh recipes for the Inspector project boards — add a card, move its Status, set or re-score its Priority, delete a card, and recover from a deleted single-select option. Covers board #28 (v2) and board #11 (v1), their node/field/option IDs, and the option-deletion hazard."
 disable-model-invocation: false
 ---
 

.claude/skills/board-ops/evals/evals.json

@@ -11,6 +11,14 @@
     "prompt": "The project board rejected my Status option ID. How do I get the current ones?",
     "expect": "board-ops"
   },
+  {
+    "prompt": "I'm about to edit the options on one of the board's single-select fields. Should I do anything first?",
+    "expect": "board-ops"
+  },
+  {
+    "prompt": "Several cards lost their Priority value after the field was edited. How do I put it back?",
+    "expect": "board-ops"
+  },
   {
     "prompt": "Explain the difference between TCP and UDP.",
     "expect": null

.claude/skills/issue-create/evals/evals.json

@@ -11,6 +11,14 @@
     "prompt": "Before I file this, how do I check nobody has reported it already?",
     "expect": "issue-create"
   },
+  {
+    "prompt": "I found a bug while working on something else. How do I get it tracked in this repo?",
+    "expect": "issue-create"
+  },
+  {
+    "prompt": "What do I need to do beyond `gh issue create` for a new issue to be properly tracked here?",
+    "expect": "issue-create"
+  },
   {
     "prompt": "What is the chemical symbol for potassium?",
     "expect": null

.claude/skills/issue-triage/evals/evals.json

@@ -4,13 +4,21 @@
     "expect": "issue-triage"
   },
   {
-    "prompt": "What Priority should issue 2189 be given?",
+    "prompt": "How do I decide what Priority an incoming issue deserves?",
     "expect": "issue-triage"
   },
   {
     "prompt": "Audit the project board for anything that has drifted.",
     "expect": "issue-triage"
   },
+  {
+    "prompt": "How do I find the issues that aren't on either board yet?",
+    "expect": "issue-triage"
+  },
+  {
+    "prompt": "After scoring an issue against the rubric, what do I do with the score?",
+    "expect": "issue-triage"
+  },
   {
     "prompt": "Who wrote the novel Moby-Dick?",
     "expect": null

.claude/skills/local-dev/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: local-dev
-description: Getting the Inspector running locally, and the reasoning behind its dependency rules. Which install to run and which script starts each client (web, cli, tui, launcher); why v2 is not an npm workspace; how the @inspector/core alias works; and why the placement rules in AGENTS.md are what they are — what each one is defending against, what it looked like when it was violated, and how to tell you have hit one.
+description: Install, build and run the Inspector locally, and place a dependency correctly. Use when starting the web, cli, tui or launcher client; when asking whether a build or rebuild is needed before a run script works; when an install, an @inspector/core import or a client bundle fails at run time; when adding or bumping a dependency and choosing which package.json declares it; or when a bundler external, a version skew or a git worktree is the suspect.
 disable-model-invocation: false
 ---
 

.claude/skills/local-dev/evals/evals.json

@@ -4,7 +4,7 @@
     "expect": "local-dev"
   },
   {
-    "prompt": "I added a dependency and the TUI bundle broke at import time. Where should it have gone?",
+    "prompt": "I added a package and now one of the client bundles fails at run time. What do I check?",
     "expect": "local-dev"
   },
   {
@@ -15,6 +15,10 @@
     "prompt": "How do I run the CLI from the built launcher in this repo instead of via npx?",
     "expect": "local-dev"
   },
+  {
+    "prompt": "Do I need to do anything special to set this repo up inside a git worktree?",
+    "expect": "local-dev"
+  },
   {
     "prompt": "Write a haiku about autumn.",
     "expect": null

.claude/skills/pr-flow/evals/evals.json

@@ -11,6 +11,14 @@
     "prompt": "The DCO check is red on my branch. How do I fix the commits I already pushed?",
     "expect": "pr-flow"
   },
+  {
+    "prompt": "Copilot left a pile of review comments on my PR. How do I answer them so nothing gets lost?",
+    "expect": "pr-flow"
+  },
+  {
+    "prompt": "My PR is open and green. Walk me through getting it merged and closed out here.",
+    "expect": "pr-flow"
+  },
   {
     "prompt": "What does this regex match? /^[a-z]+$/",
     "expect": null

.claude/skills/pre-push-gate/evals/evals.json

@@ -4,13 +4,21 @@
     "expect": "pre-push-gate"
   },
   {
-    "prompt": "The Storybook stage of the gate fails in my worktree even though the tests pass. What is wrong?",
+    "prompt": "The gate's Storybook stage is failing for me. How do I diagnose it?",
     "expect": "pre-push-gate"
   },
   {
     "prompt": "Everything in the gate started timing out at once. What causes that?",
     "expect": "pre-push-gate"
   },
+  {
+    "prompt": "How do I check whether a stage of the gate really passed?",
+    "expect": "pre-push-gate"
+  },
+  {
+    "prompt": "The gate failed at the lint stage. How do I work out what is wrong?",
+    "expect": "pre-push-gate"
+  },
   {
     "prompt": "What is 17 multiplied by 23?",
     "expect": null

.claude/skills/project-structure/evals/evals.json

@@ -4,11 +4,19 @@
     "expect": "project-structure"
   },
   {
-    "prompt": "I'm adding a helper both the CLI and the web client need. Which directory does it belong in?",
+    "prompt": "I am adding a module that both the browser side and the Node side need to run. How do I decide where it goes in this repo?",
     "expect": "project-structure"
   },
   {
-    "prompt": "Which package owns the OAuth secret storage backends?",
+    "prompt": "Does browser-only transport code belong in core or in the web client?",
+    "expect": "project-structure"
+  },
+  {
+    "prompt": "I have a new file and I'm not sure where it goes. How do I decide in this repo?",
+    "expect": "project-structure"
+  },
+  {
+    "prompt": "Does a helper that only the CLI and TUI use belong in core or in one of the clients?",
     "expect": "project-structure"
   },
   {

.claude/skills/test-servers/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: test-servers
-description: Run a composable MCP test server by hand — pick the showcase config that reproduces a given feature or bug, build test-servers, and connect with the right protocol era. Covers the stale-build hazard.
+description: Run a composable MCP test server by hand — pick the showcase config for a feature or bug, build it, and connect with the right protocol era. Use when a change, a PR or a smoke test needs a real server to exercise it; when reproducing a reported bug by hand; when choosing which fixture or protocol era to run; when a fixture keeps serving stale code after an edit; or when the config or preset you need does not exist yet.
 disable-model-invocation: false
 ---
 

.claude/skills/test-servers/evals/evals.json

@@ -8,7 +8,15 @@
     "expect": "test-servers"
   },
   {
-    "prompt": "I renamed a file under test-servers/src and the fixture is still running the old code. Why?",
+    "prompt": "I need a real server to exercise this change against by hand. What do I run?",
+    "expect": "test-servers"
+  },
+  {
+    "prompt": "Which protocol era should I connect with when I run one of these fixtures by hand?",
+    "expect": "test-servers"
+  },
+  {
+    "prompt": "I need a fixture combination that doesn't exist yet. How do I add one?",
     "expect": "test-servers"
   },
   {

.claude/skills/testing/SKILL.md

@@ -11,6 +11,12 @@ statements, functions, and branches.** That rule and the React/Mantine
 conventions live in [`AGENTS.md`](../../../AGENTS.md); this skill is where a
 test goes, how to run it, and how to clear the gate.
 
+⚠️ **Anything that needs a real server to run against — an integration test, a
+smoke, reproducing a bug by hand — is `/test-servers`, and you have to load it.**
+Integration and smoke tests here drive a real server over a real transport
+rather than a mock, so picking, building and connecting to a fixture is a
+procedure of its own that this skill does not carry.
+
 ## Where the test file goes
 
 **Side-by-side by default; `src/test/` only for what can't be co-located; and

.claude/skills/testing/evals/evals.json

@@ -1,14 +1,22 @@
 [
   {
-    "prompt": "I just added clients/tui/__tests__/serverList.test.ts. What command runs only the TUI suite?",
+    "prompt": "Which test tier in this repo spawns the built binary rather than importing it?",
     "expect": "testing"
   },
   {
-    "prompt": "In clients/web/src/components/Foo.test.tsx I need to assert on a Mantine transition mid-flight. How?",
+    "prompt": "How do I run just the TUI suite, and is there one command that runs everything?",
     "expect": "testing"
   },
   {
-    "prompt": "Which test tier in this repo spawns the built binary rather than importing it?",
+    "prompt": "How do I write a test for a TUI component in this repo?",
+    "expect": "testing"
+  },
+  {
+    "prompt": "How am I supposed to invoke the CLI from a new test in this repo?",
+    "expect": "testing"
+  },
+  {
+    "prompt": "How do I run the web integration tests, and do they run as part of the normal test command?",
     "expect": "testing"
   },
   {

AGENTS.md

@@ -154,7 +154,14 @@ that from happening:
    Code does and fails on anything that would strip the metadata — most importantly
    **malformed YAML**, which loads the body with an *empty* description, so
    `/skill-name` still works and a manual spot check passes while the skill can
-   never auto-fire again. An unquoted colon in a description is enough. It also
+   never auto-fire again. An unquoted colon in a description is enough — and so
+   is an unquoted **`#`**, which YAML reads as a comment and which truncates the
+   description *silently* from that point on rather than emptying it. `board-ops`
+   shipped that way: `Covers board #28 (v2) and board #11 (v1), their
+   node/field/option IDs, and the option-deletion hazard` was cut at `#28`, so 90
+   characters — including both board numbers — were absent from the listing while
+   every check stayed green, because a truncated description is still a non-empty
+   one. **Quote any description containing `#` or `:`.** It also
    runs `claude plugin validate` — the authoritative schema — when the installed
    CLI is **exactly** the pinned version, and otherwise says so and moves on.
    That best-effort hand-off keeps `validate` fast and offline, but it also
@@ -195,6 +202,9 @@ that from happening:
    a skill therefore has a cost paid by the *existing* ones, which only
    `skills:eval` can see. **Re-run the full eval after any flip _or description
    edit_**, not just the changed skill's own cases.
+   **How to write a description that fires, and cases that measure it, is
+   [`docs/skill-authoring.md`](./docs/skill-authoring.md)** — the case shapes
+   that work, the ones that can never pass, and the probe-then-measure loop.
    The lever that works is the description's *shape*. Leading with the actions
    and then enumerating concrete situations ("Use when … ; when … ; when …")
    beats a noun-phrase list of contents: it took `pre-push-gate` from 3/5 to 5/5
@@ -233,7 +243,7 @@ that from happening:
    overflows, and drops the least-invoked entries **first** — which are exactly the
    model-invoked skills that must fire on their own. `verify:skills` prints the
    current cost against the budget recorded in `scripts/lib/skill-manifest.mjs`
-   (2,834/4,000 characters as of this writing) and fails when it is exceeded. Raise
+   (3,234/4,000 characters as of this writing) and fails when it is exceeded. Raise
    the budget deliberately, or tighten a description; each entry is capped at 1,536
    characters regardless, so **put the key use case first**.
 

README.md

@@ -70,6 +70,7 @@ Each client has its own README with client-specific detail:
 | --- | --- |
 | [Architecture](./docs/architecture.md) | The `@inspector/core` shared package, and the web client's "dumb components" + Storybook approach |
 | [Testing and the quality gate](./docs/quality-gate.md) | What each `validate` / `coverage` / `smoke` / `verify:*` script covers, the GitHub-CI-vs-local-gate split, and the supported browsers |
+| [Writing a skill](./docs/skill-authoring.md) | How to write a skill description that actually fires, and eval cases that measure it — the case shapes that work, and the tuning loop |
 | [Test servers](./docs/test-servers.md) | The composable test servers and the showcase config for every feature — what to run, what to click, and what the broken build did |
 | [Publishing](./docs/publishing.md) | What ships in the tarball, the packaging invariants, and `pack:verify` |
 | [Docker](./docs/docker.md) | Running the container image — ports, volumes, and where secrets go |