ui-ux-designer
AGENTS.md0 starsChanged 22 days agoMITView on GitHub
Agent map and standing rules for this repository. Read this file as policy, not suggestions. Every rule carries its reason: when a situation is not covered, generalise from the reason rather than guessing.
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 33,315 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 repository10 other files it gives its agents.
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
15 rules. About 0 are common, 14 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈14
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 7
Never speculate about code or files you have not opened.
- Distinctive: line 16
Do not redo work that is already in the repository.
- Distinctive: line 22
Add docstrings, comments, or type annotations to content you did not change.
- Distinctive: line 23
Add error handling, fallbacks, or caveats for scenarios that cannot happen (e.g.
- Distinctive: line 24
Create helpers or abstractions for one-time operations, or design for hypothetical requirements.
- Distinctive: line 27
Leave useless comments behind.
- Distinctive: line 28
Prefer editing the source of a rule over editing a restatement of it.
- Distinctive: line 33
If a check cannot be run, say so explicitly instead of reporting success.
- Distinctive: line 34
Do not claim completion stronger than the evidence.
- Distinctive: line 40
Before reporting any change done, run:
- Distinctive: line 66
Ask first for anything destructive, hard to undo, or visible to others: deleting branches or history, force-pushes, changing repository …
- Very specific: line 70
Do not add Co-Authored-By trailers for AI assistants to commit messages.
- Distinctive: line 93
Keep replies under 200 words.
- Distinctive: line 94
Write in British / New Zealand English throughout: behaviour, colour, organise, initialise, "-ise" endings, NZ date and spelling …
- Distinctive: line 98
No padding, no restating the question, no caveats that carry no information.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 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
Agent map and standing rules for this repository. Read this file as policy, not suggestions. Every rule carries its reason: when a situation is not covered, generalise from the reason rather than guessing.
Ground truth
- Never speculate about code or files you have not opened. If asked about a file, read it before answering. Reason: confident claims about unread files are indistinguishable from truth in review.
- File and directory names are not reliable evidence of what something does. Reason: naming drifts; contents do not.
- Documentation describes intent, not implementation state. Verify in the actual files before reporting status. Reason: docs lag behind code in every repo.
Act only when told, and look before answering
- Do only what the user has asked for in this conversation. Do not start extra work, change files, or run side tasks on your own initiative. If you think something else is needed, say so in one line and wait. Reason: unrequested actions cost the user credit and trust, and they are hard to undo.
- Before you answer or change anything, analyse the current state of the repository for the task: open the relevant files, read what is already there, and check git status and recent history for work that is already done. Reason: answers built on assumptions waste credit and repeat finished work.
- No guesswork. Every statement about the repository must come from something you opened or ran in this session. If you have not checked it, either check it now or say plainly "I have not checked this". Never fill a gap with a plausible guess. Reason: unfounded information is worse than no answer, because the user acts on it.
- Do not redo work that is already in the repository. Find it first, report that it exists, and build on it. Never produce an answer and then correct yourself with "sorry, my mistake" when one look at the files would have prevented it.
- When a step asks the user to review, decide or approve something, first find the real thing (file path, exact wording, value or log line) and show it in that same step. Never write "decide X" or "approve Y" without showing X or Y. Reason: naming a task pushes the lookup work back onto the user.
Scope of changes
- Make the smallest correct change that satisfies the task. Reason: every extra line is extra review burden and extra risk. Concretely, do not:
- Add docstrings, comments, or type annotations to content you did not change.
- Add error handling, fallbacks, or caveats for scenarios that cannot happen (e.g. already covered by the validator). Validate at system boundaries only.
- Create helpers or abstractions for one-time operations, or design for hypothetical requirements.
- Refactor or "improve" anything beyond what the task asked.
- Add comments beyond what the code genuinely needs. Keep the codebase mostly clean: comment only where the logic is not self-evident, and keep those comments short. Reason: comments that restate the code rot into lies; the code is read far more often than it is written.
- Leave useless comments behind. When editing a file, delete comments in the lines you touch that are wrong, outdated, or say nothing the code does not already say. Reason: dead comments accumulate until readers stop trusting every comment, including the useful ones.
- Prefer editing the source of a rule over editing a restatement of it. Reason: copies drift.
Accuracy and honesty
- Separate observed fact from inference, and mark anything uncertain.
- If a check cannot be run, say so explicitly instead of reporting success.
- Do not claim completion stronger than the evidence; state exactly what was checked.
- Solve the problem, not the test. Behavioural cases measure quality; they do not define it. If a case or check is wrong, say so rather than working around it.
- Treat the user's description of their own system as the working fact. Check the real files or output, report facts only, and if the evidence differs say so once, neutrally, with the file and line, then carry on with their description. Do not contradict first and concede later. Reason: the user built the system; arguing from assumption wastes their time and teaches them to repeat themselves.
Verification
Before reporting any change done, run:
python scripts/skills_tool.py checkChecks: frontmatter, name/folder match, description length and trigger, body under 500 lines, every relative link resolves (including README.md and AGENTS.md), agent profile naming with no more than two profiles per host and exactly one -workflow main agent, agent skills: entries that exist and no skills/<name>/SKILL.md paths in agent bodies, plugin manifests valid and consistent with LICENSE and the profiles, at least 3 eval cases per skill, obvious, paraphrase and unrelated trigger queries per skill, no README.md inside a skill folder, catalogue not stale, no project-specific terms from reference-content/strip-terms.txt, and no em or en dashes in file names or in any text outside reference-content/. Once skills/example-skill/ is deleted it also fails on leftover <placeholder> text and setup-only paths that are tracked by Git or not ignored.
- The tool is necessary but not sufficient for content quality. For new or changed skill body text, also re-read the changed SKILL.md end to end. Reason: a validator checks structure; only reading checks that the instructions still make sense.
Repository map (fill in as this repo takes shape)
skills/<name>/SKILL.md: the only source of skill content. Folder name equals frontmattername.resources/agents/: optional, host-native profile sources consumed byscripts/install_agents.py. Shared agent names use theshared-namespace; skill-specific agent names use<owning-skill-slug>-<role>. No*.agent.mdfiles for a host means there are no profiles to install for that host.plugin.jsonand.agents/plugins/marketplace.json: the portable manifest and marketplace that Codex reads (OpenAI documents the rootplugin.jsonas the portable entry point).name,version,licenseandauthor.namemust match.claude-plugin/plugin.json;scripts/bump_version.pyupdates both..claude-plugin/plugin.jsonandmarketplace.json: the Claude Code plugin manifest and single-plugin marketplace. Theagentsarray lists each Claude Code profile underresources/agents/claude-code/. Reason: without the key, Claude Code scans a top-levelagents/folder and would load Codex briefs as subagents..github/agents/,.claude/agents/, andagents/codex/: optional installed host profiles and Codex role briefs in a target project, never in this repo. The installer creates these folders only when it has profiles to copy and never replaces an existing different file.- New skills follow the house format that existing skills embody: folder name equals frontmatter
name; frontmatter, gate, steps, hard rules.evals/cases.jsonlandevals/triggers.jsonlare the sources forquality/evals/; never hand-editquality/evals/, runpython scripts/export_evals.py. Numbers (44 pt, 48 dp, 24 CSS px, contrast ratios, size class breakpoints) live inskills/adaptive-layout-and-spacing/references/size-classes.mdandskills/accessible-design/references/targets-and-contrast.md; other skills quote them with their source, so change the reference first. Reason: one number repeated in several skills drifts. SETUP.md,templates/, andreference-content/are local setup material that stays ignored and outside the Git index when a repo is published. Reason: the maintainer needs these files for future work, while public commits must exclude bootstrap material and private sources.- Custom to this repo: the router
skills/ui-ux-designer/SKILL.mdowns the shared guardrails (mobile first, source every number, no framework code). Skills describe design decisions, not code; implementation belongs to the stack's own skills. Reason: design advice stays valid across stacks. hooks/: the always-on rules and safety checks.always-on.mjsloads the rules at session start;guard.mjsruns the checks (dangerous commands, secrets, invented packages, licences, risky code patterns, suspicious prompts, a reminder when code changed but no checks ran) andcommon.mjsholds the shared helpers. These three files are identical in every plugin repository; change them intemplatefirst.hooks/always-on.config.jsonholds the id, name, phrase, rules path, auto-detect markers and per-check defaults, andskills/ui-ux-designer/references/always-on-rules.mdis the only source of the rules. Keep that file under 320 words. Reason: it is paid for in tokens at the start of every session, and a copy would drift from the skills. Hooks fail open and only ask, warn or add context; they never edit files silently. The saved mode and check overrides live in the user's~/.claude/.ui-ux-designer.modeand.example-skills.features.json, never in this repo.
Irreversible and shared actions
- Proceed freely for local, reversible actions: editing files, running checks, regenerating the catalogue.
- Ask first for anything destructive, hard to undo, or visible to others: deleting branches or history, force-pushes, changing repository visibility, pushing to shared sources. Reason: damage in a public repo cannot be recalled.
Commit attribution
- Do not add
Co-Authored-Bytrailers for AI assistants to commit messages. Add co-author attribution only when the user explicitly requests it. Reason: commit trailers affect GitHub's contributor attribution.
Known deliberate states (dated)
- 26 October 2026: one of the three requested sources (a Medium article on modern mobile app design) returned HTTP 403 and was not read. Material Design 3 pages are script-rendered and were not read; Android developer pages stand in. Reason: these could not be fetched.
Anti-drift close-out
Before reporting done, confirm the change introduced no new local convention (a new section shape, a new file pattern, a divergent description style). If it did, either move it into the shared source or record the approved exception here. Reason: un-owned variations are how a standard silently dissolves.
Close-out report
Finish every task with these five points, in this order:
- What changed and why
- Files changed
- Validation run, and the result
- Validation skipped, and why
- Residual risks
How to respond
- Reply in paragraphs: flowing prose, one idea per sentence, short paragraphs. Use lists only where the content is genuinely a list (the five-point close-out report, file paths, step sequences).
- Keep replies under 200 words. Go longer only when the user clearly asks for a thorough response. If more depth seems useful, offer it in one short line rather than writing it unprompted. Reason: long replies bury the decision the user needs to make.
- Write in British / New Zealand English throughout: behaviour, colour, organise, initialise, "-ise" endings, NZ date and spelling conventions. Reason: mixed spellings in one reply read as carelessness to a NZ audience.
- Simplify so a 16-year-old high school student could follow it: everyday words first, explain any unavoidable term the first time it appears, one technical term per sentence. Reason: if the explanation needs jargon to be understood, it has not explained anything.
- If the next step is one the user must do themselves (a setting to change, something to install, a click in a website), brief them first: say what is about to happen, what the step is for, and what success will look like. Then give exactly that one step, completely and simply. Reason: handing over five steps at once invites skipped and half-understood steps.
- After each user-side step, stop and wait for the user to say they are done before giving the next step. Do not stack several manual steps in one reply. Reason: one task at a time keeps confirmation honest and lets problems surface at the step that caused them.
- No padding, no restating the question, no caveats that carry no information.
- Skip em dashes and en dashes entirely and always. They are banned in every reply, every file, every commit message, prose and code comments alike. Every dash in text must be a plain hyphen (-). If a hyphen does not fit, use a comma or rewrite the sentence. Reason: nothing justifies an em dash; a banned character that appears anywhere is a single, checkable, zero-tolerance rule.
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.

