phoenix-cli-development

Design and implementation guide for the Phoenix CLI (`px`). Covers the noun-verb command structure, dual-audience design (humans and coding agents), Commander.js patterns, configuration resolution, output formats, exit codes, and conventions for adding or modifying commands. Triggers when working on phoenix-cli commands — adding new commands, modifying existing ones, refactoring command structure, or reviewing CLI code. Also triggers on mentions of `px` commands, CLI design, or adding a new resource to the CLI.

2.25x

Quality

88%

Does it follow best practices?

Impact

99%

2.25x

Average score across 3 eval scenarios

Securityby

Risky

Do not use without reviewing

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 identifies its domain (Phoenix CLI / `px`), lists specific capabilities and patterns it covers, and provides explicit trigger conditions. It uses third-person voice appropriately and includes both natural trigger terms and a well-structured 'Triggers when...' clause that covers multiple realistic scenarios.

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete aspects: noun-verb command structure, dual-audience design, Commander.js patterns, configuration resolution, output formats, exit codes, and conventions for adding/modifying commands. These are concrete, actionable topics.	3 / 3
Completeness	Clearly answers both 'what' (design and implementation guide covering specific patterns and conventions) and 'when' (explicit 'Triggers when...' clause listing multiple scenarios like adding commands, modifying existing ones, reviewing CLI code, mentions of `px`).	3 / 3
Trigger Term Quality	Includes natural keywords users would say: 'phoenix-cli', 'px', 'CLI design', 'adding new commands', 'modifying existing ones', 'refactoring command structure', 'CLI code', 'new resource to the CLI'. Good coverage of variations a developer would naturally use.	3 / 3
Distinctiveness Conflict Risk	Highly distinctive — targets a specific tool ('Phoenix CLI', '`px`'), specific framework (Commander.js), and specific design patterns (noun-verb structure, dual-audience). Very unlikely to conflict with other skills.	3 / 3
	Total	12 / 12 Passed

Implementation

77%

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

This is a strong, highly actionable CLI design specification with excellent workflow clarity, particularly the 18-step checklist with validation gates. The content is well-structured and provides concrete, executable guidance throughout. The main weakness is moderate verbosity — some explanatory framing and rationale could be trimmed since Claude doesn't need to understand *why* noun-verb is good, just *how* to implement it in this codebase.

Suggestions

Trim explanatory framing (e.g., 'The Phoenix CLI is a command-line interface for...', RFC 2119 explanation) — Claude knows what CLIs are and can infer keyword conventions from usage.

Consider splitting reference material (exit codes table, naming conventions, standard verbs table) into a separate REFERENCE.md to keep the main skill leaner and improve progressive disclosure.

Dimension	Reasoning	Score
Conciseness	The skill is thorough and mostly well-targeted, but includes some explanatory content Claude doesn't need (e.g., explaining what RFC 2119 keywords are, explaining what noun-verb means, describing what a CLI is). Some sections like the dual-audience design rationale could be tightened. However, most content is genuinely instructive and specific to this codebase.	2 / 3
Actionability	Highly actionable with concrete code examples (TypeScript interfaces, bash commands, JSON output shapes), specific file paths (src/exitCodes.ts, src/config.ts, src/io.ts), exact function names (resolveConfig(), writeOutput(), writeError()), and a detailed 18-step checklist for adding new commands. The examples are copy-paste ready and the patterns are clearly specified.	3 / 3
Workflow Clarity	The checklist for adding a new resource command is a clear, sequenced 18-step workflow with explicit validation checkpoints (step 10: run tests, step 11: run build, step 18: manual verification with --format raw). The migration workflow for backward compatibility also has clear sequencing. Feedback loops are present (fix failures before proceeding).	3 / 3
Progressive Disclosure	The content is well-structured with clear headers and logical sections, but it's a monolithic document (~300 lines) with no references to supporting files. Some content like the full exit codes table, naming conventions, and testing details could be split into separate reference files. However, given no bundle files exist, the inline approach is reasonable though not optimal.	2 / 3
	Total	10 / 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
metadata_field	'metadata' should map string keys to string values	Warning

	Total	10 / 11 Passed

Repository: Arize-ai/phoenix
Commit: 924117e

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.