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:
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
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
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
| 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)
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 |
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
---
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
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...
```
my-skill/
├── SKILL.md
├── process.sh # Executable script
└── analyze.py # Executable script
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
