agent-native-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

agent-native-design

Purpose

用途

This skill helps analyze, design, and refactor command-line tools so they can reliably serve humans, AI agents, and orchestration systems at the same time.

It is not a skill for merely using a CLI. It is a skill for designing and reviewing a CLI as an agent-native interface.

The skill focuses on four goals:

Make CLI behavior predictable for AI agents.
Make CLI output readable and recoverable for humans.
Make CLI execution manageable for systems and orchestrators.
Define a complete interaction loop from authentication to error routing.

本技能可帮助分析、设计和重构命令行工具，使其能够同时为人类、AI Agent和编排系统提供可靠服务。

它并非仅用于使用CLI的技能，而是用于将CLI设计和评审为Agent原生接口的技能。

本技能聚焦于四大目标：

让AI Agent能够预测CLI的行为。
让人类能够轻松阅读和恢复CLI的输出内容。
让系统和编排器能够管控CLI的执行过程。
定义从认证到错误路由的完整交互流程。

When to use this skill

何时使用本技能

Use this skill when the user wants to:

evaluate whether an existing CLI is agent-friendly
redesign a CLI to better support AI agents
convert an API or SDK into an agent-native CLI
review help output, schema design, exit codes, or JSON contracts
design dry-run, auth delegation, or safety boundaries
generate CLI skills, docs, or interface conventions from schema
refactor a human-oriented CLI into a machine-friendly one
define how a CLI should interact with an agent runtime

Typical prompts include:

"Review this CLI and tell me whether it is agent-native."
"Design a CLI for this API that an AI agent can use reliably."
"Refactor this tool so stdout is machine-readable and safer for agents."
"Help me define schema introspection, dry-run, and exit code semantics."

当用户需要以下服务时，可使用本技能：

评估现有CLI是否对Agent友好
重新设计CLI以更好地支持AI Agent
将API或SDK转换为Agent原生CLI
评审帮助输出、Schema设计、退出码或JSON契约
设计预执行（dry-run）、认证委托或安全边界
根据Schema生成CLI技能、文档或接口约定
将面向人类的CLI重构为适用于机器的版本
定义CLI与Agent运行时的交互方式

典型提示词包括：

"评审这个CLI，告诉我它是否是Agent原生的。"
"为这个API设计一个AI Agent可可靠使用的CLI。"
"重构这个工具，让stdout具备机器可读性且对Agent更安全。"
"帮我定义Schema自省、预执行和退出码语义。"

When not to use this skill

何时不使用本技能

Do not use this skill when the user only wants:

help running a specific command
installation help for a CLI
shell troubleshooting unrelated to interface design
generic Linux or terminal tutorials
agent planning or memory design unrelated to tools
API business logic review without any CLI/tooling layer

当用户仅需要以下服务时，请勿使用本技能：

帮助运行特定命令
CLI安装帮助
与接口设计无关的Shell故障排查
通用Linux或终端教程
与工具无关的Agent规划或内存设计
不涉及CLI/工具层的API业务逻辑评审

Core model

核心模型

An agent-native CLI must simultaneously serve three audiences.

Agent原生CLI必须同时服务三类受众。

1. Human

1. 人类

Needs: readable output, friendly error messages, onboarding guidance. Channels:

stderr

, optional

--format table

, interactive TUI when appropriate.

需求：可读的输出、友好的错误信息、入门引导。渠道：

stderr

、可选的

--format table

参数、适当时使用交互式TUI。

2. AI Agent

Needs: structured data, stable contracts, self-description. Channels:

stdout

as JSON, stable exit codes, schema introspection, dry-run previews, generated skills/docs.

需求：结构化数据、稳定的契约、自描述能力。渠道：

stdout

输出JSON格式内容、稳定的退出码、Schema自省、预执行预览、生成的技能/文档。

3. System / Orchestrator

3. 系统/编排器

Needs: delegated authentication, process management, deterministic error routing. Channels: environment variables, exit codes, dry-run mode, stable command semantics.

需求：委托认证、进程管理、确定性错误路由。渠道：环境变量、退出码、预执行模式、稳定的命令语义。

Foundational contract

基础契约

Channel	Primary audience
`stdout`	Machines and agents
`stderr`	Humans
`exit codes`	Systems and orchestrators

This skill teaches how to make CLI a first-class interface for agents. Production agents (Claude Code, Cursor, Gemini CLI) often pair a CLI with an MCP server — CLI for state changes and local/scriptable work, MCP for multi-tenant SaaS and per-user auth. When a design needs the MCP side as well, see

references/hybrid-mcp-cli.md

for the decision matrix and the benchmark data behind the CLI/MCP tradeoff.

渠道	主要受众
`stdout`	机器与Agent
`stderr`	人类
`exit codes`	系统与编排器

本技能教授如何让CLI成为Agent的一等接口。生产环境中的Agent（如Claude Code、Cursor、Gemini CLI）通常会将CLI与MCP服务器搭配使用——CLI用于状态变更和本地/可脚本化工作，MCP用于多租户SaaS和按用户认证。若设计同时需要MCP相关内容，请查看

references/hybrid-mcp-cli.md

中的决策矩阵以及CLI/MCP权衡背后的基准数据。

The complete interaction loop

完整交互流程

Phase	Step	Description
0. Bootstrap	1	Human/system obtains auth token or credentials
0. Bootstrap	2	Set trusted env vars: token, profile, safety mode
1. Discovery	3	Agent loads skills or command summaries
1. Discovery	4	Agent queries schema/help for parameters
2. Planning	5	Agent uses `--dry-run` to preview request shape
3. Execution	6	Agent executes with validated inputs
4. Interpretation	7	Agent parses structured result
5. Recovery	8	Agent uses exit code + error object to retry, re-auth, repair, or escalate

A CLI that does not support every phase is incomplete from the agent's perspective.

阶段	步骤	描述
0. 初始化	1	人类/系统获取认证令牌或凭证
0. 初始化	2	设置可信环境变量：令牌、配置文件、安全模式
1. 发现	3	Agent加载技能或命令摘要
1. 发现	4	Agent查询Schema/帮助信息以获取参数详情
2. 规划	5	Agent使用 `--dry-run` 预览请求格式
3. 执行	6	Agent使用已验证的输入执行命令
4. 解析	7	Agent解析结构化结果
5. 恢复	8	Agent使用退出码+错误对象进行重试、重新认证、修复或升级处理

从Agent的角度来看，不支持所有阶段的CLI是不完整的。

Seven principles

七大原则

These are load-bearing. Each principle has at least one rubric criterion and at least one example backing it.

这些原则是核心支撑，每个原则都至少有一个评估标准和一个示例作为依据。

Principle 0. One CLI, Three Audiences

原则0：一个CLI，三类受众

The CLI must serve human, agent, and system simultaneously. A design that serves only one audience is incomplete.

CLI必须同时服务人类、Agent和系统。仅服务单一受众的设计是不完整的。

Principle 1. Structured Output Is the Interface

原则1：结构化输出即为接口

stdout

should always be parseable and stable. Both success and failure are structured JSON. The CLI must decide for itself which audience is reading: detect at startup whether stdout is a TTY, default to JSON when it is not, default to human-readable when it is.

NO_COLOR

and an explicit

--format json|table

flag override the auto-detection. Agents should never have to remember to pass

--format json

— if they have to, they will forget, and the run will silently produce un-parseable prose. Envelope and error contract:

references/design-patterns.md#output-envelopes

stdout

应始终可解析且稳定。成功和失败结果均为结构化JSON。CLI必须自行判断当前的受众：启动时检测stdout是否为TTY，非TTY时默认输出JSON，TTY时默认输出人类可读格式。

NO_COLOR

环境变量和显式的

--format json|table

参数可覆盖自动检测结果。Agent无需记住传递

--format json

参数——若必须传递，它们很可能会遗忘，导致运行时静默生成无法解析的文本内容。输出信封和错误契约请参考：

references/design-patterns.md#output-envelopes

。

Principle 2. Trust Is Directional

原则2：信任具有方向性

CLI arguments are not inherently trusted — they may come from a hallucinating or prompt-injected agent. Environment-level configuration set by the human or system is more trusted. The agent chooses what to do within a bounded surface; the human defines where and how it is allowed to operate.

CLI参数并非天生可信——它们可能来自产生幻觉或被提示注入的Agent。由人类或系统设置的环境级配置可信度更高。Agent在限定范围内选择要执行的操作；人类定义允许操作的范围和方式。

Principle 3. The CLI Must Describe Itself

原则3：CLI必须具备自描述能力

The CLI must be self-describing enough that an agent can use it without reading external README files. Self-description must be progressive, not eager: top-level

--help

lists resources; resource help lists actions; action help lists flags; a separate

schema <resource.action>

returns the full typed schema. A CLI with hundreds of commands that dumps everything into the first

--help

pays that token cost on every agent invocation. See

references/design-patterns.md#help-design

and

examples.md

Examples 2 and 5.

CLI的自描述能力需足够强，使得Agent无需阅读外部README文件即可使用它。自描述必须是渐进式的，而非一次性全部展示：顶级

--help

列出资源；资源帮助列出操作；操作帮助列出参数；单独的

schema <resource.action>

命令返回完整的类型化Schema。若一个拥有数百条命令的CLI在首次调用

--help

时就输出所有内容，会在每次Agent调用时产生不必要的令牌消耗。请参考

references/design-patterns.md#help-design

和

examples.md

中的示例2和示例5。

Principle 4. Safety Through Graduated Visibility

原则4：通过分级可见性保障安全

Read commands are easy to discover; mutating commands carry explicit warnings; destructive commands are hidden from skills or gated separately. Tier table and rationale:

references/design-patterns.md#safety-design

. Tiers are necessary but not sufficient — they are a prompt-side defense and approval fatigue degrades them quickly. Assume the agent runtime will additionally sandbox the CLI at the OS level (filesystem, network, processes), and design destructive commands to fail closed inside that sandbox.

只读命令易于发现；变更类命令带有明确警告；破坏性命令则隐藏在技能之外或单独设置访问权限。分级表及原理请参考：

references/design-patterns.md#safety-design

。分级是必要的但并非充分条件——它们是提示层面的防御机制，而审批疲劳会迅速降低其有效性。假设Agent运行时会在操作系统层面（文件系统、网络、进程）对CLI进行沙箱隔离，设计破坏性命令时需确保其在沙箱内默认执行失败。

Principle 5. Validate at the Boundary, Not in the Middle

原则5：在边界处验证，而非中间环节

Inputs are validated once at the CLI entry point. Internal code operates on validated, typed, trusted structures. Validation functions are centralized and tested for both pass and reject cases.

输入仅在CLI入口处验证一次。内部代码基于已验证、类型化、可信的结构运行。验证函数集中管理，并针对通过和拒绝场景进行测试。

Principle 6. The Schema Is the Source of Truth

原则6：Schema是唯一可信来源

If a schema exists, everything derives from it: CLI command structure, validation rules, help text, generated docs, generated skills, type definitions, dry-run contracts. The schema is never manually duplicated. The schema must also carry its own version and deprecation signals, surfaced in the

meta

block of every response, so agents that have cached an older view can detect drift and re-discover rather than silently calling a removed method. Full versioning contract and example:

references/design-patterns.md#schema-versioning

若存在Schema，则所有内容都应派生自它：CLI命令结构、验证规则、帮助文本、生成的文档、生成的技能、类型定义、预执行契约。Schema绝不能手动重复定义。Schema还必须携带自身的版本和弃用信号，并在每个响应的

meta

块中展示，这样缓存了旧版本视图的Agent就能检测到变更并重新发现，而非静默调用已移除的方法。完整的版本化契约及示例请参考：

references/design-patterns.md#schema-versioning

。

Principle 7. Authentication Must Be Delegatable

原则7：认证必须可委托

Authentication is obtained and refreshed by human/system-managed flows. The agent uses credentials; it never owns the auth lifecycle. Preferred mechanisms: environment variables, config files, OS keychain integration, externally refreshed tokens. Canonical pattern:

examples.md

Example 3.

认证由人类/系统管理的流程获取和刷新。Agent仅使用凭证；绝不掌控认证生命周期。推荐机制：环境变量、配置文件、操作系统密钥链集成、外部刷新令牌。标准模式请参考：

examples.md

中的示例3。

Standard review workflow

标准评审流程

Step 0. Update check (notify, don't pull) — first use per conversation

步骤0：更新检查（仅通知，不自动拉取）——每次会话首次使用时执行

Throttle to one check per 24 hours per installation; never mutate the skill directory without explicit user consent.

If
```
<this-skill-dir>/.last_update
```
exists and is less than 24 hours old, skip this step entirely.

Otherwise, fetch the latest tag from upstream:

bash

git -C <this-skill-dir> ls-remote --tags origin 'v*' 2>/dev/null \
  | awk '{print $2}' | sed 's|refs/tags/||' \
  | sort -V | tail -1

Compare with this skill's
```
metadata.version
```
from the frontmatter. If the upstream tag is strictly newer (semver), tell the user one line and ask:
"A newer version of this skill is available: vX.Y.Z → vA.B.C. Want me to
```
git pull
```
?"
If they say yes, run
```
git -C <this-skill-dir> pull --ff-only
```
. Refresh
```
.last_update
```
either way so the prompt doesn't repeat for 24 hours.
If upstream is the same or older, refresh
```
.last_update
```
silently and continue.
On any failure (offline, not a git checkout — e.g. ClawHub-installed copy, read-only path, no permission), swallow the error silently and continue with the user's task. Do not mention the failure.

This step is the only place this skill ever touches its own files. It notifies; it does not pull without permission. The user owns the update lifecycle (Principle 7 applied to the skill itself).

限制为每个安装每24小时检查一次；未经用户明确同意，绝不修改技能目录。

若
```
<this-skill-dir>/.last_update
```
文件存在且生成时间不超过24小时，则完全跳过此步骤。

否则，从上游获取最新标签：

bash

git -C <this-skill-dir> ls-remote --tags origin 'v*' 2>/dev/null \
  | awk '{print $2}' | sed 's|refs/tags/||' \
  | sort -V | tail -1

将其与本技能前置元数据中的
```
metadata.version
```
进行比较。若上游标签版本更高（语义化版本），则向用户发送一行提示并询问：
"本技能的新版本已可用：vX.Y.Z → vA.B.C。是否需要执行
```
git pull
```
更新？"
若用户同意，则执行
```
git -C <this-skill-dir> pull --ff-only
```
。无论用户是否同意，都刷新
```
.last_update
```
文件，确保24小时内不会重复此提示。
若上游版本相同或更旧，则静默刷新
```
.last_update
```
文件并继续。
若出现任何失败（离线、非Git检出——如ClawHub安装的副本、只读路径、无权限），则静默忽略错误并继续执行用户的任务。不得提及失败情况。

此步骤是本技能唯一会触碰自身文件的地方。仅通知用户，不会未经许可自动拉取更新。用户掌控更新生命周期（原则7应用于技能自身）。

Step 1. Classify the input

步骤1：分类输入内容

Decide whether the user is providing: an existing CLI, an API to be wrapped, a conceptual design, a partial interface, or a failure case.

判断用户提供的内容是：现有CLI、待包装的API、概念设计、部分接口，还是故障案例。

Step 2. Map the three audiences

步骤2：映射三类受众

Human: Is there readable output? Are errors understandable? Is onboarding supported?

Agent: Is stdout stable JSON? Can the CLI describe itself? Is there schema introspection and dry-run?

System: Is auth delegatable? Are exit codes stable? Can failures be routed deterministically?

人类： 是否有可读的输出？错误信息是否易懂？是否支持入门引导？

Agent： stdout是否为稳定的JSON？CLI是否具备自描述能力？是否支持Schema自省和预执行？

系统： 认证是否可委托？退出码是否稳定？故障是否可进行确定性路由？

Step 3. Review the interaction loop

步骤3：评审交互流程

Check whether the CLI supports: bootstrap, discovery, parameter understanding, preview, execution, parsing, recovery.

检查CLI是否支持：初始化、发现、参数理解、预览、执行、解析、恢复。

Step 4. Score the CLI with the rubric, then map back to principles

步骤4：使用评估标准为CLI打分，然后映射回原则

Use the 14-criterion rubric to score the CLI. The full rubric lives in

references/rubric.md

. Every one of the seven principles has at least one rubric row backing it, so the score-to-principle mapping is total: P0 → Three-audience support, Non-interactive operation; P1 → Stdout contract, Stderr separation, Idempotent retries, Error recoverability; P2 → Trust boundary; P3 → Self-description (help), Dry-run; P4 → Safety tiers; P5 → Boundary validation; P6 → Schema introspection; P7 → Auth delegation. Then summarize per principle with evidence, risk, and recommendation. The full review checklists live in

references/checklists.md

使用包含14项标准的评估表为CLI打分。完整评估表位于

references/rubric.md

。七大原则中的每一项都至少有一个评估表条目作为支撑，因此分数与原则的映射是全面的：P0 → 三类受众支持、非交互式操作；P1 → stdout契约、stderr分离、幂等重试、错误可恢复性；P2 → 信任边界；P3 → 自描述（帮助）、预执行；P4 → 安全分级；P5 → 边界验证；P6 → Schema自省；P7 → 认证委托。然后结合证据、风险和建议，按原则进行总结。完整的评审检查清单位于

references/checklists.md

。

Step 5. Produce a refactor plan

步骤5：生成重构计划

P0 must fix
P1 should improve
P2 long-term enhancements

P0 必须修复
P1 应该改进
P2 长期增强项

Default output format

默认输出格式

1. Overall verdict

1. 总体结论

State whether the CLI is agent-native, partially agent-native, or not yet agent-native.

说明该CLI是Agent原生、部分Agent原生还是暂未实现Agent原生。

2. Three-audience contract review

2. 三类受众契约评审

Assess support for human, agent, system.

评估对人类、Agent、系统的支持情况。

3. Interaction loop coverage

3. 交互流程覆盖范围

Assess each phase: auth bootstrap → env setup → skill/help discovery → schema introspection → dry-run → execution → parsing and recovery.

评估每个阶段：认证初始化 → 环境设置 → 技能/帮助发现 → Schema自省 → 预执行 → 执行 → 解析与恢复。

4. Rubric score + seven-principle review

4. 评估分数 + 七大原则评审

Report the 14-criterion rubric score first, then summarize the seven principles as: status · evidence · issue · recommendation.

首先报告14项标准的评估分数，然后按以下格式总结七大原则：状态 · 证据 · 问题 · 建议。

5. Key risks

5. 关键风险

Summarize design failures: human-only output, unstable JSON, no schema introspection, destructive commands overexposed, auth coupled to agent, ambiguous exit codes.

总结设计缺陷：仅面向人类的输出、不稳定的JSON、无Schema自省、破坏性命令过度暴露、认证与Agent耦合、模糊的退出码。

6. Refactor plan

6. 重构计划

Prioritized recommendations with examples drawn from

references/examples.md

结合

references/examples.md

中的示例，给出优先级排序的建议。

Things this skill should avoid recommending

本技能应避免推荐的内容

Human-readable prose as the only output contract
README required for basic command discovery
Schema and validation that drift apart
Auth supplied primarily via agent-generated arguments
Destructive actions exposed by default
CLI behavior that depends on undocumented conventions
Errors that are only textual and not machine-routable
Mutating commands that are not idempotent under retry
Confirmation prompts with no
```
--yes
```
escape and no TTY-aware fallback
Eager schema dumps in top-level
```
--help
```
— agents that call the CLI in loops pay this cost on every invocation; use progressive disclosure instead. The token-cost rationale lives in
```
references/hybrid-mcp-cli.md
```
.

将人类可读文本作为唯一输出契约
基础命令发现需要依赖README文件
Schema与验证规则不一致
主要通过Agent生成的参数提供认证信息
默认暴露破坏性操作
CLI行为依赖未记录的约定
仅提供文本形式、无法被机器路由的错误信息
重试时不具备幂等性的变更类命令
无
```
--yes
```
参数跳过确认提示且无TTY感知回退机制的确认流程
在顶级
```
--help
```
中一次性输出全部Schema内容——循环调用CLI的Agent会在每次调用时承担此令牌消耗；应使用渐进式披露方式。令牌消耗的原理请参考
```
references/hybrid-mcp-cli.md
```
。

Reference files

参考文件

Load on demand — these are not in the agent's context until needed:

File	Read when
`references/examples.md`	Showing the user a good envelope, error, dry-run, batch response, or anti-pattern
`references/rubric.md`	Producing the score component of a CLI review
`references/checklists.md`	Walking through a CLI auditing list with the user, or sanity-checking a new design
`references/design-patterns.md`	Writing the contract for envelopes, exit codes, idempotency, non-interactive mode, long-running commands, schema versioning, locale/time
`references/hybrid-mcp-cli.md`	Deciding CLI vs. MCP vs. both, or citing benchmark numbers behind the CLI efficiency claim
`references/testing.md`	Showing the user how to verify their CLI actually upholds the contract (envelope shape, idempotency replay, TTY behavior, schema drift, dry-run safety, locale determinism) — load this when the design review converges on "how do we keep it agent-native over time?"
`references/citations.md`	Citing the primary sources behind a recommendation

按需加载——在需要之前，这些文件不会进入Agent的上下文：

文件	加载时机
`references/examples.md`	向用户展示优秀的输出信封、错误处理、预执行、批量响应示例或反模式时
`references/rubric.md`	生成CLI评审的分数部分时
`references/checklists.md`	与用户一起梳理CLI审计清单，或对新设计进行 sanity 检查时
`references/design-patterns.md`	编写输出信封、退出码、幂等性、非交互式模式、长运行命令、Schema版本控制、区域设置/时间的契约时
`references/hybrid-mcp-cli.md`	决定使用CLI、MCP还是两者结合，或引用CLI效率主张背后的基准数据时
`references/testing.md`	向用户展示如何验证CLI是否真正遵守契约（输出信封格式、幂等性重放、TTY行为、Schema变更、预执行安全性、区域设置确定性）——当设计评审聚焦于“如何长期保持CLI的Agent原生特性？”时加载此文件
`references/citations.md`	引用建议背后的主要来源时

One-sentence summary

一句话总结

This skill helps turn a CLI into a trustworthy execution interface for humans, AI agents, and systems through structured output, self-description, delegated authentication, safety boundaries, and a complete interaction loop.

本技能通过结构化输出、自描述能力、委托认证、安全边界和完整交互流程，帮助将CLI转变为人类、AI Agent和系统可信赖的执行接口。