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

> Complete reference for Skills configuration

Skills are markdown files with YAML frontmatter that give Firebender specialized knowledge and capabilities. When invoked, the full skill content is injected into the conversation.

<Info>
  Type `/help me create a skill` to get help creating skills
</Info>

## File Locations

### User-level Skills

Available across all projects:

* `~/.firebender/skills/`

### Team-level Skills

Project-specific skills shared via version control:

* `.firebender/skills/`

### Plugin-level Skills

Built-in skills bundled with Firebender (like `firebender-help`).

## Precedence

When skills with the same name exist in multiple locations:

**TEAM > USER > PLUGIN**

Team skills override user skills, which override plugin skills.

## Directory Structure

Each skill lives in its own directory with a required `SKILL.md` file:

```
skills/
├── commit-helper/
│   ├── SKILL.md          # Required: Main skill definition
│   ├── reference.md      # Optional: Detailed docs
│   ├── examples.md       # Optional: Usage examples
│   └── icon.svg          # Optional: Custom icon
├── pr-reviewer/
│   ├── SKILL.md
│   └── guidelines.md
└── database-query/
    ├── SKILL.md
    ├── schema.md
    └── icon.png
```

## File Format

Skills use markdown with YAML frontmatter:

```markdown SKILL.md 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
autoTrigger: true                      # or: disable-model-invocation: false
projectTypes: [android, kotlin]
icon: icon.svg
---

# 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
```

## Frontmatter Fields

<ParamField path="name" type="string" required>
  Skill identifier used for invocation (e.g., `/skill:commit-helper`).

  * Lowercase with hyphens
  * Maximum 64 characters
  * Must be unique within scope
</ParamField>

<ParamField path="description" type="string" required>
  Describes what the skill does and when to use it. This is critical - Firebender uses this to decide when to auto-invoke the skill.

  * Maximum 1024 characters
  * Include keywords users would say
  * Explain both capabilities and use cases

  **Example**:

  ```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.
  ```
</ParamField>

<ParamField path="version" type="string?">
  Version string for documentation and tracking purposes.

  ```yaml theme={null}
  version: 1.0.0
  ```
</ParamField>

<ParamField path="autoTrigger" type="boolean?">
  Whether Firebender can automatically invoke this skill based on the description.

  * `true` (default): Skill appears in skill menu and can be auto-invoked
  * `false`: Skill must be manually invoked with `/skill:name`

  ```yaml theme={null}
  autoTrigger: true
  ```
</ParamField>

<ParamField path="disable-model-invocation" type="boolean?">
  Anthropic-compatible alternative to `autoTrigger` with inverted semantics. When `true`, the skill must be manually invoked.

  * `false` (default): Skill can be auto-invoked
  * `true`: Skill must be manually invoked with `/skill:name`

  ```yaml theme={null}
  disable-model-invocation: false
  ```

  <Info>
    `autoTrigger` takes precedence if both fields are present. Only specify one.
  </Info>
</ParamField>

<ParamField path="projectTypes" type="string[] | string?">
  Optional list of project types this skill applies to (e.g., `android`, `kotlin`, `web`).

  Can be a list or single string:

  ```yaml theme={null}
  projectTypes: [android, kotlin]
  ```

  ```yaml theme={null}
  projectTypes: android
  ```
</ParamField>

<ParamField path="icon" type="string?">
  Path to custom icon file (SVG, PNG, or JPG) relative to the skill directory.

  ```yaml theme={null}
  icon: icon.svg
  ```

  Icon search order:

  1. Path specified in frontmatter (`icon: path/to/icon.svg`)
  2. `icon.svg`, `icon.png`, or `icon.jpg` in skill directory
  3. Default markdown icon
</ParamField>

## Size Limits

* **Maximum**: 100KB per SKILL.md file
* **Warning threshold**: 50KB (will log a warning)

<Tip>
  Keep `SKILL.md` focused and under 500 lines. Put detailed reference material in separate files that Firebender reads only when needed.
</Tip>

## Supporting Files

Skills can reference additional files for detailed documentation:

```
pdf-processing/
├── SKILL.md          # Overview and quick start
├── FORMS.md          # Form field mappings
├── REFERENCE.md      # Detailed API docs
├── examples.md       # Usage examples
└── icon.svg          # Custom icon
```

Reference them in `SKILL.md`:

```markdown theme={null}
For form filling, see [FORMS.md](FORMS.md).
For detailed API reference, see [REFERENCE.md](REFERENCE.md).
```

Firebender can use the Read tool to access these files when needed, keeping the main skill content lightweight.

## Examples

<AccordionGroup>
  <Accordion title="Android Test Writer">
    ```markdown .firebender/skills/android-test-writer/SKILL.md theme={null}
    ---
    name: android-test-writer
    description: Writes comprehensive unit and UI tests for Android apps. Use when creating tests, improving test coverage, or debugging test failures.
    version: 1.0.0
    projectTypes: [android, kotlin]
    autoTrigger: true
    ---

    # Android Test Writer

    ## Unit Tests

    Use JUnit 5 with MockK for mocking. Example:

    @Test
    fun repository returns cached data when available() {
        val cachedUser = User(id = 1, name = "Test")
        every { cache.get("user_1") } returns cachedUser
        
        val result = repository.getUser(1)
        
        assertEquals(cachedUser, result)
        verify(exactly = 0) { api.fetchUser(any()) }
    }

    ## UI Tests

    Use Compose Testing for UI verification. Example:

    @Test
    fun loginScreen_showsErrorOnInvalidCredentials() {
        composeTestRule.setContent {
            LoginScreen(viewModel)
        }
        
        composeTestRule.onNodeWithText("Login").performClick()
        composeTestRule.onNodeWithText("Invalid credentials").assertIsDisplayed()
    }

    ## Best Practices

    - Test ViewModels with fake repositories
    - Use runTest for coroutine testing
    - Mock Android framework dependencies
    - Aim for 80%+ coverage on business logic
    ```
  </Accordion>

  <Accordion title="Database Query Helper">
    ```markdown ~/.firebender/skills/database-query/SKILL.md theme={null}
    ---
    name: database-query
    description: Generates SQL queries and analyzes database schemas. Use when working with databases, writing queries, or optimizing database performance.
    version: 1.0.0
    autoTrigger: true
    ---

    # Database Query Helper

    ## Schema

    Current database schema is documented in [schema.md](schema.md).

    ## Query Guidelines

    ### Performance
    - Always use indexes for WHERE clauses
    - Avoid SELECT * in production
    - Use EXPLAIN ANALYZE for complex queries

    ### Android Room

    Example query:

    @Query("SELECT * FROM users WHERE age > :minAge ORDER BY name ASC")
    suspend fun getUsersOlderThan(minAge: Int): List<User>

    ### Common Patterns

    See [examples.md](examples.md) for:
    - Pagination queries
    - Join optimization
    - Transaction patterns
    ```
  </Accordion>

  <Accordion title="Commit Message Generator">
    ```markdown ~/.firebender/skills/commit-helper/SKILL.md theme={null}
    ---
    name: commit-helper
    description: Generates clear, conventional commit messages from git diffs. Use when writing commit messages, reviewing staged changes, or before committing code.
    version: 1.0.0
    autoTrigger: true
    ---

    # Commit Message Helper

    ## Process

    1. Run git diff --staged to see changes
    2. Analyze the changes:
       - What components are affected?
       - What functionality changed?
       - Why was this change needed?
    3. Generate commit message in conventional format

    ## Format

    type(scope): subject

    body

    footer

    ## Types
    - feat: New feature
    - fix: Bug fix
    - refactor: Code restructuring
    - perf: Performance improvement
    - test: Adding tests
    - docs: Documentation changes
    - chore: Build/tooling changes

    ## Rules
    - Subject line: 50 chars max, present tense
    - Body: Explain what and why, not how
    - Reference issues in footer: Fixes #123

    ## Example

    feat(auth): add biometric authentication

    Implement fingerprint and face recognition for login.
    Users can now authenticate using device biometrics as
    an alternative to password entry.

    - Add BiometricPrompt integration
    - Update AuthViewModel with biometric flow
    - Add fallback to password on biometric failure

    Fixes #456
    ```
  </Accordion>

  <Accordion title="Code Review Skill">
    ```markdown .firebender/skills/pr-reviewer/SKILL.md theme={null}
    ---
    name: pr-reviewer
    description: Reviews pull requests for code quality, security issues, and best practices. Use when reviewing PRs, analyzing code changes, or before approving merge requests.
    version: 1.0.0
    autoTrigger: true
    projectTypes: [android, kotlin]
    ---

    # Pull Request Reviewer

    ## Review Checklist

    ### Code Quality
    - [ ] Functions are focused and single-purpose
    - [ ] Variable names are descriptive
    - [ ] No code duplication
    - [ ] Proper error handling

    ### Android Specific
    - [ ] No memory leaks (lifecycle-aware components)
    - [ ] Proper thread handling (coroutines, not blocking)
    - [ ] UI updates on main thread
    - [ ] Resources properly released

    ### Security
    - [ ] No hardcoded secrets or API keys
    - [ ] Input validation on user data
    - [ ] SQL injection prevention (use parameterized queries)
    - [ ] Proper permission checks

    ### Testing
    - [ ] Unit tests for business logic
    - [ ] UI tests for critical flows
    - [ ] Edge cases covered

    ### Performance
    - [ ] No unnecessary object creation in loops
    - [ ] Efficient list rendering (lazy loading)
    - Image loading optimized (Coil caching)

    ## Review Process

    1. Read the PR description and linked issues
    2. Check git diff main...HEAD for all changes
    3. Review each file systematically
    4. Run tests: ./gradlew test
    5. Build and run app if UI changes
    6. Provide specific, actionable feedback

    ## Feedback Template

    **Strengths:**
    - [What's done well]

    **Issues:**
    - [Critical issues that block merge]

    **Suggestions:**
    - [Optional improvements]
    ```
  </Accordion>
</AccordionGroup>

## Invocation

Skills can be invoked in three ways:

### 1. Auto-trigger

Firebender automatically invokes skills based on their description:

```
User: "Help me write a commit message for these changes"
→ Firebender auto-invokes commit-helper skill
```

### 2. Manual invocation

Use the `/skill:name` command:

```
/skill:commit-helper
```

### 3. Slash command menu

Type `/skill:` to see available skills in autocomplete.

## Live Reload

<Info>
  Skills are loaded fresh from disk on each invocation. Changes to SKILL.md files take effect immediately - no restart or cache clearing needed.
</Info>

## Version Control

### Team Skills (Recommended)

Commit team skills to share with your team:

```bash theme={null}
git add .firebender/skills/
git commit -m "Add Android test writer skill"
git push
```

Everyone who pulls gets the skills automatically.

### Personal Skills

Keep personal preferences in `~/.firebender/skills/` (not committed):

```bash theme={null}
~/.firebender/skills/
├── my-preferences/
│   └── SKILL.md
└── personal-scripts/
    └── SKILL.md
```

## Cross-Compatibility

Skills work across multiple AI coding tools. In addition to Firebender directories, Firebender also reads skills from these alternative locations:

**User-level** (in home directory):

* `~/.firebender/skills/` (recommended)
* `~/.claude/skills/`
* `~/.codex/skills/`
* `~/.cursor/skills/`
* `~/.goose/skills/`
* `~/.agents/skills/`

**Team-level** (in project directory):

* `.firebender/skills/` (recommended)
* `.claude/skills/`
* `.codex/skills/`
* `.cursor/skills/`
* `.goose/skills/`
* `.agents/skills/`

This allows teams to use the same skills across different AI coding tools without duplicating skill files.

## Best Practices

### Write Specific Descriptions

**Bad**:

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

**Good**:

```yaml theme={null}
description: Writes comprehensive unit and UI tests for Android apps using JUnit 5, MockK, and Compose Testing. Use when creating tests, improving test coverage, or debugging test failures.
```

### Progressive Disclosure

Keep `SKILL.md` concise, put details in linked files:

```markdown theme={null}
## Quick Start
[Brief instructions]

For detailed API reference, see [reference.md](reference.md).
For advanced usage, see [advanced.md](advanced.md).
```

### Use Executable Scripts

Avoid bash scripts in code blocks. Create executable files instead:

**Bad**:

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

**Good**:

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

Reference in SKILL.md:

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

### Include Concrete Examples

Show real usage:

````markdown theme={null}
## Example

```kotlin
// Create Room database
@Database(entities = [User::class], version = 1)
abstract class AppDatabase : RoomDatabase() {
    abstract fun userDao(): UserDao
}
```
````

## Troubleshooting

### Skill Not Auto-Triggering

Make the description more specific with keywords users would say:

```yaml theme={null}
# Instead of:
description: Helps with code review

# Do this:
description: Reviews pull requests for code quality, security issues, and Android best practices. Use when reviewing PRs, analyzing code changes, or checking merge requests.
```

### Skill Too Large

Split detailed content into separate files:

```
my-skill/
├── SKILL.md          # Keep under 500 lines
├── api-reference.md  # Detailed API docs
├── examples.md       # Many examples
└── advanced.md       # Advanced topics
```

## Related Documentation

* [Skills Overview](/multi-agent/skills) - User guide for creating and using skills
* [Commands](/api-reference/commands) - Custom AI commands for your workflow
* [Rules](/api-reference/rules) - Project-wide AI behavior rules