shell-builtins

Use when creating a new shell builtin command for Crush (internal/shell/), editing an existing one, or when the user needs to understand how commands are intercepted in Crush's embedded shell.

Quality

83%

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

86%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 highly actionable with executable Go examples and a clear step sequence, well-organized into sections. Minor tightening in the ctx-polling rationale and an explicit verification step would lift it further.

Suggestions

Trim the explanatory prose in step 4 to the essential invariant (poll ctx in unbounded loops; return ctx.Err() to remain interruptible).

Add a short final step to verify the new builtin, e.g. run the shell test suite or invoke the command in a smoke test.

Consider documenting how to test/debug a builtin briefly, or note where existing builtin tests live.

Dimension	Reasoning	Score
Conciseness	The body is dense and assumes Claude's knowledge of Go and POSIX shell emulation, but the extended rationale in step 4 about hook timeouts is slightly more than needed and could be trimmed.	4 / 5
Actionability	Provides copy-paste-ready Go code for the switch case, handler signature, ctx-polling loop, and return values, with specific file paths covering the common add-a-builtin case.	5 / 5
Workflow Clarity	A clear six-step numbered sequence with concrete file targets and code, but it lacks an explicit verification checkpoint (e.g. running tests to confirm the builtin registers).	4 / 5
Progressive Disclosure	A compact, well-sectioned single-file skill with clear headers and an Existing Builtins overview table; with no external references needed, the simple-skill structure qualifies for a top score.	5 / 5
	Total	18 / 20 Passed

Description

80%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.

A strong, specific description with an explicit 'Use when' trigger and a clearly scoped niche. The main weakness is limited synonym coverage in its trigger terms.

Suggestions

Add a few natural synonyms or variations to the trigger (e.g. 'intercept', 'override shell commands') to broaden keyword coverage.

Consider mentioning testing or verifying a new builtin to round out the action list toward comprehensive coverage.

Dimension	Reasoning	Score
Specificity	Names the domain and three concrete actions — 'creating a new shell builtin command', 'editing an existing one', and 'understand how commands are intercepted' — placing it above the 1-2 action anchor but short of comprehensive coverage.	4 / 5
Completeness	An explicit 'Use when' clause with three concrete trigger scenarios answers both what the skill does and when to invoke it, matching the anchor for clearly answering both with concrete trigger phrases.	5 / 5
Trigger Term Quality	Contains several relevant terms a Crush developer would say ('shell builtin command', 'editing an existing one', 'commands are intercepted'), but offers no synonyms or variations, leaving some natural phrasings uncovered.	3 / 5
Distinctiveness Conflict Risk	The narrow focus on Crush's embedded shell and the internal/shell/ path gives it a clear niche with distinct triggers and minimal overlap with other skills.	5 / 5
	Total	17 / 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/shell-builtins/SKILL.md
Commit: 8f63ee5

Reviewed: about 7 hours 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.