builtin-skills · diff
git:20260420.0a86d5f to git:20260426.b9fdf72
18 added, 15 removed. Audit A to B.
---
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.
+ 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`).
+ - `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()`).
+ - 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.
+ 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 |
- | `jq` | `builtin/jq/` | jq JSON processor usage guide |
+ | 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 |