---
name: builtin-skills
description:
  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.
---

# Builtin Skills

Crush embeds skills directly into the binary via `internal/skills/builtin/`.
These are always available without user configuration.

## How It Works

- Each skill lives in `internal/skills/builtin/<skill-name>/SKILL.md`.
- The tree is embedded at compile time via `//go:embed builtin/*` in
  `internal/skills/embed.go`.
- `DiscoverBuiltin()` walks the embedded FS, parses each `SKILL.md`, and sets
  paths with the `crush://skills/` prefix (e.g., `crush://skills/jq/SKILL.md`).
- The View tool resolves `crush://` paths from the embedded FS, not disk.
- User skills with the same name override builtins (last occurrence wins in
  `Deduplicate()`).

## Adding a New Builtin Skill

1. Create `internal/skills/builtin/<skill-name>/SKILL.md` with YAML frontmatter
   (`name`, `description`) and markdown instructions. The directory name must
   match the `name` field.
2. No extra wiring needed — `//go:embed builtin/*` picks up new directories
   automatically.
3. Add a test assertion in `TestDiscoverBuiltin` in
   `internal/skills/skills_test.go` to verify discovery.
4. Build and test: `go build . && go test ./internal/skills/...`

## Existing Builtin Skills

| Skill          | Directory               | Description                                |
| -------------- | ----------------------- | ------------------------------------------ |
| `crush-config` | `builtin/crush-config/` | Crush configuration help                   |
| `crush-hooks`  | `builtin/crush-hooks/`  | Authoring, configuring and debugging hooks |
| `jq`           | `builtin/jq/`           | jq JSON processor usage guide              |