ux-agent-skills
AGENTS.md18 starsChanged 4 months agoMITView on GitHub
Instructions for AI agents working on this repo — how it's laid out, how to author new components, and which rules the tests actually enforce. Working on a host app with this plugin installed? You want README.md. This file is for changing the plugin itself. This is a Claude Code plugin. It ships no application code — every component is Markdown, and the Python under scripts/ and tests/ exists to keep that Markdown honest. This plugin inherits the composition rule…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,439 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository6 other files it gives its agents.
- docs/agents.mdAGENTS.md
- audit-cujSkill
- render-reportSkill
- spec-cujSkill
- usability-auditSkill
- ux-auditSkill
The file
We split this AGENTS.md into the rules it gives an agent
5 rules. About 0 are common, 0 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 20
Keep the layers honest: a persona holds the point of view and never inlines a workflow.
- Very specific: line 72
Every component is YAML frontmatter + a Markdown body.
- Very specific: line 104
Must cover static/live/hybrid modes, writing under .ux/audits/, and the coverage-gap rule.
- Very specific: line 233
Testing it trips only one trap: No new SKILL.md exists, so test_evals.py stays green and no eval case is needed — the loud trap never fires.
- Very specific: line 254
test_components.pydoes not glob, and fails silent: Every check is a hardcoded function — check_persona(), check_skill(), …
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md 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.
Files
AGENTS.md
Instructions for AI agents working on this repo — how it's laid out, how to author new components, and which rules the tests actually enforce.
Working on a host app with this plugin installed? You want README.md. This file is for changing the plugin itself.
This is a Claude Code plugin. It ships no application code — every component is Markdown, and the
Python under scripts/ and tests/ exists to keep that Markdown honest.
Composition — three layers
This plugin inherits the composition rule from addyosmani/agent-skills:
- Personas (
agents/*.md) — roles with a perspective and an output format. The who. - Skills (
skills/<name>/SKILL.md) — workflows with steps and exit criteria. The how. - Slash commands (
commands/*.md) — user-facing entry points. The when.
Keep the layers honest: a persona holds the point of view and never inlines a workflow; a skill holds
the steps and its own references/; a command stays thin — parse args, invoke persona + skill,
nothing more. When you're unsure where something belongs, ask which of who / how / when it answers.
Repo layout
ux-agent-skills/
├── .claude-plugin/
│ ├── plugin.json # plugin manifest — metadata only, no component lists
│ └── marketplace.json # marketplace catalog (self-lists this plugin)
├── agents/ # personas — the who (usability-auditor, cuj-author, cuj-auditor)
├── skills/ # skills — the how
│ ├── usability-audit/ # usability audit workflow + framework lenses & report contract
│ ├── ux-audit/ # the suite roll-up (fan-out + normalize + verdict)
│ ├── spec-cuj/ # author critical user journeys by interview (+ cuj-contract)
│ ├── audit-cuj/ # replay journeys, report the step that broke
│ └── render-report/ # render reports to self-contained HTML (the one non-auditor skill)
├── commands/ # slash commands — the when
├── scripts/ # validate_report.py, validate_cuj.py, audit_safety.py, render_report_html.py
├── tests/ # contract / component / cuj-contract / safety / docs / evals / render-html checks
├── evals/ # trigger + behavioral evals (Sprout as the target)
├── docs/ # layer catalogs (agents.md, commands.md, skills.md) + README images
├── icon.svg # the directory listing's icon, referenced by plugin.json
└── SPEC.md # this repo's design spec (§1–8 usability auditor, §9 CUJs, §10 walk-through + HTML) — what/whyComponents are auto-discovered by convention from agents/, skills/*/SKILL.md, and
commands/. Adding one needs no plugin.json edit — the manifest carries metadata and
dependencies only. Touch it to bump version, to change the icon, or to add an external plugin
you wrap (mirror any dependencies change into marketplace.json).
agents/ and commands/ are swept wholesale, so every .md in them is a component —
frontmatter or not. A plain README.md there loaded as a phantom persona named "README" and as a
stray /README command, both in the always-on token budget; the published plugin review caught
them as "no frontmatter block". The layer catalogs therefore live in docs/ —
agents.md, commands.md, skills.md —
and check_discovery_dirs() fails if one comes back. Put documentation in docs/, never beside
the components it describes. (skills/ is exempt by construction: discovery there is
skills/<name>/SKILL.md, a directory, not a glob.)
The directory re-scans every published version, and some of its findings are false positives. This suite's subject is credentials, login walls and shell invocations, and a prose-level scanner cannot tell a document that writes about a hazard from code that uses one — v0.6.0 was flagged for a credential read that does not exist (it was reading
auth-handoff.md's rejection table) and for a download-and-run command inside a README screenshot. Expect both to recur. Answer with thegrepthat settles it; do not launder the prose until a scanner likes it, which would cost the reader the rejection tables that make the design reviewable. The reasoning behind each decline is inc4b5fce.
Frontmatter by layer
Every component is YAML frontmatter + a Markdown body. The fields are few and the description does
real work — it's the routing corpus (see Triggers and routing), so write
it for a matcher, not just a reader.
| Layer | Path | Frontmatter |
| Persona | agents/<name>.md | name, description |
| Skill | skills/<name>/SKILL.md | name, description |
| Command | commands/<name>.md | name, description, argument-hint |
There is no separate triggers: key — trigger phrases live inside description, in prose. Copy
the shape from agents/usability-auditor.md:
description: Senior UX auditor that runs expert heuristic evaluation of a host app and writes a
priority-ranked report to .ux/audits. Trigger phrases include "usability audit", "heuristic
evaluation", "UX audit", "usability review".name must match the file (persona/command) or the directory (skill) — test_evals.py keys off
the skill's directory name, so a mismatch fails CI.
Adding a new auditor, end to end
The suite is deliberately uniform: every auditor emits the same report contract, so a new one is mostly conformance work. In order:
agents/<x>-auditor.md— the persona. Body must state the findings-only boundary, the render-vs-source honesty rule, theP0–P3priority format with severity reported as its stated input, and point at its frameworks.skills/<x>-audit/SKILL.md— the workflow. Numbered steps with explicit exit criteria. Must cover static/live/hybrid modes, writing under.ux/audits/, and the coverage-gap rule.skills/<x>-audit/references/— the framework lenses, self-contained. Personas point here; they don't inline heuristics.commands/<x>-audit.md— thin entry point. Documenttarget,scope,mode.evals/cases/<x>-audit.json— mandatory, see the trap below.skill_namematching the directory, ≥3 positive triggers, ≥2 negatives (each naming anownerthat exists inevals/cases/competitors.json), ≥1 behavioral eval withid/prompt/expected_output/expectations.tests/test_components.py— hand-write acheck_<x>()and wire it intomain(). See the trap below.skills/ux-audit/SKILL.md— add to the roll-up fan-out if it joins the suite, and update the auditor list incheck_rollup_skill().- Docs — add the file to
DOC_FILESintests/test_docs.pyso its links get checked, and update the catalog indocs/(agents.md/skills.md/commands.md— not a README beside the component; see the discovery note above).
The CUJ family (a second triad)
Beside the auditor suite sits the critical-user-journey family — two triads, not one. The
authoring side (cuj-author persona, spec-cuj skill, /ux-spec command) interviews the
user and writes journey files under the host's .ux/cujs/; the verification side
(cuj-auditor persona, audit-cuj skill, /cuj-audit command) is an auditor like any other,
reusing the report contract with auditor: cuj. Two things to keep straight when you touch it:
- Authoring writes host docs; auditors don't.
/ux-specmay write.ux/cujs/and — only after asking, only the marker block, always with a diff — the host'sSPEC.md. That does not weaken the findings-only invariant: auditors,/cuj-auditincluded, still write nowhere but.ux/audits/. Theaudit_safety.pyallowlist is keyword-only and authoring-scoped for exactly this reason (SPEC.md §9.6–9.7). - Two files named
SPEC.mdnow exist. Say "the host'sSPEC.md" (the journey index/ux-specregenerates in an adopting app) vs "this repo'sSPEC.md" (the design spec you are reading) explicitly — never the bare name. This repo'sSPEC.mdhas no CUJ index; it has no journeys. audit-cujis a conditional roll-up member. It joins the/ux-auditfan-out only when.ux/cujs/is non-empty; absent, it is skipped with a reason, never a silent pass. Its entry incheck_rollup_skill()uses the literal"audit-cuj", not"cuj"(which the CUJ-heavy body would match anywhere).
Visual walk-throughs and the HTML companion
Two capabilities were layered onto the report contract without changing the findings-only shape. Know both before you touch reporting.
- The
## Walkthroughsection (report contract schema 2). Live/hybrid auditors capture screenshots — per journey step (cuj), per key state (usability) — into.ux/audits/assets/with stable names (cuj-<id>-step-<n>.png,usability-<scope>-<state>.png), so a re-run overwrites rather than accumulates (prune-to-latest). They're embedded inline and assembled into an optional## Walkthroughsection (after## Findings, before## Appendix, live/ hybrid only).validate_report.pyrequiresschema == 2and light-checks that walkthrough image paths are relative and under./assets/. Full spec: SPEC.md §10.1–10.5. - The HTML companion (
scripts/render_report_html.py). A deterministic, derived view: it renders any report.mdinto a self-contained.htmlbeside it (findings as cards, the walkthrough as an interactive flipbook, arollup-*.mdas a priority dashboard,index.mdas a landing page) — everything inlined, opens offline. The audit skills call it as their final step;/ux-review→ therender-reportskill render on demand. The Markdown stays the source of truth; the.htmlis never validated against or in place of it. Full spec: §10.6.
render-report is the suite's one non-auditor skill — so the "adding an auditor" recipe
above does not apply to it: no persona (a mechanical transform holds no point of view), no
references/, no frameworks, no findings. Its check_render_report_skill() asserts the
derived-view invariants (Markdown is canonical, output self-contained, writes confined to
.ux/audits/), not auditor conformance. It still trips both test traps like any skill: it
needs evals/cases/render-report.json (the loud glob) and a hand-wired check_* in
test_components.py (the silent one).
Auth handoff — a shared reference, not a fourth component
Auditing behind a login wall (SPEC §11) added one file and no components:
skills/usability-audit/references/auth-handoff.md.
It holds the handshake, the two-clause capability test, the Never list, and the artifact
posture; usability-audit, audit-cuj, and ux-audit cite it and never restate it —
the same one-owner/consumers-link-across rule as report-contract.md.
Three things to keep straight when you touch it:
- The auditor still never authenticates. SPEC §6's "Never enter credentials, bypass authentication" is preserved verbatim; the rung is the human signing in while the agent waits. Anything that would have the agent hold a secret is out of scope by construction, not by policy debate.
- The credential is not the leak — the capture is. Most of the reference is about what an
authenticated run leaves behind (screenshots and quoted records of a real account), which
is why an authenticated run recommends gitignoring
.ux/audits/wholesale: the HTML companion base64-embeds the images, so ignoringassets/alone does nothing. EXTRA_BY_PROFILE["audit"]stays(). The auditor recommends the.gitignoreline and the user applies it. Do not widen the baseline profile to let an auditor edit a root-level file.- The invariant has two halves, and both run from
main().changes_confined_to()answers "did anything escape?";writes_under()answers "did this run write what it claims?". Only the second survives.ux/audits/being gitignored, and it is only real because the CLI calls it —tests/test_safety.pytherefore asserts throughaudit_safety.main(), not through the function, precisely so an unwired-againwrites_under()fails CI. Both halves take the same content-addressedbaseline, andsnapshot()sweeps the write prefixes withwrites_under()so ignored prior reports are digested rather than mistaken for the current run's output. - The baseline's path is derived, never named.
--snapshotsaves it under a path computed from the host repo, in a private per-user directory, and--baseline autorecomputes the same path — so the two steps name no file. They cannot: a skill's steps are separate tool calls and shell state does not survive between them, which is why the superseded instruction hardcoded/tmp/ux-baseline.jsonand why$(mktemp)would have been a regression. One shared filename meant two concurrent audits overwrote each other's baseline, and the check then measured one repo against the other's tree — in the reproduction, an agent editing host application code reportedsafe. The sweep incheck_no_hardcoded_temp_paths()keeps a fixed temp path out of every component, because a component is a prompt: "pick a unique path" would be improvised differently each run. - Nothing ties a baseline to the run that took it, and two things follow. A failed
--snapshotsave deletes any leftover baseline before warning — baselines are never cleaned up, so one from an earlier run of the same repo is normally sitting there, and--baseline autowould read it and answer about the wrong point in time (reproduced: the user's own uncommittedapp.tsxreported as the agent's violation). Removing it is what makes the warning true —autothen exits 2 instead. And one audit at a time per path: a second run against the same path overwrites the first's baseline and records its report as pre-existing dirt, so the first is told it wrote nothing.baseline_path()says so, cases 31-33 intest_safety.pypin it, and separate worktrees are the supported way to run two at once. Reading a baseline prints its age so a stale read is visible in the transcript; the age comes from the file's mtime on purpose, so the saved bytes stay identical to what--snapshotprinted and there is no second on-disk format. _dirty_paths()never gets--ignored, and the second pass is why it doesn't have to.changes_confined_to()looks for ignored escapes through a pathspec-scoped sweep of_ALL_PROFILE_PATHS— the union of every profile's paths, so an ignored.ux/cujs/behaves like a non-ignored one under theauditprofile.test_safety.pycase 12 fails the repo-wide version and cases 20-25 fail its absence, so both mistakes are caught. An escape into an ignored path no profile names (dist/,tmp/) is a known, documented gap — see the module docstring; do not close it by widening the scan.
Testing it trips only one trap. No new SKILL.md exists, so test_evals.py stays green
and no eval case is needed — the loud trap never fires. The silent one does:
check_auth_handoff_reference() had to be hand-wired into CHECKS, and _check_auth_wiring()
is called from all four components that can meet a login wall (both auditor personas, both
auditing skills). Without those call sites, any of the four could drop the Never list with the
suite still green.
_flatten() before phrase-matching. These are hard-wrapped prose files, so a probe like
"session material" fails the moment the sentence shifts by a word, and inside a blockquote
the continuation carries a > as well. Match content, never the wrap.
The two test traps
The authoring rules aren't written down anywhere except the tests — and the two most important ones fail in opposite directions. Know both before you add a skill.
test_evals.py globs, and fails loud. It computes skills/*/SKILL.md against the eval cases on
disk and requires the set difference to be empty. The moment a new SKILL.md exists without a
matching evals/cases/<name>.json, CI goes red — before you've written a line of the workflow.
Author the eval case alongside the skill, not after.
test_components.py does not glob, and fails silent. Every check is a hardcoded function —
check_persona(), check_skill(), check_command(), check_references(), check_rollup_skill(),
check_rollup_command() — composed by name in main(). A new auditor is not covered until you
hand-write its check_*() and add it there. Nothing warns you; the suite just passes while your
component goes unverified. This is the quieter and more dangerous of the two.
The same shape shows up in test_docs.py: DOC_FILES is a hardcoded list, and a path that doesn't
exist is silently skipped rather than flagged. It link-checks what it's told about — no more.
The one exception, and why it is one. check_discovery_dirs() does glob — agents/*.md and
commands/*.md — and it is the only check in test_components.py that does. The hand-wired checks
verify components you meant to author; only a glob catches a file nobody meant to author at all,
which is exactly how a documentation README.md became a loaded component for five releases
(0.3.0 onward). The hand-wiring rule above is unchanged: a new component still needs its own check_*(), because this
one only asserts that a discovered file has the frontmatter its layer requires, never that it does
its job.
Triggers and routing
Tier 2 evals build a stemmed TF-IDF corpus from each SKILL.md's frontmatter description plus
competitors.json, then assert that every positive prompt ranks its own skill within top_k (3 by
default) and no negative prompt ranks it first. Descriptions must also stay distinct from each other:
≥0.75 similarity is an error, ≥0.50 warns.
Practical consequence: if a new skill's description reads too much like an existing one, routing
collides and CI fails. Differentiate on the vocabulary users actually type. If a negative trigger
names an owner not yet in competitors.json, add a description for it there.
Running the checks
python3 tests/test_report_contract.py # the report contract vs fixtures
python3 tests/test_components.py # persona / skill / command / references conformance
python3 tests/test_safety.py # writes stay under .ux/audits/
python3 tests/test_docs.py # README literals + relative links resolve
python3 tests/test_evals.py # every skill has a case; Tier 2 routing passes
python3 tests/test_render_html.py # HTML companion: self-contained, deterministic, flipbook
python3 tests/test_cuj_contract.py # CUJ files: ids, slugs, SPEC.md index idempotency
python3 tests/test_charset.py # no foreign-script letters or invisible charactersCI loops over tests/test_*.py on Python 3.12 with pyyaml as the only dependency — any new
tests/test_*.py is picked up automatically. Tier 3 (behavioral, token-consuming) runs on demand
against Sprout; see evals/README.md.
Load the working copy without installing:
claude --plugin-dir .Boundaries
The full list lives in SPEC.md §6. The one that governs every component here: this is a
findings-only suite. Auditors write reports under .ux/audits/ in the host repo and never edit,
refactor, or "fix" host application code — the handoff to a maker is the user's call. Preserve that
boundary in anything you author; several tests assert on it, and it's the reason the suite composes
cleanly with agent-skills.
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
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.

