Where should your agent’s hard-won knowledge live?
Skills vs. instructions vs. a Markdown file vs. MCP
When you build software with an AI coding agent, you accumulate knowledge: the quirks of
an API, patterns that work, dead ends to avoid, conventions your team follows. The agent
doesn’t remember any of it between sessions — and certainly not between projects. So the
real question isn’t whether to write that knowledge down. It’s where it should live
so the agent reliably picks it up, at the right moment, without drowning in context.
This is the decision framework I’ve settled on. The running example is a growing set of
Pega DX (Constellation) API integration patterns that started life as a single Markdown
file and eventually became an Agent Skill — but the framework
is tool- and platform-agnostic.
The options, and when each wins
| Put the knowledge in… | Best when… | Loaded… |
|---|---|---|
An instructions file (AGENTS.md, CLAUDE.md, .github/copilot-instructions.md) |
It’s small, always-relevant, project-specific guidance — build/test commands, conventions, “always do X.” A page or less. | Always, into every turn |
A single reference .md |
It’s a modest body of knowledge relevant to one project, cited on demand, and you’re not reusing it elsewhere yet. | On demand, but usually whole-file |
An Agent Skill (a folder: SKILL.md + reference files) |
It’s reusable across projects, growing, has distinct sub-topics, and you want drop-in portability and description-triggered loading. | On demand, only the relevant chapter |
| An MCP server / tool | You need the agent to do something or fetch live data — run a query, call a system, mutate state. This is behavior, not reference. | Invoked as a tool |
| Inline code comments / docs | The knowledge is about this code specifically and belongs next to it. | With the file |
A few of these are complementary, not either/or. A common, healthy setup: a short
instructions file that points at a Skill, and a Skill that sits alongside MCP tools —
the Skill teaches the workflow, the MCP tools execute it.
How to tell it’s time to graduate a .md into a Skill
A single Markdown file is a perfectly good starting point. Promote it to a Skill when you
notice any of these:
- It’s crossing projects. You’ve copied it into a second (or third) repo. That’s the
moment portability stops being a nice-to-have. - It’s getting big. Always-loading a 90 KB file taxes the context window and buries
the one pattern that’s relevant to the current task. - It has mutually-exclusive sections. Auth setup and attachment uploads are rarely
needed in the same breath — so don’t pay to load both every time. - You want others to reuse it. A self-contained folder with a clear entry point is
something a teammate can drop in; a loose.mdreferenced from prose is not. - You want the agent to maintain it. A Skill can carry its own contribution protocol,
so the “add what you learned” instruction travels with the artifact.
The mechanism that makes a Skill scale is progressive disclosure: the agent pre-loads
only each Skill’s short name/description, decides if it’s relevant, then reads the
entry point, then opens just the deeper file it needs. The body of knowledge can grow
without growing the cost of not using it.
The pattern that makes any of these compound
Whatever container you choose, add one instruction that turns it from a static doc into a
compounding asset:
When you solve something that isn’t covered here — and it took trial and error — add
the working pattern back to this file/Skill before moving on.
This “self-improving loop” is what makes every project smarter than the last. A .md can
do this too; a Skill just makes the result portable and shareable, so the learnings don’t
stay trapped in one repo.
Why Skills specifically travel well
Agent Skills are an open standard — the same folder is
auto-discovered across many agents (GitHub Copilot, Cursor, Claude, Gemini CLI, and
others). That means the knowledge you capture isn’t tied to one vendor’s instruction-file
format, and “deploying” it is just dropping in a folder (or linking it as a git
submodule so improvements flow back to a canonical source).
They also complement MCP rather than compete with it: MCP gives an agent new actions
and live data; a Skill gives it the know-how to use those actions well. For a domain
like Pega DX API integration, you often want both — MCP tools to talk to the server, and a
Skill full of patterns so the agent uses them correctly.
The case study
This framework came out of exactly one of these graduations. A curated file of Pega DX
API integration patterns — base URLs, ETags, case lifecycles, attachments, embedded
pages, stage jumps — outgrew its single-.md form once it started moving between
projects and pushing 90 KB. Turning it into a Skill made it load precisely, deploy in one
step, and maintain itself as the agent discovers new patterns. That Skill, and a
walkthrough of what’s in it, lives here:
GitHub - j0glesby73/pega-dx-api-patterns: A portable Agent Skill packaging battle-tested Pega DX (Constellation) API integration patterns for AI-assisted development. · GitHub.