1---
 2name: builtin-skills
 3description:
 4  Use when creating a new builtin skill for Crush, editing an existing builtin
 5  skill (internal/skills/builtin/), or when the user needs to understand how the
 6  embedded skill system works.
 7---
 8
 9# Builtin Skills
10
11Crush embeds skills directly into the binary via `internal/skills/builtin/`.
12These are always available without user configuration.
13
14## How It Works
15
16- Each skill lives in `internal/skills/builtin/<skill-name>/SKILL.md`.
17- The tree is embedded at compile time via `//go:embed builtin/*` in
18  `internal/skills/embed.go`.
19- `DiscoverBuiltin()` walks the embedded FS, parses each `SKILL.md`, and sets
20  paths with the `crush://skills/` prefix (e.g., `crush://skills/jq/SKILL.md`).
21- The View tool resolves `crush://` paths from the embedded FS, not disk.
22- User skills with the same name override builtins (last occurrence wins in
23  `Deduplicate()`).
24
25## Adding a New Builtin Skill
26
271. Create `internal/skills/builtin/<skill-name>/SKILL.md` with YAML frontmatter
28   (`name`, `description`) and markdown instructions. The directory name must
29   match the `name` field.
302. No extra wiring needed — `//go:embed builtin/*` picks up new directories
31   automatically.
323. Add a test assertion in `TestDiscoverBuiltin` in
33   `internal/skills/skills_test.go` to verify discovery.
344. Build and test: `go build . && go test ./internal/skills/...`
35
36## Existing Builtin Skills
37
38| Skill          | Directory               | Description                                |
39| -------------- | ----------------------- | ------------------------------------------ |
40| `crush-config` | `builtin/crush-config/` | Crush configuration help                   |
41| `crush-hooks`  | `builtin/crush-hooks/`  | Authoring, configuring and debugging hooks |
42| `jq`           | `builtin/jq/`           | jq JSON processor usage guide              |