Skip to main content

🤖 🧰 Agent Skills

Agent Skills provides a powerful system for AI agents to create, manage, and execute reusable code-based tool compositions.

For more information, see the Agent Skills community website, the specification, and the integration guide.

Package Scope​

Agent Skills is the skill management layer in the Datalayer AI stack:

┌─────────────────────────────────────────────────────────────┐
│                     agent-runtimes                          │
│            (Agent hosting, protocols, UI)                   │
├──────────────────────────┬──────────────────────────────────┤
│      agent-codemode      │         agent-skills             │  ◀── You are here
│  (discovery, codegen)    │     (skills management)          │
├──────────────────────────┴──────────────────────────────────┤
│                    code-sandboxes                           │
│          (Safe code execution environment)                  │
└─────────────────────────────────────────────────────────────┘

Responsibilities:

  • ✅ Skill CRUD operations (create, read, update, delete)
  • ✅ Skill discovery from directories and registries
  • ✅ Skill search by name, description, tags
  • ✅ SKILL.md format parsing (Claude Code compatible)
  • ✅ Skill versioning and lifecycle management
  • ✅ Pydantic AI toolset integration (AgentSkillsToolset)

Not Responsible For:

  • ❌ MCP tool discovery or binding generation (→ agent-codemode)
  • ❌ Raw code execution isolation (→ code-sandboxes)
  • ❌ Agent protocols or UI components (→ agent-runtimes)

Overview​

Skills are reusable Python functions that compose MCP tools to accomplish specific tasks. They allow agents to evolve their own toolbox by saving successful code patterns.

The Pattern​

  1. Skills are code files - Python files in a skills/ directory with async functions
  2. Agents discover skills - By listing the skills directory and reading file contents
  3. Agents create skills - By writing Python files to the skills directory
  4. Agents execute skills - By importing and calling them in executed code
  5. Agents compose skills - By importing multiple skills together

Why Skills?​

Traditional AI agents lose their learned patterns after each session. Skills solve this by:

  • Persistence - Save successful code patterns for reuse
  • Composability - Build complex capabilities from simpler ones
  • Sharing - Skills can be shared across agents and teams
  • Evolution - Agents improve their toolbox over time

Key Features​

🔧 SKILL.md Format​

Compatible with Claude Code's SKILL.md format:

---
name: data-analyzer
description: Analyzes datasets and provides insights
allowed-tools:
  - filesystem__read_file
  - filesystem__write_file
tags:
  - data
  - analysis
---

# Data Analyzer

Analyze CSV and JSON data files for patterns and insights.

## Usage

Call this skill with a file path to analyze...

🧰 Skills Manager​

Full lifecycle management with Anthropic SDK-compatible API:

from agent_skills import SkillsManager

manager = SkillsManager("./skills")

# Create skills
skill = manager.create(
    name="word_counter",
    description="Count words in files",
    content="# Word Counter\n\nCounts words in text files.",
    python_code='''
async def count_words(path: str) -> int:
    from generated.mcp.filesystem import read_file
    content = await read_file({"path": path})
    return len(content.split())
''',
    tags=["text", "analysis"]
)

# Discover, search, execute
skills = manager.discover()
matches = manager.search("data processing")
result = await manager.execute(skill, {"path": "/data.txt"})

🔗 Integration with agent-codemode​

Skills can import tool bindings generated by agent-codemode:

# skills/batch_processor.py
"""Skill that uses agent-codemode generated bindings."""

async def process_files(directory: str) -> dict:
    # Import tool bindings from agent-codemode
    from generated.mcp.filesystem import list_directory, read_file

    entries = await list_directory({"path": directory})
    results = []
    for entry in entries["entries"]:
        content = await read_file({"path": f"{directory}/{entry}"})
        results.append({"file": entry, "size": len(content)})
    return {"processed": len(results), "results": results}

🚀 Pydantic AI Integration​

Use with Pydantic AI agents via AgentSkillsToolset:

from pydantic_ai import Agent
from agent_skills import AgentSkillsToolset, SandboxExecutor
from code_sandboxes import CodeSandboxClient

sandbox = CodeSandboxClient.create(variant="eval")
toolset = AgentSkillsToolset(
    directories=["./skills"],
    executor=SandboxExecutor(sandbox),
)

agent = Agent(
    model='openai:gpt-4o',
    toolsets=[toolset],
)

# Agent has access to:
# - list_skills()
# - load_skill(skill_name)
# - read_skill_resource(skill_name, resource_name)
# - run_skill_script(skill_name, script_name, args)

🎨 Programmatic Skills​

Define skills in Python code with decorators:

from agent_skills import AgentSkill

skill = AgentSkill(
    name="data-analyzer",
    description="Analyzes datasets and provides insights",
    content="Use this skill to analyze CSV and JSON data files.",
)

@skill.script
async def analyze(ctx, file_path: str) -> str:
    """Analyze a data file."""
    data = await ctx.deps.filesystem.read(file_path)
    return f"Analyzed {len(data)} bytes"

@skill.resource
def get_reference() -> str:
    return "Reference documentation..."

Quick Start​

pip install agent-skills
from agent_skills import SkillsManager

# Initialize manager
manager = SkillsManager("./skills")

# Discover existing skills
skills = manager.discover()
print(f"Found {len(skills)} skills")

# Create a new skill
skill = manager.create(
    name="hello_world",
    description="A simple greeting skill",
    content="# Hello World\n\nA simple skill that greets the user.",
    python_code='''
async def greet(name: str = "World") -> str:
    """Greet someone."""
    return f"Hello, {name}!"
''',
)

# Execute the skill
result = await manager.execute(skill, {"name": "Agent"})
print(result.output)  # "Hello, Agent!"

Documentation​