laurigates /evaluate:legibility
Dispatch an isolated, zero-context agent reader at a single SKILL.md and
ask it the only two questions that matter for reuse: from this file alone, can
you tell WHEN to invoke the skill, and can you carry out its FIRST concrete
action? What confuses a cold agent reader is what will silently degrade
auto-invocation and first-step execution for every future agent that loads the
skill.
This is the comprehension gate — read and critique, never execute. It
reuses the dispatch contract of agent-patterns-plugin:cold-read-gate (isolated
haiku reader, QUESTIONS / HESITATIONS / verdict schema, triage before
acting). The difference: the reader here is an agent loading a skill, not a
human triaging an outward artifact — so the persona and the triage table are
skill-doc-specific. See that skill for the dispatch rationale; this skill does
not restate it.
The verdict is advisory, not a CI gate: haiku is non-deterministic, so a
needs-revision is a prompt to look, never a merge block.
When to Use This Skill
| Use this skill when... | Use alternative when... |
|---|---|
| Checking a SKILL.md reads clearly to a fresh agent | Testing whether the skill executes correctly -> /evaluate:matrix |
| Triaging why a skill never auto-invokes | Need structural/lint validation -> scripts/plugin-compliance-check.sh |
| Reviewing a newly-authored or just-edited skill | Gating outward issues/docs for a human reader -> agent-patterns-plugin:cold-read-gate |
| Want a cheap, no-execution legibility read | Benchmarking effectiveness vs a baseline -> /evaluate:skill |
Context
- Available skills: !
find . -path '*/skills/*' -name 'SKILL.md' -not -path '*/.claude/worktrees/*'
Parameters
| Parameter | Default | Description |
|---|---|---|
<plugin/skill-name> |
required | Target skill as plugin-name/skill-name |
Execution
Execute this legibility gate:
Step 1: Resolve the prompt
The Context block above ran emit-legibility-prompt.sh, which resolved the
target SKILL.md absolute path and emitted the cold-reader dispatch prompt
between === PROMPT === and === END PROMPT ===.
If STATUS=ERROR, report the ERROR= line and stop (bad argument or missing
SKILL.md). Otherwise read SKILL_PATH= and the === PROMPT === block.
Step 2: Dispatch the cold reader
Spawn one Task subagent to read the skill cold:
Task subagent_type: general-purpose
model: haiku
prompt: <the text between === PROMPT === and === END PROMPT ===>
The reader is deliberately haiku, isolated, and shown only the file path —
it is the measurement instrument, not a delegate (the sanctioned exception in
.claude/rules/agent-and-tool-selection.md). Do not add context, do not let it
explore the repo. Capture its final message: QUESTIONS, HESITATIONS, and a
verdict of clear or needs-revision.
Step 3: Triage — genuine gaps vs test artifacts
The cold reader cannot know the invocation context, so some complaints are artifacts of reading a skill in isolation. Triage before recommending changes:
| Genuine gap — fix it | Test artifact — ignore it |
|---|---|
| No "When to Use" table; reader can't tell when to invoke | "What is plugin X?" when X is named in the frontmatter |
description has no "Use when…" trigger phrase |
REFERENCE.md content absent (loaded on demand by design) |
| First execution step names a script/term the file never defines | Harness vars ($ARGUMENTS, ${CLAUDE_SKILL_DIR}) unrecognized |
| Skill narrates ("this skill handles X") instead of an imperative step | Full tool list absent from the body (it's in allowed-tools) |
| Acronym/jargon used before it is introduced | Demands for context a real invocation supplies |
Step 4: Report
Print the verdict, the genuine-gap QUESTIONS (each with the quoted phrase that
blocked the reader), and a one-line recommendation per gap. State explicitly
that the verdict is advisory. Do not edit the skill — surfacing the gaps is
the deliverable; fixing them is a separate, human-confirmed step.
Agentic Optimizations
| Context | Command |
|---|---|
| Resolve path + emit prompt | bash evaluate-plugin/skills/evaluate-legibility/scripts/emit-legibility-prompt.sh --plugin-skill <plugin/skill> |
| Run the script test | bash evaluate-plugin/scripts/tests/test-emit-legibility-prompt.sh |
Quick Reference
| Field | Meaning |
|---|---|
verdict: clear |
Reader could answer both (a) when and (b) first action |
verdict: needs-revision |
A genuine gap blocked (a) or (b) — advisory, not a block |
QUESTIONS |
Blocking confusions, each with a quoted phrase |
HESITATIONS |
Non-blocking uncertainties |
Related
agent-patterns-plugin:cold-read-gate— the dispatch contract this reuses (outward artifacts, human reader)/evaluate:matrix— the executability gate (run on haiku, grade the artifact)/evaluate:skill— effectiveness vs a baseline (with-skill − baseline delta).claude/rules/skill-evaluation.md— the tiered measurement methodology