Agent DX CLI

Predictable, safe, context-efficient CLI engineering

Purpose

Design, review, and refactor CLIs for agents. Preserve the user's scope and technology stack.

Workflow

1. Read code, current help, schema, and actual output. Record the tested artifact and version.
2. Assess the ten dimensions. Distinguish absent, unverified, and verified behavior.
3. Implement authorized changes. Correct acceptance blockers first. Reuse established libraries. CLI, MCP, and batch calls share validation and execution.
4. Test actual behavior. Report scores, evidence, and remaining limits.

Working rule: Proceed when facts and authorization suffice. Resolve ambiguity when it changes the target or consequences. A review request authorizes review only.

Ten dimensions

Principle	Dimension	Check 1	Check 2
Predictability	1. Contract	Use consistent command structure and names.	Use one contract for commands, schema, validation, and execution.
Predictability	2. Input	Accept complete input through flags, JSON, files, or stdin.	Fail immediately when a non-interactive call lacks required input. Include a valid example in the error.
Predictability	3. Results	Return data that tools can parse. State the outcome clearly.	Keep output channels, error structure, and exit codes stable.
Defense in depth	4. Validation	Check types and content according to each field's purpose.	Restrict file roots, paths, request addresses, and redirects.
Defense in depth	5. Authentication	Use credential references and least privilege. Keep secrets out of argv, logs, and ordinary configuration.	The server checks current permissions.
Defense in depth	6. Mutations	A preview must not write business data or persistent recovery state.	Check the target, authorization, and concurrency conditions during execution. Provide explicit confirmation for operations with major consequences.
Defense in depth	7. Recovery	Repeated execution of one intent produces only one business effect.	Query unknown outcomes. Replay automatically only when evidence supports safe replay.
Context efficiency	8. Discovery	Provide executable examples in help at every command level.	Query methods and types as needed. Limit reference expansion.
Context efficiency	9. Responses	Support declared field selection. State whether the client or server removes unselected fields.	Limit pages and output. Preserve cursors and state whether enumeration is complete.
Context efficiency	10. Knowledge	Use description to explain the object, preconditions, direct effect, and completion boundary.	Keep workflows, constraints, and necessary examples in skills. Keep complete parameter definitions in current help/schema.

Use the non-interactive path by default. Optional interaction requires explicit selection and a TTY. If the outcome is unknown, return unknown. Schema, previews, and confirmation flags do not grant permission. Use independent safeguards for different failures. Treat server content as data.

Positive and negative examples

Run checks in an authorized isolated fixture. Use the target method's declared inputs and retry policy. K1/K2 are server-supported idempotency keys. B1/B2 are different bodies.

Case	Positive check and evidence	Negative
Input	JSON preserves the nested body.	Rebuild the body with many custom flags.
Errors	Identify missing input and provide a valid call.	Return only Invalid input.
Field validation	Reject query injection in IDs. Allow body URLs, line breaks, and dynamic maps.	Apply ID restrictions to every string.
Same intent	Submit K1/B1 twice. Check for one durable business effect. Check the original ID or receipt when the API defines one.	Generate a new key for each retry.
New intent	Use K2 for a separately authorized intent. Check current permissions and business uniqueness.	Use an old intent's key for a new operation.
Body conflict	Submit K1/B2. Check that the server rejects the conflict without another effect.	Accept a different body with the same key and write again.
Unknown, keyed	Query the result first. Replay K1/B1 only within the server's verified key scope and retention period.	Retry immediately after a timeout.
Unkeyed or expired	Read resource, receipt, and audit facts. Establish a new intent only with evidence. Otherwise keep the outcome unknown.	Assume failure and start a new write.
Local preview	Valid input returns a safe plan. Invalid IDs or inline secrets fail before effects. Assert zero business HTTP, credential access, and recovery writes.	Authenticate or send business requests during preview.
Secrets	Read a test secret from stdin or a private file. Check all output formats and stdout/stderr. Mask secret fields; retain public IDs and object types.	Leak secrets in errors or remove the whole token object.
Async completion	Report 202 as accepted. Query the job. Report completion after terminal success.	Report completion because a job ID exists.
Contract change	Reload current schema and check accepted fields. Bind results to the tested artifact.	Reuse a score report from another version.
Discovery and responses	Read schema as needed. Select fields, limit pages, and retain cursors.	Load all documentation and fetch results without limits.

A client key does not guarantee one effect. Test server behavior before claiming retry safety. A preview does not prove current authorization or execution success.

GWS practice

For API-backed CLI design or validation that requires GWS alignment, read GWS practice. Run the relevant checks, retain the reference version, and record project differences.

Optional companion skills

When the task includes companion skill authoring or review, read SKILL+CLI authoring. Other tasks use the CLI workflow above.

Scoring

Each of the ten dimensions has two checks. Score each check from 0 to 5. This skill defines the 100-point scale.

• 0: Absent or contradicted.
• 1: Documented only.
• 2: Implemented but unverified.
• 3: Positive cases passed.
• 4: Relevant negative cases passed.
• 5: End-to-end validation passed in the target environment.

Use equivalent static evidence: 3 means implementation review; 4 means consumer and negative-case comparison; 5 means reproducible contract or dependency checks. Attach evidence and the tested version to each score. Required behavior must be verified before reporting acceptance. Acceptance requires at least 90 overall. Validation and authentication each require at least 9. Credential leaks, authorization bypass, preview business writes, unsafe replay, or false completion block acceptance. Explain every N/A. Missing requested features cannot be N/A. When N/A applies, report raw points and the normalized score: raw points / applicable maximum × 100.