Post cover image

October 27, 2026

SKILL.md Might Be the Missing Layer for AI Agents

Disclosure: This article was developed with AI assistance for drafting, structure, and editing, with the final direction, examples, and…

By Mr. Data Bean

5 min read

Disclosure: This article was developed with AI assistance for drafting, structure, and editing, with the final direction, examples, and editorial decisions reviewed by the author.

Prompts tell agents what we want. Tools tell them what they can do. Skills may finally teach them how we want the work done.

AI agents are becoming dramatically more capable.

But giving them capabilities is only half the problem.

Claude Code can edit a repository. Codex can investigate a codebase. Agents can browse the web, call APIs through MCP, run terminal commands, and interact with external services.

The harder question is:

How do we make different agents consistently follow the way we want a task performed?

Not just what we want them to accomplish.

But how they should get there.

That is where Agent Skills — and a surprisingly simple file called SKILL.md — start to become interesting.

In October 2026, Anthropic donated the Agent Skills standard to the Agentic AI Foundation, pushing the idea toward a broader cross-platform standard.

OpenAI also supports Skills compatible with the open Agent Skills format.

If that direction continues, SKILL.md could become a familiar part of AI-native software projects.

So, What Is an Agent Skill?

At the simplest level, an Agent Skill is a reusable package of instructions that teaches an AI agent how to perform a specific type of task.

Its core file is:

SKILL.md

But a Skill can also contain:

references/
scripts/
templates/
assets/

That makes it fundamentally different from simply saving a good prompt.

A prompt might say:

Fix this bug carefully.

A Skill can define an actual procedure:

Understand the issue
↓
Reproduce it
↓
Find the root cause
↓
Make the smallest reasonable fix
↓
Run relevant tests
↓
Review the final diff

The model already knows how programming works.

What the Skill provides is something different:

This is how we perform this kind of work.

That distinction matters.

Prompts vs Tools vs Skills

This is the mental model that made Agent Skills click for me.

Prompt

What should the agent do?

Fix the authentication bug.

Tool

What can the agent use?

For example:

  • filesystem
  • terminal
  • GitHub
  • browser
  • databases
  • MCP servers

Skill

How should the agent perform the task?

Reproduce the bug before editing code, identify the root cause, make the smallest reasonable change, and verify the result

Prompts provide intent.

Tools provide capabilities.

Skills provide procedure.

And procedure is something AI agents still need surprisingly often.

Why Not Put Everything in AGENTS.md?

Technically, you could.

But that doesn't scale particularly well.

Imagine a project with instructions for:

  • debugging
  • code review
  • security audits
  • database migrations
  • testing
  • deployment
  • documentation
  • incident investigation

Most of those instructions are irrelevant during any given task.

Eventually, your instruction file becomes another document the agent has to sift through.

Skills make this modular.

Instead of one enormous file containing every possible workflow:

AGENTS.md

you could have:

skills/
├── verified-bug-fix/
├── security-review/
├── pull-request-review/
├── database-migration/
└── release-check/

The agent can load the procedure relevant to the current job.

This follows an increasingly important idea in agent design:

progressive disclosure.

Give the model the minimum useful context first.

Load deeper instructions only when they're actually needed.

A Practical Example: verified-bug-fix

If Skills are supposed to encode repeatable procedures, vague Skills aren't very useful.

Something like:

write-good-code

doesn't provide much value.

I would rather create something narrow:

verified-bug-fix

One task.

One repeatable workflow.

The structure could look like this:

verified-bug-fix/
│
├── SKILL.md
│
├── references/
│   ├── investigation.md
│   └── verification.md
│
└── assets/
    └── fix-report.md

The main SKILL.md only needs the procedure that applies to almost every bug.

For example:

---
name: verified-bug-fix
description: Investigate and fix a reproducible software bug, then verify the fix.
---
# Verified Bug Fix
Do not begin by editing code.
First understand the reported behavior.
## Investigate
Identify:
- expected behavior
- actual behavior
- reproduction conditions
- affected component
Start narrow and inspect only relevant code.
## Reproduce
When possible, reproduce the failure before changing anything.
Do not claim reproduction unless it actually happened.
## Root Cause
Form a root-cause hypothesis.
Validate it against the code and available evidence.
## Fix
Make the smallest reasonable change.
Avoid unrelated refactoring.
## Verify
Run the relevant tests.
Add a regression test when appropriate.
Do not claim success only because the code looks correct.
## Review
Inspect the final diff and remove unrelated changes.

There is no magical prompt engineering here.

And that's exactly why I like the idea.

A Skill shouldn't depend on clever wording.

It should contain a good process.

Progressive Disclosure Is Where It Gets Interesting

The main Skill doesn't need to become a 500-line debugging manual.

More specialized knowledge can live elsewhere.

For example:

references/investigation.md

might contain guidance for:

  • stack traces
  • async bugs
  • state issues
  • dependency failures
  • configuration problems
  • data-flow tracing

While:

references/verification.md

might cover:

  • regression testing
  • unit vs integration tests
  • linting
  • type checking
  • boundary cases
  • security regressions

The agent doesn't need all of this information for every bug.

It can load the deeper material only when necessary.

That is far more attractive than continuously injecting giant instruction documents into every task.

Where Does MCP Fit?

This is where terminology starts getting confusing.

Agent Skills and MCP are not really competing technologies.

They solve different layers of the problem.

AGENTS.md

How does this project work?

Repository-level context and persistent instructions.

Agent Skill

How do we perform this task?

Reusable procedural knowledge.

MCP

What external capabilities can the agent access?

Tools, services, systems, and live information.

All three can work together.

A debugging agent could theoretically operate like this:

AGENTS.md
↓
Understand project conventions

verified-bug-fix
↓
Follow the team's debugging procedure

MCP
↓
Read GitHub issues, monitoring data,
or another external system

The combination may be more important than any single piece on its own.

Skills Could Become Organizational Knowledge

Debugging is only one obvious example.

Most companies are filled with repeatable procedures.

A team could maintain Skills for:

  • reviewing pull requests
  • investigating incidents
  • preparing financial reports
  • analyzing customer feedback
  • researching competitors
  • producing release notes
  • performing security checks
  • validating datasets
  • handling support escalations

Instead of explaining the process to an AI agent every time, the procedure itself becomes a reusable, versioned asset.

That starts to look less like prompt engineering.

It starts to look like:

operational knowledge for AI agents.

And that is a much bigger idea.

There Is Also a Security Problem

This part deserves more attention.

A Skill may look like a Markdown file.

But its instructions can influence:

  • command execution
  • file access
  • external tools
  • credentials
  • agent decisions
  • network services

Imagine downloading:

awesome-coding-skill/

from a random GitHub repository and giving it to an agent that has access to your terminal, filesystem, GitHub account, and cloud infrastructure.

That isn't the same thing as downloading a Markdown cheat sheet.

A Skill can shape what an autonomous system actually does.

As community Skill libraries grow, we may need to treat Skills less like prompt templates and more like software dependencies.

Review before trust.

Limit permissions.

Understand what the Skill instructs the agent to do.

A portable workflow is useful.

A portable malicious workflow is portable too.

Why SKILL.md Matters

For the last few years, much of the AI industry has focused on making models more intelligent.

Now another problem is becoming increasingly important:

How do we make intelligent agents reliably work the way we want them to?

More context isn't always the answer.

Larger system prompts aren't necessarily the answer either.

A more scalable architecture could look something like this:

General-purpose agent
        +
project context
        +
reusable Skills
        +
external tools
        =
specialized worker

The interesting part of Agent Skills isn't the Markdown format itself.

It's the idea that procedural knowledge can become portable.

Today, we share prompts.

Tomorrow, we may share complete workflows.

And if Agent Skills continue becoming a cross-platform standard, SKILL.md could become one of the files developers regularly encounter inside AI-native projects.