agentleFS
carlszcarlsz/ux-agent-skills/AGENTS.md

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.

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
  1. Very specific:

    Keep the layers honest: a persona holds the point of view and never inlines a workflow.

    line 20
  2. Very specific:

    Every component is YAML frontmatter + a Markdown body.

    line 72
  3. Very specific:

    Must cover static/live/hybrid modes, writing under .ux/audits/, and the coverage-gap rule.

    line 104
  4. Very specific:

    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.

    line 233
  5. Very specific:

    test_components.py does not glob, and fails silent: Every check is a hardcoded function — check_persona(), check_skill(), …

    line 254

≈ “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.

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

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/why

Components 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 the grep that 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 in c4b5fce.

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.

LayerPathFrontmatter
Personaagents/<name>.mdname, description
Skillskills/<name>/SKILL.mdname, description
Commandcommands/<name>.mdname, 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:

  1. agents/<x>-auditor.md — the persona. Body must state the findings-only boundary, the render-vs-source honesty rule, the P0–P3 priority format with severity reported as its stated input, and point at its frameworks.
  2. 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.
  3. skills/<x>-audit/references/ — the framework lenses, self-contained. Personas point here; they don't inline heuristics.
  4. commands/<x>-audit.md — thin entry point. Document target, scope, mode.
  5. evals/cases/<x>-audit.json — mandatory, see the trap below. skill_name matching the directory, ≥3 positive triggers, ≥2 negatives (each naming an owner that exists in evals/cases/competitors.json), ≥1 behavioral eval with id / prompt / expected_output / expectations.
  6. tests/test_components.py — hand-write a check_<x>() and wire it into main(). See the trap below.
  7. skills/ux-audit/SKILL.md — add to the roll-up fan-out if it joins the suite, and update the auditor list in check_rollup_skill().
  8. Docs — add the file to DOC_FILES in tests/test_docs.py so its links get checked, and update the catalog in docs/ (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-spec may write .ux/cujs/ and — only after asking, only the marker block, always with a diff — the host's SPEC.md. That does not weaken the findings-only invariant: auditors, /cuj-audit included, still write nowhere but .ux/audits/. The audit_safety.py allowlist is keyword-only and authoring-scoped for exactly this reason (SPEC.md §9.6–9.7).
  • Two files named SPEC.md now exist. Say "the host's SPEC.md" (the journey index /ux-spec regenerates in an adopting app) vs "this repo's SPEC.md" (the design spec you are reading) explicitly — never the bare name. This repo's SPEC.md has no CUJ index; it has no journeys.
  • audit-cuj is a conditional roll-up member. It joins the /ux-audit fan-out only when .ux/cujs/ is non-empty; absent, it is skipped with a reason, never a silent pass. Its entry in check_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 ## Walkthrough section (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 ## Walkthrough section (after ## Findings, before ## Appendix, live/ hybrid only). validate_report.py requires schema == 2 and 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 .md into a self-contained .html beside it (findings as cards, the walkthrough as an interactive flipbook, a rollup-*.md as a priority dashboard, index.md as a landing page) — everything inlined, opens offline. The audit skills call it as their final step; /ux-review → the render-report skill render on demand. The Markdown stays the source of truth; the .html is 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 ignoring assets/ alone does nothing.
  • EXTRA_BY_PROFILE["audit"] stays (). The auditor recommends the .gitignore line 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.py therefore asserts through audit_safety.main(), not through the function, precisely so an unwired-again writes_under() fails CI. Both halves take the same content-addressed baseline, and snapshot() sweeps the write prefixes with writes_under() so ignored prior reports are digested rather than mistaken for the current run's output.
  • The baseline's path is derived, never named. --snapshot saves it under a path computed from the host repo, in a private per-user directory, and --baseline auto recomputes 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.json and 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 reported safe. The sweep in check_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 --snapshot save 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 auto would read it and answer about the wrong point in time (reproduced: the user's own uncommitted app.tsx reported as the agent's violation). Removing it is what makes the warning true — auto then 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 in test_safety.py pin 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 --snapshot printed 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 the audit profile. test_safety.py case 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 characters

CI 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.

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.