Writing Skills

Skills are markdown files that teach the AI specific workflows. They're the simplest way to contribute to Crow — no code required.

What is a Skill?

A skill is a behavioral prompt stored in skills/. When a user's intent matches a trigger pattern, the AI loads the relevant skill file and follows its instructions. Skills define what to do and which tools to use.

Skill Anatomy

Every skill file follows this structure:

# Skill Name

## Description
One-paragraph summary of what this skill does.

## When to Use
- Bullet list of trigger conditions
- When the user says "..."
- When a specific condition is detected

## Tools Available
- **tool_name** — What it does
- **another_tool** — What it does

## Workflow: Workflow Name
1. First step
2. Second step — call `tool_name` with parameters
3. Third step — store results with `crow_store_memory`

## Best Practices
- Tips for effective use
- Common pitfalls to avoid

Adding Triggers

After creating your skill file, add a row to the trigger table in skills/superpowers.md:

| "english trigger", "another trigger" | "spanish trigger" | your-skill | primary-tools |

Multilingual Triggers

Crow supports multilingual intent matching. Provide trigger phrases in at least English. Adding Spanish (or other languages) is encouraged but optional. The AI matches intent in any language — the examples are illustrative.

Compound Workflows

Skills can combine multiple tools across different servers:

## Workflow: Research Summary Email
1. Search memories with `crow_search_memories` for the topic
2. List project sources with `crow_list_sources`
3. Compose a summary
4. Send via `send_gmail_message`
5. Store the action in memory with `crow_store_memory`

Transparency

Skills should include transparency lines so users can see what's happening:

*[crow: step 1/3 — searched memories, found 5 relevant items]*
*[crow: step 2/3 — composed summary from 3 sources]*

User Skills Directory

Skills in skills/ are part of the repo and get overwritten on git pull or updates. To protect your customizations:

• User override directory: ~/.crow/skills/ — Skills here take precedence over repo skills/. If both ~/.crow/skills/sharing.md and skills/sharing.md exist, the user version wins.
• Marketplace-installed skills: Skills installed from the Extensions panel are automatically placed in ~/.crow/skills/, so they're safe from updates.
• Custom skills: Place any custom skills you write in ~/.crow/skills/ to keep them across updates.

The AI checks ~/.crow/skills/ first when loading a skill. If a skill isn't found there, it falls back to the repo skills/ directory.

TIP

To customize a built-in skill without losing your changes on update, copy it to ~/.crow/skills/ and edit the copy:

mkdir -p ~/.crow/skills
cp skills/sharing.md ~/.crow/skills/sharing.md
# Edit ~/.crow/skills/sharing.md as needed

Testing

Skills are markdown — there's no build step. To test:

1. Place the file in skills/ or ~/.crow/skills/
2. Add the trigger row to skills/superpowers.md
3. Start a conversation and use one of the trigger phrases
4. Verify the AI follows the workflow correctly

Submit

1. Open a Skill Proposal issue
2. Fork the repo, add your skill file, and submit a PR