agentleFS
zerniezernie/vigiles/.claude/skills/audience-check/SKILL.md

audience-check

Skill15 starsChanged 5 months agoMITView on GitHub

Read the README (or any front-door doc) through the eyes of several distinct audience personas and report what each would think, miss, or bounce on

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Run all of these unless the user scopes to a subset.

    line 28
  2. Distinctive:

    Keep the report scannable and ACTIONABLE: every finding names a line and a fix.

    line 113
  3. Distinctive:

    Do not rewrite the README in place unless the user asks — this skill REPORTS.

    line 114

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Re-read the README — or whichever front-door doc the user names — as several different readers in turn, not as the author. The author knows what every line means; a first-time reader does not. The job is to surface where a specific audience gets confused, under-served, or bounces, and to propose concrete fixes.

This is an INTERNAL dev skill (not shipped to consumers). It complements the readme-brevity and docs-quality rules: those govern length/polish; this checks whether the content actually lands for who it's for.

How to run it

  1. Read the target doc in full (default: README.md; honor a path the user gives). Also skim the docs it links to, so "the README promises depth the doc doesn't deliver" is checkable.
  2. For each persona below, do a cold read — adopt that reader's goals, vocabulary, and patience. Ask their questions, not yours.
  3. Produce the report in the format at the end. Be specific: quote the exact line, name the exact fix. Vague notes ("could be clearer") are useless.

The personas

Run all of these unless the user scopes to a subset.

1. Claude Code user (the primary audience)

Already lives in Claude Code; skimming on a laptop between tasks. Wants the WOW in the first screen and a copy-paste install in seconds.

  • Does the first screen land what vigiles does and why they'd care?
  • Is the install path (npx vigiles init, the agent prompt) above the fold and obviously runnable?
  • Does it speak their language (hooks, skills, CLAUDE.md, subagents) without over-explaining?

2. Codex user (the second-harness audience)

Uses OpenAI Codex / AGENTS.md, not Claude Code. Skeptical that this is "a Claude thing."

  • Is Codex support visible early, or buried/footnoted so they assume it's CC-only?
  • Are the examples CC-only (CLAUDE.md, claude CLI) in a way that makes a Codex user feel like a second-class citizen?
  • Would they know vigiles/codex exists and what works vs. what's a documented follow-on?

3. Senior / staff engineer (the skeptic)

Scans for substance and differentiation in ~20 seconds; allergic to marketing fluff. Will mentally compare to tools they know (promptfoo, ESLint, ast-grep).

  • Is the differentiation concrete and credible, or hand-wavy? Does every load-bearing claim link to proof?
  • Does the "deterministic, no API key / runs on your sub" cost angle come through as a real architectural fact, not a slogan?
  • Anything that reads as overclaiming will cost trust — flag it.

4. Junior engineer (the newcomer)

New to agentic tooling; needs clarity, not jargon. Bounces on undefined terms.

  • Which terms are used before they're defined (harness, eval, trigger-rate, subagent, dialect)?
  • Is there a clear "what do I do first" path, or does it assume context they lack?

5. Engineering manager / decision-maker (adoption + ROI)

Won't run a command; deciding whether the team should adopt. Cares about cost, risk, and effort.

  • Is the cost story (free deterministic tiers, evals on the existing Claude sub vs. metered per-token competitors) legible to a non-runner?
  • Is adoption framed as incremental/low-risk (start permissive, tighten later)?
  • What's the "why now / why us" — is it answerable from the README alone?

6. QA / test engineer (the Test pillar)

Owns test infra; evaluates the testing story specifically.

  • Does the Test pillar speak to them — runHook, runHarnessTest, measureTriggerRate, significance/regression gating — or is it all about linting?
  • Is the deterministic-vs-real-model split clear (what runs in CI free vs. what needs a model)?
  • Would they trust it next to promptfoo/DeepEval, and is the comparison honest?

Output format

# README audience check — <file>

## <Persona> — verdict: ✅ lands / ⚠ rough / ✗ bounces
- **Reaction (cold read):** one or two sentences in this reader's voice.
- **Friction:** the specific line(s)/section(s) that confuse or under-serve them.
- **Fix:** the concrete change (move X above the fold, define Y on first use,
  link proof for claim Z, add a Codex example here).

… one block per persona …

## Cross-cutting patterns
The 2–4 issues that hurt MULTIPLE personas (these are the highest-leverage fixes).

## Ranked fixes
A short, ordered list — highest reader-impact first — each a one-line action.

Keep the report scannable and ACTIONABLE: every finding names a line and a fix. Do not rewrite the README in place unless the user asks — this skill REPORTS; applying the fixes is a separate, explicit step.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.