docs

Skills

Skills are lightweight, discoverable agent knowledge: a directory with a SKILL.md whose frontmatter is surfaced to the model, and whose body loads on demand.

Discovery

Skills are discovered from these directories (first match wins per directory):

  • <cwd>/.dex/skills
  • <cwd>/.agents/skills
  • $XDG_CONFIG_HOME/dex/skills (or ~/.config/dex/skills)
  • plus any --skill <dir> directories you pass.

Writing a skill

---
name: my-skill
description: Short description surfaced to the model.
---

Detailed instructions / reference content...
  • Only name and description enter the system prompt — cheap in tokens, visible to the model for triggering.
  • Names must be non-empty and limited to [a-zA-Z0-9_-]; an invalid name is rejected with a warning.
  • The full body is loaded when the conversation references it or you invoke it explicitly.

Loading a skill

Type /skill:<name> in the TUI to inject the skill's full content into the conversation:

> /skill:ponytail

Project instructions

Related but separate: a repo-level AGENTS.md (or CLAUDE.md, nearest parent wins) is appended to the system prompt automatically — no slash command needed. That is the right home for conventions dex should always follow; skills are for instructions you want available but loaded only when relevant.