Skip to content
Sign in
Artwork for Learn AI in Bits
Learn AI in Bits · August 27 · 5 min

037 - CLAUDE.md vs Skills vs MCP in Claude Code

Claude Code gives developers five different places to put an instruction: a CLAUDE.md file, a Skill, an MCP connection, a Hook, or a permission setting. It is easy to shove everything into CLAUDE.md because it is the most familiar option, and just as easy to end up with a bloated file that Claude follows inconsistently. This episode builds a practical map for deciding which mechanism fits a given piece of information or behavior. The episode covers CLAUDE.md as the home for persistent, project-wide guidance, loaded at the user, project, and local scopes plus nested directories, with a .claude/rules folder for instructions scoped to specific file paths. It explains Skills as reusable procedures stored in a SKILL.md file, where the body only loads into context when the Skill is used or judged relevant, making them a better fit for longer workflows than CLAUDE.md. It walks through MCP, or Model Context Protocol, using a Jira ticket example (looking up and updating issue ENG-4521) to separate a project's ticket-handling instructions, a reusable ticket-preparation workflow, and the underlying connection to Jira itself into their three respective layers. Hooks are covered as automated actions that run at defined points in Claude Code's lifecycle, whether as shell commands, HTTP calls, or prompt-based checks, with a TypeScript formatter Hook as the example. Permissions are explained as the layer that is enforced by the client regardless of what Claude decides, unlike CLAUDE.md's guidance-only instructions, and the episode notes when a PreToolUse Hook is the right tool for a hard restriction. A worked example, a project called Shop, shows all five layers working together: a root CLAUDE.md with TypeScript and testing conventions, a path-scoped backend rule, a review-payment-code Skill, MCP connections to Jira and Postgres, a test-running Hook, and permissions blocking production credentials. The episode closes on why the separation is worth maintaining: CLAUDE.md content loads into every session's context whether it is needed or not, and Anthropic recommends keeping each file under roughly two hundred lines, since longer files consume more context and get followed less reliably. Useful for anyone setting up or maintaining a Claude Code project who wants instructions Claude follows, rather than one oversized file competing with itself. Sources & References How Claude remembers your project, Claude Code docs — https://code.claude.com/docs/en/memory Extend Claude with skills, Claude Code docs — https://code.claude.com/docs/en/skills Connect Claude Code to tools via MCP, Claude Code docs — https://code.claude.com/docs/en/mcp Hooks reference, Claude Code docs — https://code.claude.com/docs/en/hooks Claude Code settings, Claude Code docs — https://code.claude.com/docs/en/settings Voice narration is AI-generated.

0:00-5:05
Play in

transcript

No transcript — this publisher did not publish one.

show notes

Claude Code gives developers five different places to put an instruction: a CLAUDE.md file, a Skill, an MCP connection, a Hook, or a permission setting. It is easy to shove everything into CLAUDE.md because it is the most familiar option, and just as easy to end up with a bloated file that Claude follows inconsistently. This episode builds a practical map for deciding which mechanism fits a given piece of information or behavior.


The episode covers CLAUDE.md as the home for persistent, project-wide guidance, loaded at the user, project, and local scopes plus nested directories, with a .claude/rules folder for instructions scoped to specific file paths. It explains Skills as reusable procedures stored in a SKILL.md file, where the body only loads into context when the Skill is used or judged relevant, making them a better fit for longer workflows than CLAUDE.md. It walks through MCP, or Model Context Protocol, using a Jira ticket example (looking up and updating issue ENG-4521) to separate a project's ticket-handling instructions, a reusable ticket-preparation workflow, and the underlying connection to Jira itself into their three respective layers. Hooks are covered as automated actions that run at defined points in Claude Code's lifecycle, whether as shell commands, HTTP calls, or prompt-based checks, with a TypeScript formatter Hook as the example. Permissions are explained as the layer that is enforced by the client regardless of what Claude decides, unlike CLAUDE.md's guidance-only instructions, and the episode notes when a PreToolUse Hook is the right tool for a hard restriction.


A worked example, a project called Shop, shows all five layers working together: a root CLAUDE.md with TypeScript and testing conventions, a path-scoped backend rule, a review-payment-code Skill, MCP connections to Jira and Postgres, a test-running Hook, and permissions blocking production credentials. The episode closes on why the separation is worth maintaining: CLAUDE.md content loads into every session's context whether it is needed or not, and Anthropic recommends keeping each file under roughly two hundred lines, since longer files consume more context and get followed less reliably.


Useful for anyone setting up or maintaining a Claude Code project who wants instructions Claude follows, rather than one oversized file competing with itself.


Sources & References

How Claude remembers your project, Claude Code docs — https://code.claude.com/docs/en/memory

Extend Claude with skills, Claude Code docs — https://code.claude.com/docs/en/skills

Connect Claude Code to tools via MCP, Claude Code docs — https://code.claude.com/docs/en/mcp

Hooks reference, Claude Code docs — https://code.claude.com/docs/en/hooks

Claude Code settings, Claude Code docs — https://code.claude.com/docs/en/settings


Voice narration is AI-generated.


more episodes

All episodes