AGENTS.md, Skills or MCP? Giving AI Agents Context

Some of the most-discussed developer posts of the past year were not about which model is best. They were about how to give an agent the right context: AGENTS.md files, agent skills, and the Model Context Protocol (MCP).

Hacker News threads such as You said no MCP, I still prefer MCP over skills and When does MCP make sense vs CLI? each drew hundreds of points and comments. The short version: each option has a job, and picking the wrong one costs tokens and reliability.

At PromptPal we see the same question from teams every week, so this guide sorts out when to use each option. It finishes with four PromptPal templates that set each one up in minutes.

The three options in one minute

• AGENTS.md / CLAUDE.md (What it is: A short instruction file in the repo; Loaded when: Every session; Best for: Commands, gotchas, a map of local docs)

• Skill (What it is: A folder with a SKILL.md and supporting files; Loaded when: Only when relevant; Best for: Team-specific procedures)

• MCP server (What it is: A service exposing tools to the agent; Loaded when: When the agent calls a tool; Best for: Live data and actions in other systems)

What the evidence says about AGENTS.md

Vercel tested this directly in AGENTS.md outperforms skills in our agent evals:

• With no docs, the agent passed 53% of tasks.

• With a skill, the agent often never opened it, and the best skill setup reached 79%.

• With a compact docs index in AGENTS.md, it passed 100%.

The reason is simple. Content in AGENTS.md is always present, so the agent never has to decide whether to look something up. Vercel also compressed the index from about 40KB to 8KB without losing that score, so short is fine.

When skills win

Skills shine for procedures that matter only sometimes: how your team writes a migration, reviews a pull request or ships a release. Loading them on demand keeps every other session lean. The trick is a description that makes it obvious when the skill applies. PromptPal's Agent Skill Builder template writes that description for you.

When MCP wins

Use MCP when the agent needs live data or actions in another system: tickets, databases, design files, browsers. Two habits keep it healthy:

1. Keep the tool list small. Large tool lists make agents choose worse and use more context.

2. Design tools, not examples. Clear names, enums, and one-line field descriptions do more than long usage examples.

If a good CLI already exists and the agent can run a shell, the CLI may be the cheaper choice. Not sure which fits? PromptPal's MCP vs CLI vs Skill Decision Helper compares them for your exact use case.

Set it up with PromptPal

PromptPal is a prompt library and testing workspace for teams. It includes a ready-made template for each option in this guide:

• AGENTS.md / CLAUDE.md Generator writes a short instruction file focused on commands, gotchas, and a docs index.

• Agent Skill Builder turns a team procedure into a SKILL.md with clear trigger conditions.

• MCP Tool Definition Writer produces tool names, descriptions, and JSON schemas that agents pick correctly.

• MCP vs CLI vs Skill Decision Helper compares the options for a specific capability and recommends one.

Fill in a template, run it across models in PromptPal's multi-model testing, then save the version that works to your prompt library. On a Team plan, share it in your workspace so everyone uses the same one.

Next step: open the AGENTS.md / CLAUDE.md Generator in PromptPal and run it on your main repository today. It is the change with the strongest evidence behind it.