Skills vs MCP comes down to know-how versus access, the split Bigcircle already runs. The model is given the procedure a step needs, and every action goes through a typed tool whose credential it never holds. A skill packages that procedure as instructions, scripts and references the host loads when the task calls for them, and an MCP server packages the access, so a production agent usually needs both.
Key facts
Definition
An Agent Skill is a folder the host loads into context, and an MCP server is a separate process that exposes typed tools and keeps the credential.
How Bigcircle does it
- Bigcircle keeps the procedure in what a plan step searches for, and keeps every action on a typed tool the agent cannot widen.
- On Solarpunk, Bigcircle injects each credential from an encrypted vault on the machine at the moment of the call, so the secret never enters the prompt.
- On Skionis, Bigcircle gives the agent no general shell, and an engineer approves a diagram of the change before it is applied to the AWS account.
Comparison
A skill loads about 100 tokens of metadata until a task activates it and then runs with the host's privileges, while an MCP server checks a token on every call and can refuse the call.
Key number
In a January 2026 scan of public skill registries, 84.2 percent of 632 confirmed vulnerabilities sat in the SKILL.md file rather than in executable code.
On Solarpunk, a desktop agent we built, direct tool calling held until roughly thirty tools, and past that point the model chose plausible tools from the wrong system and returned a confident result. We stopped handing it the registry. Each plan step searches for the handful of contracts it needs, and the credential for a call is injected from an encrypted vault on the machine so the secret never enters the prompt. The model stays a reasoning service and is never the thing holding the keys.
On Skionis, a DevOps agent we built for a live AWS account, we treat the agent as untrusted, so every step is machine-checkable or a person reviews it. There is no general shell, and a plan step cannot become an arbitrary API call. An engineer approves a diagram of the change, because engineers do not read raw template diffs carefully at the tenth change of the week. Nothing in that system depends on the model being correct.
Use a skill when the agent needs to know how, and use an MCP server when it needs governed access to a system. A production AI agent usually needs both. This guide covers the folder, what changed on 22 October 2026, the choice between the two, how to write a skill the host will actually pick, and what to review before one runs with the host's privileges.
What is an Agent Skill, and what goes in a SKILL.md file?
Treat the folder as the unit. SKILL.md is required, and scripts, references and assets sit beside it, loading only when a step needs them. The host does not read the whole folder at startup, which is the only reason a catalog of skills can exist without filling the context window.
At startup the host loads the name and the description for every installed skill, about 100 tokens for that pair. The name is 1 to 64 characters, lowercase letters, numbers and hyphens, and it must match the parent directory, with no leading or trailing hyphen and no doubled hyphen. The description runs to 1,024 characters and has to say what the skill does and when to use it, because that sentence is the whole decision the host can make before it opens the file.
When a task matches, the host loads the body, so keep that body under 5,000 tokens and keep the file under 500 lines. Move long reference material into files next to it, one directory deep, with relative paths.
Scripts and assets stay out of the prompt until a step asks for them. Copy the order, which is metadata first, instructions second and files last. A host that loads every body at startup spends the context that order was meant to save, and you should not install a large catalog on that host.
Optional fields are a license, a compatibility note of up to 500 characters, a metadata map of strings, and allowed-tools, an experimental space-separated list of tools the skill may use, which a host is free to ignore. Do not treat that list as the permission check. The check belongs on the tool, in code, where a line of markdown cannot edit it.
There is no version field, so put a version string in metadata and install by that string. Run skills-ref validate on the folder before anyone reviews the prose. It checks the name, the description length and the directory match. It does not read the instructions for a hidden action, so that reading is still yours. The sample below is the shape, including the refusal in the description.
---
name: release-notes
description: >
Draft release notes from merged pull requests and a changelog.
Use when a release owner asks for notes on a tagged version.
Do not use this skill to ship the release.
metadata:
version: "1.0"
---What changed for skills on 22 October 2026?
Label every install count as Anthropic's own, and treat the donation as a change of owner for the format. The behavior of a skill did not change on that date. What changed is who holds the name, the logo, the repository and the domain, and which numbers a buyer is being shown.
| When | What changed |
|---|---|
| October 2025 | Skills first shipped inside Claude Code |
| December 2025 | The format opened under its own organization and domain. More than 70 platforms, including ChatGPT, Cursor, GitHub Copilot and VS Code, have integrated it since, on Anthropic's own count |
| 22 October 2026 | Anthropic donated the format, the name, the logo, the GitHub organization and the agentskills.io domain to the Agentic AI Foundation, which sits under the Linux Foundation |
| 22 October 2026 | Anthropic's own count at the donation: 1 million skills and nearly 280 million installs |
| 22 October 2026 | The foundation added Agent Skills, Open Responses, OpenEnv and OpenSandbox, and the hosted set went from 3 projects to 10 |
Use the roadmap as a proposal, not as a spec a host must meet today. As of 27 October 2026 the maintainers have proposed versioned releases, a formal proposal process and security guidance, and none of those is in force. You can implement the format without joining the foundation, and a skill written to the current specification still loads where it loaded last month. Wait for the security guidance before you treat a public catalog as reviewed, because the donation did not add a review.
Skills vs MCP: which one does the job?
Put know-how in the skill and governed access on the server. A skill answers how this team does the task, and an MCP server answers which system may be touched, by whom, and with which credential. Production agents need both answers, and the figure is that split with the gates marked, where blue loads into the prompt, green stays on the server, and orange marks the review before either runs.
Read the rows as a review, and stop on the first row you cannot fill in for a skill you are about to trust with a real system. A row you cannot answer is a skill you are not ready to install.
| Question | Skill | MCP server |
|---|---|---|
| What it carries | Instructions, scripts and references the host loads into context | Typed tools on a process you run and administer |
| Where it runs | In the host, with that host user's privileges | On the server, apart from the model |
| Who holds the credential | The host, unless the skill calls a tool and stops | The server, which checks a token on every request as of the 2026-07-28 specification |
| What is contracted | An experimental allowed-tools list a host may ignore | A schema of inputs, outputs and side effects, checked before the call |
| What you can record | Whatever the host logs about the load | One log per call, including the refusal |
| What it costs in context | About 100 tokens until the task matches, then a body kept under 5,000 tokens | Only the tool definitions you chose to expose |
| How far it travels | Any host that reads the format | Any client that speaks MCP |
| How Bigcircle handles this | A plan step searches for the procedure | The action is a typed tool, and the credential is injected at the call |
Token checks, and the rule that a protected server does not forward the user's token, are the subject of MCP authorization, so this table only needs the consequence. The server can refuse the call, and the skill file cannot.
Can agent skills replace MCP?
A skill can call a tool and still cannot be the tool. The overlap is real and it is narrow: both can carry a procedure, and a host that runs scripts can reach a system with no MCP server in the middle. That reach is the problem. The script runs as the user, with the user's files and the user's credentials in reach, and nothing in the folder checks a token on the request.
Keep the procedure that must run the same way every time where MCP prompts and agent playbooks already puts it. A workflow an agent should find and run on its own is a playbook with a typed contract, exposed as a tool, with search, schema and execute in front of the catalog, and that conclusion stands.
A skill is the judgment around the playbook: which one fits, which near-miss does not, and when to stop. When the job touches a governed system, the skill names the tool and stops.
Do not put a password, a token or a shell in the skill folder. Do not move a playbook out of the tool and into the file because the file is easier to edit. Ease of editing is why the markdown is the wrong home for an action. Shape the tool with the rules in MCP tool design: one action per tool, with the side effect declared, so a reviewer can see what the call will change before it runs.
How do you write a skill a production host will pick?
Write the description for the task you want refused, not only for the task you want done. At startup the host has the description and nothing else, so a description that only lists capabilities gives the model no way to decline a lookalike. Drafting the notes and shipping the release are the near-miss in the sample above. Write the second into the field, in the words a person would use when they ask for the wrong thing.
Prefer a script where the step is deterministic, and prefer instructions where the step is a judgment. A script that computes a checksum should be a script. A paragraph that tells the model how your team names a release should stay prose. The script still needs a sandbox, because it runs with the host's privileges, and the prose still needs a review, because the model will follow it. Putting the deterministic step in prose is how a checksum becomes a guess.
Pin the version in metadata, and change the skill by changing that string. A folder whose contents move while the name stays still is an unpinned dependency. Review the diff the way you review code, and reject a skill whose description and body disagree about the stop. If the description tells the agent to call a tool and the body walks through the API by hand, the body is the one the model will follow once the skill has loaded.
Score two behaviors separately, with the method in how to build LLM evals. Those two scores are evals, and mixing them hides the failure you can actually fix. Activation asks whether the host loads this skill for the real task and refuses the near-miss.
Adherence asks whether, once loaded, the agent follows the stop, including the instruction to call the MCP tool and not continue on its own. A skill that loads on every prompt, or never loads, fails the first. A skill that loads and then improvises the action fails the second.
What do you review before a skill is installed?
Check the SKILL.md text before you check any script. In a January 2026 snapshot, Yi Liu and colleagues counted 98,380 skills across two public registries, gathered within 3 months of launch, and confirmed 157 malicious skills carrying 632 vulnerabilities. 84.2 percent of those vulnerabilities sat in the SKILL.md file. Executable code accounted for 8.5 percent, and config and other files for 7.3 percent. The confirmed set is 0.16 percent of the full corpus, small enough that a spot check of familiar names will miss it.
One actor, using templated brand impersonation, accounted for 54.1 percent of the malicious skills. A familiar name is not a review. The snapshot covers those two public registries and does not cover private repositories, skills passed around directly, enterprise deployments, MCP servers, or a vendor's curated collection. Neither registry ran a central check. All 157 confirmed skills were removed after disclosure, and removal after the fact is not a control you can install. The next upload is not in that count.
The threat model matches the privilege a skill actually has on the hosts they studied. The host loads the file and runs the scripts as the user. An MCP server is the contrast they draw: that code runs on a machine someone administers, and it can refuse a call.
Treat every third-party skill as supply chain. Keep an internal registry, pin the version, and read the diff when the pin moves. Record the load, the version and the tool call, which is the observability you need before you widen what a skill may do.
Three controls already have their own guides, and this one should not restate them. AI agent sandboxing is the limit once a script runs: a sandbox sized to the task, an allowlist of network destinations, and credentials kept outside that sandbox. AI agent permissions is one action at a time on the MCP tools, because the skill inherits whatever the host can already do.
Prompt injection in multi-agent systems is the same failure prompt injection names inside one file: a line that tells the agent to ignore a check is untrusted text read as an instruction, so check the arguments inside the tool. A prompt rule is not a guardrail you can count on.
How the procedure and the action stay apart
Solarpunk forced the split, and a skill folder does not change it. We built that agent to reach email, calendar, documents and the systems around them, well past a hundred tools. Handing the model the whole registry worked until roughly thirty tools, and then it picked a plausible tool from the wrong system, which is why we stopped giving it the registry.
A planner breaks the goal into steps, and each step searches for a handful of contracts, so the registered set is everything the agent can do. Every tool is a typed contract with inputs, outputs and side effects, and the agent cannot invent access it was not given.
We inject the credential from an encrypted vault on the machine at the moment of the call, so the secret never enters the prompt, and the agent drives a session without learning a password.
On an insurance voice agent we built, the model's output is a request to call a tool and never itself an action, and the disclosure lives in the tool contract so the operation cannot run without it. On a current engagement for a telecom marketing platform, we keep prompts as a user-experience layer, and no policy check depends on them. A SKILL.md line is a prompt that can tell the agent how and still cannot hold the policy.
Skionis is the gate on the action itself: the agent runs against a live AWS account and is untrusted, so every step is machine-checkable or a person reviews it. There is no general shell, and a plan step cannot become an arbitrary API call. The engineer approves a diagram of the change, because at the tenth change of the week a raw template diff does not get read. We also compare the agent's claim of completion with the state of the application, which catches work that was never finished.
Map a skill onto that design without adding a new privilege. The description the host loads, about 100 tokens, is the same idea as searching before you invoke: the model sees a little, then asks for the rest. It is not a permission.
The body is the procedure a step was searching for. The MCP tool is the contract, and the vault still injects the credential. The layer that loads the skill, dispatches the tool and enforces the permission is the harness, which is the work in agent harness engineering.
When should a team skip skills?
Keep a skill private when one person is the only user and no shared credential is in reach. A folder on one laptop, with nothing in it that can touch a shared system, does not need an internal registry or a pinned release. The moment a second person installs it, or it can call a tool that changes a system, the review above applies, and a private file has become supply chain.
Keep the procedure on the server when it already lives as a playbook behind a tool, and when the host would load every skill body at startup. The small metadata load is the reason a catalog stays usable, and a host that ignores it will fill the window with every body you add.
In that host a skill catalog is the old failure, a long prompt full of procedures the task does not need, and the tool behind search, schema and execute is the fix you already have.
Common questions
What is a SKILL.md file?#
A SKILL.md file is the required file in a skill folder. It carries a name and a description the host loads at startup, about 100 tokens, and a body of instructions it loads when a task matches. Keep the body under 5,000 tokens and the file under 500 lines, and put long references in files beside it.
Agent skills vs MCP: which should a team standardise on?#
Use both, and keep the split hard. Put the procedure in a skill the host loads into context, and put governed access on an MCP server that checks a token and holds the credential. A skill that needs a system of record should name the MCP tool and stop, rather than carry a password or a shell.
Are Claude skills the same as Agent Skills?#
Claude skills are the product that first shipped inside Claude Code in October 2025. The open format those files follow opened in December 2025 and was donated to the Agentic AI Foundation on 22 October 2026. A skill written to that format can load in any host that implements it.
Are third-party skills safe to install?#
Treat a familiar brand as a reason to read harder, not as a pass. A January 2026 scan of two public registries counted 98,380 skills and confirmed 157 malicious skills with 632 vulnerabilities. 84.2 percent of those vulnerabilities sat in the SKILL.md file, and 54.1 percent of the malicious skills came from one actor impersonating known brands. Review the file, pin a version, and run any script in a sandbox.
Claude skills vs MCP: where should the workflow live?#
Keep a workflow the agent should find and run on its own as an MCP tool with a typed contract. Use a skill for the instructions that say which workflow fits and when to stop. The skill loads into the host's context and runs with the host's privileges, so it should name the tool rather than hold the credential.
What are AI agent skills?#
AI agent skills are folders of instructions, scripts and references that a host loads into the model's context when a task matches the folder's description. They do not replace an MCP server. The skill tells the agent how to do the work, and the server lets it reach a system under a checked credential.
Further reading
- Anthropic, Donating the Agent Skills standard to the Agentic AI Foundation, 22 October 2026. The donation, the October 2025 and December 2025 dates, the platform count, and the 1 million skills and nearly 280 million installs figures, which are Anthropic's own.
- Agentic AI Foundation, four new projects, 22 October 2026. Agent Skills, Open Responses, OpenEnv and OpenSandbox, and the move from 3 hosted projects to 10. David Soria Parra and Mahesh Murag are named as lead maintainers of the skills project.
- Agent Skills specification. Folder layout, required name and description, experimental allowed-tools, the about 100 tokens and under 5,000 tokens disclosure guidance, the 500 line file guidance, and
skills-ref validate. - Yi Liu, Zhihao Chen, Yanjun Zhang, Gelei Deng, Yuekang Li, Jianting Ning and Leo Yu Zhang, "Do Not Mention This to the User": Detecting and Understanding Malicious Agent Skills in the Wild, January 2026 snapshot, accepted to USENIX Security 2026. The 98,380 skills, 157 confirmed malicious skills, 632 vulnerabilities, the 84.2 percent, 8.5 percent and 7.3 percent breakdown, the 0.16 percent rate, the 54.1 percent brand-impersonation share, the privilege model, and the removal of all 157 after disclosure.
- MCP specification, revision 2026-07-28. A protected HTTP server checks a token on every request.
- The Solarpunk build, the Skionis build and the insurance voice agent build.
- MCP prompts and agent playbooks, MCP tool design, MCP authorization, AI agent permissions, AI agent sandboxing, prompt injection in multi-agent systems and how to build LLM evals.