Claude Code Cheat Sheet: Hooks, Skills, Plugins, CLAUDE.md, SKILL.md and AGENTS.md Explained

If you spend any serious time with Claude Code, you will quickly collide with a wall of overloaded terms: hooks, skills, plugins, CLAUDE.md, SKILL.md, AGENTS.md and subagents. Most tutorials drop these names into example READMEs without ever explaining how the pieces fit together - or, more importantly, when not to use each one.

I have been integrating Claude Code into real production workflows across PHP, Symfony and TypeScript codebases since the early access phase. The patterns below are not abstract - they are the same separations I rely on when I onboard a team to Claude Code, or when I review a setup that has degenerated into a single 800-line CLAUDE.md that nobody dares to touch.

When should I use a hook? When should I create a skill? What belongs into CLAUDE.md? And what is AGENTS.md actually for?

This article gives you the mental model I use, plus a compact cheat sheet you can keep next to your editor while you structure a project.

The short version

Before we go deep, here is the one-screen overview. If you only remember this table, you will already avoid 80% of the misuse I see in the wild.

1. What is CLAUDE.md?

CLAUDE.md is the project instruction file for Claude Code. Think of it as the onboarding document Claude reads on every session that starts inside your repository. It is the closest thing Claude Code has to a "system prompt" that you, as a maintainer, fully control.

It should contain stable, project-level information that Claude needs again and again:

• Project architecture and layering rules
• Important commands (test, lint, format, build)
• Testing conventions and how to run a single test
• Coding conventions (naming, structure, what to inject vs. instantiate)
• Framework-specific rules (e.g. "no ORM, use DBAL only")
• Things Claude should avoid (e.g. "do not introduce new global state")

Example CLAUDE.md

# Project Instructions

This is a Symfony application using PHP 8.4.

## Commands

Run tests with:

composer test

Run static analysis with:

composer phpstan

## Coding Rules

- Prefer constructor injection.
- Do not use reflection in tests unless absolutely necessary.
- Follow Symfony service conventions.
- Keep controllers thin.
- Put business logic into services.

## Important

Before changing database-related code, inspect existing migrations and entities.

A good CLAUDE.md is not a wiki. The most common failure mode I see is teams copying their full developer handbook into it. That works for a week and then becomes noise: Claude has to wade through 200 lines of historical context to find the rule that actually matters for the current task. Keep it lean. Move the rest into skills.

2. What is AGENTS.md?

AGENTS.md is similar in spirit to CLAUDE.md, but it is intended to be tool-agnostic. The convention has emerged across multiple AI coding tools as a shared interface, so that a single file can serve Claude Code, Codex, Cursor and other coding agents at the same time.

The pragmatic setup looks like this:

CLAUDE.md
AGENTS.md

And inside CLAUDE.md you simply reference AGENTS.md:

# Claude Instructions

Read @AGENTS.md for the shared project instructions.

This keeps your setup maintainable. Instead of duplicating the same rules into per-tool files - and inevitably letting them drift - you centralise the truth in one place that every agent reads.

When to use AGENTS.md

• Your team uses more than one AI coding tool.
• You want one shared source of truth for project rules.
• You do not want to maintain parallel instruction files for every agent.
• You want humans and AI tools to read the same onboarding guidance.

If you only ever use Claude Code, AGENTS.md is overhead. Skip it. CLAUDE.md alone is enough.

3. What is a Skill?

A skill is a reusable, task-specific workflow. While CLAUDE.md describes the project, a skill describes how to do a certain kind of work. The distinction matters more than it sounds, because it is the line that separates a tidy setup from a CLAUDE.md that quietly grows into a 600-line wall of text.

Use a skill the moment you catch yourself repeating instructions like:

• "When writing this kind of ticket, use this structure."
• "When reviewing this kind of code, check these things."
• "When generating this report, follow these steps."
• "When creating this kind of document, use this format."

Example skill: Pull Request Review

# Pull Request Review Skill

Use this skill when reviewing pull requests.

## Goal

Review the code for correctness, maintainability, security and consistency with project conventions.

## Steps

1. Identify the purpose of the change.
2. Check whether the implementation matches the stated goal.
3. Look for edge cases.
4. Check naming, structure and readability.
5. Check test coverage.
6. Mention blocking issues first.
7. Separate required changes from optional suggestions.

## Output Format

- Summary
- Blocking issues
- Non-blocking suggestions
- Test coverage notes
- Final recommendation

The critical difference:

CLAUDE.md is about the project. A skill is about a repeatable task.

4. What is SKILL.md?

SKILL.md is the instruction file that describes a single skill. It is to a skill what CLAUDE.md is to a project: a focused, declarative entry point.

A good SKILL.md answers exactly five questions:

• What is this skill for?
• When should it be used?
• What steps should be followed?
• What should the output look like?
• What should the agent avoid?

Treat SKILL.md as operational guidance, not documentation. The test is simple: if Claude reads this file cold and still cannot perform the task to your standard, the file is incomplete.

5. What is a Hook?

A hook is event-driven automation. Use a hook when something should happen automatically, before or after a specific event - independent of whether Claude "remembers" to do it.

Examples

• Run a formatter after Claude edits a file.
• Run tests after code changes.
• Block dangerous shell commands.
• Validate generated files before accepting them.
• Log tool usage to a central audit trail.

A clean mental separation:

A skill tells Claude how to do something. A hook automatically does something when an event happens.

Hook example

Imagine Claude modifies PHP files. You may want a hook that runs automatically:

composer cs-fix
composer test

That is not a skill. Claude does not need to "learn" how to format code. The action should simply happen at the right time, enforced by the environment - not requested politely by an instruction file. This is the single biggest leverage point most teams miss: anything you find yourself reminding Claude to do "after every change" belongs in a hook.

6. What is a Plugin?

A plugin is an installable extension or bundle of functionality. It is broader than a skill or a hook, because it can package both - together with templates, commands or external integrations.

Compared to hooks and skills:

• A skill defines task knowledge.
• A hook defines event-based automation.
• A plugin extends the environment itself with packaged functionality.

Use a plugin when you want to share a capability across multiple projects or teams, and when the capability is too large to live as a single instruction file.

7. What is a Subagent?

A subagent is a delegated AI worker with its own task and its own context window. This is useful when a task can be cleanly separated from the main conversation - either because it is large, because it should not pollute the main context, or because you want multiple checks to run in parallel.

Examples

• One subagent reviews security risks.
• Another subagent inspects test coverage.
• Another subagent summarises a large file.
• Another subagent compares two implementation approaches.

The difference between a skill and a subagent:

A skill is reusable knowledge. A subagent is delegated execution.

In practice, subagents pair extremely well with skills: the parent agent decides that a task should be delegated, the subagent picks up a skill that defines how the task is done. This is how you scale a Claude Code setup beyond a single conversation without losing structure.

The practical decision guide

When a teammate asks me "should this be a skill or a hook?", the answer almost always falls out of one of the six checklists below. Run through them in order.

Use CLAUDE.md when...

• The instruction applies to the whole project.
• Claude should know it whenever working in this repository.
• It describes architecture, commands or conventions.

Use AGENTS.md when...

• The instruction should be shared across different AI coding tools.
• You want one common source of truth.
• You do not want to duplicate project rules.

Use a Skill when...

• You repeat the same kind of task often.
• The task has a preferred process.
• The output should follow a specific structure.

Use a Hook when...

• Something should happen automatically.
• The action is triggered by an event.
• You want enforcement, not advice.

Use a Plugin when...

• You want to install reusable functionality.
• The capability is bigger than one instruction file.
• You want to package behaviour for reuse across projects.

Use a Subagent when...

• The task can be delegated.
• You want independent analysis.
• You want to keep the main context clean.
• You want multiple specialised checks in parallel.

A clean project setup

Putting it all together, this is the layout I use as a starting point on real projects:

.
├── CLAUDE.md
├── AGENTS.md
├── skills
│   ├── pr-review
│   │   └── SKILL.md
│   ├── ticket-writing
│   │   └── SKILL.md
│   └── release-notes
│       └── SKILL.md
└── hooks
    ├── after-edit.sh
    └── before-command.sh

In this setup:

• CLAUDE.md is the Claude Code entry point.
• AGENTS.md contains shared repo rules.
• skills/ contains reusable task workflows, one folder per skill.
• hooks/ contains automation triggered by events.

Subagents and plugins do not need their own folder in most projects. They are configured in Claude Code itself and can reach into the skills directory when they need a known workflow.

Final mental model

CLAUDE.md  = How Claude should behave in this project
AGENTS.md  = Shared instructions for AI coding agents
SKILL.md   = How to perform a specific repeatable task
Hook       = When X happens, automatically do Y
Plugin     = Installable extension or capability bundle
Subagent   = Delegate a focused task to another AI worker

The mistake most teams make is to dump everything into a single giant instruction file. That works for a week. It collapses the moment a second contributor joins, or the moment you try to reuse a workflow in a second repository.

A better approach is to separate the four concerns explicitly: stable project knowledge in CLAUDE.md, reusable workflows in skills, automation in hooks, delegation through subagents - and use plugins only when a capability really wants to live outside any single project.

That way, Claude gets the right context at the right time, your instruction files stay small enough to actually read, and the setup keeps working as your codebase grows.