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.

Type /help me create a skill to get help creating skills

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:

SKILL.md

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

name · string · required

Skill identifier used for invocation (e.g., /skill:commit-helper).

• Lowercase with hyphens
• Maximum 64 characters
• Must be unique within scope

description · 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:

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.

version · string?

Version string for documentation and tracking purposes.

version: 1.0.0

autoTrigger · 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

autoTrigger: true

disable-model-invocation · 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

disable-model-invocation: false

autoTrigger takes precedence if both fields are present. Only specify one.

projectTypes · string[] | string?

Optional list of project types this skill applies to (e.g., android, kotlin, web).

Can be a list or single string:

projectTypes: [android, kotlin]

projectTypes: android

icon · string?

Path to custom icon file (SVG, PNG, or JPG) relative to the skill directory.

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

Size Limits

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

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

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:

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

Android Test Writer

.firebender/skills/android-test-writer/SKILL.md

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

Database Query Helper

~/.firebender/skills/database-query/SKILL.md

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

Commit Message Generator

~/.firebender/skills/commit-helper/SKILL.md

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

Code Review Skill

.firebender/skills/pr-reviewer/SKILL.md

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

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

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

Version Control

Team Skills (Recommended)

Commit team skills to share with your team:

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):

~/.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:

description: Helps with testing

Good:

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:

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

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

Good:

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

Reference in SKILL.md:

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

Include Concrete Examples

Show real usage:

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

# 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 - User guide for creating and using skills
• Commands - Custom AI commands for your workflow
• Rules - Project-wide AI behavior rules