What Is Agentic AI SKILL.md? Advisory, Not Enforceable

An agentic AI skill is a folder of instructions, reference files and scripts that an agent loads on demand when a task matches the skill’s description. Anthropic published the format in October 2025 as a SKILL.md file with YAML metadata on top and plain Markdown instructions below. By December it was an open standard. Other model vendors now read the same file.

That is the whole definition. A skill is instructions in a file. Keep that sentence in mind. Everything that follows depends on it.

The governance question

Here is the mistake I see most often. A team writes a skill that says “never touch the secrets folder” or “always run the test suite before committing.” They file it under controls. They tell the auditor it is a control.

It is not. You cannot enforce with a skill. You can enforce around it.

A skill sits in the model’s context window. So does every other instruction. They all compete for attention. Compliance drops as the session gets longer. One practitioner put it plainly: everything you feed an agent through its context is, in the end, a suggestion.

That is fine for a coding convention. It is not fine for a rule that protects a production database or a credit decision.

How a skill actually works

The mechanics matter, so here they are from the vendor documentation.

A skill has three layers, and the agent loads them in stages. At startup it reads only the name and the one-line description from the frontmatter. That costs about 80 tokens per skill. An agent can know about dozens of skills for less context than one activated skill consumes.

When a task matches, the agent loads the full SKILL.md body. A typical body runs around 2,000 tokens. Only then does it open any referenced files or run any bundled scripts.

Anthropic calls this progressive disclosure. It is a good design for cost and context. It is also the reason a skill cannot be a control. The agent decides when the skill is relevant. Nothing forces the load. Nothing forces the follow-through.

When a skill does load, the runtime injects its instructions into the conversation and can adjust the execution context, such as which tools are allowed. Skills prepare the agent to solve a problem. They do not solve it, and they do not stop it.

One more thing from the same documentation. Anthropic’s own guidance says to use skills only from trusted sources, because a malicious skill can direct an agent to invoke tools or run code in ways that do not match its stated purpose. Read that twice. The vendor is telling you that a skill is a capability, and capabilities need governing.

Where it sits in the six layers

In my six-layer architecture, a skill belongs to the capability layer. It is the same layer as tools and MCP servers. It expands what the agent can do.

It does not belong to the enforcement layer. That layer holds the things that run whether the model agrees or not: hooks, permission rules, sandboxes, credential scopes, branch protection.

The two layers are not rivals. They are a pair. A skill tells the agent how to do the work well. A hook checks the work before it lands.

The confusion comes from the fact that both are written in files, both live in the same repository, and both are called “configuration.” The difference is not where they live. The difference is who gets to ignore them. The model can ignore a skill. The model cannot ignore a hook.

The advisory-or-enforcing test

I run one test on every component before I let it into a control inventory. Can the model bypass it on a bad day?

If yes, it is advisory. If no, it is enforcing. That is the whole test.

Apply it to a skill. The agent might not load it. It might load it and drift after thirty turns. It might load it and decide the instruction does not apply here. Every one of those is a bypass. A skill is advisory. Always.

Apply it to a hook. A pre-tool-use hook is ordinary code. It runs before the tool call, every time, on the same input, with the same result. It can return allow or block. The model does not get a vote. A hook is enforcing.

Hooks now exist in every major coding agent. Claude Code shipped them first. Cursor, Codex and VS Code Copilot followed with near-identical surfaces. The primitive is settled enough to build on.

So the pattern is simple. Put the how in a skill. Put the must in a hook. Then wire the hook to fire on the actions the skill is supposed to protect.

What breaks when you get this wrong

I have watched three versions of this failure.

The skill that stops loading: A team writes a careful review skill. It works for a month. Then someone adds twelve more skills to the same repository. The description-matching gets noisier. The review skill loads on half the tasks it used to. Nobody notices because nothing logs a skill that did not load.

The skill that gets outrun: The instruction says to run tests before any commit. The session runs long. The agent has forty tool calls of context behind it. It commits without testing. Ask it why and it will apologize. Apology is not a control.

The skill nobody audited: A skill pulled from a public marketplace bundles a script. The script does more than the description says. The agent had the credentials. The vendor documentation warned about exactly this case. The team read the SKILL.md and skipped the scripts folder.

None of those are model failures. All three are architecture failures. Someone put a must in a file the model could ignore.

What transfers to regulated origination

In loan origination I use skills heavily. A skill knows how to read a paystub. A skill knows the order of steps for a title check. A skill knows what a clean underwriting summary looks like.

None of those skills is a control. The controls sit around them.

The agent cannot post a credit decision without a hook that checks the decision against policy. It cannot write to the loan file without a scoped credential. It cannot skip the human gate on any adverse action, because the gate is a hook, not a sentence.

That is what enforce-around-it looks like in practice. The skill makes the agent competent. The hook makes the system defensible. When the examiner asks how I know the rule held on every file, I do not point at the SKILL.md. I point at the hook log.

The roadmap diagnostic

One question tells you where a team sits on the Five-Stage Roadmap.

Show me a rule that lives only in a skill. Now show me what stops the agent when it ignores that rule.

If the second answer is “the skill,” you are at Piloted, whatever the deck says. If the second answer is a hook, a permission rule or a sandbox, you have crossed into Governed. That crossing is the whole difference between a demo and a deployment.

Bottom line

Skills are one of the best things to happen to agent engineering in the last year. They make procedural knowledge portable, readable and cheap to load. Use them everywhere.

Just do not put them in the control inventory. A skill is a capability. It lives in the capability layer. It is advisory by design, and the vendor says so.

Enforce around it. Hooks for actions. Permission rules for tools. Credential scopes for data. Branch protection for code. Then let the skill do what it is good at, which is making the agent better at the job.

I go deeper on this split, and on how to build the enforcement layer, in Intent In, Outcomes Out and Earned Autonomy.

Which rule in your repository lives only in a skill today?

Go deeper

Agentic AI Architect: control design for enterprise agents.
Agentic AI Case Studies: deployment evidence, one teardown at a time.
Agentic AI P&L: cost, payback, and risk in a CFO’s voice.
Agentic AI Governance: who owns the harness.
Substack first access: agenticaiarch.substack.com/subscribe

Dr. Harish Kotadia, Ph.D., is an Enterprise AI Architect with 20+ years of IT consulting experience serving Fortune 100 clients, specializing in agentic AI systems built on Anthropic Claude, AWS Bedrock, and Google Vertex AI.

Disclaimer: This blog post is based on publicly available academic publications, vendor documentation, open standards, and news items from reputed media sources linked above. This post is intended for educational purposes, to help the enterprise agentic AI community build a shared vocabulary from public, authoritative sources.

Views and opinions expressed here are my own and do not represent those of any employer or client, past or present. The analysis presented is my independent interpretation of the published sources linked above and does not constitute legal, financial, or consulting advice of any kind.

What Is Agentic AI SKILL.md and Why It Is Advisory and Cannot Be Enforced