Using Skills

Skills are reusable sets of instructions and resources that teach goose how to perform specific tasks. A skill can range from a simple checklist to a detailed workflow with domain expertise, and can include supporting files like scripts or templates. Example use cases include deployment procedures, code review checklists, and API integration guides.

info

This functionality requires the built-in Skills extension to be enabled (it's enabled by default).

When a session starts, goose adds any skills that it discovers to its instructions. During the session, goose automatically loads a skill when:

Your request clearly matches a skill's purpose
You explicitly ask to use a skill, for example:
- "Use the code-review skill to review this PR"
- "Follow the new-service skill to set up the auth service"
- "Apply the deployment skill"

You can also ask goose what skills are available.

Other goose features that support reuse

.goosehints: Best for general preferences, project context, and repeated instructions like "Always use TypeScript"
recipes: Shareable configurations that package instructions, prompts, and settings together

Claude Compatibility

goose skills use the same format as Claude Desktop skills. goose discovers skills from both .claude/skills/ and .goose/skills/ directories, so you can share skills between both tools or create tool-specific versions as needed.

When the same skill name exists in multiple directories, goose follows the priority order listed in Skill Locations. Later directories override earlier ones regardless of whether they're .claude or .goose directories.

Creating a Skill

Create a skill when you have a repeatable workflow that involves multiple steps, specialized knowledge, or supporting files.

Skill Locations

Skills can be stored globally and/or per-project. goose checks all of these directories in order and combines what it finds. If the same skill name exists in multiple directories, the latest directory takes priority:

~/.claude/skills/ — Global, shared with Claude Desktop
~/.config/goose/skills/ — Global, goose-specific
./.claude/skills/ — Current directory, shared with Claude Desktop
./.goose/skills/ — Current directory, goose-specific (highest priority)

Use global skills for workflows you use across projects. Use project-specific skills for procedures unique to a codebase.

Skill File Structure

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

~/.config/goose/skills/
└── code-review/
    └── SKILL.md

A SKILL.md file requires YAML frontmatter with name and description, followed by the skill content:

---
name: code-review
description: Comprehensive code review checklist for pull requests
---

# Code Review Checklist

When reviewing code, check each of these areas:

## Functionality
- [ ] Code does what the PR description claims
- [ ] Edge cases are handled
- [ ] Error handling is appropriate

## Code Quality
- [ ] Follows project style guide
- [ ] No hardcoded values that should be configurable
- [ ] Functions are focused and well-named

## Testing
- [ ] New functionality has tests
- [ ] Tests are meaningful, not just for coverage
- [ ] Existing tests still pass

## Security
- [ ] No credentials or secrets in code
- [ ] User input is validated
- [ ] SQL queries are parameterized

Supporting Files

Skills can include supporting files like scripts, templates, or configuration files. Place them in the skill directory:

~/.config/goose/skills/
└── api-setup/
    ├── SKILL.md
    ├── setup.sh
    └── templates/
        └── config.template.json

When goose loads the skill, it sees the supporting files and can access them using the Developer extension's file tools.

Example Skill with Supporting Files

SKILL.md:

---
name: api-setup
description: Set up API integration with configuration and helper scripts
---

# API Setup

This skill helps you set up a new API integration with our standard configuration.

## Steps

1. Run `setup.sh <api-name>` to create the integration directory
2. Copy `templates/config.template.json` to your integration directory
3. Update the config with your API credentials
4. Test the connection

## Configuration

The config template includes:
- `api_key`: Your API key (get from the provider's dashboard)
- `endpoint`: API endpoint URL
- `timeout`: Request timeout in seconds (default: 30)

## Verification

After setup, verify:
- [ ] Config file is valid JSON
- [ ] API key is set and not a placeholder
- [ ] Test connection succeeds

setup.sh:

#!/bin/bash
API_NAME=$1
mkdir -p "integrations/$API_NAME"
cp templates/config.template.json "integrations/$API_NAME/config.json"
echo "Created integration directory for $API_NAME"
echo "Edit integrations/$API_NAME/config.json with your credentials"

templates/config.template.json:

{
  "api_key": "YOUR_API_KEY_HERE",
  "endpoint": "https://api.example.com/v1",
  "timeout": 30,
  "retry_attempts": 3
}

Common Use Case Examples

Deployment Workflow

---
name: production-deploy
description: Safe deployment procedure for production environment
---

# Production Deployment

## Pre-deployment
1. Ensure all tests pass
2. Get approval from at least 2 reviewers
3. Notify #deployments channel

## Deploy
1. Create release branch from main
2. Run `npm run build:prod`
3. Deploy to staging, verify, then production
4. Monitor error rates for 30 minutes

## Rollback
If error rate exceeds 1%:
1. Revert to previous deployment
2. Notify #incidents channel
3. Create incident report

Testing Strategy

---
name: testing-strategy
description: Guidelines for writing effective tests in this project
---

# Testing Guidelines

## Unit Tests
- Test one thing per test
- Use descriptive test names: `test_user_creation_fails_with_invalid_email`
- Mock external dependencies

## Integration Tests
- Test API endpoints with realistic data
- Verify database state changes
- Clean up test data after each test

## Running Tests
- `npm test` — Run all tests
- `npm test:unit` — Unit tests only
- `npm test:integration` — Integration tests (requires database)

API Integration Guide

---
name: square-integration
description: How to integrate with our Square account
---

# Square Integration

## Authentication
- Test key: Use `SQUARE_TEST_KEY` from `.env.test`
- Production key: In 1Password under "Square Production"

## Common Operations

### Create a customer
```javascript
const customer = await squareup.customers.create({
  email: user.email,
  metadata: { userId: user.id }
});
```

### Handle webhooks
Always verify webhook signatures. See `src/webhooks/square.js` for our handler pattern.

## Error Handling
- `card_declined`: Show user-friendly message, suggest different payment method
- `rate_limit`: Implement exponential backoff
- `invalid_request`: Log full error, likely a bug in our code

Best Practices

Keep skills focused — One skill per workflow or domain. If a skill is getting long, consider splitting it.
Write for clarity — Skills are instructions for goose. Use clear, direct language and numbered steps.
Include verification steps — Help goose confirm the workflow completed successfully.

Claude Compatibility​

Creating a Skill​

Skill Locations​

Skill File Structure​

Supporting Files​

Common Use Case Examples​

Best Practices​