How I structure Claude Code skills and rules for a frontend codebase

Out of the box, a coding agent writes the code an average repository would contain. That's a reasonable default, but your repository isn't average. It has a folder structure, a testing style, a way of naming things and a list of mistakes the team already made once. Until the agent knows those, you spend your time correcting it instead of shipping.

Over the past year I've settled on a two-layer setup for frontend codebases (mostly Angular, but nothing here is Angular-specific): repo rules that are always loaded, and skills that are loaded only when a task needs them. This post is the structure I'd set up on day one of a new project.

Layer 1: repo rules, short and specific

Claude Code reads a CLAUDE.md at the root of the repository on every session (other agents have their own equivalent, such as AGENTS.md). Everything in it costs context on every task, so I treat it like a budget.

What earns a place there:

• Conventions a linter can't express. "Feature folders own their state; shared code goes in shared/ only once two features use it." "Never call the API from a component; go through the feature's data service."
• Pointers to real examples. "For a new list page, copy the structure of features/orders/." A path to a good file beats a paragraph of description.
• The commands that prove work is done. How to run the unit tests for one file, the linter and the type check. If the agent can't check its own work, it will tell you it's finished when it isn't.
• Known traps. The one library you must not upgrade, the module that is generated and must not be edited by hand.

What doesn't belong there: anything your formatter or linter already enforces, general advice ("write clean code") and long explanations of the architecture. Link to a doc instead.

My rough test: if a rule doesn't change what the agent would do, delete it.

Layer 2: skills that each do one job

A skill is a folder with a SKILL.md that describes when to use it and how. The description is loaded up front; the full instructions are loaded only when the task matches. That's what makes them cheap: you can have many without bloating every session.

For a frontend repo, these four pay off fastest:

1. Branch review. Diff the branch against the base, check it against the repo rules, run the tests and lint for the touched files, and report blockers separately from suggestions.
2. Unit-test generation. Write tests that look like the tests already in the repo, with the same helpers, the same mocking style and the same naming. This is where generic agents are weakest.
3. Quality-gate fixes. Take the output of the linter, type checker or static-analysis gate, fix the findings and re-run until it's clean, without "fixing" things by disabling rules.
4. Feature scaffolding. Generate a new feature the way the team builds them: folder layout, routing, data service, a first test.

A skeleton I start from:

---
name: branch-review
description: Review the current branch against the repo rules before opening a PR.
  Use when asked to review, check or "look over" a branch or diff.
---

## Steps
1. Get the diff against the base branch (`git diff origin/main...HEAD`).
2. For each changed file, check it against the rules in CLAUDE.md.
3. Run the unit tests and lint for the changed files only.
4. Report: blockers first, then suggestions, each with file:line.

## Don't
- Don't rewrite code during a review; propose changes instead.
- Don't report anything the linter already reports.

Rules of thumb that held up

• Make every skill verify. A skill that ends with "run the tests and show the result" produces far fewer surprises than one that ends with "write the code".
• Point at files, not prose. "Match the style of user.service.spec.ts" works better than describing that style.
• Keep skills small and composable. A review skill that also fixes, refactors and writes docs is hard to trust and harder to debug.
• Version them in the repo and review them like code. Rules and skills go stale as the codebase moves. When the agent gets something wrong twice, that's a rule or a skill that needs updating.
• Measure by adoption. The real test is whether teammates reach for a skill without being reminded. If nobody uses one, find out why before writing the next.

Where this goes next

The same idea scales beyond the editor. Once the rules and skills are in the repo, they work in CI too: a review skill can run on every pull request, and an MCP server can give the agent access to your issue tracker or design files with narrowly scoped permissions.

If you want this set up for your team's codebase, that's one of the things I do. Get in touch.