cli-design

Design and build agent-first CLIs with HATEOAS JSON responses, context-protecting output, and self-documenting command trees. Use when creating new CLI tools, adding commands to existing CLIs such as joelclaw, or reviewing CLI design for agent-friendliness. Triggers on 'build a CLI', 'add a command', 'CLI design', 'agent-friendly output', or any task involving command-line tool creation.

Quality

89%

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

78%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 code and a clear command-creation workflow, but it is dense and monolithic — envelope and streaming detail that could live in separate referenced files is inlined, limiting navigation and token efficiency.

Suggestions

Move the full Streaming Protocol (NDJSON) section and TypeScript type definitions into a separate referenced file (e.g. references/streaming.md) and keep only a concise summary plus a one-level link in SKILL.md.

Trim or relocate the long OAuth device-flow TODO into a roadmap reference file; it consumes significant tokens without guiding current command creation.

Reduce overlap between the Response Envelope section, the HATEOAS core principle, and the streaming terminal envelope by cross-referencing instead of restating the same shape.

Dimension	Reasoning	Score
Conciseness	Code-forward and free of padded explanations of concepts Claude already knows, but the envelope spec, HATEOAS section, and streaming-protocol/type-definition sections restate overlapping detail, and the lengthy inline TODO adds tokens that could be trimmed.	4 / 5
Actionability	Fully executable guidance throughout — Effect CLI Command.make examples, emit/emitResult/emitError helpers, streamFromRedis usage, bun build commands, and a concrete envelope schema — covering the common cases copy-paste ready.	5 / 5
Workflow Clarity	The 'Adding a new command' section is a clear 7-step sequence reinforced by a checklist, and streaming cleanup specifies SIGINT/SIGTERM and timeout handling; scored 4 rather than 5 because there is no explicit validate→fix→retry loop, though the skill is not primarily destructive/batch.	4 / 5
Progressive Disclosure	Well-organized with clear headers, but monolithic: the full envelope spec, streaming protocol, and TypeScript type definitions are all inlined in SKILL.md rather than split into one-level-deep reference files, and the provided assets (logos) are not referenced in the body.	3 / 5
	Total	16 / 20 Passed

Description

100%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 is precise, third-person, and fully answers both what the skill does and when to invoke it, with comprehensive natural trigger terms and a distinct niche. It is a model of the highest anchor on every dimension.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete capabilities — 'HATEOAS JSON responses', 'context-protecting output', and 'self-documenting command trees' — matching the comprehensive-coverage anchor; not 4 because coverage is full rather than having minor gaps.	5 / 5
Completeness	Explicitly answers both what ('Design and build agent-first CLIs with HATEOAS JSON responses, context-protecting output, and self-documenting command trees') and when ('Use when creating new CLI tools, adding commands to existing CLIs such as joelclaw, or reviewing CLI design for agent-friendliness') with concrete triggers.	5 / 5
Trigger Term Quality	Comprehensive natural trigger phrases with synonyms — 'build a CLI', 'add a command', 'CLI design', 'agent-friendly output' — plus 'any task involving command-line tool creation'; matches the anchor for full coverage including variations.	5 / 5
Distinctiveness Conflict Risk	Occupies a clear niche (agent-first CLI design with HATEOAS) anchored by the specific joelclaw system; trigger language is specialized enough to avoid firing for unrelated skills.	5 / 5
	Total	20 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: joelhooks/joelclaw
Path: skills/cli-design/SKILL.md
Commit: d952451

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.