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.

1.47x

Quality

96%

Does it follow best practices?

Impact

100%

1.47x

Average score across 2 eval scenarios

Securityby

High

Do not use without reviewing

Quality

Content

92%

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

A highly actionable, concise specification with a well-sequenced, validated workflow for adding commands. Its main weakness is progressive disclosure: it is a monolithic single file with no bundle references to offload reference-grade detail.

Suggestions

Extract the shared options type table and the MSW testing-harness detail into a references/ file (e.g., references/options-and-testing.md), leaving SKILL.md as a concise overview that links one level deep.

Move the full exit-code constant table and StructuredError interface into a reference file, summarizing only the essential invariants inline.

Add a brief "Where to look" navigation block near the top pointing to any future reference files so discovery is one level deep rather than all-inline.

Dimension	Reasoning	Score
Conciseness	Dense, directive prose using RFC 2119 keywords and compact tables; it does not explain concepts Claude already knows and nearly every line carries load-bearing specification. It is not level 2 because padding and beginner-level explanation are absent rather than present-but-tightenable.	3 / 3
Actionability	Provides executable, copy-paste-ready guidance throughout: typed interfaces (SpanListOptions), exact CLI invocations, named functions (resolveConfig(), writeOutput()), and a fully worked --help example. It is not level 2 because the examples are complete and runnable, not pseudocode or partially specified.	3 / 3
Workflow Clarity	The 18-step "Checklist for Adding a New Resource Command" is a clearly sequenced process with explicit validation checkpoints ("Run pnpm test — fix any failures before proceeding", "Run pnpm build — fix any type errors before proceeding", "Run manually with --format raw and --no-input to verify"). It is not level 2 because validation and feedback loops are explicit at each gate.	3 / 3
Progressive Disclosure	No bundle files exist (references/, scripts/, assets/ absent), so the ~300-line body is a single monolithic file with reference-grade detail (options type table, MSW testing harness, exit-code table) inlined that could be split into separate reference files. It is not level 3 because there is no one-level-deep reference structure to offload detail; it is not level 1 because sections are well-organized with clear headings.	2 / 3
	Total	11 / 12 Passed

Description

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.

A strong, third-person description that names a distinct tool and enumerates concrete capabilities with explicit, natural-language triggers. Both the what and the when are clearly answered, and there is no vague fluff.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete capabilities — "noun-verb command structure, dual-audience design (humans and coding agents), Commander.js patterns, configuration resolution, output formats, exit codes" — each a specific action area rather than vague language. It is not level 2 because the actions are enumerated comprehensively, not just naming the domain.	3 / 3
Completeness	Explicitly answers both what ("Design and implementation guide...Covers [enumerated capabilities]") and when ("Triggers when working on phoenix-cli commands... Also triggers on mentions of..."). It is not level 2 because the when/trigger guidance is explicit, not merely implied.	3 / 3
Trigger Term Quality	Natural phrases a user would say are present: "adding new commands, modifying existing ones, refactoring command structure, or reviewing CLI code" plus "mentions of `px` commands, CLI design, or adding a new resource." It is not level 2 because it covers multiple natural variations rather than a single keyword.	3 / 3
Distinctiveness Conflict Risk	Tied to a distinct niche ("Phoenix CLI (`px`)" with specific ``px`` command tokens) and narrow triggers, making conflict with unrelated skills unlikely. It is not level 2 because the named tool and concrete trigger terms create a clear, non-generic niche.	3 / 3
	Total	12 / 12 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
metadata_field	'metadata' should map string keys to string values	Warning

	Total	15 / 16 Passed

Repository: Arize-ai/phoenix
Path: js/packages/phoenix-cli/.agents/skills/phoenix-cli-development/SKILL.md
Commit: d9421a4

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.