Skip to main content

​
What are Skills?

Skills provide domain-specific knowledge and tools that agents can selectively activate based on user requests. Each skill is a module with its own documentation and tools that become accessible only when the skill is activated. This is an extension of Anthropic’s Agent Skills

​
How Skills Work

​
Structure

Each skill is a directory containing:
  • SKILL.md (required): Knowledge provided by the Skill
  • tools/ (optional): Folder for python files defining instances of skill-specific tools
  • Supporting Files (optional): Additional documentation (must be referenced in SKILL.md)
Example structure: 
skills/
└── payment_processing/
    ├── SKILL.md
    ├── fraud_detection.md
    ├── ...
    └── tools/
        ├── process_refund.py
        └── check_status.py
└── ...

​
Loading Behavior

  1. Discovery: The agent receives a list of available skills with their names and descriptions
  2. Activation: When relevant to a user query, the agent loads the SKILL.md file and its associated tools
  3. Persistence: Once loaded, skills remain available throughout the conversation
This lazy-loading approach keeps the agent’s context efficient while ensuring specialized knowledge is available when needed.
Skills and memory compaction. A skill’s documentation reaches the model as the result of the read_skill tool call. Those results are pinned, so memory compaction never drops or truncates them — the guidance stays available for as long as the skill is active, even on long runs where the rest of the history is compacted. This keeps an agent’s tools and the instructions for using them from drifting apart.

​
Using Skills

​
Step 1: Enable Skills in Your Agent

Create a skills directory and configure your agent to use it: 
from timbal import Agent

agent = Agent(
    name="my_agent",
    model="anthropic/claude-sonnet-4-6",
    skills_path="./skills"
)
The agent can now discover skills from this directory.

​
Step 2: Create the SKILL.md File

Every skill requires a SKILL.md file with YAML frontmatter defining its name and description:
skills/payment_processing/SKILL.md
---
name: payment_processing
description: Complete payment processing including payments, refunds, and fraud detection
---

## Overview
There are different operations for e-commerce orders.

### Payment Policy
- Payments must be made within 30 days of order placement
- See `fraud_detection.md` for security guidelines

### Usage Guidelines
Always verify the order exists before processing payments or refunds.

### Escalation Process
If you cannot resolve an issue, escalate to the customer support team.
Important:
The name and description fields are required in the YAML frontmatter. The agent uses these fields to decide when to activate the skill
The name field must match the skill’s directory name

​
Step 3: Add Tools (Optional)

Skills can provide specialized tools that only become available when the skill is used.
skills/payment_processing/tools/process_refund.py
from timbal import Tool

async def process_refund(order_id: str, amount: float, reason: str) -> str:
    """Process a customer refund."""
    # Your refund logic here
    return f"Refund of ${amount} processed for order {order_id}"

# Create the tool instance
process_refund_tool = Tool(
    name="process_refund",
    description="Process a refund for a customer order",
    handler=process_refund
)

​
Step 4: Add Supporting Documentation (Optional)

For complex skills, include additional reference files and link to them in SKILL.md. In the previous example, the fraud_detection.md file will only be read when the agent determines it is needed.

​
Selecting Which Skills to Load

By default, every skill under skills_path is loaded into the agent. When a single directory is shared across multiple agents — each needing a different subset — use skills_include (whitelist) or skills_exclude (blacklist) to filter by directory name.

​
Whitelist

Load only the listed skills: 
agent = Agent(
    name="payments_agent",
    model="anthropic/claude-sonnet-4-6",
    skills_path="./skills",
    skills_include=["payment_processing", "inventory_lookup"],
)
Unknown names raise ValueError — typos fail loudly instead of silently loading nothing.

​
Blacklist

Load every skill except the listed ones: 
agent = Agent(
    name="support_agent",
    model="anthropic/claude-sonnet-4-6",
    skills_path="./skills",
    skills_exclude=["experimental_billing"],
)
Unknown names in skills_exclude are silently ignored.
skills_include and skills_exclude are mutually exclusive. Both require skills_path to be set.

​
Explicit Selection Without skills_path

For full control, pass Skill instances directly via tools=[...]. This bypasses skills_path entirely and is useful when skills live in unrelated locations or when an agent only needs one or two: 
from timbal import Agent
from timbal.core.skill import Skill

agent = Agent(
    name="refunds_agent",
    model="anthropic/claude-sonnet-4-6",
    tools=[Skill(path="./skills/payment_processing")],
)

​
Best Practices

  • Each skill should have a single, well-defined purpose.
  • Write clear descriptions. Agents use it to decide when to activate a Skill.
  • Use descriptive names for the skill.

​
Key Takeaways

  • Skills are modular packages that combine knowledge and tools for specific domains
  • Dynamic loading keeps agents efficient by loading only relevant capabilities
  • SKILL.md YAML frontmatter defines the skill’s identity and purpose
  • Tools and supporting documentation are loaded on demand when the skill is activated