One team, one set of skills
Most teams get their AI instruction files wrong. They have no shared skills across the team that unify their workflow and make it consistent and predictable.
A CLAUDE.md, an AGENTS.md or a folder of Cursor rules is a set of rules. What’s missing is the checklist.
The pilot’s checklist
Pilots don’t rely on memory. Everyone runs the same checklist, every time.
The checklist came out of a crash. In 1935, the prototype of Boeing’s B-17, then called the Model 299, crashed on a test flight at Wright Field in Dayton, Ohio, killing both pilots. They had forgotten to release the gust locks that hold the controls in place on the ground. Boeing’s management and engineers answered with the pre-flight checklist.
Shared skills are your team’s checklist.
Flying without a shared checklist
Without a shared checklist you get five styles in one repo, unpredictable output, and knowledge that stays in people’s heads. All of that, but really just the need to have to make sure that you do your thing every time.
Someone committed a PR without a good description? No one knows if it was reviewed? Well, time for you to sit and take time making sure it’s good and running your own tools, when someone else could have already done so.
Rules and skills are different things
Rules = always, skills = on demand. Rules load every time. Skills are workflows the agent pulls in for a specific task.
Anthropic’s docs for Claude Code draw the same line: CLAUDE.md sits in context on every turn, while “a skill’s body loads only when it’s used”. They also say when to write one: “when you keep pasting the same instructions, checklist, or multi-step procedure into chat.” AGENTS.md, which over 60,000 open-source projects use, is a rule file too.
Both are guardrails an engineer builds for the AI. The rules say how to behave. The checklist says what to do, in what order, every time.
The three skills on the checklist
The core shared skills were really these three:
/sync-main: a shared skill for merging in main and resolving conflicts in the repo./push-and-pr: a skill that made consistent PRs and messages./review-pr: a final skill that was consistently updated, checking for the things we know need it in our code and repo, so a lot of that review was done before we touched it.
That’s how the side project that replaced our old product in a month worked: we started with skills, rules and good AI dev design, and we all used the same things.
What /review-pr should check
The /review-pr checklist is specific to the repo. It looks for problems that might come up in the domain space, and problems specific to the company.
SOC2 compliant or otherwise? Probably should be reviewing for that. Want to make sure that migrations aren’t out of hand and maybe squashed into one per PR? Add that to review. Want consistent architecture and patterns? Put them in the review skill, as well as other places.
Where the checklist lives
The checklist lives in the repo. It’s checked in like code, reviewed in PRs, and anyone can improve one.
Claude Code supports this directly: project skills live in .claude/skills/ in the repository, and the docs say “commit it so your team gets it too.”
Why rules decay
Rules have a problem the checklist mostly doesn’t: they decay.
I struggle, as many do, with the verbosity of Claude or other coding agents. I tried a lot of different things, from changing settings to installing other skills and heavily updating CLAUDE.md. Short of saying every time I asked for information “make it short and concise, make it bullets under 10 words, etc.”, nothing really worked.
The real issue here is that this kind of small instruction gets lost in context and ignored, especially once it grows. Researchers have measured it. A 2023 paper, “Lost in the Middle”, found that model performance “can degrade significantly when changing the position of relevant information,” and is worst when that information sits in the middle of a long context. Chroma tested 18 models in its Context Rot report and found their “performance grows increasingly unreliable as input length grows.”
I would assume, like many engineers, I don’t like losing all the context I’ve built in a session. That’s half of what makes it feel like coding and makes it a skill. You’re prompting 45 times, not one-shotting “build me a fun mobile app that does blah blah.”
Re-reading the rules mid-flight
Facing the problem of Claude being so damn loquacious, I ended up building a tool to help: personal_stylist. It works by having a Claude hook append the rules to context every so often.
It uses two Claude Code hooks and one rules file, ~/.claude/STYLE.md. A SessionStart hook puts the rules in before the first turn and again after compaction. A UserPromptSubmit hook runs every turn and says them again every 50k tokens of growth. Nothing touches CLAUDE.md. Rules that live there decay. That’s the problem, not the fix.
It has really cut down on the verbosity, though it’s still a lot sometimes.
Where to start tomorrow
Write your three core skills. Keep CLAUDE.md short, and move workflows into skills. Re-inject what matters with hooks like personal_stylist.
Consider all of it, but if you don’t have core skills, make those. The checklist comes first.
The checklist isn’t clever. Predictable beats clever.