Skills

Give Firebender specialized knowledge with Skills

What are Skills?

Skills teach Firebender how to do something specific using markdown files. When you ask Firebender something that matches a Skill’s purpose, Firebender can invoke it to get specialized guidance.

A Skill might teach Firebender to:

• Review PRs using your team’s standards
• Generate commit messages in your preferred format
• Query your company’s database schema
• Follow your team’s coding conventions

Why Skills?

Skills allow Firebender to progressively improve at a specific, well-defined task, that can be personal or specific for your team.

At runtime, Firebender chooses which skills to load into context based on the task. This differs from Commands which are user triggered, and MCPs which are solely focused on connecting data sources with your agent.

Create a Skill

Ask Firebender:

/help me create a skill

Firebender will guide you through creating a skill. If you prefer to create one manually, read on.

Skills are markdown files with YAML frontmatter stored in special directories.

1. Create the directory structure

User skills (available across all projects):

mkdir -p ~/.firebender/skills/my-skill

Team skills (shared with your team via git):

mkdir -p .firebender/skills/my-skill

2. Write SKILL.md (Required)

Create a SKILL.md file in your skill directory:

---
name: commit-helper
description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
version: 1.0.0
---

# Commit Message Helper

## Instructions

1. Run `git diff --staged` to see changes
2. Suggest a commit message with:
   - Summary under 50 characters
   - Detailed description
   - Affected components

## Best practices

- Use present tense
- Explain what and why, not how

The description is critical - Firebender uses it to decide when to invoke your Skill.

3. Use your Skill

Skills are loaded immediately. You can:

• Invoke it directly: /skill:commit-helper
• Ask Firebender: “What skills can you use?”
• Let Firebender auto-invoke it based on your request

Skill metadata

Field	Required	Description
name	Yes	Skill identifier (lowercase, hyphens, max 64 chars)
description	Yes	What the Skill does and when to use it (max 1024 chars). Firebender uses this to decide when to invoke.
version	No	Version string for your reference
autoTrigger	No	Whether Firebender can auto-invoke (default: true)
projectTypes	No	Project types this Skill applies to (e.g., [android, kotlin])
icon	No	Path to icon file (SVG, PNG, or JPG) relative to skill directory

Supporting files

Put detailed reference material in separate files that Firebender reads only when needed:

my-skill/
├── SKILL.md              # Overview and quick start (Required)
├── reference.md          # Detailed API docs (Optional)
├── examples.md           # Usage examples (Optional)
└── icon.svg              # Custom icon (Optional)

Link to them from SKILL.md:

For detailed API reference, see [reference.md](reference.md).
For examples, see [examples.md](examples.md).

Keep SKILL.md under 500 lines. Split detailed content into separate files.

Skill locations

Location	Path	Applies to
User	~/.firebender/skills/	You, across all projects
Team	.firebender/skills/	Anyone working in this repository

Team skills override user skills with the same name.

Example: Multi-file Skill

A PDF processing Skill with supporting documentation:

pdf-processing/
├── SKILL.md          # Overview
├── FORMS.md          # Form field mappings
├── REFERENCE.md      # API details
└── icon.svg

SKILL.md:

---
name: pdf-processing
description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction.
version: 1.0.0
icon: icon.svg
---

# PDF Processing

## Quick start

Extract text with pdfplumber:

```python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

For form filling, see [FORMS.md](FORMS.md).
For detailed API reference, see [REFERENCE.md](REFERENCE.md).

## Requirements

```bash
pip install pypdf pdfplumber
```

Distribution

Via Git (Team Skills)

Commit .firebender/skills/ to version control. Anyone who clones gets the Skills.

Cross-compatible

Skills work with multiple AI coding tools. Store them in:

• ~/.firebender/skills/ (Firebender)
• ~/.goose/skills/ (Goose)
• ~/.claude/skills/ (Claude Code)
• ~/.codex/skills/ (Codex)
• ~/.cursor/skills/ (Cursor)
• ~/.agents/skills/ (Generic agents)

Firebender loads from all these directories for compatibility.

Best practices

Write clear descriptions

Bad:

description: Helps with documents

Good:

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

Use progressive disclosure

Keep core instructions in SKILL.md. Put detailed documentation in linked files:

## Quick reference

[Basic instructions here]

For advanced usage, see [advanced.md](advanced.md).
For API details, see [api-reference.md](api-reference.md).

Use executable scripts, not code blocks

Avoid putting bash scripts in triple backticks in your markdown files. Instead, create executable scripts in your skill directory. This allows the agent to use them directly without rewriting the script.

Bad:

```bash
#!/bin/bash
# Complex script here...
```

Good:

my-skill/
├── SKILL.md
├── process.sh       # Executable script
└── analyze.py       # Executable script

Reference them in SKILL.md:

Run the analysis script: `./process.sh input.txt`

Include examples

Show concrete examples in your Skills:

## Example usage

```bash
# Search for issues
gh search issues "bug" --repo=owner/repo

# Clone for analysis
cd /tmp && git clone https://github.com/owner/repo.git
```

Troubleshooting

Skill not triggering

Make your description more specific with keywords users would say:

# Instead of this:
description: Helps with code review

# Do this:
description: Reviews pull requests for code quality and suggests improvements. Use when user asks to review code, check a PR, or analyze changes.

Continuous Skill improvement

If you see the agent load in a skill and improperly use it or continue to stumble over bad bash commands/tool use, you should ask it to analyze and improve:

/help analyze your previous actions, find ways that you could have done this task faster and in less tool calls. Propose a couple of concise changes to update to this skill without being out of scope