laurigates/evaluate-legibility

/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