Skill Creation

You can create new skills to extend your own capabilities. Skills are Markdown instruction modules that persist across conversations and require no restart.

When to Create a Skill

• A recurring task that benefits from a structured workflow
• Domain knowledge worth preserving across conversations
• A multi-step process the user asks about repeatedly
• Integration with a new CLI tool or API

When NOT to Create a Skill

• One-off tasks that won't recur
• Information that belongs in MEMORY.md (user preferences, personal facts)
• Temporary instructions or experiment notes

How to Create a Skill

1. Choose a name: lowercase, digits, hyphens only (e.g., meeting-notes, code-review)
2. Create the file using write_file:

write_file("skills/<name>/SKILL.md", content)

3. The skill is available immediately on the next message — no restart needed
4. Always tell the user when you create a new skill

SKILL.md Format

Every skill needs a YAML frontmatter block followed by Markdown instructions:

---
name: <skill-name>
description: "Brief description of what this skill does and when to use it. Max 1024 chars."
---

# Skill Title

Instructions in markdown...

Frontmatter Fields

Frontmatter Examples

Simple skill (no dependencies):

---
name: meeting-notes
description: "Generate structured meeting notes from conversations. Use when the user asks to summarize or document a meeting."
---

Skill requiring an API key:

---
name: notion
description: "Manage Notion workspace: create pages, query databases, add content blocks. Requires NOTION_API_KEY."
requires_env:
  - NOTION_API_KEY
---

Skill requiring a host bridge:

---
name: spotify
description: "Control Spotify playback: play, pause, skip, search tracks/albums/playlists via spogo CLI."
requires_bridge: "spotify"
---

Body Structure

Follow this structure for the Markdown body:

# Skill Title

Brief one-line summary.

## When to Use

- Trigger phrase or scenario 1
- Trigger phrase or scenario 2

## When NOT to Use

- Scenario where another approach is better

## Commands / Workflow

Step-by-step instructions, code blocks, curl examples, etc.

## Notes

- Caveats, rate limits, known issues

Guidelines for the Body

• Be procedural: write steps the agent can follow, not conceptual explanations
• Include concrete examples: real commands, API calls, curl snippets
• Use code blocks with language hints for syntax highlighting
• Document known issues and workarounds — these save the most time
• Keep it concise: aim for what's needed to execute, not exhaustive documentation

Rules

• Only create SKILL.md files — never create Python scripts or executable code in skill directories
• The name in frontmatter MUST match the directory name
• One skill per directory, one SKILL.md per skill
• You can add supporting files (configs, docs) in the same directory if needed
• You can update or delete your own skills when they become outdated
• Always verify the skill works by reading it back after creation

Updating & Deleting Skills

• Update: use edit_file or write_file to modify skills/<name>/SKILL.md
• Delete: remove the skill directory (tell the user first)
• Changes take effect on the next message — no restart needed