Skip to main content
Crush supports the Agent Skills open standard for extending agent capabilities with reusable skill packages. Skills are folders containing a SKILL.md file with instructions that Crush can discover and activate on demand.

​
What are Agent Skills?

Agent Skills provide:
  • Reusable capabilities - Package domain knowledge and workflows
  • On-demand activation - Skills are loaded when needed
  • Standardized format - Works across compatible agent systems
  • Portable knowledge - Share skills across projects and teams

​
Skill Discovery Locations

Crush automatically discovers skills from these directories: Unix/Linux/macOS:
  • ~/.config/crush/skills/ (default)
  • ~/.config/agents/skills/ (alternative)
Windows:
  • %LOCALAPPDATA%\crush\skills\ (default)
  • %LOCALAPPDATA%\agents\skills\ (alternative)
The default skills directory can be overridden with the CRUSH_SKILLS_DIR environment variable.

​
Environment Variable Override

Set CRUSH_SKILLS_DIR to customize the skills directory: 
# Unix/Linux/macOS
export CRUSH_SKILLS_DIR="/custom/path/to/skills"

# Windows (PowerShell)
$env:CRUSH_SKILLS_DIR = "C:\custom\path\to\skills"

​
Configuration

Add additional skills paths in your crush.json: 
{
  "$schema": "https://charm.land/crush.json",
  "options": {
    "skills_paths": [
      "~/.config/crush/skills",
      "./project-skills",
      "./docs/skills"
    ]
  }
}
Windows example: 
{
  "$schema": "https://charm.land/crush.json",
  "options": {
    "skills_paths": [
      "%LOCALAPPDATA%\\crush\\skills",
      ".\\project-skills"
    ]
  }
}
Skills paths can be absolute or relative. Relative paths are resolved from the project root.

​
Installing Example Skills

Get started with example skills from anthropics/skills: 
# Create skills directory
mkdir -p ~/.config/crush/skills
cd ~/.config/crush/skills

# Clone and install skills
git clone https://github.com/anthropics/skills.git _temp
mv _temp/skills/* .
rm -rf _temp

​
Skill Structure

Each skill is a directory containing a SKILL.md file: 
~/.config/crush/skills/
├── web-research/
│   └── SKILL.md
├── code-review/
│   └── SKILL.md
└── documentation/
    ├── SKILL.md
    ├── templates/
    └── examples/
The SKILL.md file contains:
  • Skill name and description
  • Instructions for the agent
  • Example usage
  • Any supporting context

​
Creating Custom Skills

Create a custom skill by adding a directory with a SKILL.md file: 
# Create skill directory
mkdir -p ~/.config/crush/skills/my-custom-skill

# Create SKILL.md
cat > ~/.config/crush/skills/my-custom-skill/SKILL.md << 'EOF'
# My Custom Skill

This skill helps with [describe purpose].

## Instructions

When this skill is activated:

1. [Step-by-step instructions]
2. [What the agent should do]
3. [Expected outcomes]

## Examples

[Provide examples of how to use this skill]
EOF

​
Skill Template

Here’s a template for creating skills: 
# [Skill Name]

[Brief description of what this skill does]

## Purpose

[Detailed explanation of the skill's purpose and when to use it]

## Instructions

When activated, this skill provides the following capabilities:

1. **[Capability 1]**: [Description]
2. **[Capability 2]**: [Description]
3. **[Capability 3]**: [Description]

## Workflow

[Step-by-step process the agent should follow]

## Examples

### Example 1: [Use Case]

```
[Example input/output or scenario]
```

### Example 2: [Use Case]

```
[Example input/output or scenario]
```

## Best Practices

- [Practice 1]
- [Practice 2]
- [Practice 3]

## Resources

[Links to additional documentation or references]

​
Project-Specific Skills

You can create project-specific skills in your project directory: 
# Create project skills directory
mkdir -p ./skills/deployment

# Add project-specific deployment skill
cat > ./skills/deployment/SKILL.md << 'EOF'
# Deployment Skill

This skill handles deployment workflows for this project.

## Instructions

1. Build the project with `npm run build`
2. Run tests with `npm test`
3. Deploy to staging with `./scripts/deploy-staging.sh`
4. Deploy to production with `./scripts/deploy-prod.sh`
EOF
Then reference it in your configuration: 
{
  "$schema": "https://charm.land/crush.json",
  "options": {
    "skills_paths": [
      "~/.config/crush/skills",
      "./skills"
    ]
  }
}

​
Using Skills

Crush automatically discovers and loads skills from configured paths. You can reference skills in your conversations: 
> Use the code-review skill to review this pull request
or 
> Activate the deployment skill and deploy to staging
Skills are loaded on-demand, so there’s no performance penalty for having many skills configured.

​
Organizing Skills

Organize skills by category or purpose: 
~/.config/crush/skills/
├── development/
│   ├── code-review/
│   ├── testing/
│   └── refactoring/
├── documentation/
│   ├── api-docs/
│   ├── readme/
│   └── changelog/
├── devops/
│   ├── deployment/
│   ├── monitoring/
│   └── ci-cd/
└── research/
    ├── web-research/
    └── documentation-research/

​
Sharing Skills

Skills are portable - you can share them with your team:
  1. Git repository: Store skills in a Git repo
  2. Package manager: Distribute as npm/pip packages
  3. Direct sharing: Copy skill directories between projects

​
Security Considerations

Skills can contain arbitrary instructions for the agent. Review skills before adding them:
  • Only use skills from trusted sources
  • Review SKILL.md contents before activation
  • Be cautious with skills that execute commands
  • Use project-specific skill paths for sensitive workflows
Skills have access to the same tools and permissions as Crush. Only install skills you trust.

​
Next Steps

Permissions

Configure tool permissions

Agent Skills Standard

Learn more about the Agent Skills standard

Build docs developers (and LLMs) love

Get started for freeTalk to us