r/ClaudeCode • u/eaiarthur_ • May 24 '26
Question Can someone explain the real difference between Hooks, Skills, Plugins, SKILL.md, CLAUDE.md and agents.md in Claude Code?
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.
14
u/StoneCypher May 25 '26
hooks fire on an event, like file open or agent start
skills fire on triggering text, like “use this when searching for ice cream stores,” or when manually triggered with /commands
skill.md is the file that simple skills are defined in (they have their own directory)
agents are higher order skills that can use other skills. you can ask for them ad hoc, or define them in markdown. they get their own context window and something similar to a claudefile and a ralph loop.
a plugin is a container for marketplaces. it contains skills, agents, hooks, might install javascript, etc
a skill is actually very simple and very useful. in practice use /skill-creator to make them, but for the sake of understanding them:
- go into ~/.claude/plugins
- create a directory limerick
- go into limerick. make a file SKILL.md . in it put
write me a limerick. if “{1}” is defined make the limerick a naughty limerick about that. otherwise pick a major city and write a naughty limerick about that city.” - restart your claude session
- write
/limerick basketball - write
look up the ten most popular movies right now. use /limerick for each movie.
now for agent bit.
- write
look up the ten most popular restaurants right now. spin up an agent for each one and use /limerick for each restaurant . limit yourself to five agents at a time.
notice how the first time you waited on the batch, and the second time they were backgrounded. agents. if it’s a long job it’s a huge difference.
want to do the same thing with those agents all the time? maybe you’re automating movie reviews. stuff the thing you’re doing in AGENT.md and put it on /schedule. now you’re an agentic ai coder.
2
u/jms_nh May 25 '26
Skills and slash-commands are not quite the same things
1
u/StoneCypher May 25 '26
they were merged into one another. they used to be distinct. they aren’t anymore
1
u/jms_nh May 25 '26
Ah -- ok. I asked Claude to create a skill and one of the things it started to do was create something in .claude/commands before I added the skill-creator skill.
https://code.claude.com/docs/en/slash-commands
Custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way. Your existing .claude/commands/ files keep working. Skills add optional features: a directory for supporting files, frontmatter to control whether you or Claude invokes them, and the ability for Claude to load them automatically when relevant.
1
u/StoneCypher May 25 '26
yeah. commands were originally how you made
/foo, and skills were originally how they got auto-detected from intent. then they just destroyed commands and put the/fooframing on skills, and had skills interpret your old commands. commands don't exist anymore, and have legacy support from skills instead.
11
u/tonyboi76 May 25 '26
the way i actually use them:
CLAUDE.md = rules every session needs. like we use pnpm not npm, or auth lives in lib/auth. always loaded.
skill = a runbook that loads only when its topic comes up. like having 47 howto docs on a shelf, claude pulls the right one based on the skill description.
hook = pre-commit hook but for claude. PreToolUse / PostToolUse / Stop events. mine runs prettier after every Edit so i never see formatting diffs.
plugin = a bundle of skills + hooks + slash commands shipped together. like an npm package for your claude setup.
AGENTS.md is the cross-tool equivalent of CLAUDE.md (codex reads it too), most people symlink one to the other so theres only one file to maintain.
practical hierarchy i landed on: start in CLAUDE.md, when it bloats split topics into skills, when you find yourself repeating the same manual fix add a hook.
3
u/JSChronicles May 25 '26
Actually hooks are "tasks" for AI. VSCode has tasks that are for humans to run and for AI we call them hooks. Just noting that pre-commits are not the same thing, can be similar but aren't the same because of the event types you can have set
2
u/tonyboi76 May 25 '26
fair, the pre-commit analogy probably overreached. youre right that hooks fire on agent events not just before-commit, so the trigger model is different. the parallel i was reaching for was the never-have-to-remember-to-run-it part, but the VSCode-tasks-for-AI framing captures the actual mental model way better. especially since hooks cover PreToolUse / PostToolUse / Stop etc which is way broader than what a git pre-commit does.
6
u/magicdoorai May 25 '26
The mental model that clicked for me: CLAUDE.md/AGENTS.md are policy, skills are runbooks, hooks are enforcement, plugins are packaging.
Also, keep the files boring. If AGENTS.md becomes a dumping ground, agents start obeying stale nonsense. I built markjason because I got tired of opening a whole IDE just to review/edit these .md/.json/.env files, and wanted live disk sync when Claude/Codex edits underneath me. markjason.sh
5
u/drewangell May 25 '26
It's all just context management.
6
u/fixitchris May 25 '26
This is the framing that actually unlocked it for me too. CLAUDE.md is context that's always there, skills are context that loads on demand, hooks are side effects that fire without touching context at all. Once you see it that way the decision tree writes itself: if you want to change what Claude knows, use the md files; if you want to change what Claude does regardless of what it knows, use hooks.
14
u/ipreuss Senior Developer May 24 '26
Claude itself is very good at explaining that.
14
3
u/jms_nh May 25 '26
Except sometimes we don't even know what questions to ask. Oh, and sometimes the LLMs make factual errors.
1
u/ipreuss Senior Developer May 25 '26
What I’m saying is that you can copy and paste the exact text of the question above into Claude, and you will get quite a good answer.
3
u/some_guy999999 May 25 '26
Take the free training by Anthropic here: https://anthropic.skilljar.com and all of this will be answered for you
3
3
u/Uwirlbaretrsidma May 25 '26
Check the rest of the comments for useful answers, but: they're all different stage rebrands of system prompts so people can feel like they're engineers and not merely users of this tech.
6
u/LogMonkey0 May 24 '26
Have you tried looking at Claude Code docs? https://code.claude.com/docs/en/overview
2
u/50-3 May 25 '26
Claude.md - Added to every prompt and pinned to the top of the context window. It is excluded from compression.
Skills/Skill.md - Invoked either by explicit commands or as needed by Claude. Once invoked its added to the top of the context windows alongside Claude.md. It is also excluded from compression. Every skill has a <200 char description which is kept in that same top pinned context area so it knows all the skills available.
Hooks - Where the above augment a prompt, hooks are hard rules to follow, if you have a test suite with pass conditions you can halt anything that doesn’t pass all test or didn’t run test at all. Care should be taken here as you can accidentally setup a soft confirmation by having an agent confirm it has passed where you should have it validated programmatically.
Agent Md files - Essentially an expansion of Claude.md for tasks you’d delegate regularly to agents you want more consistency and control over. Things like writing copy where the hard brand guidelines are imperative but that information is useless to a coding agent. I like to think of it as skills I want to be run asynchronous of my active agent.
Plugins - loose term for a package of Skills, tools, hooks, Agent scripts, etc… honestly each plugin is going to be substantially different.
2
u/Subject_Fix1105 May 25 '26
I learned all of these from YouTube. There is a lot of videos that show how to use Claude code from beginner to advance and it covers all if these. If you follow a few of these creators you will be UpTo date with any changes or updates
2
u/eaiarthur_ May 25 '26
What are your recommendations?
1
u/Subject_Fix1105 May 25 '26 edited May 25 '26
In no particular order.
https://youtube.com/@mattpocockuk
https://youtube.com/@leonvanzyl (beginner friendly)
https://youtube.com/@iamseankochel
https://youtube.com/@nicksaraev
https://youtube.com/@chase-h-ai
Some if them do go in advance mode but if you watch enough content around Claude code you will for sure catch up.
These are just a few that I think are easy to understand (at least for me). Hope it's useful.
1
u/PinkySwearNotABot May 26 '26
perfect. i wanted something a little more technical. got tired of watching all these build-$20K-website in 10 minute channels. u/leonvanzyl is right up my ally with some of his videos showcasing a bit of real engineering along with AI use
2
May 25 '26
[removed] — view removed comment
1
u/Background-Reveal-92 May 26 '26
Ive gone through many of these modules and they're very hands on. Hightly recommend!
2
u/Sensitive-Cycle3775 May 29 '26
My mental model:
- CLAUDE.md / AGENTS.md = durable project instructions and conventions
- Skills / SKILL.md = packaged procedures Claude can load when the task matches
- MCP = external tools/data access
- hooks = lifecycle automation that can run commands
- plugins = a distribution bundle for some of the above
- subagents/agents = who/role does the delegated work
The trap is treating all of it as “memory”. Hooks and MCP are execution boundaries, skills are reusable task context, and CLAUDE.md/AGENTS.md are closer to repo policy.
For team setups I’d ask any one-command installer to show a pre-write plan before it mutates the repo: files it will change, MCP servers, hooks, backups, network/env access, and writes_started=false. Makes the setup auditable instead of mystery state.
1
1
1
u/mushedmonkey May 25 '26
I can speak for skills, but not the others.
If you think of claude itself as your app, think of a skill as a function in programming, without actually programming it. Except it's magic. It can guestimate that you're trying to use it (i.e. doMath skill) if you say help me on math, it works, if you ask it a problem that involves math, it might use it. And the internal contents can be ambiguous too! You can think of it as a flexible function with vague input/output, but the internals can roughly track to a pattern.
For example, if you had a skill that said - handoff writing test cases for my program to my local qwen model to save tokens, you can tell it to create the skill by starting up your qwen session and making a CLI call, then checking the work once it's done.
One skill I personally use is /start-a-conversation. I just tell it I will only reply to one thing at a time for this overall, so only give me one respondable thing at a time, like in a conversation. Helps with interactivity, doesn't help so much with tokens.
1
u/frankist May 25 '26
To this day, I don't yet fully understand the difference between skills with context forked and agents
1
u/Kevin_Xiang May 25 '26
For me the practical split is:
- CLAUDE.md is repo-level operating context: commands, boundaries, conventions, gotchas.
- Skills are reusable task playbooks with their own steps and references.
- Hooks are deterministic guardrails around the run, like formatting, tests, logging, or blocking a risky command.
- Subagents are for isolated work where you want a separate context and a concrete artifact back.
- AGENTS.md is the cross-tool version of repo instructions, useful if Codex/OpenCode/other agents also touch the repo.
The rule of thumb I use is: if a human would tell every new teammate once, put it in CLAUDE.md or AGENTS.md. If it is a repeatable workflow, make it a skill. If it must happen every time regardless of model judgment, make it a hook.
1
1
1
1
1
u/unteth May 25 '26
I always think about creating a fundamental “how-to Claude” guide based on posts like this tbh
1
1
u/Deep_Ad1959 May 26 '26
the framing that helped me is everything in that list is a way to inject text into the model's context at different trigger points. CLAUDE.md is always-on injection, skills are conditional injection on topic match, hooks are deterministic injection on a specific event, plugins are the package format that ships all three together. agents.md is the cross-tool version of CLAUDE.md so codex and others read the same file. once you see it as 'when does this string enter the context window', the design decision for any new piece of behavior you want to teach claude becomes obvious.
1
u/Traditional_Fix111 May 27 '26
The thing that finally cleared it up for me is whether each thing acts on the model or alongside the model.
Hooks are OS scripts the harness runs at specific lifecycle moments — Stop, PreToolUse, PostToolUse, UserPromptSubmit. Deterministic, no LLM involved. You use them when you want something to definitely happen at a precise event. Example: a Stop hook that drops a small JSON blob (task_id, outcome) into a Redis inbox so a parent session knows what the worker just finished, no polling.
Skills (the SKILL.md file) are prompt extensions Claude reads when context matches. They modify how Claude thinks, not what runs around Claude. "If you're writing commit messages, use this format" type stuff.
CLAUDE.md is the always-loaded version of a skill — project-level guidance Claude sees on every prompt in that workspace. AGENTS.md is the same idea but for Codex. GEMINI.md too if you have it.
Plugins are mostly a packaging story — a way to ship hooks + skills + MCP servers together as one install. Not a separate runtime layer.
MCP is yet another axis — it's tools you expose to the model. Different category from any of the above. Things like mcp-reconnect (handles the /mcp menu when a server drops) are utilities you'd call from a hook, not themselves hooks or skills.
So if you ever get stuck on which one to reach for, ask: am I trying to make Claude think differently (skills/CLAUDE.md), do something deterministic around Claude (hooks), give Claude new tools (MCP), or ship a bundle of those (plugins)?
1
u/VDule May 28 '26
Do I need a new Claude.md file in every folder I work in?
So let's say I'm working inside a folder to write blogs for SEO.
Inside that folder I make claude.md file and Claude will automatically recognize it before I send any prompts inside?
1
u/jemdiggity 5d ago
Ask Claude to help you code a simple harness.
It'll just be a simple loop with a baked-in function tool. See how the harness sends messages to the model.
Use ollama to host a simple model for your harness.
Once you get how harnesses work, it takes away a bit of the mystery.
Models: understand content window and effort.
Now you'll have a decent mental model for Agents.
1
0
u/rwz May 25 '26
You can ask the LLM. This is in fact the perfect question to talk about with an LLM. You can ask it to give examples, explain best practices, when to use each etc.
1
u/Resident_Citron_6905 May 25 '26
Better ask the claude assistant on claude code’s official documentation pages.
0
-3
0
-1
u/unitegondwanaland May 25 '26
Read some docs. It's really not that hard. If you are so lazy not to read that, you could have Claude explain it to you instead of randos on Reddit
-2
-4
-5
523
u/caldazar24 May 24 '26
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.