What an agent skill actually is

A skill is a saved procedure an AI agent can load when it needs to do a particular task. The instructions are readable text. Supporting files can include scripts, references, and templates.

I like the simplicity of this approach. You can inspect what the agent is being told, change it, and keep a record of the changes. You can also share a procedure without building a separate agent for every task.

A procedure the agent can load#

In the Agent Skills format, a skill is a directory containing a SKILL.md file. The file begins with metadata describing its name and purpose, followed by Markdown instructions. Supporting files can hold executable helpers, reference material, or assets.

For example, a skill for preparing a research note could start like this:

---
name: research-note
description: Prepare a research note comparing technical approaches from papers and official documentation. Use for literature reviews and technology comparisons.
---

Read the original sources before summarizing their claims.
Separate reported results from your interpretation.
Use assets/research-template.md for the draft.
Link each factual claim to its supporting source.
Record the hardware, dataset, and baseline behind performance claims.
State what remains uncertain.

This example needs a template and examples of acceptable notes before it would be worth using. The description tells the agent when to load it; the body tells it how to work.

The instructions do not change the model's weights. They become context that guides its behavior. If the skill includes a script, the agent may also run that code in its available environment.

Anthropic's original engineering explanation describes this as packaging procedural expertise for general-purpose agents. The model supplies general capability; the skill supplies a working method.

Why this is more useful than a giant prompt#

The format supports progressive disclosure. An agent initially sees a short description of each skill. It reads the full instructions when a task calls for them, and opens supporting resources as needed. This avoids putting every procedure and reference document into every conversation. Agent Skills specification

The description therefore matters. “Helps with research” gives the agent little basis for choosing it. A description that names the task and when it applies makes selection easier to inspect.

Loading behavior also depends on the agent application. LangChain's October 7 Deep Agents update adds explicit skill pinning, tools that load with a skill, and refreshing the available skill list within a thread. Those are runtime capabilities around the format. Sharing a folder does not ensure every host discovers or executes it in the same way.

Simon Willison's early reaction to skills makes the case for their simplicity and portability. The qualification I would add is that sharing files is easier than making them work consistently in another environment.

Prompts, tools, and skills do different jobs#

A prompt is an instruction or other input given to a model. A skill organizes instructions for a recurring task. A tool gives the agent an operation it can perform. These categories overlap: loading a skill supplies instructions as prompt context, and a skill can be one way to store procedural memory.

An instruction saying “read the paper” does not create a browsing tool. An instruction saying “do not publish” does not enforce permissions. The application must provide access and enforce those boundaries independently of the prose.

Likewise, a skill that includes code depends on the right environment. A portable description is easier to share than a complete working setup with credentials, libraries, and organization-specific APIs.

Where memory fits#

Repeated explanation can have several causes. Sometimes the agent forgot a preference. Sometimes it lacks a current project fact. Sometimes it has never been given the procedure.

LangChain's memory overview distinguishes memory within a conversation from information retained across conversations. It also separates facts, experiences, and procedures. These distinctions are useful design choices rather than a requirement to put everything into a particular database.

The research skill describes how to compare evidence. The current request identifies which papers to compare. A saved preference might specify the reader's technical level. These pieces belong together when the agent works, but they change for different reasons and need not be stored in the same file.

Useful instructions still need evidence#

A skill can be beautifully written and make an agent worse.

The SWE-Skills-Bench preprint tested 49 public software engineering skills against requirement-based tasks. In that setup, 39 produced no pass-rate improvement; some mismatched guidance caused regressions. This does not establish that skills generally fail. It shows why a convincing instruction file is insufficient evidence of benefit.

For the research note, I would compare outputs with and without the skill. Does it preserve the conditions behind a result? Does it distinguish the paper's claim from its own inference? Does it load for a literature review and stay out of an unrelated writing task? The test should tell us whether the skill earns the context and time it consumes.

Code can handle mechanical checks, such as required sections or missing links. The skill can explain when to run those checks and how to respond. There is little reason to make the model reinvent a reliable check on every run.

I would start with one procedure you already know well enough to judge. If the instructions do not improve that task, a larger library will not fix the problem.

Research checked on October 15, 2026. The sample skill is illustrative. Product behavior varies by host and version.