Skills System

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

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

## 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")

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

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")

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

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>"

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

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)

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

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

### 3. Add Scripts (Optional)

Place helper scripts in `scripts/`:

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

assets/
  template.json
  config.yaml

references/
  api-docs.md
  troubleshooting.md

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

## Deployment Process

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

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

from agentor.tools import ShellTool

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

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()]
)

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

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

# 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")

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