> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firebender.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/input/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):

```bash theme={null}
mkdir -p ~/.firebender/skills/my-skill
```

**Team skills** (shared with your team via git):

```bash theme={null}
mkdir -p .firebender/skills/my-skill
```

### 2. Write SKILL.md (Required)

Create a `SKILL.md` file in your skill directory:

```markdown theme={null}
---
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`:

```markdown theme={null}
For detailed API reference, see [reference.md](reference.md).
For examples, see [examples.md](examples.md).
```

<Tip>Keep `SKILL.md` under 500 lines. Split detailed content into separate files.</Tip>

## 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**:

````markdown theme={null}
---
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:

```yaml theme={null}
description: Helps with documents
```

Good:

```yaml theme={null}
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:

```markdown theme={null}
## 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:**

````markdown theme={null}
```bash
#!/bin/bash
# Complex script here...
```
````

**Good:**

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

Reference them in `SKILL.md`:

```markdown theme={null}
Run the analysis script: `./process.sh input.txt`
```

### Include examples

Show concrete examples in your Skills:

````markdown theme={null}
## 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:

```yaml theme={null}
# 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
```