Skills

A skill is a set of instructions (packaged as a simple folder) that teaches an LLM how to handle specific tasks or workflows.

That’s what it fundamentally is. A folder. The folder contains a SKILL.md file (Markdown with YAML frontmatter), along with optional scripts, reference docs, templates, and assets.

When an LLM invokes a skill, the system loads the markdown file, expands it into detailed instructions, injects those instructions as new user messages into the conversation context, modifies the execution context, and continues the conversation with this enriched environment.

Skills extend an LLM’s capabilities by packaging expertise into composable resources for itself. Skills prepare the LLM to solve a problem more efficiently, rather than solving it directly.

Skills can turn general purpose agents into specialized agents that fit custom needs. They achieve this without model retraining. They also help reduce the limitation of limited context windows.

Anthropic helpfully published a 33-page document titled ‘The Complete Guide To Building Skill For Claude’ on Jan 29th 2026. It mentions: ‘Instead of re-explaining your preferences, processes, and domain expertise in every conversation, skills let you teach Claude once and benefit every time.’

Their most powerful current application is in domains with repeatable, rule-governed workflows.

Multiple skills can load simultaneously. They can also automatically stack together when needed for complex workflows. (eg an agent using our fund’s brand guidelines skill, a financial reporting skill, and presentation formatting skill to generate a quarterly investor deck).

Skills are cross-platform. Any model can use them without having any baked-in knowledge. They have high interoperability.

Currently, there is no public skill marketplace. Within LLMs (including Claude), there’s no built-in mechanism for discovering or sharing skills across users.

The precursor to Skills was something developers had already been doing informally: dropping Markdown instruction files into repositories and telling agents to read them before starting work.

It was simple. And yet very powerful and effective. But not yet formalized.

Anthropic was smart enough to formalize this into a ‘skill’. The core architecture was designed by Anthropic engineers (Barry Zhang, Keith Lazuka, Mahesh Murag). A skill was defined as a directory containing a SKILL.md file that contains organized folders of instructions, scripts, and resources that give agents additional capabilities.

The skill-creator skill itself was designed so that Claude creates new skills iteratively through a defined loop (drafting, testing, evaluating, and refining them).

Anthropic defined the loop as:

human describes intent → Claude writes SKILL.md → Claude runs test cases against itself → human reviews → Claude iterates.

On Oct 16th 2025, Anthropic launched Agent Skills (blog release here Equipping agents for the real world with Agent Skills).

On Dec 18th 2025, Anthropic published Agent Skills as an open standard for cross-platform portability.

Let’s break down the three components of a Skills file.

Part 1: Metadata in YAML (stood for Yet Another Markup Language; this isn’t a joke…)

YAML is a human-readable data format introduced in 2001. Its syntax represents structured data associations through indentation, number of spaces, and key-value pairs separated by colons. Eg:

profession: teacher

In Skills, it’s used for configuration and metadata (including key-value pairs, lists, nested structures). It is used as a block of structured metadata at the very top of a Markdown file. It’s fenced by triple dashes —. An example is:

The part between the — delimiters is YAML. Everything below it is regular Markdown body. The Markdown body gives humans readable documentation, instructions, or content.

YAML is designed with readability in mind. It allows expression of complex data in a format that resembles natural language. YAML is easier to comprehend for a brain that thinks in natural language. It’s perfect for LLMs for this use case.

Now let’s assess a more populated SKILL.md. Below is an example for processing PDFs:

The name/title and description fields are the most important. They’re always loaded into the LLM’s context so it can decide when to use the skill.

The description acts as a trigger. It tells the model that if the user says anything matching these patterns, read the rest of this file.” This is why descriptions tend to be detailed and seemingly quite obvious + pushy. They need to catch the right requests.

Part 2: Markdown (MD) body

Note on Markdown: Markdown is a lightweight text formatting language. You’ve likely come across a variety of README files in the past.

In a skills file, the Markdown body is the instruction manual the LLM reads when the skill triggers. It sits below the YAML frontmatter. It contains the step-by-step workflow, commands, file references, error-handling guidance, and examples.

Below is the structure of the Markdown portion (the part that goes under the YAML):

Anthropic mentions the following best practices for this section:

• Every step must include a runnable command or concrete action. “Never “validate the data before proceeding””
• Bundled files should be referenced by exact path (references/, scripts/)
• The SKILL.md should contain only the core workflow (with detailed documentation pushed to a references/ subdirectory)
• Common error messages should be documented with real error messages and fixes. Anthropic’s threshold is anything that fails >10% of the time.
• Examples should mirror actual user trigger phrases from the YAML description

The skill-creator documentation also recommends keeping SKILL.md <500 lines and the markdown body <5k tokens. It also instructs to challenge each piece of information by asking “Does Claude really need this explanation?” and “Does this paragraph justify its token cost?”.

(The 5k token threshold is because performance starts to deteriorate for longer markdown body. This will not be a perpetual problem: I expect Moonshot’s new Attention Residual paper to allow longer, more effective Skills files in the future)

Part 3: (Optional) Linked Files

Additional files are bundled within the skill directory that the LLM can choose to navigate and discover only as needed.

One of Anthropic’s key founding engineers of skills, Barry Zhang, pitches skills as:

• They allow anyone to customize agents with a simple primitive — files
• They give us continuous learning until continuous learning arrives
• They are powerful, composable, and sufficiently AGI-pilled

Skills are powerful when there are repeatable, rule-governed workflows. Especially if they are deterministic (like coding or regulatory compliance).

Before skills, every time a domain-specific output was needed, a user had to either 1. provide the expertise in the prompt, or 2. hope the LLM’s training data covered it. The quality ceiling was often bottlenecked by prompt engineering skill.

After skills, expertise is codified, reusable, and composable. Prompt engineering is democratized. One person / agent writes the skill, and anyone can benefit.

A core limitation of LLMs in professional settings is output reliability. Eg the same model can do a brilliant pdf conversion, or a terrible one, depending heavily on how well the user prompts it. Skills solve this by separating expertise from the interaction. A pdf conversion skill, once written and validated, delivers consistent output regardless of who invokes it.

This also reduces compute use by not requiring repeated prompting (goes from per-session expense to a reusable asset). Ordinary prompts are conversation-level instructions for one-off tasks. Skills persist.

The architectural advantage of skills provides:

• LLM capability expansion without retraining
• Specialization through domain-specific tools (not domain-specific training)
• Modularity
• Faster iteration cycles (by updating the tool without touching the model)

How Triggering Works

The key design philosophy for skills is progressive disclosure with a three-level loading system:

1. Metadata: name + description is always in context. Takes ~100 tokens.
2. SKILL.md body: loads on trigger
3. Bundled resources: bundled scripts/references only get read when actually needed. scripts can execute without ever being read into context.

Only the skill’s metadata (~100 tokens) sit in the agent’s working memory at all times. The full instruction body loads only when triggered. When a user’s message matches the patterns described in a skill’s description, the system loads the full SKILL.md body into context. Bundled resources load only when the agent determines it needs them.

This progressive disclosure keeps the LLM’s context window lean until it needs the detail. This minimizes token usage while maintaining specialized expertise.

The following diagram shows how the context window changes in Claude when a skill is triggered by a user’s message.

To start, the context window has the core system prompt, the metadata for each installed skill, and the user’s initial message. The user asked about a PDF, which causes Claude to trigger the PDF skill and use a tool to read the PDF SKILL.md.

After asking Claude many times to reverse-engineer itself, it showed me how it uses skills:

“You can see this in my own behavior right now: my system prompt contains an <available_skills> block listing each skill’s name, description, and file path. When you ask me to create a Word doc, I read /mnt/skills/public/docx/SKILL.md before writing any code. That SKILL.md tells me to use docx-js (not python-docx), to validate output, to use specific XML patterns — knowledge I wouldn’t reliably have otherwise.”

Skills are not a panacea.

They work best for deterministic workflows with clear success criteria. Messy, judgement-heavy work (where the right answer depends on nuanced context) can’t be one-shot automated.

The new open standard also creates an attack surface. This is a new security vulnerability. Skills are executable instructions that modify agent behavior. A malicious or compromised skill could cause an agent to hallucinate specific outputs, extract data through crafted tool calls, or bypass safety guardrails.

There is also a time-based limitation (a temporal limitation; I love using this word). Skills represent expertise at that point in time. But technology and regulations evolve. A model is designed to read a skill, not audit it. A particular skill may become outdated in time. If triggered, it will produce a confidently wrong outcome. A future framework for maintaining and updating skills at scale will require its own infrastructure and compute overhead. This is a problem that compounds as the ecosystem expands.

Anthropic’s Skills docs also note that the feature is not eligible for Zero Data Retention. Anthropic does not allow you to keep them private from them. I wager that they grow their skills inventory from user-generated skills to iteratively improve Claude. (Unlike skills, Claude Code is eligible for Zero Data Retention). The lack of ZDR is also a negative for enterprise customers wanting to use skills.

Anthropic published the Skills specification as an open standard on Dec 18th 2025.

Skills are cross-platform by design. They have high interoperability. Any model can use them without having any baked-in knowledge.

Skills are moving beyond a local developer feature into an ecosystem layer. Organization-wide skill management is the natural next step.

That said, there is currently no public skill marketplace. Within LLMs (including Claude), there’s no built-in mechanism for discovering or sharing skills across users. The open standard defines what a skill is, but not how to find one. Anthropic already ships pre-built skills for common document workflows.

OpenAI initially took a different approach with Custom GPTs and its function-calling architecture. It achieves similar outcomes but with tighter coupling to the OpenAI ecosystem. By Dec-2025, OpenAI had already adopted the Agent Skills standard itself (in both Codex CLI and internally in ChatGPT).

The open-source community (eg frameworks like LangChain and CrewAI) has adopted skill-like patterns but without the progressive disclosure optimization that makes Anthropic’s implementation token-efficient.

This dynamic may follow the broader software industry’s recurring pattern of proprietary platforms losing ground to open standards over time (eg proprietary messaging protocols to AMQP/MQTT).

Anthropic’s Defensability

Anthropic hasn’t given away all the secret sauce behind Skills. The runtime layer remains proprietary and defensible. Skill quality depends not only on what is written in the file, but on whether the model activates the right skill at the right time, with the right tools + context.

This orchestration layer (triggering activation quality, context management, permissions, execution environment) remains proprietary and platform-specific.

This is where switching costs accumulate. Proprietary runtimes can compound them through richer extensions, admin tooling, and tighter tool integration.

Claude Code also extends switching costs with proprietary features such as invocation control, subagent execution, and dynamic context injection.

The Claude Code leak was a pleasure for me. Let me focus on what more it has revealed about Skills.

It proves Anthropic’s Skills system is a foundational subsystem inside Claude Code. Skills are woven into the command registry, tool execution layer, plugin ecosystem, agent orchestration system, telemetry pipeline, and forward-looking product roadmap.

The codebase’s Feature Inventory describes Skills plainly as “Reusable prompt templates (commit, review, init, etc.)”

Skills are executable through a dedicated SkillTool in the 45+ tool ecosystem, described as “Execute skill prompts in forked agents.” This means skill execution is not inline. It spawns an isolated sub-agent with its own context window, runs the skill prompt within that agent, and returns results. This provides 1. parallelism, and 2. fault isolation.

How Skills Are Distributed

The codebase shows that Skills are distributable through the plugin marketplace system. Each plugin can bundle skills, hooks, and MCP servers. Any 3P plugin can package and ship its own skill definitions alongside hooks and MCP server configurations. The plugin ID format ({name}@builtin for built-in, marketplace ID for external) confirms this dual-channel distribution.

The EXPERIMENTAL_SKILL_SEARCH flag indicates an in-development remote skill registry. This is a precursor to a public marketplace.

The structure is similar to the extension marketplace model that propelled Microsoft VS Code to dominance. The difference is that it operates at the agent-orchestration layer rather than the IDE layer.

Apple’s App Store (launched 2008) and Google’s Play Store (launched 2012) built on earlier developments to pioneer the ‘everything is a plugin’ model. Skills will likely follow a similar trajectory.

The Claude Code leak shows there is also a meta-skill (skillify) which enables users to create new skills from within the CLI (the terminal on your computer), further lowering the barrier to skill ecosystem growth.

Telemetry Integration

Skills have deep telemetry integration. Every skill invocation is tracked as a first-class (priority) analytics event across Datadog and OpenTelemetry (60+ tracked event types). Anthropic can measure adoption, latency, failure rates, and usage patterns per-skill. This enables usage-driven prioritization.

Skills Relationship To The Claude Code Agent Orchestration Stack

Skills sit within a broader agent orchestration hierarchy revealed by the codebase. The AgentTool provides general-purpose sub-agent spawning. The SkillTool specializes this for skill-specific prompt execution. And the feature-flagged COORDINATOR_MODE and TEAMMATE_MODE systems suggest a future in which skills can be distributed across multiple coordinated agents. This is a swarm architecture where different agents execute different skills in parallel on a shared codebase.

The 13 Bundled Skills With Claude Code

The leaked code reveals 13 named skills bundled directly with Claude Code. They’re split into three tiers: production skills, utility/testing skills, and feature-gated experimental skills tied to unreleased product capabilities.

Production Skills shipped with Claude Code:

Skill Name	Purpose	Category
updateConfig	Configure Claude Code settings programmatically	Configuration
keybindings	Customize keyboard shortcuts via structured prompts	Configuration
remember	Manage persistent file-based memory across sessions	Memory
simplify	Refactor and simplify code	Code Quality
batch	Execute batch operations across multiple files	Automation
stuck	Diagnostic help when the agent encounters blockers	Recovery
skillify	Meta-skill: create new skills from within the CLI	Ecosystem

Swipe to see more →

Utility / Testing Skills shipped with Claude Code

Skill Name	Purpose	Category
verify	Run test verification workflows	Testing
debug	Structured debugging assistance	Diagnostics
loremIpsum	Generate test/placeholder content	Testing

Swipe to see more →

Feature-gated Skills shipped with Claude Code

Skill	Feature Gate	Purpose	Strategic Implication
dream	KAIROS	Proactive background task execution without user prompting	Autonomous agent that monitors repos, suggests actions via GitHub webhooks
hunter	REVIEW_ARTIFACT	Deep automated bug hunting (15-20 min review cycles)	Quality assurance automation that competes with dedicated code review tools
loop	AGENT_TRIGGERS	Recurring/scheduled task execution	Persistent agent. Claude as always-on infrastructure, not session-bound

Swipe to see more →

I am creating a deeper report on the full Claude Code leak. It’ll be with you as soon as complete.

← The Library