Skill: Term That Means Two Things

It’s a Friday afternoon, and I catch part of a conversation between a couple of colleagues. They’re trying to make sense of what “skills” means for a multi-agent platform we’re planning. One of the engineers (relatively new, but not inexperienced) asked a fair question: “Are we just expected to write a bunch of markdown files?”

Engineers coming from Copilot or Claude often get tripped up by the word “skill.” The file, SKILL.md, tends to be the frame of reference. It mean something specific and narrow.

The more senior engineer is trying to explain, but it’s not quite landing. The terminology is getting in the way more than it’s helping. At that point, I step in.

The confusion

If you have spent any time with Claude Code or GitHub Copilot, you have probably encountered a SKILL.md file – a short markdown document that tells the coding agent how to behave in a specific context. Maybe it describes how to write code (e.g., TDD, SOLID, DRY) or how to render frontend components in a particular environment. Engineers new to agentic AI tools tend to internalize this as the definition of a skill: a file, probably markdown, that lives in a folder and informs an agent about something.

Then they read about “AI skills” in a broader architectural sense; agents that can use tools, connect to MCPs, invoke APIs, retrieve documents. The two ideas feel disconnected. They are not. The core confusion is mistaking a specific implementation details (a markdown file) for the abstract concept it represents (a discrete, reusable capability that an AI Agent can invoke).

What is a skill?

At the abstract level, a skill is simply a bounded, reusable capability that an agent can discover and invoke to accomplish something it could not do through reasoning alone. That is it.

A skill might give an agent the ability to:

• Call an external API (send an email, query a database, book a meeting)
• Operate specialized software (create a spreadsheet, manipulate a PDF, run code)
• Follow a domain-specific procedure (generate a new data pipeline, register metadata, govern it)
• Retrieve knowledge it does not have in its context window (search past conversations, look up long term memory)

The form that skill takes – whether it is a markdown file, an MCP server endpoint, a tool declaration, a system prompt instruction, or something else entirely – is an implementation choice, not the definition of the concept.

Two manifestations, one idea

Here is the clearest way to think about it. Consider what skills look like in two different contexts:

Both are skills. The first is a skill implemented as instructional context. The second is a skill implemented as a callable function. The intent is identical: give the agent a capability it would not otherwise have, in a form it can discover and apply correctly.

Why markdown files?

The SKILL.md pattern in tools like Claude Code is a deliberate, practical choice; not a fundamental constraint of what skills must be. Coding agents operate in a local file system. They can read files directly. Markdown is human-readable, version-controllable, and easy to write without tooling. Putting skill instructions into a SKILL.md file means:

• Teams can write and maintain skill instructions the same way they maintain documentation
• Skills can be reviewed in pull requests and tracked in git history
• The agent can discover available skills by scanning the file system
• No external infrastructure is required – just files

It is a sensible implementation for that environment. It is not the shape of all skills everywhere.

A coding agent chose to implement skills as markdown files because that fits its environment. A conversational agent with MCP connectivity implements skills as callable tools. Both are expressing the same underlying concept, a bounded capability the agent can discover and invoke, through the mechanism that makes sense for their context.

Unified mental model

Once you stop conflating the implementation with the concept, a clean mental model emerges

A skill is anything that extends what an agent can do, packaged in a form the agent can discover, understand, and apply. The packaging varies. The concept does not.

Whether you are authoring a SKILL.md for a coding agent or configuring an MCP server for a conversational one, you are doing the same thing: defining a capability boundary, describing how to use it correctly, and making it discoverable. The medium is different. The work is the same.

Understanding skills at the conceptual level, not just as files or tools, changes how you think about designing AI systems:

• Scope tightly. A good skill does one thing well. Whether it is a markdown file or an MCP server, the boundary should be clear enough that the agent can decide confidently whether to invoke it.
• Document the contract. Every skill has a contract: what it expects, what it produces, and when to use it. That contract lives in the SKILL.md description, or in the tool’s description field, or in both. The form differs; the need is constant.
• Design for discoverability. An agent can only use a skill it can find. In a coding agent that means co-locating SKILL.md files sensibly. In an MCP system it means writing good tool descriptions. Same problem, same discipline.

The engineers who get furthest fastest with AI tooling tend to be the ones who can hold both levels of the “skill” concept simultaneously – concrete enough to write a good SKILL.md, abstract enough to see it as an instance of a general pattern. The two are not in tension. The concrete is just the abstract, made real in a particular place.