agent-dx-cli-scale

A scoring guide for judging how well a command-line program works for AI agents. It rates features such as machine-readable output and structured input on a scale from 0 to 3.

In plain words
What is it for?
Use it to review a CLI's output formats, JSON input, error handling, command discoverability, and other agent-oriented design choices.
Why use it?
It makes weaknesses visible when an agent must discover commands, send data, interpret results, or handle errors reliably.

Skill for Claude CodeCodex

▶ How to Use Codex as a Designer Griffin Wooldridge · about google-labs-code/design.md · on YouTube →
Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add skills/google-labs-code/design.md/agent-dx-cli-scale
Any agent
npx skills add google-labs-code/design.md --skill agent-dx-cli-scale
Clone the repo
git clone --depth 1 https://github.com/google-labs-code/design.md

Made for: Claude Code, Codex.

Per session 34 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 1,427 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00034 $0.01427
Opus 5 $0.00017 $0.00714
Sonnet 5 $0.00007 $0.00285
Haiku 4.5 $0.00003 $0.00143

Measured 2d ago against content hash 2020ed49b598, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

agent-dx-cli-scale scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

.agents/skills/agent-dx-cli-scale/SKILL.md · 115 lines

How it starts

The opening of the file, as written. The whole thing — 115 lines — stays where its author put it; the contents beside it link to each section on GitHub.

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.

Read the full file on GitHub · 115 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 2d ago First seen · 115 lines · 34 tokens per session scan A 2020ed49b598

Subscribe to this mod's changes

agent-dx-cli-scale is a skill published in the GitHub repository google-labs-code/design.md (27,650 stars, last pushed 1mo ago), licensed Apache-2.0. It adds 34 tokens to every session and 1,427 once invoked, about $0.0002 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.