Coding agents
AI skills vs MCP vs prompts: what belongs where
Decide when to use a prompt, reusable skill, AGENTS.md instruction or MCP server so AI agents stay understandable, portable, safer and easier to maintain.
Three layers, three jobs
Prompts, skills and MCP servers solve different problems. A prompt tells the model what to do now. A skill packages reusable instructions and supporting files for a class of work; Claude Code documents skills as reusable workflows built around a SKILL.md file in the Claude Code skills guide. MCP connects the agent to external capabilities through hosts, clients and servers as described in the MCP architecture guide. Repository instructions such as AGENTS.md add another layer: they tell coding agents how to behave in one codebase, as covered by the Codex AGENTS.md guide.
Use a prompt for the temporary part
A prompt is best for task-specific intent: fix this bug, compare these files, write this migration, or explain this stack trace. Keep it close to the current task. A good prompt names the desired outcome, constraints, owned files, verification command and what counts as done. A task prompt should focus on the current request; stable project policy is easier to maintain in a shared instruction file. If you paste the same instruction every week, it probably belongs somewhere else.
Use a skill for a repeatable method
A skill is a good home for a workflow that crosses projects or repeats often. Example: a release-note skill might say how to inspect commits, group changes, avoid marketing language and format output. A document-conversion skill might include helper scripts and layout checks. The advantage is consistency. The risk is stale procedure. Put version-sensitive facts in links or checks, not in forever prose. Keep skills small enough that the agent can decide when they apply.
Use MCP for live capability
MCP belongs where the agent needs to read or act through a system: search a database, inspect a browser, open tickets, query a vector store, or call an internal API. MCP servers can also expose resources and prompt templates. A local skill or instruction file is usually simpler when you only need to distribute a writing rule. Do not use prompts to simulate permissions. If an action changes external state, the permission boundary should exist in the tool design and the workflow around it, not only in a sentence asking the model to be careful.
Decision table
| Need | Put it in | Example |
|---|---|---|
| One-time task instruction | Prompt | Update this article JSON and validate word count. |
| Repository policy | AGENTS.md | Do not edit generated files; run npm run build before deployment. |
| Reusable specialist procedure | Skill | Render a PDF, inspect pages, and iterate until layout is clean. |
| External read or action | MCP | List open issues, query docs, or create a draft ticket. |
Concrete example
Suppose your team wants agents to write help-center articles. The prompt says the exact topic and audience. AGENTS.md says where article JSON files live, which generated files are off limits, and how validation works. A writing skill contains the house style, checklist and example outline. An MCP server connects to the content inventory so the agent can find related articles. This split keeps each layer honest. If the style changes, update the skill. If the repository changes, update AGENTS.md. If the content system changes, update the MCP server. If the topic changes, write a new prompt.
Problems to check
- Prompt pileup: permanent rules accumulate in every prompt until nobody knows which rule wins. Move stable rules into project instructions or skills.
- Skill overreach: a skill tries to cover too many workflows and fires when it should not. Split it by job.
- MCP as magic: a server exposes broad actions because it is convenient. Start read-only, then add writes with explicit review.
- Contradictory context: the prompt asks for one style while a skill or repository file asks for another. Check the host's instruction precedence and remove conflicting local rules; a repository file cannot rewrite the host's permission model.
Next steps
Audit one agent workflow you use today. Highlight each instruction in three colors: temporary task, reusable method and live system access. Move the first group into the next prompt, the second into a skill or checklist, and the third into a tool connection with scoped permissions. The result is less dramatic than a giant prompt, but it is easier to review, easier to update and less likely to surprise the next person who runs the agent.
Test each layer independently
Try the article workflow with a topic that needs no external data. The prompt and writing skill should produce the required format even with the content-inventory server disconnected. Next, change only the topic and confirm that the house style remains consistent. Finally, connect the inventory and ask for related articles; verify that returned titles match the actual records. These checks help locate faults. A wrong related link may come from stale inventory data, while a wrong tone may come from the skill or a conflicting prompt. Keeping those tests separate makes repairs smaller and prevents a new tool integration from becoming the default explanation for every failure.
Sources and further reading
Documentation checked October 4, 2026. Product features and availability can change.