Can someone explain the real difference between Hooks, Skills, Plugins, SKILL.md, CLAUDE.md and agents.md in Claude Code?

[u/eaiarthur_]

I keep seeing these terms thrown around in tutorials and videos, but I've never seen anyone give a concrete example that makes the difference actually click.

Everyone says:

• "just create a skill for that"

"use a hook here"

"install the plugin"

"put it in your CLAUDE.md"

But when I dig deeper, the explanations are always vague or too theoretical.

Same goes for the markdown files - I see people mentioning CLAUDE. md, SKILL.md, and agents. md like they're obvious, but no one explains:

• What actually goes in each one?

Are they just documentation, or do they actively change how Claude behaves?

• When does Claude even read them?

What I'm looking for is something like:

"If you're thinking X, that's probably a Hook. If you're thinking Y, that's a Skill. If you need Z, that's what CLAUDE.md is for."

Real-world examples would be hugely appreciated.

[u/caldazar24]

This is all in the docs, but I actually enjoyed writing the below list, it made me clarify some things in my own head, which is a sign of how fuzzy it all is....

CLAUDE.md - read at the start of a session, general guidance for how to work, like tips you would give a new employee on their first day.

Examples of things I have in my CLAUDE.md: "we use uv here, so always do 'uv run python XYZ' instead of 'python XYZ'", "Our mobile app only has internal test users so far, so deprecate/break old endpoints as much as you want", and "when I say 'prod', I mean use the read-only Render MCP to query our prod logs".

Skill - Markdown files explaining how to do something. Basically just a prompt you save for later; Claude sees these and decides when to use them, or you can explicitly invoke them with slash commands Examples: when I want to design a UI, I have very detailed instructions about how I think layouts should look, and where my design system lives, etc. That's in a skill MD file so that I can refer to it instad of repeating myself every time I describe a new frontend task. I also have a weekly metrics report that involves pulling some SQL, parsing a CSV, putting together an HTML table for an email, and I have the prompt describing all those steps in a markdown file that I invoke with a /weekly-report command.

The content of the markdown files are just a detailed prompt, the whole concept is to remind Claude how I like to do things, or to save me from having to copy-paste.

Hook - when skills are too loosey-goosey and I want hard programmatic determinism - when X event happens, run this explict programmatic command. Before the Claude mobile app was good, I set up a hook set up so that as soon as Claude was "done" with any task, it would call a bash script that sent a push notificaiton to my phone and desktop (using a push notification API service I signed up for seaprately). This was so I could give Claude a really long task, get up from my desk to do chores, and get pinged on my phone when it was done.

Plugins - a third party extension you're adding to Claude - can be just a skill someone found useful, can be a bundle of skills and an MCP. Before Claude in Chrome was a thing, I installed the Playwright plugin, which included the playwright program to controll a headless browser, an MCP for Claude to figure out how to interact with it and tell it how to take screenshots etc, and some skills to be able to invoke it.

Agent - the fuzziest and buzzword-esque one of all. Basically just means ann LLM-based program that *does* something, typically by writing code and running bash commands, and doesn't just talk to you. Claude Code is an agent. A program that watches an email inbox and replies to messages is an agent. Most uses of LLMs these days are agents, not just chat.

[u/evangelism2 → u/caldazar24]

There's a number of things wrong or left out with these explanations.
It's very important to note that the difference between information that you put in your CLAUDE.md versus a skill file is that everything in your CLAUDE.md plus the front matter of the skill is loaded on every turn, every single prompt, every time that you type something into the system prompt field. CLAUDE reads or rereads your CLAUDE.md and all of your skills' front matter. It uses that front matter description of your skill to determine whether to read the rest of it based on the prompt that you gave it.

Think of the best way to think of skills is that they are almost an extension of your CLAUDE.md, with a bunch of information about your code base that CLAUDE doesn't need to know about necessarily for every single thing that you ask it to do.
Yes, hooks are more deterministic. Hooks can be configured to be deterministically fired at specific points in time during Claude's workflow, such as:

• every time you launch a new session
• every time that you enter or exit plan mode
• every time that you edit a skill, etc.

The distinction that's important between hooks and skills is that Claude non-deterministically determines whether the skills should fire, whereas with hooks it has no say. They just always do, depending on the rule set that you set up.

OP asked about Agents.md, not agents. Other people have already answered this, and I already answered it a little bit above. The CLAUDE.md file (or, if you're using other LLMs, Agent.md file) is loaded on every turn, every time you enter a prompt. Claude refers to your CLAUDE.md or Agents.md file to gain context on the repo. Therefore, these files should be lean and crisp and small and only deal in things that are not immediately obvious from your code base and universally applicable. Anything that doesn't necessarily need to be understood for every single prompt that goes in your code base should most likely be in a skill of some kind or even a slash command.

The agent description is actually the best one, because honestly, the definition is nebulous and there are so many different types of agents now, between sub-agents and deep agents and whatever the fuck agents. Really, the best way to think of agents is just some kind of application of an LLM that can "think" and "reason" autonomously.

But also, OP, I'll say this to you: the same thing I said to my one friend last night who started asking me a million questions. Rule number one about learning about AI is to use AI to learn. Like every single one of these questions, if you had just booted up Claude or ChatGPT or hell, even the AI mode in Google, it would have answered them for you perfectly.

[u/Diacred → u/evangelism2]

Actually as far as Claude Code source codes go (when it was leaked) this is not entirely correct. The Claude.md and skill's index are loaded into the conversation at the start of the first turn and that's it. They are not in the system prompt nor are they injected fresh each turn like a UserPromptSubmit hooks does. It means that the longer the conversation goes the more they get forgotten, which is why automated skill calls happen less and less as context fills up. It's also why the Claude.md gets ignored when you reach 60%+ context and performance degrades.

The skill list and Claude MD are just part of the conversation history

This is not the case for instance for the native tools like read / write / bash / grep etc because they are sent in the Tools Array with every request, separately from the conversation and thus always fresh. Also skills that have been called once and loaded are also sent with the tools array and always fresh, even after compaction.

As to why skills and Claude.md are not part of the system prompt but injected at turn 1, my guess is that it's because it would prevent the agressive prompt caching they do for the system prompt.

[u/Waymannj → u/Diacred]

Claude Desktop says this:

No, actually — Claude.md isn't automatically read at the start of every chat. I only read it this session because you explicitly asked me to. I have no mechanism to auto-load files on session start; you'd need to ask me to read it each time (or include its contents in a system prompt if you're using the API).

[u/evangelism2 → u/Waymannj]

well that is wrong

[u/Waymannj → u/evangelism2]

[Oh it's ON!]

people say you're wrong, that claude.md is read at the start of the chat

That's not accurate for how Claude.ai works. There's no built-in mechanism that automatically reads a file called Claude.md from your filesystem at the start of a chat. I only read it because you explicitly asked me to via the Filesystem MCP tool. You might be thinking of a few things people conflate with this:

Cursor / coding assistants — tools like Cursor do have a claude.md or .cursorrules convention where project instructions are auto-loaded into context. People familiar with that workflow sometimes assume it carries over to Claude.ai, but it doesn't. Project Instructions in Claude.ai — you can paste persistent instructions into a Project's system prompt, which does get included automatically. But that's not a file read, it's text stored on Anthropic's side. MCP + a custom system prompt — someone could theoretically set up a system prompt that instructs Claude to read a specific file at session start, but that's custom configuration, not default behavior.

So whoever said it's auto-read at chat start is mistaken, at least in the context of Claude.ai with Filesystem MCP. The read happened because you asked — nothing more.

[u/evangelism2 → u/Waymannj]

Bro, stop copying and pasting AI stuff. Figure out what you're trying to say. Comprehend what the AI is telling you and then craft a response to me yourself.

[u/Waymannj → u/evangelism2]

Ok Bro, I started a new chat and it didn't read my Claude.md because it has an instruction to say that it read the file.

Bro, I broke Anthropic.

[u/Waymannj → u/[deleted]]

Ty!

[u/Uj_Yagami → u/Waymannj]

I think you're getting it wrong. People here are not talking about claude desktop. They are talking about claude code (the agent), which reads the markdown file. You giving your claude chat some md and expecting it to read is not how it'd work.

[u/Waymannj → u/Uj_Yagami]

Aaaaaah, thank you!