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

`skills:eval` was at 38/46 with several skills measuring 0-33%. The low
scores were mostly bad eval cases rather than bad descriptions, for two
reasons that were nowhere written down:

- The harness runs each case with `--max-turns 1`, so the skill has to be
  the model's FIRST tool call. A prompt asking "how does X work here", or
  naming a concrete file, sends the model to Read/Grep first — a better
  answer to the question, scored as a miss. Every 0% case was one of these.
- `AGENTS.md` is resident on every turn, so a prompt it already answers is
  answered without any skill and the case can never pass.

Replace the cases that measured the wrong thing, expand every model-invoked
skill from 3 to 5 positives (negatives kept) so one flake cannot cross the
threshold, and reshape `local-dev`'s description to the action-first form.

Add `docs/skill-authoring.md` with the case shapes that fire, the ones that
cannot, and the probe-then-measure loop.

RUNS=5 npm run skills:eval: 63/63 at or above threshold, 60 at 100%,
all 18 negatives clean.

Closes #2202

Signed-off-by: cliffhall <cliff@futurescale.com>
This commit is contained in:
cliffhall 2026-08-31 23:22:25 -04:00
commit 6dd43e78ba

View file

@ -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": "Does a new Node-only backend piece for the web client belong in core or in the web client itself?",
"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"
},
{