SKILL.md, CLAUDE.md, and why my repo has no AGENTS.md

An AI coding agent starts every session knowing nothing about your project. No memory of yesterday, no idea that you banned floats for money, no clue the API runs on Fastify and not Express.

Whatever it needs to know, it has to read. So the files it reads became the most important code in ParkEase that isn't code.

There are three kinds.

1. CLAUDE.md: the project's constitution

Claude Code loads a file called CLAUDE.md from the repo root into every session automatically. Mine is short on prose and long on rules. The core of it is a section called "The ten rules that matter most":

1. Money is integer paise, and the ledger is the truth.
2. Controllers authorise and delegate. Nothing more.
3. One transaction per write, with the outbox inside it.
4. Never call an external service inside a transaction.
5. The database enforces invariants the application cannot be trusted with.
...
10. Loading, error, and empty on every screen.

Plus the stack (and what it's not: "Drizzle ORM, NOT TypeORM", "NestJS on Fastify, NOT Express"), the code layout, a "Don't" list, and the commands.

The "NOT" lines matter more than they look. A model's prior is the average of the internet. Ask for a NestJS validation layer without saying otherwise and you'll get class-validator, because that's what most tutorials use. One line in CLAUDE.md moves the default.

The file also sets the order of authority: the architecture decision records override the rules, which override the product spec. When a tool's advice contradicts a decision record, the decision wins, and the AI has to say so out loud.

2. SKILL.md: instructions that load on demand

You can't put everything in CLAUDE.md; it would be enormous, and most of it irrelevant to any one task. Skills solve that.

A skill is a folder with a SKILL.md inside. The top of the file is a name and a description:

---
name: flow
description: "Use when working on ParkEase — any of its 22 tasks, or any"
  feature, bugfix, refactor, review, UI or motion work...
---

The agent sees only the descriptions until a task matches one; then it loads the whole file. So the description is effectively a trigger, and writing a good one ("use when…", naming the situations) matters more than the body.

ParkEase used two layers: general skills installed for every project (brainstorming, test-driven-development, systematic-debugging, verification-before-completion, the design skills), and project-local skills in .claude/skills/ that only exist inside this repo, like a delivery gate and a curated set of stack-specific skills (Postgres, Redis, Docker, error handling). On top sat flow, a routing skill that says which skills apply at which phase for which part of the stack.

3. Agent files: specialists with one lens

.claude/agents/ holds subagent definitions: a security reviewer, a TypeScript reviewer, a database reviewer, a test-coverage analyzer, and my favourite, a "silent failure hunter" that only looks for swallowed errors, empty catch blocks and lost stack traces. Each is a markdown file with a focused prompt and a restricted toolset.

They turn "review the code" into several narrow reviews. More on how that went, including the bill, later in the series.

Why there's no AGENTS.md

AGENTS.md is becoming a cross-tool convention for exactly what CLAUDE.md does. I considered adding one, and decided against it, in writing, so the AI wouldn't keep re-proposing it:

CLAUDE.md is the single source of truth for this project. A second context file carrying the same governance chain is how the two drift apart, and a partial copy is worse than none.

Two files saying the same thing will eventually say two different things, and an agent that reads the stale one will follow it confidently. If you use several tools, pick one canonical file and point the others at it. Don't maintain two copies of your rules.

What I'd tell you before you start

Treat these files like code. Review changes to them. Delete rules that no longer apply. When the AI makes the same mistake twice, the fix belongs in one of these files, not in your next prompt. A prompt lasts one session; a rule lasts the project.

Next: the skill I typed by hand more than any other, and the one with the funniest name: ponytail, the lazy senior developer who deleted more code than he wrote.

ParkEase is a peer-to-peer parking marketplace for India, built solo with Claude Code.
Code: https://github.com/Deonkar/parkease