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