Agentic skills: How they work, when to use them, and where they fail

When the agent needs stable know-how, a workflow, and a way of approaching specialized tasks, a skill is simpler and cheaper because the knowledge holds for weeks and needs no separate runtime. A skill describes how to think about a problem, while model context protocol (MCP) and tools perform the task.

An agent skill is a directory generally containing a SKILL.md file¹, which holds metadata and instructions, plus optional scripts, reference documents, and assets the agent loads only when a task calls for them. This skill structure is the same whether you use a pre-built skill² or a custom skill you write yourself. 

• The metadata is a short block of front matter with a name and a description. 

• The body is the procedural knowledge: the steps, the workflow, and the specialized knowledge an artificial intelligence (AI) agent needs to perform a specific task the same way each time. 

A document-handling skill might bundle a PDF skill alongside a script that fills forms, so the agent reads the instructions first and runs the code only when necessary. The same idea holds whether a Claude skill runs inside a chat interface or a skill you upload through the Claude API runs in a coding agent.

A note on scope. Agent skills are not a Claude-only feature. Anthropic introduced the format and then released it as an open standard³ in December 2025, published at agentskills.io, and it has since been adopted across a range of agent products, so a skill built once can run on any client that supports the specification. This guide uses concrete examples from specific platforms, Claude among them, because they are the most fully documented today, not because the concepts stop at any one vendor. Where a detail is implementation-specific rather than part of the shared standard, the text says so. A naming note helps newcomers searching older material: one major framework renamed its "skills" to "plugins,"⁴ so tutorials using the old term describe the same idea under a different word.

While it may seem like a skill is just markdown, the structure has benefits. A static prompt sits in context whether the agent needs it or not, but a skill advertises itself through its description, loads its full instructions when a task matches, and reaches for bundled scripts and resources only when it executes. That staged loading, often called progressive disclosure, means you pay only for the capability in use, rather than paying for every capability on every turn.

Skills are programmable context that are reusable, extending agent capabilities across many tasks. 

Skills vs. MCP vs. tools vs. functions: The decision that matters most

AI agents have several abstractions. How do you decide which one to use? The terms blur together: an agent skill, an MCP server, a tool, a function. Each does something different.

The first question to ask is: Does the data change between invocations? When an AI agent needs live data or an external action, a connected tool or an MCP server is the right choice, because those abstractions provide a more consistent answer than natural-language instructions, and they fetch what is current. The tool is not fully deterministic end to end, because the model still chooses which tool to call and generates the arguments, but once invoked, the tool runs the same way each time. 

Other factors to consider include latency, authentication, cost, observability, and side effects. The most-cited guideline: use a tool when the data changes between invocations, and a skill when the procedure stays the same. It scales from one agent to a fleet of specialized agents, and from one task to complex workflows that chain many tasks.  

MCP and skills aren’t mutually exclusive. A skill carries the procedural knowledge and the reasoning steps, and MCP or a tool supplies the live data and the execution. Think of them as layers: one for instructions and one for action. 

The roles should be clearly separated: 

• CLAUDE.md provides project context and explains why things are done a certain way

• Skills explain how to do specific tasks

• Commands or other explicit triggers perform actions that change files or systems

How skills load

A skill loads in several stages, and understanding those stages explains when and why the skill gets activated. Many skill systems are designed to expose lightweight metadata first and retrieve fuller instructions only when relevant.

• At startup, the agent reads the name and description of each available skill, which costs almost nothing and tells the agent what exists. 

• If a task matches a skill, the agent reads the corresponding SKILL.md file and makes its instructions available to the model.

• When the instructions point to a reference file or a script, the agent reads or runs that resource on demand. 

The exact mechanics vary by platform, because routing, ranking, and context selection differ and some systems preload more than metadata, but the staged shape is common. This is why you can have a large library of skills without using much context: the agent holds the metadata for all of them and the full instructions for only the few in use.

However, skills are natural-language instructions, which means an AI agent may misread, ignore, or misapply them in ways a function call cannot. People expect a skill to work like an API, when it doesn’t. In fact, even explicit instruction may not force the load. Sometimes, agents instructed to use several skills load only a few of them, because a retrieval and scoring step⁵ weighs relevance against a context budget and overrules the instruction to save room. 

If a skill needs to run every time and run the same way each time, that means you should use a tool or an MCP server instead. Skills make behavior more reusable and structured, but because they themselves are AI, they aren’t predictable. They give you flexible, reasoning-driven behavior, not guaranteed execution, and it’s important to know which one a task needs. 

Writing a useful description 

The description field decides whether a skill runs. The description is not a summary of what the skill does, but a specification of when to invoke it, including a decision condition the agent evaluates against the task.

For example, a description of 'Handles billing library usage' doesn't trigger well, because it states a topic rather than a condition. 'Use when writing code that touches the billing library' works better, because it gives the agent an explicit situation to match. Front-loading the use case and the trigger words matters because some clients shorten descriptions under a budget, and a description that has its condition first keeps its trigger in this case. Other requirements include: a name in lowercase with hyphens, a description under roughly 1,000 characters, no reserved words, and no markup.

The description is the most important part for anyone building skills. A capable skill with a vague description is invisible, and all the work in the instructions and scripts behind it never runs. A modest skill with a precise description runs when it should.

When skills fail: How to troubleshoot

The biggest problem with agent skills is that they fail without saying so. There is no error, no stack trace, and no signal that anything went wrong, just a skill that should have run and did not. Here are some common problems:

• A skill that never loads. The usual causes are a wrong path, file permissions the agent cannot read, a session that needs restarting before it picks up a new skill, or a packaged skill with a folder double-nested inside its archive so the SKILL.md sits one level too deep. 

• A skill that loads but does not trigger on a matching request. This is from the description and relevance scoring. 

• Truncation. The combined descriptions of many skills exceed an internal character budget, so some get stripped, and the affected skills go quiet with no way to tell from the outside. This happens with large skill libraries; resolve it by raising the budget through an environment setting. 

• Formatting damage. An autoformatter rewrites a single-line description into multiple lines and breaks the frontmatter; keep the description on one line and mark it to be left alone. 

• Staleness. This doesn’t fail, but it produces wrong output because markdown does not update itself and a skill gives instructions that no longer hold.

In summary:

• Check the path and permissions

• Restart the session

• Check the description

• Watch for the truncation ceiling

• Confirm the skill is still relevant

Authentication, secrets, and what to build

One limitation skills have is a lack of authentication features. Skills carry no built-in mechanism for OAuth or credential handling the way a connected MCP server does. A skill is instructions and optional code; it has no native concept of a token exchange. That limits workflows that need to reach a protected third-party API. 

It’s a bigger problem for hosted web interfaces. On some hosted web chats, for instance, there is no way to supply environment secrets to a skill, which means a skill that depends on a credential cannot run there. Network access varies by platform in a way that determines what is buildable. In some hosted products, skill code runs with restricted network access, reaching only a short list of package and code-hosting domains. 

On the agent's own machine, an AI coding agent runs skill code with the same access any program on that machine has. Through some APIs, skill code has no network access. The same SKILL.md therefore behaves differently depending on where it executes, so an AI agent skill that calls an external AI tool needs a mechanism that permits the call. Treat these as examples of how capabilities differ, and confirm the behavior on the platform you are targeting.

This means matching the skill to the interface before building it. A skill that needs live authenticated calls belongs where it can reach the network and hold a credential, which usually means pairing it with a tool or an MCP server that owns the auth, not asking the skill to carry secrets it was never designed to hold. Knowing this in advance avoids building a skill that cannot run where it is needed.

The security reality: Empirical risk in the skills ecosystem

Because a skill ships executable behavior next to its instructions, security is important. A vendor audit by Snyk, published February 2026, scanned 3,984 published skills from two registries and found that 36.8% carried at least one security flaw⁶, and 13.4% carried a critical-level issue. Moreover, 76 contained malicious payloads; of those confirmed malicious skills, 91% paired the payload with traditional malware patterns alongside prompt injection. 

A separate academic analysis (Liu et al., January 2026) used static analysis plus model-based classification across 31,132 skills and found 26.1% contained at least one vulnerability⁷ spanning 14 patterns, with data exfiltration (13.3%) and privilege escalation (11.8%) most common, though authors said this could be attributed to negligence rather than malice. 

A third investigation traced a large block of malicious entries in one marketplace to one coordinated campaign⁸, which indicates the registries are already targeted at scale rather than by isolated bad actors. 

Numbers differ by scanner and scope, but the point is skills could have security issues and should be verified before you trust them. NVIDIA recommends that skills move through a pipeline that scans them for both conventional software risks and agent-specific ones,⁹ such as prompt injection and hidden instructions, signs them cryptographically so a download can be checked for tampering, and documents each with a machine-readable card describing ownership, dependencies, and known limitations. An agent can load the card alongside the skill, so the trust check happens once at the source rather than through a manual audit on every install.

For anyone deploying skills, this means. Audit a skill's contents before use, including the instructions and the scripts and the bundled files, and prefer skills with clear provenance over anonymous ones. For any skill that performs a destructive or irreversible action, turn off automatic invocation where the platform supports it so the agent cannot run it just because a question sounded relevant. A skill that runs itself is the property an attacker, or an unlucky phrasing, exploits.

Do you even need a framework? 

Before choosing an agent framework, make sure you need one. Some teams run agents on custom code with no framework, because the abstraction a framework provides also includes challenges such as breaking changes between versions, behavior hidden behind layers you cannot see into, and a learning curve. 

When a framework is needed, pick it by the dominant constraint rather than by popularity. If the work needs fine control over state and branching, a graph-oriented framework fits. If the priority is getting role-based agents running fast, a lighter framework reaches a first working agent in fewer lines. If the interaction is conversational among multiple agents, a framework built for that suits it. If the deployment is enterprise and tied to a particular platform, the framework aligned to that stack works better. Abstractions are not interchangeable, and matching the abstraction to the dominant need saves time. 

Another way to look at it is to decide the evaluation pipeline, observability, and the failure-recovery path first rather than the framework, so the framework sees what the agent is doing.

The architecture production teams converge on

Most production teams combine skills and MCP. A skill holds the reasoning and the procedural knowledge, the way to think about a class of problems, while an MCP server or tool supplies the live data and the execution. 

How do you know when your app has outgrown skills?

• Data that changes between invocations

• A need for authenticated calls

• A requirement that a step run every time and run exactly

Each points toward adding a tool or an MCP runner beneath the skill. 

Subagents work the same way. The main skill hands each one a specific, well-defined part of the task to complete. How these pieces fit together is a little more complicated. 

When multiple skills combine, they may act unpredictably. The more active skills there are, the more likely that this could happen. That is why it is important to keep the set small and deliberate rather than install every available skill. Expanding AI capabilities by adding skills indefinitely tends not to work as well, because it’s more likely that the wrong skill will run. 

The benefit is knowing where you're headed from the beginning. If a team knows the long-term design will separate skills from the component that executes them, it can build that separation into the first version instead of having to add it later after a problem exposes the need.

Distribution, versioning, and the missing package manager

Distributing and maintaining skills is also challenging. Each skill is stored in its own directory and can be available at the repository, user, machine, or system level.

Packaging several together into a plugin is the current way to ship a set. 

That covers authoring and local use, but does not include maintenance. A skill pulled from a code host does not update itself, so a fix at the source does not reach the copies already installed, and there is no standard way for an author to update, publish, or charge for what they built.

Practitioners with large libraries want a package manager with an install command that fetches a skill by name and tracks its version, and authors with thousands of published skills want a way to maintain and monetize them. But until that standard arrives, skills get distributed through code hosts and manual updates, which doesn’t scale well. 

This means that, so far, you have to handle versioning and updates yourself. Pin the versions you depend on, track where each skill came from, and plan for the maintenance burden to grow with the count, because skills don’t yet have standardized tools for it.

A track for non-developers

Skills don’t have to be only for developers. Non-developers often have the most repeatable workflows to capture. A skill does not require code. At its simplest, it is a name, a precise description that says when to use it, and a set of instructions written in plain language, which is enough to package a recurring task. Non-developers can build skills that work without writing any code.

Where do you start? Pick a workflow you repeat, write the steps as you would explain them to a new colleague, and lead the description with the condition that should trigger it. The same rule that governs developer skills governs these: the description is the decision condition, not the summary, and a clear "use when" is what makes the skill run. 

That said, remember the authentication challenges. A skill in a hosted web interface cannot hold secrets or reach arbitrary services, so the workflows that fit are ones built on reasoning and instructions rather than on authenticated calls to outside systems. 

Quick-reference decision summary

On which abstraction to use:

• Does the data change between invocations? Stable know-how belongs in a skill, live data or external action belongs in a tool or an MCP server, and the production answer is usually both, with the skill describing the workflow and the runner doing the work. 

• Where should logic be stored? Declarative context describes what and why, a skill describes how, and a side-effect action sits behind a trigger with automatic invocation turned off.

On why a skill failed: 

• Check the path and the file permissions

• Restart the session so the skill is picked up

• Read the description as a trigger condition rather than a summary

• Watch for the truncation ceiling that strips descriptions at scale

• Confirm the skill has not gone stale

On whether to trust a skill:

• Audit its full contents before installing

• Prefer clear provenance and a signature over an anonymous download

• Disable automatic invocation for anything destructive

Aerospike and agent skills

This is where infrastructure comes in. An agent skill describes how to think about a problem, but when that reasoning needs current state, such as a fraud check against a live profile, an inventory lookup, or a session that has to reflect what happened a second ago, the work moves to the runner beneath the skill, and the runner is only as reliable as the data layer it reads from. 

Infrastructure cannot make an agent reason correctly. What it determines is whether the agent still works correctly when many agents query at once and a slow read becomes a stalled decision. 

Aerospike is built for that. It’s a distributed database designed for low-latency reads and writes at high throughput, like when an agentic AI system has to act on live data. Production examples include an MCP server answering natural-language queries against a live graph, and a runner that owns persistent agent state by pairing the skill with a memory store rather than asking the skill to carry it. 

The skill carries the procedural knowledge, but the data platform under it keeps the answer both fast and current when the system is under load.