mech.app

Posted on Sep 6 Originally published at mech.app

Anthropic's Skills Repository: How Claude Loads Dynamic Instructions to Extend Agent Capabilities Without Retraining

Anthropic just open-sourced its Skills repository (174K+ stars, trending #2 on GitHub Python), including the production document-creation skills that power Claude's file capabilities. This is the first public look at how a major AI lab structures reusable, composable agent instructions at scale.

Skills are folders of markdown instructions, scripts, and resources that Claude loads dynamically to extend its capabilities without model updates. This is not fine-tuning, not RAG, and not tool-calling in the MCP sense. It is a runtime instruction-loading pattern that sits between the model's base capabilities and external tools.

What the SKILL.md Format Reveals

Each skill is a self-contained folder with a SKILL.md file. The format structures instructions, metadata, and resources so Claude can load them dynamically:

Instructions: Natural language directives that tell Claude how to complete a specific task in a repeatable way.
Metadata: Name, description, version, and tags that help Claude decide when to invoke the skill.
Resources: Scripts, templates, or reference files that the skill needs to execute.

The SKILL.md format is not a DSL. It is markdown with conventions. Claude parses the structure and loads the instructions into its context window when the skill is invoked. This means the skill's instructions become part of the prompt, not part of the model weights.

Example structure:

# Skill: Create DOCX Document

## Description
Create professional Word documents with formatting, tables, and images.

## Instructions
1. Parse user requirements for document structure
2. Generate document outline with sections
3. Apply formatting rules: headings use Calibri 16pt bold, body uses Calibri 11pt
4. Insert tables with borders and shading
5. Embed images with captions
6. Export as .docx with proper metadata

## Resources
- template.docx: Base template with company branding
- formatting_rules.json: Style definitions for headings, body, tables

The system does not compile or validate these instructions ahead of time. Claude reads them at runtime and interprets them as additional context for the current task.

Boundaries Between Skills and Base Capabilities

The Skills system introduces a new boundary in the agent architecture: when does Claude use a skill versus its native reasoning?

The decision is not explicit. Claude does not have a router that says "if task == document_creation, load docx skill." Instead, the skill metadata and instructions are loaded into the context window, and Claude decides whether to follow them based on the user's request.

This creates three failure modes:

Skill not loaded: Claude attempts the task with base capabilities, producing lower-quality output.
Skill loaded but ignored: Claude reads the instructions but does not follow them, either because they conflict with the user's request or because the base model's behavior overrides them.
Skill loaded and followed incorrectly: Claude interprets the instructions in a way the skill author did not intend.

The repository does not include observability hooks to detect these failures. You would need to instrument your own logging to see when skills are loaded, when they are followed, and when they are ignored.

Production Document Skills: State and Error Recovery

The production document skills (docx, pdf, pptx, xlsx) are source-available (not open source) but shared as reference implementations. These skills handle multi-step workflows with state management and error recovery.

Key patterns:

State tracking: Skills maintain a mental model of the document structure as they build it. For example, the DOCX skill tracks section hierarchy, table positions, and image references.
Error recovery: Skills include fallback instructions for common failure cases. If an image cannot be embedded, the skill inserts a placeholder and logs the error.
Multi-step workflows: Skills break complex tasks into smaller steps with validation checkpoints. For example, the PPTX skill generates an outline, validates it with the user, then creates slides.

These patterns are not enforced by the Skills system. They are conventions that Anthropic's engineers follow when writing production skills. If you write your own skills, you need to implement these patterns yourself.

Trade-offs: Prompt Engineering vs. RAG vs. Fine-Tuning vs. Skills

The Skills pattern sits in a specific niche between other methods of extending agent capabilities:

Method	When to Use	Limitations
Prompt Engineering	One-off tasks, rapid iteration, no persistence needed	Instructions lost after conversation ends, no reusability across sessions
RAG	Knowledge retrieval, factual grounding, large knowledge bases	Retrieval latency, relevance ranking failures, no procedural logic
Fine-Tuning	Behavior change across all tasks, style adaptation, domain-specific reasoning	Expensive, slow iteration, risk of catastrophic forgetting
Skills	Reusable procedures, multi-step workflows, organization-specific tasks	Context window overhead, no guarantees Claude will follow instructions, no versioning or rollback

Skills work best when you need reusable, composable instructions that are too complex for prompt engineering but do not require model-level changes. They fail when the task requires factual knowledge (use RAG), behavior change across all tasks (use fine-tuning), or guaranteed execution (use tool-calling).

Architecture: How Skills Load at Runtime

The Skills system is a context-injection pattern. When a user invokes a skill, the system:

Locates the skill folder based on the skill name or metadata tags.
Reads the SKILL.md file and any referenced resources.
Injects the instructions into the context window as additional system or user messages.
Passes the augmented context to Claude for inference.

This is not a plugin system. There is no skill registry, no version control, and no dependency resolution. Skills are just folders that get loaded into the prompt.

The repository does not include the orchestration code that performs these steps. You would need to build your own skill loader if you want to replicate this pattern outside of Claude's production environment.

Example pseudocode:

def load_skill(skill_name: str, context: dict) -> dict:
    skill_path = f"skills/{skill_name}/SKILL.md"
    with open(skill_path, "r") as f:
        skill_instructions = f.read()

    context["system_messages"].append({
        "role": "system",
        "content": skill_instructions
    })

    return context

def invoke_claude_with_skill(user_request: str, skill_name: str):
    context = {"system_messages": [], "user_messages": [user_request]}
    context = load_skill(skill_name, context)
    response = claude_api.complete(context)
    return response

Observability and Debugging

The Skills repository does not include observability hooks. You cannot see:

Which skills were loaded for a given request.
Whether Claude followed the skill instructions.
How much of the context window the skill consumed.
Whether the skill conflicted with other instructions.

If you deploy skills in production, you need to instrument your own logging:

Skill load events: Log when a skill is loaded, including the skill name, version, and timestamp.
Context window usage: Track how much of the context window is consumed by skill instructions versus user messages.
Instruction adherence: Compare the output to the skill's expected behavior and log deviations.

Without these logs, you will not know why a skill failed or how to improve it.

Security Boundaries

Skills are not sandboxed. If a skill includes a script or resource, Claude can execute it with the same permissions as the user. This creates two attack vectors:

Malicious skills: An attacker could create a skill that exfiltrates data or executes arbitrary code.
Skill injection: An attacker could trick Claude into loading a malicious skill by crafting a user request that matches the skill's metadata.

The repository does not include security controls for skills. You would need to implement your own:

Skill signing: Verify that skills are signed by a trusted author before loading them.
Sandboxing: Run skills in a restricted environment with limited file system and network access.
Input validation: Sanitize user requests to prevent skill injection attacks.

Deployment Shape

The Skills pattern does not prescribe a deployment shape. You can deploy skills in several ways:

Embedded in the application: Package skills with your application code and load them from the file system.
Remote skill registry: Store skills in a remote repository (S3, GitHub, etc.) and fetch them at runtime.
User-uploaded skills: Allow users to upload their own skills and load them dynamically.

Each deployment shape has different trade-offs for latency, security, and versioning. The repository does not include guidance on which shape to use.

Likely Failure Modes

Based on the architecture, these are the most likely failure modes:

Context window overflow: Skills consume too much of the context window, leaving no room for user messages or Claude's reasoning.
Instruction conflict: Multiple skills are loaded with conflicting instructions, and Claude does not know which to follow.
Skill not found: The skill loader cannot locate the skill folder, and the request fails silently.
Resource missing: The skill references a resource (template, script, etc.) that does not exist, and Claude cannot complete the task.
Instruction ambiguity: The skill's instructions are vague or contradictory, and Claude interprets them incorrectly.

None of these failure modes have built-in recovery mechanisms. You need to handle them in your orchestration layer.

Technical Verdict

Use Skills when:

You need reusable, composable instructions for multi-step workflows.
The task is too complex for prompt engineering but does not require model-level changes.
You want to share agent capabilities across teams or users without retraining the model.
You can tolerate non-deterministic execution (Claude may not always follow the instructions).

Avoid Skills when:

You need guaranteed execution (use tool-calling or MCP instead).
The task requires factual knowledge retrieval (use RAG instead).
You need behavior change across all tasks (use fine-tuning instead).
You cannot afford context window overhead (skills consume tokens).
You need versioning, rollback, or dependency resolution (the Skills pattern does not support these).

The Skills pattern is a lightweight way to extend agent capabilities without model updates, but it trades determinism for flexibility. If your use case requires guaranteed execution or strict versioning, you need a different approach.

DEV Community