Never under‑engineer. Never over‑engineer.
A tech-agnostic skill that teaches an AI agent to write boring, adequate, predictable frontend software. It names no libraries — tools rotate, judgement doesn't. It governs where state lives, where components belong, when a dependency earns its place, and how an agent should behave inside a codebase it doesn't own. Drop it into any React project, on any stack.
What it governs
Six decisions, one standard: the minimum complexity the task demands.
Every rule in the skill carries its reasoning with it, so the agent can apply the principle even on stacks the skill never anticipated — and every default yields to two things: the repo's existing conventions, and your explicit instruction.
- State placement
- A five-rung ladder, asked in order. Server-owned, URL-worthy, local, shared, or injected — the first "yes" wins, and mirrors are banned.
- Component taxonomy
- Atom, molecule, feature, view, page — five roles with one boundary rule each, mapped onto whatever names the repo already uses.
- Data flow
- One direction, server to view, validated once at the edge and trusted inside. No view reaches around its feature to touch transport.
- Styling
- Colocation over ceremony, platform over polyfill, tokens only when the palette has a second consumer, accessibility as structure.
- Dependency policy
- Three conditions to add a library, a rule of one-job-one-answer, and removal treated as a feature in every maintenance cycle.
- Agent conduct
- Smallest diff that fully solves the task, conform to surrounding style, flag problems in prose, never claim a check passed unrun.
Prime directives
Five sentences that decide most arguments.
- 01
Predictability beats cleverness.
Anyone — human or agent — should guess where a piece of code lives, and be right. Optimize for the reader six months out, not the writer today.
- 02
Data flows one direction.
Server → data layer → feature → view, typed edge to edge. A shared primitive never learns the domain exists.
- 03
Encapsulation is scope.
A thing belongs to the narrowest scope that uses it, promoted only when a second real consumer appears — never speculatively.
- 04
Duplication is cheaper than the wrong abstraction.
Similar-looking code with different reasons to change stays separate. Merge only what changes together, for the same reason, repeatedly.
- 05
"No change needed" is a successful outcome.
So is "this must change now." Activity is not progress — but neither is timidity: real problems get reported at their true severity.
The signature move
The state placement ladder.
Most frontend bugs are state placed one level too high; most performance problems, state placed too globally. The ladder is asked in order — the first "yes" wins — and it works whatever your data-fetching library or store happens to be.
1Does the server own it?
→ The data-fetching layer, and nowhere else.
Its cache is the single source of truth. A mirror in a client store is a second source of truth — and two sources of truth is one bug factory.
2Should a URL reproduce it?
→ The router. The platform's free state manager.
Filters, tabs, pagination, sort. Back-button and deep-link semantics users already trust. If losing it on refresh would annoy someone, it belongs here.
3Does one small subtree own it?
→ Local component state.
Passing props a level or two is honest — it keeps the flow visible. Reach for a reducer when the transitions, not the values, are the complexity.
4Do distant siblings share it, changing often?
→ A client store, scoped per feature.
Never one god store. Subscribe narrowly. A store slice that only holds server data is a mirror — retire it and return to rung one.
5Is it injected rather than changed?
→ Context — dependency injection, not state.
Theme, session, flags, services. If an injected value updates often and re-renders half the app, it was misfiled: go back to rung three or four.
The skill, in full
One markdown file. Roughly 2,400 tokens. Zero library names.
Rendered below exactly as an agent reads it. The copy button takes the raw markdown, frontmatter included, ready to save as a skill file.
Use it
Copy once, and it triggers itself.
STEP 1
Copy the markdown
Either copy button on this page puts the complete file — frontmatter and all — on your clipboard.
STEP 2
Save it as a skill
Drop it into your agent's skills directory as a folder named after the skill, containing a SKILL.md.
STEP 3
Do frontend work
The description triggers on any FE task — writing components, placing state, adding a dependency, auditing a repo. No invocation needed.
.claude/skills/frontend-engineering/SKILL.md · or your runtime's equivalent skills path