DEV Community

Cover image for How to structure CLAUDE.md, Skills and Agents
Hamid Shoja
Hamid Shoja

Posted on

How to structure CLAUDE.md, Skills and Agents

#frontend #claude #ai #agentskills

Hi friends

Here's a tip for when you're setting up Claude Code (or any coding agent) in a real codebase, this came in clutch for me when I discovered our agent docs were actively generating broken code.

The problem

Most projects end up with four kinds of instruction files:

  • CLAUDE.md / AGENTS.md files
  • skills (.claude/skills/...)
  • agent definitions (.claude/agents/...)
  • big reference docs (UI library API, internal tooling, etc.)

And the same knowledge gets copy-pasted into all of them. Each copy drifts separately. When I finally audited every claim in ours against the actual code, it was worse than I thought:

  • The styling docs showed a CSS-modules pattern that produces class names that never match the build config. Any agent following it ships broken styles.
  • The canonical test template set up mocks in beforeAll, but the test setup file restores all mocks after every test. So the mock silently dies after test one.
  • The same template rendered a data-fetching component without its required provider. Instant crash on render.
  • The "recommended" test helper was used by exactly 1 of 50 real test files.

The docs looked complete. They were confidently wrong. And every wrong doc costs you a multi-thousand-token debug loop when the agent hits it.

The rule of thumb

It's all about when it loads and who needs it:

Surface Loads Should own
CLAUDE.md / AGENTS.md always, every session rules true for every edit
Skill on demand, per task type deep how-to knowledge
Agent when delegated workflow and gates, not knowledge
Hook enforced by code rules that must never be skipped

Four questions to route any piece of content:

  1. Applies to every change in the folder? Then CLAUDE.md: import style, naming, commands, project structure. Keep it small, it pays token rent every single session.
  2. Only needed for one kind of task, but deep? Then a skill: styling mechanics, data-fetching patterns, testing recipes. Costs nothing while idle, only the description loads until it triggers.
  3. Is it a role or a process rather than knowledge? Then an agent: the workflow order, the definition of done, which skill to load. Keep agents thin, knowledge buried in an agent file is invisible to everyone else.
  4. Not acceptable to ever skip? Then a hook. Instructions can be rationalized away, code can't. Run your formatter from a hook, not from a sentence asking nicely.

The one rule that stops the rot

Every fact lives in exactly one file. Everything else links to it.

Our drift existed precisely because one test template was pasted into three places and evolved independently. After the cleanup:

CLAUDE.md / AGENTS.md  -> rules in 3 lines max + link to the skill
skill                  -> the deep patterns, citing real source files
agent                  -> workflow + "run the check command and observe it pass"
reference doc          -> single home for the heavy API reference
Enter fullscreen mode Exit fullscreen mode

So we can define the boundary in one sentence: if a pattern needs more than a few lines, it goes in the skill and CLAUDE.md gets a link.

Verify your docs like you verify code

This was the fun part. Docs claims are testable, so test them:

First, grep before you trust. Every example in your docs should exist in the codebase. Ours didn't:

# "best practice" from our docs vs reality
grep -rl "prefetchQuery" src/ | wc -l      # 0 uses
grep -rl "recommendedHelper" src/ | wc -l  # 1 of 50 test files
Enter fullscreen mode Exit fullscreen mode

Then run a retrieval test with a subagent. Give it ONLY the doc files, no repo access, and make it answer real implementation questions:

"Write a test for a component that fetches data."
"Which package does this component come from?"
"Where do global stores live?"
Enter fullscreen mode Exit fullscreen mode

Grade the answers against the codebase. If the agent following your docs writes code that would fail, your docs failed the test, fix them before merging. We caught every regression this way, before it cost anyone a debug session.

What it achieved

  • ~11% smaller context per typical feature task, leaner always-on footprint
  • a convention change now touches 1 file instead of 3
  • and the big one: the docs no longer generate broken styles and failing tests, each of those was a few thousand tokens of debugging every time an agent stepped on it

this example demonstrates that agent docs are a system with loading semantics, not a wiki: put each fact where its loading model matches, keep one home per fact, and test docs like code.

Hope that helped!
Hash

Top comments (0)