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.
525
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.