builtin-skills
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.
Best for Crush developersWorks with GitHubLow risk
⌘source
- author
@charmbracelet- language
- Go
★23kstars
1.5kforks
Apr 21, 2026
✦overview.md
Key Features
- ·Embedded directly into Crush binary
- ·Always available without user configuration
- ·User skills can override builtins with same name
Use Cases
- →Creating a new builtin skill for Crush
- →Editing an existing builtin skill in internal/skills/builtin/
- →Understanding how the embedded skill system works
Best for
- ✓Crush developers
- ✓System maintainers
Not ideal for
- !End users
- !External skill development
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/*ininternal/skills/embed.go. DiscoverBuiltin()walks the embedded FS, parses eachSKILL.md, and sets paths with thecrush://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
- Create
internal/skills/builtin/<skill-name>/SKILL.mdwith YAML frontmatter (name,description) and markdown instructions. The directory name must match thenamefield. - No extra wiring needed —
//go:embed builtin/*picks up new directories automatically. - Add a test assertion in
TestDiscoverBuiltinininternal/skills/skills_test.goto verify discovery. - Build and test:
go build . && go test ./internal/skills/...
Existing Builtin Skills
$install
1-click copynpx skills add charmbracelet/crush --skill builtin-skillsSafety assessment
★
Clarity score
How clear and easy to understand the SKILL.md instructions are, rated from 1 to 5.
1/ 5
poorThe SKILL.md content is hard to understand and quite ambiguous.
◎
Actionability score
How directly an agent can act on the SKILL.md instructions, rated from 1 to 5.
1/ 5
not actionableThe SKILL.md is hard to act on; an agent would not know what to do.