Agent Skills Explained: SKILL.md, Uses & vs MCP

An agent skill is a reusable package of procedural knowledge that an agent loads only when it is relevant. Concretely, a skill is a folder, and the folder contains a SKILL.md file: a Markdown document that opens with YAML frontmatter declaring a name and a description, followed by the actual instructions. Optionally the folder also carries scripts or reference files the instructions can point to. Anthropic introduced this format in 2025 as a portable way to give agents “how-to” knowledge that survives across sessions.

The mechanism that makes skills different from a static conventions file is that they are model-invoked and loaded on demand. The model reads the short description of each available skill and, when a task matches, pulls the full instructions into context, only then. A skill you never trigger costs you nothing but a one-line description. That is the whole trick: procedural knowledge that shows up exactly when the work calls for it.

Here is a small, realistic skill, a repo's pull-request conventions. Note the frontmatter: the name is the trigger, and the description is written so the model can tell from it alone when the skill applies.

---
name: pr-conventions
description: >
  How this repo opens pull requests. Use whenever the task is to
  create, format, or describe a PR, write a commit body, or prepare
  a change for review.
---

# Pull request conventions

- Title: imperative mood, <70 chars, no trailing period.
- Body: a "## Summary" section (1-3 bullets on the why) and a
  "## Test plan" checklist of what you verified.
- One story per PR. Never mix an unrelated refactor into a feature PR.
- Run the test + lint gate before opening; paste the result in the body.
- Link the story/issue id in the description.

That is a complete skill. Drop this file at ~/.claude/skills/pr-conventions/SKILL.md and Claude Code picks it up automatically; the next time you ask it to open a PR, it loads these rules without you pasting them. For a deeper look at file placement and a downloadable set, see the AIDEN Method skill pack.

The obvious alternative to a skill is to write everything into a durable project context file like CLAUDE.md, or to re-explain your process at the start of every session. Both have a cost. A CLAUDE.md that tries to hold every procedure your repo has ever needed becomes a wall the agent reads on every task, whether the task is a PR, a migration, or a typo fix. Re-explaining by hand is worse: it is tedious, and you inevitably forget a step.

Skills split the difference. Because the model only loads a skill when its description matches the current task, procedural knowledge stops competing for the context window when it is irrelevant. Your release checklist does not sit in the window while the agent fixes a CSS bug. This is straightforward context engineering: relevance beats volume, and skills give you a mechanism to keep the window lean without losing the knowledge.

Skills and MCP are the two most-confused pieces of the modern agent stack, because both “extend” an agent. They extend it in opposite directions. MCP gives the agent new capabilities, tools it can call and data sources it can read, like a database, a browser, or the GitHub API. Skills give the agent procedural knowledge, the instructions for how to carry out a kind of task the way you want it done. One is what the agent can do; the other is how it should do it.

The best candidates for a skill are the processes you find yourself explaining again and again, the ones where consistency matters and the “right way” is specific to your team. Examples that pay for themselves quickly:

Each of these is procedure, not capability, which is exactly why they belong in skills rather than MCP servers. The first three of these are shipped, ready to use, in AIDEN's free skill pack.

A skill is only useful if the model reliably loads it at the right moment and then follows it. The two failure modes are a skill that never triggers (because the description is vague) and a skill that triggers but muddies the work (because the instructions ramble). Author against both:

1. 1

   Name it by the trigger

   Name the folder and skill after the situation it applies to, not after a feature: pr-conventions, test-gate, release-checklist. The name is the first signal the model uses.
2. 2

   Write a sharp description

   The description in the frontmatter is what the model reads to decide whether to load the skill. Make it specific about when it applies, list the trigger tasks explicitly ('use whenever the task is to open a PR, write a commit body, or prepare a change for review'). A fuzzy description means the skill fires at the wrong time or never.
3. 3

   Keep instructions imperative and short

   The body should be direct commands, not essays. Bullet points, exact commands, concrete conventions. Every extra paragraph is context the model has to wade through once the skill loads; terse instructions get followed more faithfully.
4. 4

   Add scripts for determinism

   For any step that must be exact, running the right test command, formatting output a fixed way, bundle a script in the skill folder and have the instructions call it. Prose asks the model to reproduce a procedure; a script removes the guesswork.
5. 5

   Test that it fires

   Give the agent a request that should trigger the skill and confirm it loads and follows the instructions, then give it an unrelated request and confirm the skill stays quiet. If it misfires either way, tighten the description before touching the body.

Skills are one layer of a real agent setup, and they earn their keep next to the others. Picture a single story, “add a soft-delete column and expose it in the API”, running through a well-equipped agent:

The layer that carries all of this, launching the agent, wiring in MCP, managing subagents, and keeping skills available, is the agent harness. Skills are the procedural-knowledge slot in that harness, and they are one of the core practices in the broader discipline of agentic engineering.

AIDEN is a cockpit over your coding-agent CLIs: it orchestrates your local Claude Code and Codex behind a spec-first kanban with a PR per story, and it uses your own inference, your Claude or Codex subscription or API key. Because it runs your existing CLIs rather than replacing them, it inherits your skills automatically. Every skill in ~/.claude/skills or a project's .claude/skills is available to every agent AIDEN launches, exactly as it is when you run Claude Code by hand. Nothing to configure twice.

If you are new to the underlying CLI, the Claude Code tutorial covers the basics that skills build on. Pair skills with the right MCP servers and you have both halves, capability and procedure, of an agent that ships code your way.