agentleFS
Sign inStart free
fergo5002fergo5002/design-director/AGENTS.md

design-director

AGENTS.md1 starsChanged 4 days agoMITView on GitHub

This repo is a design workflow for coding agents (Claude Code, Codex, Cursor, Gemini CLI and anything else that reads AGENTS.md). If you are an agent doing design work in a project that has this installed, start here. Any design work: a page, a component, a dashboard, a brand, a deck, motion, imagery, or a review of any of those. Load the skill before writing markup, picking a colour or choosing a typeface. Agents that support skills natively get them…

  • 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 repository5 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, 3 are distinctive, and 2 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.

  • 2

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run ddr <command> (or python tools/ddr.py <command> from this repo):

    line 27
  2. Distinctive:

    Never record a reference as seen that you did not see.

    line 46
  3. Distinctive:

    Never claim more than you checked.

    line 48
  4. Distinctive:

    Never scrape a site whose terms forbid it, never copy paywalled screens into a public repo, never pirate a typeface.

    line 51
  5. Very specific:

    When changing this repo: run python -m unittest discover -s tests, python tools/ddr.py sources validate, python tools/check_routes.py and …

    line 53

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

design-director for coding agents

This repo is a design workflow for coding agents (Claude Code, Codex, Cursor, Gemini CLI and anything else that reads AGENTS.md). If you are an agent doing design work in a project that has this installed, start here.

When to use it

Any design work: a page, a component, a dashboard, a brand, a deck, motion, imagery, or a review of any of those. Load the skill before writing markup, picking a colour or choosing a typeface.

The four skills

SkillReadWhen
design-directorskills/design-director/SKILL.mdAny design work. The lead: names the job, routes to the guides, sets the gate.
design-researchskills/design-research/SKILL.mdWhen domain confidence is below the stakes, a brief is new territory, or the work looks generic.
design-reviewskills/design-review/SKILL.mdBefore calling anything done.
design-tasteskills/design-taste/SKILL.mdWhenever someone praises or rejects a design, something ships, or a process goes wrong.

Agents that support skills natively get them from python tools/ddr.py install. Agents that do not should read the SKILL.md files above directly when the trigger applies.

The tools

Run ddr <command> (or python tools/ddr.py <command> from this repo):

  • ddr domain match "<brief>": read first. Which design domains the brief falls in and how much you actually know about each (0 to 100). Below the stakes target, research before designing.
  • ddr domain brief <slug>: the dossier, exemplars, counter-examples and ledger for a domain.
  • ddr domain new|ref add|ref retire|relate|merge|audit|status|plan: build and curate the expertise.
  • ddr taste brief: what was rejected, what landed, what is saturated.
  • ddr sources search "<need>" -v: the verified catalogue of sites, libraries, MCP servers, skills and AI tools.
  • ddr sources shuffle -n 3: a random cross-discipline draw, for a direction that is not your default.
  • ddr lint <src>: the obvious generated-design tells.
  • ddr shots <url> --full: render at desktop, phone and 320px, with and without reduced motion, and measure.
  • ddr ux --file <page>: the countable UX rules at a phone and a desktop size (UX.md).
  • ddr palette ramp|check|blend: OKLCH ramps and measured contrast.
  • ddr fonts: inline a subset webfont for sandboxed pages.
  • ddr mcp: recommended MCP servers with setup per agent.
  • ddr taste win|miss|shipped|error: log outcomes as they happen.

Rules that apply to every agent

  • Say your domain confidence before designing, and research on your own when it is too low for the stakes.
  • Never record a reference as seen that you did not see. The confidence score is only worth anything if the evidence behind it is true.
  • Never claim more than you checked. Say what you verified and what you did not.
  • Prove the instrument before blaming the page: run tools/instrument-check.js before diagnosing any rendering, freeze or timeout problem in a browser.
  • Never scrape a site whose terms forbid it, never copy paywalled screens into a public repo, never pirate a typeface.
  • When changing this repo: run python -m unittest discover -s tests, python tools/ddr.py sources validate, python tools/check_routes.py and python tools/ddr.py sources render before committing. Starter domains live in domains/; write to them with DDR_HOME=<this repo> so ddr domain edits them in place.

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.

Check your setup, free