agentleFS
Sign inStart free
jpoehneltjpoehnelt/skills/eng-agent-dx-cli-scale/SKILL.md

eng-agent-dx-cli-scale

Skill23 starsChanged 11 days agoMITView on GitHub

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.

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill to evaluate any CLI against the principles of agent-first design.

    line 8
  2. Distinctive:

    Not scored, but note whether the CLI exposes multiple agent surfaces from the same binary:

    line 110

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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?

ScoreCriteria
0Human-only output (tables, color codes, prose). No structured format available.
1--output json or equivalent exists but is incomplete or inconsistent across commands.
2Consistent JSON output across all commands. Errors also return structured JSON.
3NDJSON 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?

ScoreCriteria
0Only bespoke flags. No way to pass structured input.
1Accepts --json or stdin JSON for some commands, but most require flags.
2All mutating commands accept a raw JSON payload that maps directly to the underlying API schema.
3Raw 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?

ScoreCriteria
0Only --help text. No machine-readable schema.
1--help --json or a describe command for some surfaces, but incomplete.
2Full schema introspection for all commands, including params, types, and required fields, as JSON.
3Live, 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?

ScoreCriteria
0Returns full API responses with no way to limit fields or paginate.
1Supports --fields or field masks on some commands.
2Field masks on all read commands. Pagination with --page-all or equivalent.
3Streaming 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)?

ScoreCriteria
0No input validation beyond basic type checks.
1Validates some inputs, but does not cover agent-specific hallucination patterns (path traversals, embedded query params, double encoding).
2Rejects control characters, path traversals (../), percent-encoded segments (%2e), and embedded query params (?, #) in resource IDs.
3Comprehensive 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."

6. Safety Rails

Can agents validate before acting, and are responses sanitized against prompt injection?

ScoreCriteria
0No dry-run mode. No response sanitization.
1--dry-run exists for some mutating commands.
2--dry-run for all mutating commands. Agent can validate requests without side effects.
3Dry-run plus response sanitization (e.g., via Model Armor) to defend against prompt injection embedded in API data. The full request→response loop is defended.

7. Agent Knowledge Packaging

Does the CLI ship knowledge in formats agents can consume at conversation start?

ScoreCriteria
0Only --help and a docs site. No agent-specific context files.
1A CONTEXT.md or AGENTS.md with basic usage guidance.
2Structured skill files (YAML frontmatter + Markdown) covering per-command or per-API-surface workflows and invariants.
3Comprehensive skill library encoding agent-specific guardrails ("always use --dry-run", "always use --fields"). Skills are versioned, discoverable, and follow a standard like OpenClaw.

Interpreting the Total

RangeRatingDescription
0–5Human-onlyBuilt for humans. Agents will struggle with parsing, hallucinate inputs, and lack safety rails.
6–10Agent-tolerantAgents can use it, but they'll waste tokens, make avoidable errors, and require heavy prompt engineering to compensate.
11–15Agent-readySolid agent support. Structured I/O, input validation, and some introspection. A few gaps remain.
16–21Agent-firstPurpose-built for agents. Full schema introspection, comprehensive input hardening, safety rails, and packaged agent knowledge.

Bonus: Multi-Surface Readiness

Not scored, but note whether the CLI exposes multiple agent surfaces from the same binary:

  • MCP (stdio JSON-RPC): typed tool invocation, no shell escaping
  • Extension / plugin install: agent treats the CLI as a native capability
  • Headless auth: env vars for tokens/credentials, no browser redirect required

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free