The AI Coding Customization Stack: What Goes in AGENTS.md, Skills, MCP, Subagents, and Hooks

AI coding tools used to feel simple. You opened a chat box, pasted a prompt, and hoped the model did not invent a package that last existed in 2019.

Now the setup has layers: AGENTS.md, CLAUDE.md, Cursor rules, Copilot instructions, skills, MCP servers, custom subagents, hooks, permissions, sandboxing, project memories, and whatever your editor shipped last Tuesday.

That is useful, but it also creates a new problem. People keep putting the wrong thing in the wrong layer.

They put stable project facts in a one-off prompt. They put reusable workflows inside a 900-line CLAUDE.md. They use MCP when a Markdown file would work. They create five subagents for a CSS change. Then they wonder why the AI coding workflow feels heavier than the app they are trying to build.

Here is the short version:

The trick is not to use every layer. The trick is to use the smallest layer that solves the actual problem.

The Short Version: What Goes Where?

Use this as the decision guide before you add another file, rule, server, or agent.

Layer	Use it for	Do not use it for	Example
Repo instruction files	Stable project context, commands, conventions, safety notes	Long reusable tutorials or unrelated personal preferences	AGENTS.md, CLAUDE.md, repo-level instructions
Tool-specific rules	Behavior that only matters inside one tool	Universal project facts that should travel with the repo	Cursor rules, Copilot instructions, Claude-specific preferences
Skills	Repeatable workflows you use across projects	One-off facts about one repo	Code review checklist, deployment review, SEO draft review
MCP servers	External tools, data, APIs, docs, databases, issue trackers	Static instructions or vibes	GitHub issues, docs lookup, browser automation, database inspection
Subagents	Specialized roles or independent review	Every small task	Researcher, security reviewer, QA tester, technical editor
Hooks, permissions, sandboxing	Hard safety boundaries and approval rules	Teaching the agent what your app does	Block dangerous commands, require approval before deploys

If you only remember one thing, make it this:

Start With Repo Instructions

For most AI coding projects, the first useful layer is boring: a project instruction file.

That might be AGENTS.md, CLAUDE.md, Cursor project rules, Copilot instructions, or another format your tool supports. The filename matters less than the job it performs.

A repo instruction file should answer the questions the agent keeps asking or guessing:

• What is this project?
• What stack does it use?
• How do you install dependencies?
• How do you run tests, lint, type checks, and builds?
• Which folders matter?
• Which files are generated and should not be edited by hand?
• What style or architecture rules matter?
• What counts as done?
• What actions require approval?

This is where stable project knowledge belongs.

For example, if your app is a Next.js dashboard deployed on Vercel with Supabase auth, the agent should not rediscover that every session. Put the basics in the repo:

# Project instructions

This is a Next.js app deployed on Vercel. Supabase handles auth and database access.

Verify changes with:

- npm run typecheck
- npm run lint
- npm run build

Do not edit generated files in `src/generated/`.
Do not expose Supabase service role keys to browser code.
Ask before changing auth, database policies, payments, or deployment settings.

That kind of file saves time because it prevents repeated steering. It also reduces the number of quiet, confident mistakes an AI coding agent can make before you notice.

If you want the hands-on version, use the VibeCodeSource AGENTS.md template for AI coding tools. If you are still choosing between CLAUDE.md, AGENTS.md, and Cursor rules, read the guide to CLAUDE.md, AGENTS.md, and Cursor rules.

This article is about the layer above that: deciding when repo instructions are enough and when you need something else.

Use Tool Rules for Tool-Specific Behavior

Tool rules are useful, but they are easy to abuse.

Cursor rules, Claude Code memory files, Copilot custom instructions, and similar systems can all shape how the assistant behaves. Some are repo-level. Some are user-level. Some are scoped to certain file patterns. Tool support changes, so check the current docs for the exact loading behavior.

The practical rule is simple:

If the instruction is true for the project, keep it in project instructions. If it only matters inside one tool, put it in that tool’s rules.

Good tool-rule examples:

• Cursor should prefer existing shadcn/ui components before making new ones.
• Copilot should follow a team’s preferred PR summary style.
• Claude Code should use a specific review workflow when asked to audit a change.
• A tool should avoid auto-formatting certain generated files.

Bad tool-rule examples:

• The app uses Supabase.
• Run npm run build before handoff.
• Do not commit .env files.
• The apps/web folder contains the frontend.

Those are project facts. Put them where every coding agent can see them.

The risk with tool rules is drift. You add one version of the project rules to Cursor, another to Claude, another to Copilot, and six weeks later each assistant is following a slightly different map. That is how teams end up debugging the AI setup instead of the code.

A clean setup usually has one durable project instruction file, plus small tool-specific rules where a tool really needs different behavior.

Use Skills for Reusable Workflows

A skill is best thought of as a reusable procedure.

Do not use a skill just because you have a lot of instructions. Use a skill when you have a repeatable job that needs the same steps, checks, examples, or support files across more than one task.

Good skill candidates:

• review a pull request for security and data exposure risks
• turn a bug report into a reproduction plan
• check an AI-generated app before deployment
• draft and review an SEO blog post
• audit a Supabase app for common auth and row-level security mistakes
• convert messy notes into a client handoff document

A skill can hold the process. The repo instructions hold the project facts.

That distinction matters. If you put everything in the repo file, it becomes prompt soup. If you put project facts inside a reusable skill, the skill stops being reusable.

For example, a deployment-readiness skill might say:

When reviewing a web app before launch:

1. Identify the app's main user flows.
2. Check environment variables and secret handling.
3. Verify auth and permissions.
4. Run tests, lint, type checks, and build commands listed in the project instructions.
5. Check mobile behavior and empty/error states.
6. Produce a launch risk list with blockers separated from nice-to-haves.

That skill can work across many projects. It does not need to know that this specific repo uses Vercel, Netlify, Railway, Supabase, Clerk, Stripe, or a custom VPS. The project file can provide those details.

For the checklist version of that workflow, see the vibe coding deployment checklist.

Use MCP When the Agent Needs External Tools or Data

MCP, the Model Context Protocol, is for connecting AI applications to outside context and tools. In plain English: MCP helps an AI assistant reach things beyond the chat and the local prompt.

That might include:

• documentation
• GitHub issues and pull requests
• a database
• a browser
• a design system
• a ticket tracker
• internal docs
• local scripts or services
• cloud APIs

MCP is not a better README.

If the agent only needs to know that the project uses Next.js, write that in the project instructions. If the agent needs to fetch current framework docs, inspect a GitHub issue, query a local database, or interact with a browser, MCP may be the right layer.

A good MCP use case sounds like this:

“When debugging this issue, the agent needs to inspect the GitHub issue, check the current docs, and verify the behavior in a browser.”

A bad MCP use case sounds like this:

“I do not want to write a short AGENTS.md, so I will wire up a bunch of servers and hope the agent figures it out.”

More access means more blast radius. Before you connect an AI coding agent to databases, repos, ticket systems, browsers, or deployment tools, think about permissions:

• Can it read only, or can it write?
• Can it access secrets?
• Can it modify production data?
• Can it trigger deployments?
• Are actions logged?
• Can you review before anything risky happens?

MCP can be powerful. It can also turn a sloppy prompt into a real incident if you connect it to the wrong thing with too much permission.

Use Subagents for Specialized Roles

Subagents are useful when you want separation of responsibility.

Instead of asking one AI context to research, plan, code, test, review, and write docs, you give focused jobs to smaller specialist agents. A researcher can compare options. A reviewer can look for flaws. A security reviewer can check dangerous areas. A technical editor can clean up docs without steering the implementation.

Good subagent jobs:

• “Review this auth change for security risks. Do not edit files.”
• “Compare these three libraries and cite official docs.”
• “Check this draft for publish readiness and AI-sounding filler.”
• “Inspect the test failures and recommend the smallest fix.”
• “Review this deployment plan for rollback and secret-handling gaps.”

Bad subagent jobs:

• “Build the whole app.”
• “Figure everything out.”
• “Make it better.”
• “Create five agents because that sounds more advanced.”

Subagents work best when one main agent or human stays in charge. The specialists advise or handle scoped work. They do not all become project managers.

If you want the deeper workflow, read the VibeCodeSource guide to AI coding subagents and the broader overview of autonomous AI coding agents.

The simple rule:

Use subagents when an independent perspective or specialist checklist improves the result. Do not use them to make a small task feel fancy.

Use Hooks, Permissions, and Sandboxing for Safety

Instructions are soft control. Safety boundaries are hard control.

An instruction can say, “Do not deploy without approval.” A permission system can actually block the deploy command. A hook can stop a risky action. A sandbox can prevent the agent from touching files outside the project.

You want hard boundaries around actions like:

• deleting files
• changing production services
• running database migrations
• exposing local services publicly
• sending email
• publishing to a live site
• touching credentials or .env files
• pushing to a protected branch
• deploying to production

This is especially important for vibe-coded apps because the same workflow that helps you move quickly can also help you break things quickly.

Exact safety features vary by tool. Some assistants support hooks. Some have command approvals. Some rely on sandboxing, workspace permissions, or manual review. Check your tool’s current docs before assuming it can block a command, hide a file, or require approval.

A useful safety setup might include:

• read-only mode for audits
• approval required before destructive commands
• blocked access to credential files where the tool supports it
• command allowlists for normal verification commands
• logs for agent actions
• separate local, staging, and production credentials
• a required build/test check before handoff

For more on launch risk, read why vibe-coded apps break in production and the guide to vibe coding security risks.

Do not rely on a sentence in a prompt to protect production. Prompts are reminders. Permissions are seatbelts.

A Practical Decision Tree

When you are not sure where something belongs, use this.

Is it true for this specific repo?
→ Put it in AGENTS.md, CLAUDE.md, or repo-level project instructions.

Is it only relevant to one tool's behavior?
→ Put it in that tool's rules or settings.

Is it a repeatable workflow you use across projects?
→ Make it a skill.

Does the agent need access to external data, tools, APIs, docs, or services?
→ Consider MCP, with tight permissions.

Does the task need an independent role or second opinion?
→ Use a subagent.

Is it a safety boundary or approval rule?
→ Use hooks, permissions, sandboxing, or a manual approval step.

Could a shorter prompt or note solve it?
→ Do that first.

That last line saves people from a lot of nonsense.

Do not build infrastructure for a problem you only had once. If the same instruction keeps coming up, promote it to the right layer. Until then, keep it simple.

Example Setup for a Beginner Vibe-Coded SaaS App

Say you are building a small SaaS MVP with Claude Code, Cursor, Supabase, Stripe, and Vercel.

You do not need a giant agent architecture on day one. You need a setup that prevents the obvious mistakes.

Start here:

Repo instructions. Use AGENTS.md, CLAUDE.md, or the instruction file your tool supports. Include the app purpose, stack, important folders, setup commands, test/lint/typecheck/build commands, environment variable rules, auth and payment safety notes, deployment expectations, and when to ask before proceeding.

Tool rules. Add small tool-specific rules only if needed — for example, Cursor should follow existing component patterns, Claude Code should summarize risky changes before editing auth or billing code, Copilot should use your team’s preferred style for tests. Do not duplicate the whole project file in every tool.

Skills. Create reusable workflows when they repeat: deployment readiness review, security review, bug reproduction plan, pull request review, documentation cleanup.

MCP. Add MCP only when the assistant truly needs outside access — read GitHub issues, check current framework docs, inspect browser behavior, query a local development database. Keep production access locked down.

Subagents. Use one or two specialists for risky or complex work: a security reviewer before launch, a QA tester for main user flows, a researcher when choosing a library or hosting option.

Hooks and permissions. Add hard boundaries around dangerous actions — require approval before migrations, block production deploy commands, prevent reading .env files unless explicitly approved, require tests/build before handoff.

That is enough for most early projects. Anything more should earn its place.

Common Mistakes

Putting Everything in One Giant Instruction File

A long instruction file feels thorough until the agent starts ignoring half of it. Keep repo instructions short, current, and specific. Link out to longer docs when needed.

Duplicating the Same Rules Everywhere

If the same project rule lives in AGENTS.md, CLAUDE.md, Cursor rules, Copilot instructions, and a skill, it will drift. Pick a source of truth.

Using MCP for Static Information

If the information rarely changes and fits in a Markdown file, put it in a Markdown file. MCP is for access and actions, not for replacing basic docs.

Creating Subagents Before Basic Context Exists

Subagents cannot save a project with no map. Set up project instructions first. Then add specialist roles when the workflow needs them.

Treating Instructions as Security

“Do not leak secrets” is a good instruction. It is not a security model. Use permissions, environment separation, secret scanning, and approval gates.

Making the Stack Tool-Specific Too Early

If you use multiple AI coding tools, keep the portable project facts in a portable file. Tool-specific rules should stay small.

Adding Complexity Because It Looks Professional

A clean AI coding setup should make the work lighter. If your customization stack requires its own onboarding course, it may be doing too much.

What Should Never Go in Your AI Coding Customization Files?

Do not put sensitive material in instruction files, rules, skills, or examples.

Keep these out:

• API keys
• .env contents
• database passwords
• production credentials
• private tokens
• customer data
• private client information
• service role keys
• anything you would not want copied into a model context or log

It is fine to write rules about secrets:

Do not expose service role keys to frontend code.
Ask before editing auth, payments, database policies, or deployment settings.

It is not fine to paste the actual secrets.

Recommended Minimal Setup

If you are just getting started, use this stack:

1. One project instruction file with commands, structure, conventions, and safety notes.
2. Small tool-specific rules only where the tool needs special behavior.
3. One reusable checklist or skill for the workflow you repeat most often.
4. One reviewer subagent for risky launches or security-sensitive changes.
5. MCP only when the assistant needs real external access.
6. Permission checks before destructive commands, deployments, migrations, or credential access.

That setup is boring in the right way.

It gives the AI enough context to be useful, enough process to be consistent, and enough guardrails to avoid the dumbest mistakes.

If you want a starting point, begin with the AGENTS.md template for AI coding tools and add the other layers only when your workflow starts repeating the same problem.

FAQ

What Is the AI Coding Customization Stack?

The AI coding customization stack is the set of files, rules, workflows, tools, and safety controls you use to guide AI coding assistants. It can include AGENTS.md, CLAUDE.md, Cursor rules, Copilot instructions, skills, MCP servers, subagents, hooks, permissions, and sandboxing.

Should I Use AGENTS.md, CLAUDE.md, or Cursor Rules?

Use the format your tool supports. The important part is purpose. Repo-level instructions should explain the project, commands, conventions, and safety rules. Tool-specific rules should only contain behavior that applies to that tool.

What Is the Difference Between AGENTS.md and Skills?

AGENTS.md is best for project-specific context: what the app is, how it is structured, how to verify changes, and what the agent should avoid. Skills are better for reusable workflows, such as code review, debugging, deployment checks, or content editing.

When Should I Use MCP for AI Coding?

Use MCP when the assistant needs access to external tools or data, such as documentation, GitHub issues, databases, browser automation, local services, or internal systems. Do not use MCP for static instructions that would work better in a Markdown file.

Are Subagents Necessary for Vibe Coding?

No. Subagents help when a task benefits from a specialist role or independent review. For small changes, one clear prompt and one well-configured assistant is usually better.

What Is the Safest Beginner Setup?

Start with one project instruction file, one set of tool-specific rules if needed, and a basic deployment or security checklist. Add skills, MCP, subagents, and hooks only when you understand the problem each layer solves.

Final Rule

Put stable project knowledge in repo instructions. Put tool quirks in tool rules. Put repeatable process in skills. Put external access in MCP. Put specialist judgment in subagents. Put hard safety limits in permissions and sandboxing.

If a layer does not make the workflow clearer, safer, or more repeatable, skip it for now.