eng-agent-dx-cli-scale
A scoring scale for evaluating how well a CLI is designed for AI agents, based on the "Rewrite Your CLI for AI Agents" principles. Use when reviewing, designing, or comparing a CLI for agent use, or scoring its agent readiness.
jpoehnelt · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add jpoehnelt/skills --skill eng-agent-dx-cli-scale技能说明
name: eng-agent-dx-cli-scale description: A scoring scale for evaluating how well a CLI is designed for AI agents, based on the "Rewrite Your CLI for AI Agents" principles. Use when reviewing, designing, or comparing a CLI for agent use, or scoring its agent readiness.
Agent DX CLI Scale
Use this skill to evaluate any CLI against the principles of agent-first design. Score each axis from 0–3, then sum for a total between 0–21.
Human DX optimizes for discoverability and forgiveness. Agent DX optimizes for predictability and defense-in-depth. — You Need to Rewrite Your CLI for AI Agents
Scoring Axes
1. Machine-Readable Output
Can an agent parse the CLI's output without heuristics?
| Score | Criteria |
|---|---|
| 0 | Human-only output (tables, color codes, prose). No structured format available. |
| 1 | --output json or equivalent exists but is incomplete or inconsistent across commands. |
| 2 | Consistent JSON output across all commands. Errors also return structured JSON. |
| 3 | NDJSON streaming for paginated results. Structured output is the default in non-TTY (piped) contexts. |
2. Raw Payload Input
Can an agent send the full API payload without translation through bespoke flags?
| Score | Criteria |
|---|---|
| 0 | Only bespoke flags. No way to pass structured input. |
| 1 | Accepts --json or stdin JSON for some commands, but most require flags. |
| 2 | All mutating commands accept a raw JSON payload that maps directly to the underlying API schema. |
| 3 | Raw payload is first-class alongside convenience flags. The agent can use the API schema as documentation with zero translation loss. |
3. Schema Introspection
Can an agent discover what the CLI accepts at runtime without pre-stuffed documentation?
| Score | Criteria |
|---|---|
| 0 | Only --help text. No machine-readable schema. |
| 1 | --help --json or a describe command for some surfaces, but incomplete. |
| 2 | Full schema introspection for all commands, including params, types, and required fields, as JSON. |
| 3 | Live, runtime-resolved schemas (e.g., from a discovery document) that always reflect the current API version. Includes scopes, enums, and nested types. |
4. Context Window Discipline
Does the CLI help agents control response size to protect their context window?
| Score | Criteria |
|---|---|
| 0 | Returns full API responses with no way to limit fields or paginate. |
| 1 | Supports --fields or field masks on some commands. |
| 2 | Field masks on all read commands. Pagination with --page-all or equivalent. |
| 3 | Streaming pagination (NDJSON per page). Explicit guidance in context/skill files on field mask usage. The CLI actively protects the agent from token waste. |
5. Input Hardening
Does the CLI defend against the specific ways agents fail (hallucinations, not typos)?
| Score | Criteria |
|---|---|
| 0 | No input validation beyond basic type checks. |
| 1 | Validates some inputs, but does not cover agent-specific hallucination patterns (path traversals, embedded query params, double encoding). |
| 2 | Rejects control characters, path traversals (../), percent-encoded segments (%2e), and embedded query params (?, #) in resource IDs. |
| 3 | Comprehensive hardening: all of the above, plus output path sandboxing to CWD, HTTP-layer percent-encoding, and an explicit security posture: "The agent is not a trusted operator." |