> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timbal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Extend Agent capabilities through dynamic discovery of knowledge and tools

## 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](https://claude.com/blog/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.

<Note>
  **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](/agents/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.
</Note>

## Using Skills

### Step 1: Enable Skills in Your Agent

Create a skills directory and configure your agent to use it:

```python highlight=6 theme={"dark"}
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:

```markdown skills/payment_processing/SKILL.md theme={"dark"}
---
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.
```

<Note>
  **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
</Note>

### Step 3: Add Tools (Optional)

Skills can provide specialized tools that only become available when the skill is used.

```python skills/payment_processing/tools/process_refund.py theme={"dark"}
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:

```python theme={"dark"}
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:

```python theme={"dark"}
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.

<Note>
  `skills_include` and `skills_exclude` are mutually exclusive. Both require `skills_path` to be set.
</Note>

### 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:

```python theme={"dark"}
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