Astryx skill for coding agents

Live demo → — the twelve reference applications this skill's taste is drawn from, running in the browser.

An agent skill that makes coding agents build UI with the Astryx design system the way a designer would — frame first, system components before blank files, and a screenshot review before calling it done. It is plain SKILL.md + references/ with nothing agent-specific in the workflow, so it runs anywhere agent skills do — Claude Code and Codex among them.

The problem it solves is not correctness. An agent will happily emit Astryx code that typechecks, lints and still looks like a prototype: a centred column of stacked Cards, a badge on every row, one gap value everywhere, Item 1 / Item 2 / Item 3 for content. This skill encodes the procedure and the taste that prevent that.

Astryx is new, so the skill carries no API facts. Component names, props, tokens and template names would rot into confident-looking hallucinations, so every factual claim is fetched from the astryx CLI at runtime instead. What lives here is procedure and taste only.

Install

With the skills CLI, which works for either agent and installs into the current project:

npx skills add hex2null/astryx                 # pick your agents interactively
npx skills add hex2null/astryx -a claude-code  # Claude Code → .claude/skills/
npx skills add hex2null/astryx -a codex        # Codex       → .agents/skills/

Claude Code can also take it as a plugin, which the skills CLI route does not give you:

/plugin marketplace add hex2null/astryx
/plugin install astryx@astryx-skills

Or copy the directory in by hand — it is just files:

git clone https://github.com/hex2null/astryx.git
cp -R astryx/skills/astryx ~/.claude/skills/astryx   # Claude Code, personal
cp -R astryx/skills/astryx .claude/skills/astryx     # Claude Code, per-project
cp -R astryx/skills/astryx ~/.agents/skills/astryx   # Codex, personal
cp -R astryx/skills/astryx .agents/skills/astryx     # Codex, per-project

Every route gives you the same thing. The skill activates on its own when you work in a project that depends on @astryxdesign/*, or when you say a page looks generic, unpolished or off — both agents match on the description, and Codex allows implicit invocation by default. To reach for it deliberately, ask for it by name: /astryx in Claude Code, $astryx or /skills in Codex.

It expects the Astryx CLI to be reachable as npx astryx from the project root. The visual review step needs some way to drive a browser — a browser-automation MCP server (Claude in Chrome, Chrome DevTools) or, failing that, a headless npx playwright screenshot.

Using it

/astryx build the billing settings page for this console
/astryx this dashboard looks generic, fix it
/astryx make the orders table denser and give it a real empty state
/astryx port this page onto the incident-console template

What each one changes about how the agent works:

• build the billing settings page for this console — budgets the regions and writes the frame contract before any JSX, then adapts the closest template astryx build returns instead of starting from an empty file.
• this dashboard looks generic, fix it — Fix mode. Diagnoses setup and frame before anything cosmetic, then walks the composition checklist over what is already there: card soup, a badge on every row, one gap value everywhere, placeholder copy.
• make the orders table denser and give it a real empty state — reads the component's documented props with astryx component rather than restyling a raw <div>, and treats the empty state as real work instead of a centred "No data" line.
• port this page onto the incident-console template — scaffolds beside the existing file and moves the content across, never over it. The usual cause of a page looking wrong is the frame, and no amount of spacing and shadows fixes that.

Each ends with a screenshot review rather than a green typecheck, because the defect this skill targets is invisible to every code-level check.

What it does

Two modes — Build a new page, or Fix UI that looks wrong — over five phases:

Phase	What happens
0. Ground yourself	npx astryx doctor, read docs layout and docs principles, and audit the global stylesheet. Scaffolder leftovers that cap and centre #root, or a :root block of hex colors, silently fight the design system and look exactly like bad design.
1. Frame first	Pick the archetype and budget the regions in px before any JSX, recorded as a contract comment at the frame root. Skipping this is the single largest cause of unprofessional output.
2. Start from the system	npx astryx build "<what you're building>" returns a kit — closest page template, blocks, components. Adapt the template; blank is the last resort.
3. Composition	Apply references/composition.md while writing.
4. Verify	doctor, the project's own checks, a screenshot review, and a mechanical sweep for raw <div>s, hex values and magic px.

The two reference files are the substance:

• composition.md — the ten defects that make generated UI read as generated. Card soup, badge confetti, flat hierarchy, uniform spacing, placeholder content, images, decorative icons, dead states, alignment, theme discipline. Each one is a model habit rather than an Astryx fact, which is why correct code still fails it.
• visual-review.md — run the dev server, screenshot at 1440×900 and 768, critique against a named checklist, iterate. Capped at two or three rounds: if it is still wrong after that, the frame is wrong, so go back to Phase 1 rather than adjusting cosmetics.

Repository layout

.claude-plugin/
  plugin.json          plugin metadata
  marketplace.json     catalog entry, so the repo doubles as a marketplace
skills/
  astryx/
    SKILL.md           the workflow — phases, modes, verification
    agents/
      openai.yaml      display name for Codex's skill selector
    references/
      composition.md   composition checklist
      visual-review.md screenshot review loop

skills/ sits at the repo root, not inside .claude-plugin/ — that is where Claude Code scans for skills, and neither manifest declares component paths, so the default scan is what picks this up. It is also the layout the skills CLI walks, which is why one repo serves every agent.

agents/openai.yaml is cosmetic. It only names the skill in Codex's /skills list; implicit invocation is on by default and nothing here declares a tool dependency, because declaring the browser MCP as required would suppress the skill wherever that MCP is absent — exactly the case the npx playwright screenshot fallback exists for.

Related

• @astryxdesign/core — the design system
• astryx-templates — twelve reference applications built with it, and the source of most of the taste encoded here

License

MIT.