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 (joelclaw, slog), 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.

1.64x

Quality

85%

Does it follow best practices?

Impact

94%

1.64x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Quality

Discovery

100%

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

This is a strong skill description that clearly defines a specific niche (agent-first CLI design), lists concrete capabilities, and provides explicit trigger guidance with both a 'Use when' clause and a 'Triggers on' clause. The description is concise yet comprehensive, with domain-specific terminology that distinguishes it from general coding skills while remaining accessible through natural trigger terms.

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions: 'Design and build agent-first CLIs', 'HATEOAS JSON responses', 'context-protecting output', 'self-documenting command trees'. These are concrete, specific capabilities rather than vague language.	3 / 3
Completeness	Clearly answers both 'what' (design/build agent-first CLIs with HATEOAS JSON, context-protecting output, self-documenting command trees) and 'when' (explicit 'Use when...' clause with specific triggers and scenarios). The 'Triggers on' clause adds further explicit guidance.	3 / 3
Trigger Term Quality	Includes natural trigger terms users would say: 'build a CLI', 'add a command', 'CLI design', 'agent-friendly output', 'command-line tool creation'. Also mentions specific CLI names (joelclaw, slog) for disambiguation. Good coverage of natural variations.	3 / 3
Distinctiveness Conflict Risk	Highly distinctive niche: agent-first CLI design with HATEOAS JSON is a very specific domain. The mention of specific CLI names (joelclaw, slog) and specialized concepts (context-protecting output, self-documenting command trees) make it unlikely to conflict with generic coding or other tool-building skills.	3 / 3
	Total	12 / 12 Passed

Implementation

70%

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

This is a highly actionable and well-structured skill with excellent concrete examples, complete TypeScript types, and a thorough checklist. Its main weakness is that it's monolithic — the streaming protocol (ADR-0058), anti-patterns, and implementation details should be split into referenced files to respect token budget. The content itself is high quality but would benefit significantly from progressive disclosure restructuring.

Suggestions

Extract the Streaming Protocol (NDJSON/ADR-0058) section into a separate STREAMING.md file and reference it from the main skill with a one-line summary

Move the anti-patterns table to an ANTI-PATTERNS.md or append it to a reference file, since it largely restates the core principles already covered in detail

Consider extracting the full TypeScript type definitions and Redis subscription patterns into a REFERENCE.md file, keeping only the response envelope shape inline

Dimension	Reasoning	Score
Conciseness	The skill is comprehensive and mostly well-written, but it's quite long (~300+ lines) with some redundancy. The anti-patterns table largely restates principles already covered in detail above. The streaming section is extensive and could be split into a separate file. However, it generally avoids explaining things Claude already knows and stays focused on domain-specific patterns.	2 / 3
Actionability	Excellent actionability throughout — concrete JSON envelope schemas, executable TypeScript code examples, specific bash commands for building/installing, complete type definitions, and a detailed checklist for new commands. The HATEOAS examples are copy-paste ready with realistic data.	3 / 3
Workflow Clarity	The 'Adding a new command' section provides a clear 7-step sequence. The checklist at the end serves as a validation checkpoint. The streaming section has explicit cleanup requirements and signal handling. Error handling workflows include fix suggestions and contextual next_actions, creating a natural feedback loop.	3 / 3
Progressive Disclosure	This is a monolithic wall of content — the streaming protocol section alone is substantial enough to warrant its own file. There are no references to separate files for advanced topics despite the content being well over 200 lines. The TODO section, anti-patterns table, streaming protocol, and Redis subscription patterns could all be split out. Reference implementations are mentioned but not linked to separate documentation files.	1 / 3
	Total	9 / 12 Passed

Validation

90%

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 — 10 / 11 Passed

Validation for skill structure

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

	Total	10 / 11 Passed

Repository: joelhooks/joelclaw
Commit: 03f0a59

Reviewed: 5 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.