# Skills vs. instructions vs. a Markdown file vs. MCP

**URL:** <https://forums.pega.com/t/skills-vs-instructions-vs-a-markdown-file-vs-mcp/12969>\
**Category:** AI\
**Created:** [August 1, 2026, 12:34am UTC](https://forums.pega.com/t/skills-vs-instructions-vs-a-markdown-file-vs-mcp/12969 "2026-08-01T00:34:45Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![oglej](https://yyz2.discourse-cdn.com/pega/user_avatar/forums.pega.com/oglej/32/14486_2.png) [@oglej](https://forums.pega.com/u/oglej)\
**Post date:** [August 1, 2026, 12:34am UTC](https://forums.pega.com/t/skills-vs-instructions-vs-a-markdown-file-vs-mcp/12969/1 "2026-08-01T00:34:45Z")

</div>

# 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](https://agentskills.io) — 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 `.md` referenced 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](https://agentskills.io) 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](https://github.com/j0glesby73/pega-dx-api-patterns)**.
