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.

Quality

81%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

92%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is an exemplary lean skill document: concrete paths, commands, and constraints with no filler, a clear numbered workflow ending in build/test verification, and appropriate structure for its size. The only minor gap is the absence of a minimal SKILL.md template snippet for the create step.

Dimension	Reasoning	Score
Conciseness	Roughly 35 lean lines with zero padding: no explanation of concepts Claude already knows (no "what a skill is" tutorial, no Go embed primer); every line (embed directive, Deduplicate override rule, test name, build command) earns its place.	5 / 5
Actionability	Concrete, executable guidance throughout — exact paths ("internal/skills/builtin/<skill-name>/SKILL.md"), copy-paste commands ("go build . && go test ./internal/skills/..."), a specific test ("TestDiscoverBuiltin"), and a hard constraint ("The directory name must match the `name` field"). Falls short of 5 only because no minimal SKILL.md frontmatter template is provided to copy.	4 / 5
Workflow Clarity	The "Adding a New Builtin Skill" section gives a clear numbered sequence (create file → auto-picked-up by embed → add test assertion → build and test) with an explicit verification step. This is a simple, non-destructive single-task skill where the sequence is unambiguous.	5 / 5
Progressive Disclosure	Under 50 lines with no need for external reference files; content is well-organized into "How It Works", "Adding a New Builtin Skill", and an existing-skills table, so well-organized sections fully satisfy disclosure for a skill this size.	5 / 5
	Total	19 / 20 Passed

Description

61%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description has a strong, explicit "Use when..." trigger clause with good niche scoping, but it never states what the skill provides — the entire description is a when-clause. Adding a one-line what-statement (e.g., how skills are embedded via go:embed and how to add or edit one) would round it out.

Suggestions

Add a what-statement before the Use when clause, e.g. "Documents how Crush embeds skills into the binary (go:embed, discovery, override rules) and how to add or edit them. Use when..."

Include natural trigger synonyms such as "add a skill", "SKILL.md", or "embed a skill" to broaden keyword coverage.

Mention a concrete artifact or two (e.g., "SKILL.md frontmatter format", "crush://skills/ paths") to raise specificity beyond generic create/edit/understand verbs.

Dimension	Reasoning	Score
Specificity	Names the domain (Crush builtin skills) with a couple of actions ("creating a new builtin skill", "editing an existing builtin skill"), but "understand how the embedded skill system works" is abstract and no concrete artifacts like the embed mechanism or SKILL.md format are mentioned.	3 / 5
Completeness	The "when" is explicit ("Use when creating... editing... or when the user needs to understand..."), but there is no statement of what the skill does — the what is only weakly implied through the trigger actions, sitting between anchor 2 (only 'when' without 'what') and a clearly stated what.	3 / 5
Trigger Term Quality	"builtin skill", "Crush", "embedded skill system", and "internal/skills/builtin/" are phrases a user would naturally say, but common variations like "add a skill", "SKILL.md", or "embed a skill" are missing.	4 / 5
Distinctiveness Conflict Risk	Scoped narrowly to "builtin skill for Crush" and "internal/skills/builtin/", giving a clear niche with only minor overlap risk against generic skill-authoring guidance.	4 / 5
	Total	14 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: charmbracelet/crush
Path: .agents/skills/builtin-skills/SKILL.md
Commit: 8da3490

Reviewed: 4 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.