This one file is the difference between an AI you can trust to run real work and one you babysit line by line. Here is my actual file, what I deleted, and the rule that keeps it working.
I’m starting adding lots of file reference in my ClAUDE.md to provide context to Claude and let it decide when to load a md file.
What’s your take on delegating project context discovery to a skill? The skill could be one line like “read context.md for information about X, Y, Z,…”
Either you link to context.md by reference or you ship it with the skill.
The idea being you can easily maintain context, let Claude decide what to load, and save precious tokens in claude.md.
Good instinct, and yes, I lean toward the skill route for most of it.
The mental model I use: CLAUDE.md always loads in full, every session. So it should only hold what's true 100% of the time. Rules, conventions, non-negotiables. The stuff that's only relevant when you're doing a specific task doesn't belong there, it just taxes every run.
A skill fixes that because of how it loads. Only the name and description sit in context up front. The body (and anything it references) loads when the description matches what you're doing. So the description is really a router, "use this when the task is X." That's the piece a bare file reference in CLAUDE.md doesn't give you. A @context.md link still needs Claude to decide to open it with no strong signal for when.
On ship-vs-link: I ship context.md with the skill. It versions together, moves together, and you're never debugging a skill that points at a file that drifted. Link by reference only when the same context is shared across several skills and you want one source of truth.
Net: CLAUDE.md for always-on rules, skills for task-scoped context, ship the context file inside the skill. You keep CLAUDE.md lean and let the description do the "what to load" work for you.
100%. I am also leaning toward less global unless truly used everywhere. Right now only the voice definition is global because you tend to use it in most projects as a business user (email, proposals, social media, etc).
Voice is the perfect thing to keep global, because it's the cleanest test for what belongs there: is this about who you are, or what you're doing right now? Identity goes global. Task goes local. Voice is pure identity, so it earns the slot in every project. Most other things people cram into global fail that test the moment you ask it.
I’m starting adding lots of file reference in my ClAUDE.md to provide context to Claude and let it decide when to load a md file.
What’s your take on delegating project context discovery to a skill? The skill could be one line like “read context.md for information about X, Y, Z,…”
Either you link to context.md by reference or you ship it with the skill.
The idea being you can easily maintain context, let Claude decide what to load, and save precious tokens in claude.md.
Appreciate your thoughts on this one!
Good instinct, and yes, I lean toward the skill route for most of it.
The mental model I use: CLAUDE.md always loads in full, every session. So it should only hold what's true 100% of the time. Rules, conventions, non-negotiables. The stuff that's only relevant when you're doing a specific task doesn't belong there, it just taxes every run.
A skill fixes that because of how it loads. Only the name and description sit in context up front. The body (and anything it references) loads when the description matches what you're doing. So the description is really a router, "use this when the task is X." That's the piece a bare file reference in CLAUDE.md doesn't give you. A @context.md link still needs Claude to decide to open it with no strong signal for when.
On ship-vs-link: I ship context.md with the skill. It versions together, moves together, and you're never debugging a skill that points at a file that drifted. Link by reference only when the same context is shared across several skills and you want one source of truth.
Net: CLAUDE.md for always-on rules, skills for task-scoped context, ship the context file inside the skill. You keep CLAUDE.md lean and let the description do the "what to load" work for you.
100%. I am also leaning toward less global unless truly used everywhere. Right now only the voice definition is global because you tend to use it in most projects as a business user (email, proposals, social media, etc).
Voice is the perfect thing to keep global, because it's the cleanest test for what belongs there: is this about who you are, or what you're doing right now? Identity goes global. Task goes local. Voice is pure identity, so it earns the slot in every project. Most other things people cram into global fail that test the moment you ask it.