Skills and agents

Everything under .claude/ is the Claude Code tooling for this repo: the skills you invoke as /<name>, the sub-agents the component pipeline runs, the rules Claude reads before editing a given kind of file, and the references and plans behind them. Most of it came with the template this repo was generated from and keeps arriving through /sync-upstream; the ELB-specific parts — the motion-spec digest, the ELB Figma inventories, the SSO references and the working plans — are this project's own.

It is built for one job above all: turning ELB's Figma files into typed vanilla-extract components, then keeping the content model, the tickets and the docs in step with the code. Generated token contracts are the source of truth throughout — no skill hand-writes a token value; changes route through tokens.json and the @v4/token-parser regeneration loop.

Layout

.claude/
├── mcp.json                  Figma MCP server (npx figma-developer-mcp, FIGMA_PAT in root .env)
├── manifest.json             machine-readable asset registry, Figma file keys, templateCommit (the template baseline)
├── rules/
│   ├── frontend/             component-architecture · vanilla-extract-conventions · theme-variant-patterns · fork-refactor · intermediate-rungs · motion
│   ├── testing/              test-conventions (.test.tsx, vitest)
│   ├── documentation/        storybook-conventions · ai-tooling-docs (this page's currency rule)
│   ├── model/                contentful-model (the @v4/model hard rules + field lessons) · contentful-apps (app registry → lint-apps → sync-apps → lock)
│   └── tickets/              acceptance-criteria · tickets-as-code · platform-and-client
├── reference/tokens/         token-reference.md — THE canonical Token Studio ↔ contract mapping
├── reference/motion/         elb-motion-spec.md — the digest of ELB's motion spec (patterns, tokens, decisions)
├── reference/figma/          ghost-core, ghost-content and ghost-basketball inventories and plans, the ELB – Web – Core chrome inventory, the ghost-video plan, the C9–C14 content briefs
├── reference/model/          contentful-model-plan.md — the @v4/model build plan + deployment contract
├── reference/SSO/            the Cortex SSO developer overview (PDF) and sso-mvp-plan.md — the plan @v4/cortex-sso was built from
├── reference/tickets/        tickets-plan.md — the @v4/tickets contract
├── plans/                    working plans and audits for in-flight campaigns (motion spec, basketball, video, news, analytics, …)
├── skills/                   38 skills (36 with frontmatter; add-feature and sync-upstream have none)
└── agents/                   design-to-code/ + quality-gates/ sub-agent definitions

.mcp.json (repo root)         the docs-MCP server, v4-docs (packages/docs-mcp)

One structural principle runs through it: one canonical body per concern. Where a skill and an agent cover the same ground (accessibility, test ids), the skill holds the content and the agent is a thin wrapper; the Token Studio ↔ contract mapping exists once, in reference/tokens/token-reference.md.

Ownership. .claude/skills, agents, rules and reference are template-owned paths: a /sync-upstream pull request patches them, so a local edit to a template file conflicts with the next update unless it is made in the template too. Files that exist only here (the ELB references) are left alone, and .claude/plans/ and manifest.json are never offered — they are this project's. See Take template updates.

.claude/skills/ holds thirty-eight skills, each invocable as /<name>. Thirty-five of them do work in this repo and are listed in three tables below: ten for building components and taking template updates, fifteen for the content model and the rest of the site, and ten for tickets. The other three arrive with the template's .claude/ but have no job here — see the note at the end.

Component and template-update skills

Content model and site skills

Ticket skills (tickets as code)

Sub-agents

Agents are the parallel workers generate-from-figma orchestrates. Design-to-code agents build; quality gates verify. Every agent takes the owning package (--package on the skill, default ghost-core) and resolves its paths, --filter, registrations and story/e2e folders from it.

Rules

• frontend/component-architecture.md — per-file responsibilities, flat component dirs, the six registration points, contract-first theming with a code-only fallback, and the "naming convention is the API" rule (Figma namespace ↔ component name ↔ --ph__* vars).
• frontend/vanilla-extract-conventions.md — style() vs recipe() vs globalStyle(), the what-goes-where table (.theme.ts = colours/spacing/radius; .css.ts = layout/states/breakpoints), motion utilities with automatic reduced-motion, and performance rules.
• frontend/theme-variant-patterns.md — colour sets are the theming axis, never an onDark prop; the five override levels, owner-keyed theme emission, and how the app emits the ELB theme in parts.
• frontend/fork-refactor.md — the playbook for how this project's design works: ELB's Figma files are COPIES of the Ghost files, modified heavily in place, and we refactor the code to match. The fork PRESERVES node ids, so a bridge naming the upstream file resolves perfectly while measuring the wrong design — four of four components audited on ELB were built to upstream. Covers the preserved-id trap, why a coverage percentage means "matches whichever file the extraction came from", hollow client masters, bindings that contradict their own render, and the ordered sequence that actually works.
• frontend/intermediate-rungs.md — the two bands the design does not draw (tablet 768–1023, laptop 1024–1439): a band binds the page measure (min(100% − 2 × gutter, ContainerWidth.XL)) on its outermost container, families declare an md step from the M grid, the header hands off at 1440 by design, and the rungs stay measured (census script, audit defaults, Playwright tablet / laptop).
• frontend/motion.md — what moves and how much, from ELB's design-owned motion spec (v0.3, 27 Oct 2026; digest at reference/motion/elb-motion-spec.md): every animation names its spec pattern (P-CASCADE, P-REORDER…), values come from the motion.* tokens and never literals, reduced motion gets the complete page instantly, entrances play once per visit, ads and logos never animate, the animation budget is measured, and each pattern is tested in both directions.
• testing/test-conventions.md — .test.tsx, vitest, required coverage list, colour-set render cases, --ph__* token-override assertions.
• documentation/storybook-conventions.md — stories live in apps/storybook, category map, the required AllColourSets story, and the figma.mdx / accessibility.mdx companion-doc specs.
• documentation/ai-tooling-docs.md — this catalogue stays current: any commit that adds, removes or repurposes a skill, agent, rules file or reference updates these pages (and CLAUDE.md's skill list) in the same commit.
• model/contentful-model.md — the model-as-code spine: domain-sliced migrations with ownership lint, expand/contract discipline, the vendored-schema drift gate, fragment curation rules and the dictionary-key flow.
• model/contentful-apps.md — the Contentful apps installed in the space. Their source is built and released in the template; what this repo has is the registry, the lock and the sync. Declared only in packages/model/apps/registry.json, checked by lint-apps, installed and bound by sync-apps (which migrate.mjs runs after the migrations) and recorded in the generated apps.lock.json. Migrations bind an app by slug, never by definition id; each app has a develop and a production release channel that follows the environment.
• tickets/tickets-as-code.md — tickets are authored as typed TS in packages/tickets and pushed ONE-WAY to Jira: the spine, the board bindings, and the hard rules (derived titles and labels, one Figma feature frame per ticket, the resync fingerprint that refuses a ticket someone edited in Jira).
• tickets/acceptance-criteria.md — the single source for what an acceptance criterion says and how it is worded: written for a QA tester or an editor, purely functional, no developer vocabulary, and every content type and field named as Contentful shows it. lint-ac-voice and lint-cms-fields enforce it.
• tickets/platform-and-client.md — this repo is in Client mode: the ELBWEB board, the Contentful space and ELB's own Figma files are authoritative, not the repo. Read before changing where any ticket tool reads facts from: a tool that silently assumes the repo is authoritative passes every gate and is wrong on the board.

Reference

reference/tokens/token-reference.md is the single canonical Token Studio ↔ contract-path mapping. Every skill points here instead of embedding its own table. Where it and the generated packages/tokens/src/__generated__/tokens.ts disagree, the generated file wins.

The other references:

• reference/motion/elb-motion-spec.md — the digest of ELB's motion spec: every pattern, value and open decision, with a "code today" column.
• reference/figma/ — the component inventories and build plans (ghost-core, ghost-content, ghost-basketball, the ELB – Web – Core chrome inventory, the ghost-video plan) and the ghost-content batch briefs. Read the ghost-core and ghost-content inventories with the fork rule in mind: they record Ghost node ids, which resolve in ELB's files too.
• reference/model/contentful-model-plan.md — the @v4/model build plan and the deployment contract.
• reference/SSO/ — the Cortex SSO developer overview and the MVP plan @v4/cortex-sso was built from.
• reference/tickets/tickets-plan.md — the full @v4/tickets contract behind the ticket rules.

Working plans for in-flight campaigns live beside these in .claude/plans/; they are records of a piece of work rather than standing rules.

Several skills, agents and rules cover neighbouring ground. These are the boundaries, so you reach for the right one and do not expect two of them to do the same job.

One canonical body per concern

• Accessibility. /component-accessibility holds the checklist (stable check ids, the widget ARIA table, live-region politeness rules). The quality-gates/accessibility-review agent is a thin wrapper over it.
• Test ids. Likewise /add-test-ids and its agent.
• Token mapping. The Token Studio ↔ contract table exists once, in reference/tokens/token-reference.md; where it disagrees with the generated packages/tokens/src/__generated__/tokens.ts, the generated file wins.
• Generation detail. /generate-from-figma is the seven-phase orchestration; the Figma parsing lives in the figma-parser agent and the file templates in the component-scaffolder agent, which its first phases run.

Reviewing a component against Figma: which skill

• /review-against-figma — the exhaustive audit-and-fix: every token, spacing, typography, colour and child component, recursively. Colour gaps it finds are routed back to the token pipeline.
• /sync-figma-styles — the targeted refresh of theme wiring and structural styles. It ignores colours and routes contract gaps to tokens.json.
• /fork-status — run first, before either: it says which ELB designs are finished and which components are bridged to the wrong file. Reviewing a component against a design that is still moving, or against Ghost instead of ELB, is the expensive mistake (.claude/rules/frontend/fork-refactor.md).

House terms the tooling assumes

Every skill uses the same vocabulary: colour set (code key colourSet1, never "color set" or "colourTheme"), the ph CSS-variable prefix (never gam), @v4/ghost-core for the theme helpers (there is no separate @v4/theme package), the six registration points a component must keep in sync, and compoundVariants over contract paths for the colour-set × state matrix. A skill that says otherwise is out of date — raise it rather than following it.

Frontmatter

36 of the 38 skills carry YAML frontmatter, with names matching their directories; add-feature and sync-upstream have none, so Claude Code lists them without a description, but they run as /add-feature and /sync-upstream all the same.

Work this project does by hand today because no skill covers it. New skills arrive from the template through /sync-upstream, so a gap that applies beyond this site is best raised there.

Using the tooling today

Everything listed in the catalogue is live in this repo. The Figma MCP server (.claude/mcp.json) and the Figma-dependent skills need FIGMA_PAT in the root .env; the ticket skills need JIRA_EMAIL and JIRA_API_TOKEN there too. Skills invoke as /generate-from-figma, /review-against-figma, and so on; how to run each one, with or without Claude, is on the next page.

Every skill under .claude/skills/ can be run two ways, and they read from the same source. /<name> in Claude Code loads that skill's SKILL.md and Claude executes it. Running it manually means following the same SKILL.md yourself — and for a large share of the skills a deterministic pnpm/node command IS the heart of the procedure, so the "manual path" is just invoking that command with the right arguments.

So the useful question is not "which skills have a manual path" (all of them do — the SKILL.md) but "does a single command do the real work, or is the work judgment?". That splits the thirty-five skills used here cleanly in two: twenty script-backed, fifteen orchestrated by Claude. (The three template-only skills — new-club, new-contentful-app, ticket-resolve — are left out; see the catalogue.)

Script-backed skills — a command is the deterministic core

Here a pnpm/node entrypoint does the mutating work. The skill wraps it with an interview (collect the arguments), a sandbox step (an ephemeral Contentful clone for the model skills), and verification (drift/regen/tests) — but you can drive the command directly when you already know the arguments, and CI does exactly that. Run the skill for the guided flow; run the command when you want just the one step.

Claude-orchestrated skills — the work is judgment, not a command

These have no single mutating command: the work is gathering evidence (from the Figma REST API, or across the codebase) and making calls a script cannot — which token a node binds, whether a discrepancy is a bug or a cleanup, which WAI-ARIA pattern applies. The SKILL.md is the manual procedure, step by step. The command listed is only the verification or build step you run after the judgment work — never a substitute for it.