/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

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

evaluate-legibility