Skills System

Overview

Skills are folders of instructions, scripts, and resources that agents load dynamically to improve performance on specialized tasks. The agent first sees only a skill’s name and short description. When the task matches, it loads the full SKILL.md and can execute commands the skill references.

How Skills Work

Starts light - Agent discovers skills by name/description only
Loads on demand - Pulls full instructions from SKILL.md when relevant
Executes safely - Runs skill-driven commands in isolated environment

Skill Structure

A skill is a directory with this layout:

example-skill/
├── SKILL.md        # Required: instructions + metadata
├── scripts/        # Optional: helper scripts
├── assets/         # Optional: templates/resources
└── references/     # Optional: docs or checklists

SKILL.md Format

The SKILL.md file contains YAML frontmatter and markdown content:

---
name: Slack GIF Creator
description: Create GIFs for Slack from video files
---

# Slack GIF Creator

This skill helps create optimized GIFs for Slack.

## Usage

1. Accept a video file path or URL
2. Use ffmpeg to convert to GIF
3. Optimize for Slack's size limits (< 1MB)

## Commands

```bash
ffmpeg -i input.mp4 -vf "scale=480:-1" -r 10 output.gif

Notes

Slack prefers GIFs under 1MB
480px width is optimal
10 fps is usually sufficient

## Loading Skills

The `Skills` class (src/agentor/skills.py:8) loads skills from paths:

```python
from agentor.skills import Skills

# Load from directory
skill = Skills.load_from_path(".skills/slack-gif-creator")

# Load from SKILL.md directly
skill = Skills.load_from_path(".skills/slack-gif-creator/SKILL.md")

Skill Attributes

@dataclass
class Skills:
    name: str          # From YAML frontmatter
    description: str   # From YAML frontmatter
    location: str      # File path

Using Skills with Agents

Pass skill paths to the agent constructor (src/agentor/core/agent.py:182):

from agentor import Agentor
from agentor.tools import ShellTool

agent = Agentor(
    name="Assistant",
    model="gemini/gemini-3-flash-preview",
    instructions="Your job is to create GIFs. Use available skills.",
    skills=[".skills/slack-gif-creator"],
    tools=[ShellTool()],
)

result = await agent.chat("produce a cat gif")

Multiple Skills

Provide multiple skills for different capabilities:

agent = Agentor(
    name="Developer Assistant",
    skills=[
        ".skills/git-workflow",
        ".skills/python-debugging",
        ".skills/api-testing"
    ],
    tools=[ShellTool()]
)

Skill Injection

Skills are injected into the agent’s system prompt as XML (src/agentor/core/agent.py:227):

def _inject_skills(self, skills: List[str]) -> str:
    """Inject skills into the agent system prompt."""
    instructions = []
    for skill in skills:
        skill = Skills.load_from_path(skill)
        instructions.append(f"{skill.to_xml()}")
    return "<available_skills>" + "".join(instructions) + "</available_skills>"

XML Format

Skills are serialized to XML (src/agentor/skills.py:34):

<available_skills>
  <skill>
    <name>Slack GIF Creator</name>
    <description>Create GIFs for Slack from video files</description>
    <location>.skills/slack-gif-creator/SKILL.md</location>
  </skill>
</available_skills>

The agent sees this in its system prompt and can load the full skill content when needed.

Example: GIF Creator Skill

From the README example:

from agentor.tools import ShellTool
from agentor import Agentor

agent = Agentor(
    name="GIF Assistant",
    model="gemini/gemini-3-flash-preview",
    instructions="Create GIFs using available tools and skills.",
    skills=[".skills/slack-gif-creator"],
    tools=[ShellTool()],
)

async for chunk in await agent.chat("produce a cat gif", stream=True):
    print(chunk)

The agent:

Sees the skill name and description in its prompt
Recognizes the task matches the skill
Loads full instructions from .skills/slack-gif-creator/SKILL.md
Uses ShellTool to execute ffmpeg commands from the skill
Creates an optimized GIF for Slack

Creating Custom Skills

1. Create Directory Structure

mkdir -p .skills/my-skill/{scripts,assets,references}

2. Write SKILL.md

---
name: My Custom Skill
description: Brief description of what this skill does
---

# My Custom Skill

Detailed instructions for the agent.

## When to Use

Use this skill when:
- Condition 1
- Condition 2

## Steps

1. First step
2. Second step

## Example Commands

```bash
# Helpful commands the agent can run
ls -la

Tips

Important tip 1
Important tip 2

### 3. Add Scripts (Optional)

Place helper scripts in `scripts/`:

```bash
# scripts/process.sh
#!/bin/bash
echo "Processing $1"

4. Add Resources (Optional)

Place templates or reference files:

assets/
  template.json
  config.yaml

references/
  api-docs.md
  troubleshooting.md

Skill Best Practices

Clear Descriptions

Write concise descriptions that help the agent decide when to use the skill:

---
name: Docker Deployment
description: Build and deploy Docker containers to production
---

Step-by-Step Instructions

Provide clear, ordered steps:

## Deployment Process

Build the Docker image: `docker build -t app:latest .`
Tag for registry: `docker tag app:latest registry.io/app:latest`
Push to registry: `docker push registry.io/app:latest`
Deploy to production: `kubectl apply -f deployment.yaml`

Include Examples

Show concrete examples the agent can follow:

## Example: Deploy Web App

```bash
# Build and deploy
docker build -t myapp:v1.0 .
docker push registry.io/myapp:v1.0
kubectl set image deployment/myapp app=registry.io/myapp:v1.0

### Safety Warnings

Include warnings for destructive operations:

```markdown
## Important

⚠️ Always backup the database before running migrations.
⚠️ Never run `DROP DATABASE` in production.

Tool Integration

Skills work best with tools that can execute their instructions:

Shell Tool

For command execution:

from agentor.tools import ShellTool

agent = Agentor(
    skills=[".skills/bash-operations"],
    tools=[ShellTool()]
)

File Tools

For file manipulation:

from agentor.tools.base import BaseTool, capability

class FileTool(BaseTool):
    @capability
    def read_file(self, path: str) -> str:
        with open(path) as f:
            return f.read()

agent = Agentor(
    skills=[".skills/file-processing"],
    tools=[FileTool()]
)

JSON Serialization

Export skills to JSON (src/agentor/skills.py:43):

skill = Skills.load_from_path(".skills/my-skill")
json_data = skill.to_json()
print(json_data)

Output:

{
  "name": "My Skill",
  "description": "Skill description",
  "location": ".skills/my-skill/SKILL.md"
}

Error Handling

The loader validates skill structure (src/agentor/skills.py:14):

# Raises FileNotFoundError if path doesn't exist
skill = Skills.load_from_path("invalid/path")

# Raises ValueError if not a markdown file
skill = Skills.load_from_path("file.txt")

Skill Discovery

Agents see skill summaries in their system prompt:

<available_skills>
  <skill>
    <name>Git Workflow</name>
    <description>Standard Git operations and best practices</description>
    <location>.skills/git-workflow/SKILL.md</location>
  </skill>
  <skill>
    <name>Python Debugging</name>
    <description>Debug Python applications using pdb and logging</description>
    <location>.skills/python-debugging/SKILL.md</location>
  </skill>
</available_skills>

The agent can then request the full content when needed.

Next Steps

Tools

Learn about tools that execute skill instructions

Agents

Understand agent architecture and lifecycle

Examples

See example skills and implementations

Start Here

Build Agents

Concepts

Tool Use & MCP

Guides

API Reference

Overview

How Skills Work

Skill Structure

SKILL.md Format

Notes

Skill Attributes

Using Skills with Agents

Multiple Skills

Skill Injection

XML Format

Example: GIF Creator Skill

Creating Custom Skills

1. Create Directory Structure

2. Write SKILL.md

Tips

4. Add Resources (Optional)

Skill Best Practices

Clear Descriptions

Step-by-Step Instructions

Include Examples

Tool Integration

Shell Tool

File Tools

JSON Serialization

Error Handling

Skill Discovery

Next Steps

Tools

Agents

Examples

Start Here

Build Agents

Concepts

Tool Use & MCP

Guides

API Reference

​Overview

​How Skills Work

​Skill Structure

​SKILL.md Format

​Notes

​Skill Attributes

​Using Skills with Agents

​Multiple Skills

​Skill Injection

​XML Format

​Example: GIF Creator Skill

​Creating Custom Skills

​1. Create Directory Structure

​2. Write SKILL.md

​Tips

​4. Add Resources (Optional)

​Skill Best Practices

​Clear Descriptions

​Step-by-Step Instructions

​Include Examples

​Tool Integration

​Shell Tool

​File Tools

​JSON Serialization

​Error Handling

​Skill Discovery

​Next Steps

Tools

Agents

Examples

Overview

How Skills Work

Skill Structure

SKILL.md Format

Notes

Skill Attributes

Using Skills with Agents

Multiple Skills

Skill Injection

XML Format

Example: GIF Creator Skill

Creating Custom Skills

1. Create Directory Structure

2. Write SKILL.md

Tips

4. Add Resources (Optional)

Skill Best Practices

Clear Descriptions

Step-by-Step Instructions

Include Examples

Tool Integration

Shell Tool

File Tools

JSON Serialization

Error Handling

Skill Discovery

Next Steps