Charm Docs

Appearance

Agent Skills ​

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.

Skill Discovery Paths ​

The global paths Crush looks for skills are:

  • $CRUSH_SKILLS_DIR
  • $XDG_CONFIG_HOME/agents/skills or ~/.config/agents/skills/
  • $XDG_CONFIG_HOME/crush/skills or ~/.config/crush/skills/
  • ~/.agents/skills/
  • ~/.claude/skills/
  • On Windows, Crush also looks at:
    • %LOCALAPPDATA%\agents\skills\ or %USERPROFILE%\AppData\Local\agents\skills\
    • %LOCALAPPDATA%\crush\skills\ or %USERPROFILE%\AppData\Local\crush\skills\
  • Additional paths configured via options.skills_paths

On top of that, Crush also loads skills in your project from the following relative paths:

  • .agents/skills
  • .crush/skills
  • .claude/skills
  • .cursor/skills
jsonc
{
  "$schema": "https://charm.land/crush.json",
  "options": {
    "skills_paths": [
      "~/.config/crush/skills", // Windows: "%LOCALAPPDATA%\\crush\\skills",
      "./project-skills",
    ],
  },
}

You can get started with example skills from anthropics/skills:

bash
# Unix
mkdir -p ~/.config/crush/skills
cd ~/.config/crush/skills
git clone https://github.com/anthropics/skills.git _temp
mv _temp/skills/* . && rm -rf _temp
powershell
# Windows (PowerShell)
mkdir -Force "$env:LOCALAPPDATA\crush\skills"
cd "$env:LOCALAPPDATA\crush\skills"
git clone https://github.com/anthropics/skills.git _temp
mv _temp/skills/* . ; rm -r -force _temp

User-Invocable Skills ​

Skills can be made invocable as commands from the commands palette (Ctrl+P). Add user-invocable: true to the skill's YAML frontmatter:

yaml
---
name: my-skill
description: A skill that can be invoked as a command.
user-invocable: true
---

User-invocable skills appear in the commands palette with a user: or project: prefix:

  • Skills from global directories show as user:skill-name
  • Skills from project directories show as project:skill-name

When invoked, the skill's instructions are loaded into the conversation context.

To prevent the model from auto-triggering a skill (while still allowing user invocation), add disable-model-invocation: true:

yaml
---
name: my-skill
description: Only invocable by users, not the model.
user-invocable: true
disable-model-invocation: true
---

Skills with disable-model-invocation won't appear in the model's available skills list but can still be invoked manually by users.

Disabling Skills ​

If you'd like to prevent Crush from using certain skills entirely, you can disable them via the options.disabled_skills list. Disabled skills are hidden from the agent, including builtin skills and skills discovered from disk.

json
{
  "$schema": "https://charm.land/crush.json",
  "options": {
    "disabled_skills": ["crush-config"]
  }
}