Skip to content
Crystal CodeDocs
ENEnglish
AutoEnglish简体中文繁體中文

Skills

Skills are OpenCode-compatible instruction folders. They are not prompt overlays. The model sees a list of available skills and loads one with the skill tool. When Skills is enabled, read/list/tree/glob/grep/search of any path inside a Skills search directory (skill / skills trees, including scripts and other files that are not SKILL.md) auto-passes; it does not ask you. Set "skills": false in config.json to disable the tool, the guidance, and that auto-pass. Other files outside the workspace still need approval (you, or the Review model in Review or Audit).

Each skill is a directory with a SKILL.md that starts with YAML frontmatter (name and description required). The skill id is the directory name when it matches ^[a-z0-9]+(-[a-z0-9]+)*$ (1–64 characters). Frontmatter name may be that id or a display title and does not have to match the directory. If the directory name is not a valid id, a valid frontmatter name is used instead. Folded (>) and literal (|) YAML descriptions are accepted.

Discovery follows OpenCode’s global and project walk. Later sources overwrite earlier ones with the same name. Crystal-native paths win over OpenCode-compatible paths.

Global:

  1. ~/.claude/skills/<name>/SKILL.md
  2. ~/.agents/skills/<name>/SKILL.md
  3. ~/.config/opencode/{skill,skills}/<name>/SKILL.md (XDG_CONFIG_HOME is honored)
  4. ~/.opencode/{skill,skills}/<name>/SKILL.md
  5. ~/.crystal/{skill,skills}/<name>/SKILL.md

Project, walking from the workspace up to the git root:

  1. .claude/skills/<name>/SKILL.md
  2. .agents/skills/<name>/SKILL.md
  3. .opencode/{skill,skills}/<name>/SKILL.md
  4. .crystal/{skill,skills}/<name>/SKILL.md

/cd and /space reload skills and external tool sets from the new workspace. Both, and a resume that enters another directory, reload prompts from that workspace. Resume refreshes the first system message from the current prompt files, the current <env> block, and current skill guidance.