AGENTS.md vs Skills vs Hooks vs Prompts
You've learned how to create a good AGENTS.md.
But there's another important question:
Should this instruction even be in AGENTS.md?
Modern coding-agent environments can provide several ways to guide or extend an agent.
Four concepts you'll commonly encounter are:
AGENTS.md
Skills
Hooks
Prompts
They solve different problems.
Understanding those differences prevents your AGENTS.md from becoming the place where everything gets stored.
The Simple Mental Model
Start with this:
AGENTS.md
→ How should the agent generally work in this repository?
Skill
→ How should the agent perform this reusable workflow?
Hook
→ What should automatically happen at a runtime lifecycle event?
Prompt
→ What do I want the agent to do right now?
That's the core distinction.
Let's explore each one.
1. AGENTS.md — Repository Guidance
Use AGENTS.md for persistent instructions that help an agent work correctly inside a repository.
Example:
# Project Guidelines
- Use `pnpm`.
- Keep business logic inside services.
- Add regression tests for bug fixes.
- Do not manually edit files inside `src/generated`.
These aren't instructions for one particular task.
They describe how work should generally happen in the repository.
Think:
Repository conventions
Architecture boundaries
Development commands
Testing expectations
Validation workflow
Important restrictions
These are strong AGENTS.md candidates.
2. Prompt — The Current Task
Suppose you want the agent to:
Add password reset functionality.
That's a task.
It belongs in your prompt.
For example:
Add password reset functionality.
Users should be able to request a reset link from
the login screen.
Use the existing email service.
Add tests for the new flow.
Don't modify AGENTS.md with:
## Current Task
Build password reset functionality.
Why?
Because tomorrow the task will be finished.
Your repository guidance should remain useful after the task ends.
AGENTS.md + Prompt
These two mechanisms naturally work together.
AGENTS.md
- Keep business logic inside services.
- Validate request payloads using Zod.
- Add tests for new API endpoints.
Prompt
Add an API endpoint that allows users to request
a password reset email.
Together:
Prompt
"What should I build?"
+
AGENTS.md
"How should work happen in this repository?"
This is one of the most useful distinctions to remember.
3. Skills — Reusable Workflows
Sometimes you have instructions that shouldn't apply to every repository task.
Instead, they're needed when performing a particular kind of work.
That's a good candidate for a Skill.
A skill can package reusable instructions and supporting resources for a recognizable workflow.
For example:
Review a pull request
Generate a database migration
Prepare a release
Investigate a production incident
Create API documentation
Perform a security review
These aren't necessarily rules that should influence every coding task.
They're workflows that become relevant when needed.
Example Skill
Conceptually, a skill might look like:
skills/
└── review-pr/
├── SKILL.md
├── references/
└── scripts/
And its SKILL.md could describe:
---
name: review-pr
description: Review a pull request for correctness,
security, tests, and maintainability.
---
When reviewing a pull request:
1. Understand the intended change.
2. Inspect the diff.
3. Identify correctness issues.
4. Check relevant tests.
5. Look for security risks.
6. Report findings by severity.
The workflow is reusable.
But it doesn't need to affect every task the agent performs.
AGENTS.md vs Skill
Suppose your repository says:
- Add regression tests for bug fixes.
That's a repository expectation.
Keep it in:
AGENTS.md
Now suppose you have a detailed process:
How to perform a production-readiness review
including:
Architecture review
Security review
Observability checks
Dependency checks
Performance checks
Deployment review
Report template
That could become a:
Skill
instead of adding 100 lines to AGENTS.md.
Another Example
Imagine you regularly ask your coding agent:
Create a database migration.
Your repository might contain:
# AGENTS.md
- Create migrations for database schema changes.
- Never edit migrations that have already been applied.
Those are persistent repository rules.
But a reusable migration workflow might contain:
Inspect schema
↓
Create migration
↓
Check backward compatibility
↓
Run migration locally
↓
Run database tests
↓
Generate migration summary
That workflow may be better represented as a Skill.
4. Hooks — Event-Driven Automation
Hooks solve a different problem.
They allow something to happen automatically when a supported lifecycle event occurs.
Think:
Event happens
↓
Run configured action
This is fundamentally different from simply giving the model instructions.
Example
Imagine you want formatting or validation to run automatically at a supported point in an agent workflow.
Conceptually:
Agent reaches lifecycle event
↓
Hook executes
↓
Script / command runs
The important distinction is:
AGENTS.md
→ tells the agent what it should do
Hook
→ runtime automatically invokes configured behavior
Hooks therefore belong to automation, not general repository explanation.
Exact hook events, configuration, permissions, and availability depend on the agent runtime you're using.
Don't Confuse Instructions With Enforcement
Suppose you write:
- Format modified files before completing changes.
That's an instruction.
The agent is expected to follow it.
But if your runtime supports an appropriate hook, you might configure formatting to execute automatically.
Conceptually:
Instruction
"Please run formatting."
vs
Automation
"Formatting runs automatically at this event."
These aren't equivalent mechanisms.
5. What About Tools?
There's another concept worth distinguishing.
A tool gives the agent a capability.
For example:
Read GitHub issues
Query a database
Search documentation
Send a message
Execute a command
Access an external API
Think:
Tool
→ What can the agent DO?
Skill
→ How should it perform a reusable workflow?
AGENTS.md
→ How should it work in this repository?
Prompt
→ What should it do now?
Hook
→ What automatically happens at a lifecycle event?
This distinction becomes increasingly useful as you build more advanced agent workflows.
6. What About MCP?
You may also encounter MCP — Model Context Protocol.
MCP can expose tools and resources from external systems to an agent.
For example:
Coding Agent
↓
MCP Server
↓
GitHub
Database
Documentation
Internal service
Other systems
MCP isn't a replacement for AGENTS.md.
They solve different problems.
For example:
MCP server
→ gives the agent access to project-management data
Skill
→ explains how to turn that data into a release report
AGENTS.md
→ defines repository development conventions
Prompt
→ asks for this week's release report
These mechanisms can work together.
7. Choosing the Right Mechanism
Let's classify some examples.
Example A
Use pnpm for this repository.
Use:
AGENTS.md
Why?
It's a persistent repository convention.
Example B
Fix the mobile navigation bug.
Use:
Prompt
Why?
It's today's task.
Example C
Whenever performing a production-readiness review, inspect security, observability, architecture, tests, dependencies, and deployment configuration.
Use:
Skill
Why?
It's a reusable workflow invoked for a specific kind of task.
Example D
Automatically execute a configured validation command when a supported lifecycle event occurs.
Potentially use:
Hook
Why?
You want runtime-triggered automation rather than merely an instruction.
Example E
Allow the agent to retrieve issues from an external project-management system.
Use:
Tool / MCP
Why?
The agent needs a capability and external data access.
8. One Task Can Use Several Mechanisms
These concepts aren't competitors.
They often work together.
Imagine:
Prepare a release.
AGENTS.md
Provides repository rules:
- Use `pnpm`.
- Never manually modify generated files.
- Run relevant tests before completing changes.
Skill
Provides the release workflow:
Review changes
Run release validation
Generate changelog
Check migration requirements
Prepare release summary
Tools
Provide capabilities:
Git
GitHub
CI
Issue tracker
Hooks
Could automate supported lifecycle actions.
Prompt
Starts the specific task:
Prepare version 2.4.0 for release.
Together:
Prompt
↓
Reusable Skill
↓
Repository guidance
↓
Tools
↓
Optional automated Hooks
Different layers solve different problems.
9. The "Should This Be in AGENTS.md?" Test
When you're about to add something to AGENTS.md, ask:
Is this about the current task?
Yes
→ Prompt
Is this a persistent repository convention?
Yes
→ AGENTS.md
Is this a reusable workflow needed only for certain tasks?
Yes
→ Consider a Skill
Should something execute automatically at a runtime event?
Yes
→ Consider a Hook
Does the agent need a new capability or external system?
Yes
→ Tool / MCP
This simple decision tree prevents a lot of instruction clutter.
10. A Common Anti-Pattern
Imagine this AGENTS.md:
# Instructions
Use pnpm.
When reviewing PRs:
1. Inspect every changed file.
2. Categorize findings.
3. Generate a review report.
4. Use this exact report template...
Current task:
Fix authentication.
After editing files, automatically execute this script...
Here are instructions for querying Jira...
Here are 200 lines describing our release workflow...
Several different concerns have been mixed together.
A cleaner setup could be:
AGENTS.md
├── Repository conventions
Skills
├── PR review workflow
└── Release workflow
Hooks
└── Supported automated lifecycle actions
Tools / MCP
└── External system access
Prompt
└── Current authentication task
Each mechanism has a clear responsibility.
11. Avoid Context Bloat
There's a deeper reason to separate these mechanisms.
If every possible workflow is permanently loaded into repository instructions, the agent may receive lots of irrelevant context.
Imagine:
Current task:
Fix one CSS issue.
Context:
Release process
Database migration workflow
Security review process
PR review instructions
Documentation workflow
Deployment procedure
Incident-response procedure
Most of that doesn't help.
A better design provides relevant guidance when it's actually needed.
Think:
Persistent essentials
→ AGENTS.md
Reusable task-specific guidance
→ Skills
Current objective
→ Prompt
This keeps context focused.
12. Don't Create a Skill for Everything Either
The opposite mistake is turning every small instruction into a Skill.
You probably don't need:
use-pnpm skill
write-typescript skill
run-tests skill
use-tailwind skill
if these are simply normal repository conventions.
Keep the system simple.
Start with:
AGENTS.md
+
Prompt
Introduce Skills when you have genuinely reusable workflows.
Introduce Hooks when automatic lifecycle behavior provides real value.
Introduce external tools when the agent actually needs additional capabilities.
13. Codex-Specific Perspective
In Codex, these concepts can work together, but they remain different layers.
Codex can use repository guidance such as AGENTS.md.
Codex also supports reusable Skills containing a SKILL.md plus optional supporting resources such as:
references/
scripts/
assets/
Skills are useful when a workflow should be discoverable and reusable without permanently placing all of its instructions into repository context.
Codex environments can also support hooks that run configured commands at supported lifecycle points.
These are Codex capabilities, not requirements of the general AGENTS.md convention.
Other coding agents may provide similar concepts using different names, formats, or behavior.
14. Decision Table
| Need | Best starting point |
|---|---|
| Repository-wide coding convention | AGENTS.md |
| Directory-specific convention | Nested AGENTS.md |
| Current coding task | Prompt |
| Repeatable specialized workflow | Skill |
| Automatic lifecycle action | Hook |
| External capability | Tool / MCP |
| Mechanical formatting | Formatter |
| Static code rule | Linter |
| Type correctness | Type checker |
| Behavioral correctness | Tests |
The phrase starting point matters.
Real systems sometimes combine several mechanisms.
15. Example: Building an API Endpoint
Suppose the task is:
Add an endpoint for cancelling subscriptions.
Prompt
Add an endpoint that allows authenticated users
to cancel their active subscription.
AGENTS.md
- Validate request payloads using Zod.
- Keep business logic inside services.
- Access the database through repositories.
- Add integration tests for new endpoints.
Skill
Maybe your organization has an:
API security review
skill that can be invoked when performing a security review.
Tools
The agent may use:
Shell
Git
Documentation search
Hook
Your runtime might automatically run an approved validation action at an appropriate lifecycle event.
Each mechanism has a different responsibility.
16. Example: Production Readiness Review
Suppose you repeatedly perform:
Architecture
Security
Code quality
Testing
Logging
Monitoring
Error handling
Performance
Deployment
Don't necessarily paste the entire review process into every repository's AGENTS.md.
Instead:
AGENTS.md
- Follow the repository architecture.
- Run relevant validation before completing changes.
Production Readiness Skill
Inspect architecture
↓
Inspect security
↓
Inspect tests
↓
Inspect observability
↓
Inspect deployment
↓
Produce structured report
Prompt
Run a production-readiness review on this repository.
Now the workflow is reusable across projects.
17. The Bigger Picture
As coding-agent setups mature, think in layers:
CURRENT GOAL
Prompt
↓
REUSABLE WORKFLOW
Skill
↓
REPOSITORY GUIDANCE
AGENTS.md
↓
CAPABILITIES
Tools / MCP
↓
AUTOMATIC LIFECYCLE
Hooks
This isn't a strict execution order.
It's a mental model for understanding responsibilities.
Quick Decision Exercise
Where would you put each instruction?
1
Use pnpm throughout this monorepo.
Answer: AGENTS.md
2
Add dark mode to the settings page.
Answer: Prompt
3
Follow our 12-step pull-request review process whenever performing a formal PR review.
Answer: Skill
4
Run an approved script automatically at a configured lifecycle event.
Answer: Hook
5
Retrieve issue details from our project-management platform.
Answer: Tool / MCP
6
Never manually modify generated API clients.
Answer: AGENTS.md
7
Fix issue #482.
Answer: Prompt
Final Checklist
Before adding guidance, ask:
Is it persistent?
Is it repository-specific?
Is it task-specific?
Is it a reusable workflow?
Does it require automatic execution?
Does it require an external capability?
Can an existing development tool enforce it better?
Then choose the simplest mechanism that fits.
Key Takeaway
AGENTS.md is important.
But a mature coding-agent setup doesn't put everything inside it.
Remember:
AGENTS.md
→ Persistent repository guidance
Skill
→ Reusable specialized workflow
Hook
→ Runtime-triggered automation
Prompt
→ Current task
Tool / MCP
→ Capability and external access
Use each mechanism for the job it handles best.
The goal isn't to build the most complicated agent configuration.
The goal is to give the agent:
the right instruction, at the right scope, at the right time.
Course Complete
You now understand:
- What
AGENTS.mdis. - How instruction discovery and scope work.
- What belongs in it.
- What should stay out.
- How to write effective instructions.
- How to design nested instruction scopes.
- How to diagnose conflicts and common mistakes.
- How real-world projects structure their instructions.
- How
AGENTS.mdfits alongside Skills, Hooks, Prompts, and Tools.
But knowing the concepts isn't enough.
The next section is Samples.
There you'll study real AGENTS.md configurations across different stacks, architectures, and development scenarios.
After that, the Workbook will give you broken and incomplete instruction files to fix yourself.