Meta Description: A deep technical dive into the Agent Skills standard, SKILL.md format, LangChain DeepAgents, and Claude Code Plugins — the emerging ecosystem redefining how AI agents share and reuse capabilities in 2026.

The Agent Skills Standard: How SKILL.md Is Becoming the package.json of AI Agents

---

Table of Contents

1. Why Agent Composability Is the 2026 Engineering Problem
2. What Is the Agent Skills Standard?
3. Anatomy of a SKILL.md File
4. Progressive Disclosure: Solving Context Bloat
5. The Ecosystem: 15+ Platforms, One Standard
6. Building Your First Agent Skill
7. Claude Code Plugins: Distributing Skills at Scale
8. LangChain DeepAgents: The Batteries-Included Harness
9. Sub-Agent Orchestration with Skills
10. Production Considerations: Security, Testing, Versioning
11. The Future: Agent-to-Agent Skill Discovery
12. Conclusion

---

1. Why Agent Composability Is the 2026 Engineering Problem

Here is a scenario every engineer building with AI agents encounters within the first week: you build a great agent that knows how to query a PostgreSQL database. Then you build another that knows how to parse PDFs. Then a third that understands your internal API style guide. And then you realise — these agents cannot talk to each other, share what they know, or reuse any of that hard-won prompt engineering.

You end up with the agent equivalent of copy-pasting functions across codebases.

This is not a minor inconvenience. It is the central scalability problem of the agent era. As teams move from one-off AI experiments to production systems with dozens of specialized agents, the absence of a standardized packaging format for agent behaviors becomes a genuine blocker. Engineering time gets burned duplicating context-loading logic. Systems become fragile. Prompt engineering wisdom dies in private repositories.

The industry has known this problem existed. In 2026, it finally has a credible answer: the Agent Skills standard, built around a single, deceptively simple file — SKILL.md.

This post is a deep technical walkthrough of the standard: how to write skills that work across every major platform, how LangChain's new DeepAgents harness uses them for production-grade context management, how to package them into distributable Claude Code plugins, and what architectural patterns make multi-agent systems composed of skills reliable at scale.

---

2. What Is the Agent Skills Standard?

The Agent Skills standard is an open specification maintained at agentskills.io that defines a portable format for packaging reusable AI agent capabilities. The core premise is elegant: a skill is a directory containing a SKILL.md file, optionally accompanied by scripts, reference documents, and templates.

The analogy to traditional software packaging is precise:

Concept	Traditional Software	Agent Skills
Packaging unit	npm package / Python wheel	Skill directory
Manifest file	package.json / pyproject.toml	SKILL.md (YAML frontmatter)
Registry	npm / PyPI	Plugin marketplaces (Claude, GitHub, etc.)
Consumption	import / require	Loaded into agent context at invocation
Versioning	semver tags	metadata.version + Git tags

The key distinction from prior art like monolithic system prompts or CLAUDE.md files is portability and progressive loading. A skill written once is designed to work across any compliant agent runtime — from Claude Code to GitHub Copilot to LangChain DeepAgents to Gemini CLI. The runtime handles when to load the skill and how to inject it into context; the skill author just writes good instructions.

The standard was seeded by Anthropic's work on Claude Code's slash-command system, then opened up and ratified as a cross-vendor specification. Today it is the de-facto standard across the 2026 AI coding-agent ecosystem — with every major AI vendor shipping a compliant implementation.

---

3. Anatomy of a SKILL.md File

Every SKILL.md file follows a strict two-part schema: YAML frontmatter delimited by --- fences, followed by Markdown instructions for the agent body.

3.1 The Frontmatter Schema

---
name: pdf-processing          # Required. Max 64 chars. Lowercase letters, numbers, hyphens only.
description: >                # Required. Max 1024 chars. What it does AND when to use it.
  Extracts text and tables from PDF files, fills PDF forms, and merges 
  multiple PDFs. Use when working with PDF documents or when the user 
  mentions PDFs, forms, or document extraction.
license: Apache-2.0           # Optional. License name or reference to bundled file.
compatibility: >              # Optional. Max 500 chars. Environment requirements.
  Requires Python 3.12+, pdfplumber, and pypdf installed in the environment.
  Network access required for fetching remote PDFs.
metadata:                     # Optional. Arbitrary key-value mapping for tooling.
  author: your-org
  version: "2.1"
  domain: document-processing
allowed-tools: read_file write_file bash   # Optional (experimental). Pre-approved tools.
---

Let's break down the constraints that matter in practice:

name: Must match the parent directory name exactly. This constraint enforces filesystem consistency and enables deterministic skill lookup. Only lowercase letters, numbers, and single hyphens are permitted — no consecutive hyphens (--). This naming convention will feel familiar to anyone who has worked with npm package names.

description: This field does double duty. It is both human documentation and the activation signal the agent runtime uses to decide whether to load this skill. Write it as a semantic trigger: include the task domain, specific actions, and user-facing keywords the agent should match. A description that says "Helps with PDFs" will get ignored. A description that says "Use when the user mentions PDFs, extracting text from documents, filling forms, or merging files" will activate reliably across every compliant runtime.

compatibility: Often omitted, but critical for skills that depend on system tools, external APIs, or specific runtimes. Be explicit here — a skill that silently fails because pdfplumber is not installed is far worse than one that never activates.

allowed-tools: An experimental field that declares which tools this skill is pre-authorized to use. Runtimes can use this to enforce least-privilege execution — only the tools the skill needs are available during its execution window.

3.2 The Instructions Body

After the frontmatter, the Markdown body is what the agent reads and executes when the skill is activated. High-quality skill instructions follow a pattern that mirrors good API documentation: a brief overview, then step-by-step instructions, then edge case handling.

---
name: code-review
description: >
  Perform a thorough code review on a diff or file. Use when the user asks 
  to review code, check for bugs, audit a PR, or evaluate implementation quality.
license: MIT
---

# Code Review Skill

## Overview
This skill guides you through a structured code review covering correctness,
security, performance, and maintainability.

## Instructions

### Step 1: Parse the scope
Identify what changed. Ask the user for the diff, PR URL, or file path if not
already provided. Use `read_file` to load relevant files.

### Step 2: Run the review checklist
For each changed file, evaluate:
- **Correctness**: Does the logic match the stated intent? Edge cases covered?
- **Security**: SQL injection, path traversal, improper auth, secret exposure?
- **Performance**: O(n²) loops over large data, unnecessary DB calls in hot paths?
- **Maintainability**: Is the code readable? Are abstractions at the right level?

### Step 3: Format findings
Output findings grouped by severity:
1. 🔴 **Critical** (must fix before merge)
2. 🟡 **Warning** (should address)
3. 🟢 **Suggestion** (nice to have)

### Step 4: Summarize
End with a one-paragraph verdict and a clear merge recommendation.

3.3 Supporting Files

The skill directory can include three optional subdirectories:

code-review/
├── SKILL.md                         # Required
├── scripts/
│   └── fetch_pr_diff.py             # Executable helpers the agent can run
├── references/
│   ├── security-checklist.md        # Reference documentation
│   └── style-guide.md
└── assets/
    └── review-report-template.md    # Output templates

These files are not loaded into agent context at startup. They only enter context when the active skill's SKILL.md instructions explicitly direct the agent to read them. This is the progressive disclosure mechanism — and it is the most important engineering decision in the entire standard.

---

4. Progressive Disclosure: Solving Context Bloat

This is the most important architectural innovation in the Agent Skills design, and it is worth understanding in depth before you start building.

The naive approach to giving an agent domain expertise is to dump everything into the system prompt. One big SYSTEM_PROMPT.md that contains all your instructions. This approach breaks down fast: at 10 skills, you are burning 20,000–50,000 tokens of context before a single user message arrives. At 50 skills, you have exceeded most models' effective reasoning budget for actual task work. And every single skill pays its full token cost, even on tasks that touch none of them.

The Agent Skills standard solves this with a three-level lazy-loading pattern:

Level	What loads	When
Level 1 — Metadata	name + description from frontmatter only	Agent startup, for every configured skill
Level 2 — Instructions	Full SKILL.md body	When the skill is activated for the current task
Level 3 — Resources	scripts/, references/, assets/ files	Lazily, only when the SKILL.md instructions reference them

In practice, Level 1 for a library of 50 skills costs roughly 2,000–5,000 tokens — a manageable flat overhead regardless of skill count. A skill activation (Level 2) typically costs another 500–3,000 tokens. Level 3 resources only load on the specific code paths that need them.

The analogy to software module loading is exact: you import a module's exported type signature at compile time (Level 1), load the actual bytecode when the module is first called at runtime (Level 2), and lazy-load its heavy data dependencies only on the specific code paths that trigger them (Level 3).

In the LangChain DeepAgents implementation, this is handled by SkillsMiddleware as part of the agent's execution stack:

1. Discovery (Level 1): At agent start, the middleware scans all configured skill paths, parses each SKILL.md frontmatter, and injects name+description pairs into the system prompt as a structured "available skills" directory.
2. Invocation (Level 2): When the agent's reasoning identifies a skill as relevant to the current task, it reads the full SKILL.md body and injects it into the active context window.
3. Resource access (Level 3): The LLM reads supporting files when the skill instructions direct it to — there is no special middleware for this layer; the agent uses its standard file-reading tools.

The agent never explicitly "calls" a skill like an API. It recognises from the description that a skill is relevant, activates it, and follows its step-by-step instructions — the same way a developer reads a function's docstring to decide whether to use it, then reads the implementation when they need to understand a subtle detail.

---

5. The Ecosystem: 15+ Platforms, One Standard

The adoption velocity across the agent ecosystem in 2026 is remarkable. Here is the current list of platforms with native SKILL.md support:

Coding Agents & IDEs:

• Claude Code (Anthropic) — full plugin + skill marketplace with /plugin install
• GitHub Copilot — Agent Skills via .github/copilot/skills/
• VS Code — native agent skills in Copilot Chat agent mode
• Cursor — skills for project-specific agent context
• JetBrains Junie — built on IntelliJ Platform with full skill integration
• Amp (ampcode.com) — frontier coding agent with skills
• OpenCode — open-source terminal agent (MIT licensed)
• Autohand Code CLI — ReAct pattern agent with skills
• Firebender — Android-native coding agent with multi-agent skills
• Goose (Block/Square) — open-source extensible agent

Agent Frameworks:

• LangChain DeepAgents — native skills= parameter in create_deep_agent()
• OpenHands — cloud-scale coding agent platform
• Mux (Coder) — parallel agent runner for isolated workspaces
• Letta — stateful agents with memory + skills integration
• ZeroClaw Labs — Rust-first local agent runtime (open-source)

AI Assistants:

• ChatGPT + Codex (OpenAI) — skills for the Codex coding agent
• Gemini CLI (Google) — terminal agent with full skill support
• Claude (claude.ai) — skills via the Anthropic platform API

The cross-vendor ratification of this standard is unprecedented in the AI tooling space. The fact that OpenAI, Google, Anthropic, Microsoft/GitHub, and JetBrains all ship compliant implementations means any skill you write today is immediately portable across the entire ecosystem. A SKILL.md you write for your Claude Code workflow works in Cursor, Gemini CLI, GitHub Copilot, and LangChain DeepAgents without modification.

That is the npm moment for AI agents.

---

6. Building Your First Agent Skill

Let's build a production-quality skill from scratch: a db-query-assistant that helps agents safely query PostgreSQL databases.

6.1 Directory structure

mkdir -p db-query-assistant/{scripts,references,assets}

6.2 The SKILL.md

---
name: db-query-assistant
description: >
  Safely query PostgreSQL databases, write optimized SQL, explain query plans, 
  and audit queries for correctness and performance. Use when the user asks to 
  query a database, write SQL, debug slow queries, inspect table schemas, or 
  troubleshoot query performance.
license: MIT
compatibility: >
  Requires PostgreSQL client (psql) or Python asyncpg/psycopg2 in the environment.
  DATABASE_URL environment variable must be set.
metadata:
  author: your-org
  version: "1.0"
  domain: database
allowed-tools: bash read_file write_file
---

# DB Query Assistant

## Overview
This skill helps you interact with PostgreSQL databases safely and efficiently.
Follow these steps for every database interaction.

## Instructions

### Step 1: Understand the schema first
Before writing any query, inspect the schema:

sql
-- List all tables in the public schema
SELECT tablename FROM pg_tables WHERE schemaname = 'public' ORDER BY tablename;

-- Inspect a specific table's columns
SELECT column_name, data_type, is_nullable, column_default
FROM information_schema.columns
WHERE table_name = 'your_table'
ORDER BY ordinal_position;

### Step 2: Write safe, parameterized queries
**Mandatory rules — never skip these:**
- Always use parameterized queries. Never concatenate user input into SQL strings.
- Add LIMIT clauses on exploratory SELECTs (default: 100 rows maximum).
- Run EXPLAIN ANALYZE before executing expensive queries on tables > 100k rows.
- Prefer CTEs over subqueries for multi-step logic (improves readability and plan caching).

### Step 3: Explain the query plan when needed
For any query that scans a large table, run:

sql
EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)
;

Read `references/query-plan-guide.md` for interpreting EXPLAIN output.

### Step 4: Format and return results
Return results as a markdown table with:
- A header line showing the row count
- Column names as table headers
- Cell values truncated to 80 characters
- A one-sentence summary of the result

## Error handling
- `relation does not exist` → list available tables and ask for clarification
- `permission denied` → explain the restriction; do not attempt privilege escalation
- Query timeout → suggest an index before retrying

python

6.3 The safe execution helper (scripts/execute_query.py)

#!/usr/bin/env python3
"""
Safe PostgreSQL query executor for the db-query-assistant skill.
Run with: python scripts/execute_query.py "<SQL>" [param1 param2 ...]
"""
import asyncio
import asyncpg
import os
import sys
import json

async def execute_query(query: str, params: list) -> dict:
    """Execute a parameterized query and return results as a dict."""
    database_url = os.environ.get("DATABASE_URL")
    if not database_url:
        return {"error": "DATABASE_URL environment variable is not set."}

    conn = await asyncpg.connect(database_url)
    try:
        # asyncpg uses $1, $2... placeholders — safe from SQL injection
        rows = await conn.fetch(query, *params)

        if not rows:
            return {"rows": [], "count": 0}

        # Serialize to JSON-safe dicts (handle special types)
        serialized = []
        for row in rows[:100]:  # Hard cap at 100 rows for safety
            serialized.append({
                k: str(v) if not isinstance(v, (str, int, float, bool, type(None))) else v
                for k, v in dict(row).items()
            })

        return {"rows": serialized, "count": len(rows), "truncated": len(rows) > 100}

    except asyncpg.PostgresError as e:
        return {"error": f"PostgreSQL error: {e.sqlstate} — {str(e)}"}

    finally:
        await conn.close()

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: python execute_query.py '<SQL>' [param1 param2 ...]")
        sys.exit(1)

    query = sys.argv[1]
    params = sys.argv[2:] if len(sys.argv) > 2 else []

    result = asyncio.run(execute_query(query, params))
    print(json.dumps(result, indent=2))

6.4 Test the skill locally

With Claude Code:

# Test locally without publishing to the marketplace
claude --plugin-dir ./db-query-assistant

# Then invoke via slash command
# /db-query-assistant:db-query-assistant "Show top 10 users by order count"

With LangChain DeepAgents:

import asyncio
from deepagents import create_deep_agent
from deepagents.backends.filesystem import FilesystemBackend

backend = FilesystemBackend(root_dir="./workspace")

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[],  # The skill's script handles DB access via bash tool
    backend=backend,
    skills=["./db-query-assistant"],
    system_prompt="You are a database engineering assistant.",
)

result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "Show me the top 10 users by order count from the orders table."
    }]
})

print(result["messages"][-1]["content"])

---

7. Claude Code Plugins: Distributing Skills at Scale

A skill by itself is a local capability. A Claude Code plugin is a versioned, distributable package of one or more skills (plus optional agents, hooks, and MCP server configurations) that can be published to a marketplace and installed by any Claude Code user worldwide.

7.1 Plugin directory layout

my-db-plugin/
├── .claude-plugin/
│   └── plugin.json              # Plugin identity manifest (only file inside .claude-plugin/)
├── skills/
│   └── db-query-assistant/
│       ├── SKILL.md
│       ├── scripts/
│       │   └── execute_query.py
│       └── references/
│           └── query-plan-guide.md
├── agents/
│   └── db-audit-agent.md        # Optional: a dedicated sub-agent definition
├── .mcp.json                    # Optional: bundled MCP server config
└── README.md

⚠️ Common mistake: Never put skills/, agents/, or hooks/ inside the .claude-plugin/ directory. Only plugin.json lives there. All functional directories live at the plugin root.

7.2 The plugin manifest

{
  "name": "my-db-plugin",
  "displayName": "Database Query Assistant",
  "description": "Production-safe PostgreSQL querying, schema inspection, and query plan analysis for engineering teams.",
  "version": "1.2.0",
  "author": {
    "name": "Your Engineering Team",
    "email": "[e-mail]",
    "url": "https://yourcompany.com"
  },
  "homepage": "https://github.com/yourorg/my-db-plugin",
  "repository": "https://github.com/yourorg/my-db-plugin",
  "license": "MIT",
  "category": "databases"
}

The name field is immutable after publishing — it is the install slug users have on disk. Use displayName for any human-readable renames. Bump version to push update notifications to installed users.

7.3 Scaffold, test, and install

# Scaffold a new plugin from scratch
claude plugin init my-db-plugin

# Test locally — loads plugin without marketplace install
claude --plugin-dir ./my-db-plugin

# Install from the official Anthropic marketplace (after publishing)
# /plugin install my-db-plugin@claude-plugins-official

# Or keep it as a personal plugin loaded from your skills directory
# (auto-loaded by Claude Code at session start)
# cp -r ./my-db-plugin ~/.claude/skills/

🔐 Security note: Plugins can include MCP servers that execute arbitrary code. Always read .mcp.json and any scripts/ files before installing third-party plugins. The official Anthropic marketplace applies a review process, but community plugins require your own due diligence.

---

8. LangChain DeepAgents: The Batteries-Included Harness

LangChain's DeepAgents is the most technically comprehensive open-source agent harness in the current ecosystem. Built on LangGraph, it ships with the capabilities that production agents actually need out of the box — and the Agent Skills standard is a first-class primitive.

8.1 Installation

pip install deepagents

8.2 Full production configuration

import os
from deepagents import create_deep_agent
from deepagents.backends.filesystem import FilesystemBackend
from deepagents.memory import MemoryStore

# Persistent memory that survives across agent sessions
memory = MemoryStore(connection_string=os.environ["MEMORY_DB_URL"])

# Filesystem backend with declarative permission rules
# Boundaries are enforced at the harness level — not by prompting the model
backend = FilesystemBackend(
    root_dir="./workspace",
    permissions={
        "read":  ["**/*"],
        "write": ["output/**", "reports/**", "tmp/**"],
        "deny":  ["**/.env", "**/secrets/**", "**/*.pem", "**/*.key"]
    }
)

agent = create_deep_agent(
    model="openai:gpt-5.5",
    tools=[search_web, run_tests, fetch_url],
    backend=backend,
    # Agent Skills: loaded with progressive disclosure
    skills=[
        "./skills/code-review",
        "./skills/db-query-assistant",
        "./skills/test-writer",
    ],
    memory=memory,
    # Sub-agents run in isolated context windows
    subagents={
        "researcher": {"model": "openai:gpt-5.5-mini"},
        "coder":      {"model": "anthropic:claude-sonnet-4-6"},
    },
    # Require human approval before these tool categories execute
    human_in_the_loop=["file_write", "bash_execute"],
    system_prompt="You are a senior engineering assistant.",
)

8.3 Streaming typed events

for event in agent.stream(
    {"messages": [{"role": "user", "content": "Refactor auth module and run tests"}]},
    config={"configurable": {"thread_id": "session-42"}},
    stream_mode="events"
):
    event_type = event.get("event")

    if event_type == "on_chat_model_stream":
        # Incremental LLM token output
        print(event["data"]["chunk"].content, end="", flush=True)

    elif event_type == "on_tool_start":
        print(f"\n🔧 Calling: {event['name']}({event['data'].get('input', {})})")

    elif event_type == "on_tool_end":
        print(f"✅ Done: {event['name']}")

    elif event_type == "on_human_in_the_loop":
        # Agent paused, requesting approval before an action
        tool = event["data"]["tool"]
        args = event["data"]["args"]
        print(f"\n⏸️  Approval needed: {tool} with args {args}")
        approval = input("Approve? (y/n): ").strip().lower()
        event["data"]["approve"](approval == "y")

The thread_id in configurable is how LangGraph persists agent state for multi-turn conversations and resumable long-running tasks. The same thread can be paused, inspected via LangSmith, and resumed from exactly where it left off.

---

9. Sub-Agent Orchestration with Skills

The most powerful architectural pattern enabled by the Agent Skills standard is skill-specialized sub-agents. Instead of a single monolithic agent loaded with all skills (and therefore all context overhead), you compose a system where a coordinator delegates tasks to specialized sub-agents, each loaded with only the skills relevant to their domain.

from deepagents import create_deep_agent
from deepagents.backends.filesystem import FilesystemBackend

backend = FilesystemBackend(root_dir="./workspace")

# --- Specialist sub-agents ---
# Each sub-agent only loads skills it needs — minimal context overhead

research_agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",   # Fast/cheap for web research
    tools=[search_web, fetch_url],
    backend=backend,
    skills=["./skills/web-research", "./skills/citation-formatter"],
    system_prompt="You are a research assistant. Find accurate, cited information."
)

code_agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",      # Strong model for code generation
    tools=[read_file, write_file, bash],
    backend=backend,
    skills=[
        "./skills/code-review",
        "./skills/db-query-assistant",
        "./skills/test-writer"
    ],
    system_prompt="You are a senior software engineer. Write clean, well-tested code."
)

security_agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[read_file],
    backend=backend,
    skills=["./skills/code-review", "./skills/security-audit"],
    system_prompt="You are a security-focused code reviewer. Flag all vulnerabilities."
)

# --- Coordinator agent delegates using built-in subagent spawning ---
orchestrator = create_deep_agent(
    model="openai:gpt-5.5",
    tools=[],
    backend=backend,
    skills=["./skills/project-management"],
    subagents={
        "researcher":  research_agent,
        "coder":       code_agent,
        "security":    security_agent,
    },
    system_prompt="""You are an engineering team lead. 
    - Delegate research tasks to the 'researcher' subagent.
    - Delegate implementation tasks to the 'coder' subagent.  
    - Delegate security reviews to the 'security' subagent.
    Synthesize their outputs into a final, cohesive deliverable."""
)

# Single high-level task — orchestrator handles routing and synthesis
result = orchestrator.invoke({
    "messages": [{
        "role": "user",
        "content": """Research JWT token rotation best practices, implement them 
                      in our auth module at src/auth/tokens.py, then review 
                      the implementation for security vulnerabilities."""
    }]
})

Each sub-agent runs in an isolated context window — a sub-agent's full working context does not leak into the orchestrator's context or into sibling sub-agents. This isolation is what makes the pattern scale: the orchestrator sees only the sub-agents' final outputs, not all their intermediate reasoning, file reads, and tool calls.

The total context cost of this three-agent system is far lower than a single agent that has loaded all six skills simultaneously, while being far more capable because each specialist can reason deeply within its domain without competing for context space.

---

10. Production Considerations: Security, Testing, Versioning

10.1 Security: enforce boundaries at the tool level

DeepAgents adopts the right security philosophy: trust the LLM to follow skill instructions, but enforce hard boundaries at the tool and filesystem level. Never rely on prompt-level restrictions as your primary security control.

# Filesystem permissions are enforced by the harness — not by asking the model nicely
backend = FilesystemBackend(
    root_dir="./workspace",
    permissions={
        "read":  ["**/*"],
        "write": ["output/**", "reports/**"],
        "deny":  ["**/.env", "**/secrets/**", "**/*.pem", "**/*.key", "**/*.pfx"]
    }
)

# For production: use an isolated sandbox instead of local filesystem
from deepagents.backends.sandbox import E2BSandboxBackend

backend = E2BSandboxBackend(
    template="python-data-science",
    timeout=300  # Kill the sandbox after 5 minutes regardless of state
)

10.2 Skill testing with LLM-in-the-loop evaluation

Skills are prompt engineering artifacts, so their tests must include the LLM as part of the evaluation:

import pytest
from deepagents import create_deep_agent
from deepagents.backends.filesystem import FilesystemBackend

@pytest.mark.asyncio
async def test_code_review_skill_flags_sql_injection():
    """The code-review skill must flag SQL injection as Critical severity."""
    agent = create_deep_agent(
        model="anthropic:claude-sonnet-4-6",
        tools=[],
        backend=FilesystemBackend(root_dir="./test_fixtures"),
        skills=["./skills/code-review"],
    )

    vulnerable_code = """
    def get_user(username):
        # VULNERABLE: direct string interpolation into SQL
        query = f"SELECT * FROM users WHERE username = '{username}'"
        return db.execute(query)
    """

    result = agent.invoke({
        "messages": [{
            "role": "user",
            "content": f"Review this Python code:\n```
{% endraw %}
python\n{vulnerable_code}\n
{% raw %}
```"
        }]
    })

    response = result["messages"][-1]["content"].lower()

    # The skill must identify the specific vulnerability
    assert "sql injection" in response or "parameterized" in response, \
        "Code review skill failed to identify SQL injection"

    # The skill must classify it as critical
    assert "critical" in response or "🔴" in response, \
        "SQL injection must be flagged as Critical severity"

10.3 Versioning and managing skill libraries

# Bump metadata.version on every change
---
name: code-review
description: "Perform structured code reviews covering correctness, security, performance, and maintainability..."
metadata:
  version: "2.1"
  breaking-changes: "v2.0 restructured output format; v2.1 adds OWASP Top 10 checks"
  changelog: "references/CHANGELOG.md"
---

Structure your skill library as a Git repository with a clear directory layout:

skills/
├── code-review/          v2.1
├── db-query-assistant/   v1.0
├── test-writer/          v1.3
├── security-audit/       v1.0
└── web-research/         v2.0

Use Git tags (git tag skills/code-review@2.1) to pin specific skill versions in downstream agents. When using LangChain DeepAgents, the skills= parameter accepts both local paths and remote Git URLs (verify this against the latest DeepAgents docs for remote loading support).

---

11. The Future: Agent-to-Agent Skill Discovery

Every major system in the Agent Skills ecosystem today requires humans to explicitly configure which skills an agent loads. The obvious evolution — already being prototyped — is dynamic skill discovery at runtime: agents that query a skill registry, evaluate semantic relevance to the current task, and load matching skills on demand without pre-configuration.

The plumbing for this already exists. The Agent Skills description field is already written as a semantic trigger. Every runtime already implements a "does this description match the current task?" evaluation. The step from "check pre-configured skills" to "query a registry and check returned skills" is an engineering increment, not a research breakthrough.

What changes when this lands: a single create_deep_agent() call with dynamic_skills=registry would give your agent the ability to self-extend with capabilities it was not explicitly programmed with — as long as those capabilities exist somewhere in the registry and have a well-written description.

The Model Hardware Standard (MHS) — announced simultaneously by Anthropic as a research preview — extends the same skills-based composability model into the physical world: a standardized format for AI agents to safely operate physical devices in scientific labs and manufacturing environments. The abstraction is identical: portable, declarative capability packages that agents load on demand.

The trajectory is clear: agent composability in 2026–2028 will mirror what package managers did for software in 2010–2015. The Agent Skills standard and SKILL.md are the moment it crystallizes.

---

12. Conclusion

The Agent Skills standard solves a real, painful, and expensive engineering problem: the inability to build, share, and reuse AI agent capabilities across platforms, teams, and agent frameworks. In under a year, the ecosystem has moved from fragmented proprietary approaches to a single open specification ratified by every major vendor — Anthropic, OpenAI, Google, Microsoft/GitHub, JetBrains, and over a dozen open-source projects.

What you should do this week:

1. Audit your existing agent system prompts. Any section that describes domain-specific expertise is a candidate for extraction into a SKILL.md. Break that monolith apart.

2. Create a skills/ directory in your codebase and commit your first skill. Even before adopting DeepAgents, this gets your prompt engineering under version control, testable, and reusable.

3. Install LangChain DeepAgents (pip install deepagents) and port your most-used agent to it. The create_deep_agent() API is the fastest path to sub-agents, persistent memory, and skills-based context management.

4. Scaffold a Claude Code plugin with claude plugin init my-team-skills and start packaging your internal runbooks, coding standards, and workflow automation as distributable skills.

5. Write excellent description fields. This is the single highest-leverage improvement you can make to any skill right now. A semantic, keyword-rich description is the activation trigger across every compliant runtime. Treat it with the same care you give a good function name.

The engineering team that masters composable agent skills today will ship faster, build more reliable multi-agent systems, and accumulate a reusable library of captured expertise — while teams without a skill strategy are still copy-pasting system prompts into every new agent they build.

---

Found this useful? Drop a comment with the first skill you're writing — I'd love to see what domains the community is tackling. If you build something with DeepAgents or Claude Code plugins, share the GitHub link below.