Skip to content

Commit 8a0dd5e

Browse files
Agents365-aiAgents365-ai
committed
feat: initial release of agent-native-cli skill
Seven-principle framework for designing and reviewing CLIs that serve humans, AI agents, and orchestration systems simultaneously. Includes structured output contracts, schema introspection, dry-run, safety tiers, delegated auth, 10-criterion scoring rubric, examples, non-examples, and review checklist. Multi-platform support: Claude Code, OpenClaw, Hermes, Pi-Mo, Codex, SkillsMP.
0 parents  commit 8a0dd5e

4 files changed

Lines changed: 900 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# agent-native-cli — Agent-Native CLI Design & Review Skill
2+
3+
[中文文档](README_CN.md)
4+
5+
## What it does
6+
7+
- Evaluates whether an existing CLI is reliably usable by AI agents
8+
- Designs CLI interfaces that serve humans, agents, and orchestration systems simultaneously
9+
- Converts REST APIs and SDKs into agent-native CLI command trees
10+
- Reviews stdout contracts, exit code semantics, and error envelope design
11+
- Designs schema-driven self-description, dry-run previews, and schema introspection
12+
- Defines safety tiers (open / warned / hidden) for graduated command visibility
13+
- Designs delegated authentication so agents never own the auth lifecycle
14+
- Produces prioritized refactor plans with concrete interface examples
15+
16+
## Multi-Platform Support
17+
18+
Works with all major AI agents that support the [Agent Skills](https://agentskills.io) format:
19+
20+
| Platform | Status | Details |
21+
|----------|--------|---------|
22+
| **Claude Code** | ✅ Full support | Native SKILL.md format |
23+
| **OpenClaw / ClawHub** | ✅ Full support | `metadata.openclaw` namespace |
24+
| **Hermes Agent** | ✅ Full support | `metadata.hermes` namespace, category: engineering |
25+
| **Pi-Mo** | ✅ Full support | `metadata.pimo` namespace |
26+
| **OpenAI Codex** | ✅ Full support | `agents/openai.yaml` sidecar |
27+
| **SkillsMP** | ✅ Indexed | GitHub topics configured |
28+
29+
## Comparison: with vs. without this skill
30+
31+
| Capability | Native agent | This skill |
32+
|------------|-------------|------------|
33+
| Evaluate whether a CLI is agent-native | No | Yes — structured diagnosis across 7 principles |
34+
| Design stdout JSON contract | Inconsistent | Always — stable envelope with `ok`, `data`, `error` |
35+
| Define exit code semantics | Ad hoc | Yes — documented, deterministic per failure class |
36+
| Design layered `--help` and schema introspection | No | Yes — full self-description pattern |
37+
| Design dry-run previews | Rarely | Always — request shape preview without execution |
38+
| Define safety tiers for commands | No | Yes — open / warned / hidden tiers |
39+
| Design delegated authentication | No | Yes — human manages auth lifecycle; agent uses token |
40+
| Separate trust levels for env vs. CLI args | No | Yes — directional trust model |
41+
| Produce prioritized refactor plan | Rarely | Always — P0 / P1 / P2 with examples |
42+
| Score CLI across 10-criterion rubric | No | Yes — 0–2 per criterion with verdict |
43+
44+
## When to use
45+
46+
- Evaluating whether an existing CLI is usable by an AI agent
47+
- Designing a new CLI interface for an API or SDK
48+
- Refactoring a human-first CLI to be machine-readable
49+
- Reviewing stdout, stderr, and exit code contract design
50+
- Defining dry-run, schema introspection, and self-description layers
51+
- Designing auth delegation and trust boundaries for agent safety
52+
- Producing a SKILL.md or skill docs from a CLI schema
53+
54+
## Skill Installation
55+
56+
### Claude Code
57+
58+
```bash
59+
# Global install (available in all projects)
60+
git clone https://github.com/Agents365-ai/agent-native-cli.git ~/.claude/skills/agent-native-cli
61+
62+
# Project-level install
63+
git clone https://github.com/Agents365-ai/agent-native-cli.git .claude/skills/agent-native-cli
64+
```
65+
66+
### OpenClaw / ClawHub
67+
68+
```bash
69+
# Via ClawHub
70+
clawhub install agent-native-cli
71+
72+
# Manual install
73+
git clone https://github.com/Agents365-ai/agent-native-cli.git ~/.openclaw/skills/agent-native-cli
74+
75+
# Project-level install
76+
git clone https://github.com/Agents365-ai/agent-native-cli.git skills/agent-native-cli
77+
```
78+
79+
### Hermes Agent
80+
81+
```bash
82+
git clone https://github.com/Agents365-ai/agent-native-cli.git ~/.hermes/skills/engineering/agent-native-cli
83+
```
84+
85+
Or add to `~/.hermes/config.yaml`:
86+
87+
```yaml
88+
skills:
89+
external_dirs:
90+
- ~/myskills/agent-native-cli
91+
```
92+
93+
### Pi-Mo
94+
95+
```bash
96+
git clone https://github.com/Agents365-ai/agent-native-cli.git ~/.pimo/skills/agent-native-cli
97+
```
98+
99+
### OpenAI Codex
100+
101+
```bash
102+
# User-level install
103+
git clone https://github.com/Agents365-ai/agent-native-cli.git ~/.agents/skills/agent-native-cli
104+
105+
# Project-level install
106+
git clone https://github.com/Agents365-ai/agent-native-cli.git .agents/skills/agent-native-cli
107+
```
108+
109+
### SkillsMP
110+
111+
```bash
112+
skills install agent-native-cli
113+
```
114+
115+
### Installation paths summary
116+
117+
| Platform | Global path | Project path |
118+
|----------|-------------|--------------|
119+
| Claude Code | `~/.claude/skills/agent-native-cli/` | `.claude/skills/agent-native-cli/` |
120+
| OpenClaw | `~/.openclaw/skills/agent-native-cli/` | `skills/agent-native-cli/` |
121+
| Hermes Agent | `~/.hermes/skills/engineering/agent-native-cli/` | Via `external_dirs` config |
122+
| Pi-Mo | `~/.pimo/skills/agent-native-cli/` | — |
123+
| OpenAI Codex | `~/.agents/skills/agent-native-cli/` | `.agents/skills/agent-native-cli/` |
124+
125+
## Files
126+
127+
- `SKILL.md` — **the only required file**. Loaded by all platforms as the skill instructions.
128+
- `agents/openai.yaml` — OpenAI Codex-specific configuration (display, policy, capabilities)
129+
- `README.md` — this file (English)
130+
- `README_CN.md` — Chinese documentation
131+
132+
> **Note:** Only `SKILL.md` is needed for the skill to work. All other files are supplementary.
133+
134+
## GitHub Topics
135+
136+
For SkillsMP indexing, this repository uses the following topics:
137+
138+
`claude-code` `claude-code-skill` `claude-skills` `agent-skills` `skillsmp` `skill-md` `agent-native-cli` `cli-design` `interface-design` `structured-output` `schema-driven` `dry-run` `exit-codes` `tool-design`
139+
140+
## License
141+
142+
MIT
143+
144+
## Support
145+
146+
If this skill helps your work, consider supporting the author:
147+
148+
<table>
149+
<tr>
150+
<td align="center">
151+
<img src="https://raw.githubusercontent.com/Agents365-ai/images_payment/main/qrcode/wechat-pay.png" width="180" alt="WeChat Pay">
152+
<br>
153+
<b>WeChat Pay</b>
154+
</td>
155+
<td align="center">
156+
<img src="https://raw.githubusercontent.com/Agents365-ai/images_payment/main/qrcode/alipay.png" width="180" alt="Alipay">
157+
<br>
158+
<b>Alipay</b>
159+
</td>
160+
<td align="center">
161+
<img src="https://raw.githubusercontent.com/Agents365-ai/images_payment/main/qrcode/buymeacoffee.png" width="180" alt="Buy Me a Coffee">
162+
<br>
163+
<b>Buy Me a Coffee</b>
164+
</td>
165+
</tr>
166+
</table>
167+
168+
## Author
169+
170+
**Agents365-ai**
171+
172+
- Bilibili: https://space.bilibili.com/441831884
173+
- GitHub: https://github.com/Agents365-ai

‎README_CN.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# agent-native-cli — AI 智能体原生 CLI 设计与评审 Skill
2+
3+
[English](README.md)
4+
5+
## 功能说明
6+
7+
- 评估现有 CLI 是否能被 AI 智能体可靠使用
8+
- 设计同时服务人类、智能体和编排系统的 CLI 接口
9+
- 将 REST API 和 SDK 转换为智能体原生的 CLI 命令树
10+
- 审查 stdout 契约、退出码语义和错误信封设计
11+
- 设计基于 Schema 的自描述能力、dry-run 预览和 Schema 自省
12+
- 定义安全分级（开放 / 警示 / 隐藏），实现命令可见性的渐进式控制
13+
- 设计委托式认证，使智能体永远不拥有认证生命周期
14+
- 生成带有具体接口示例的优先级重构计划
15+
16+
## 多平台支持
17+
18+
兼容所有主流支持 [Agent Skills](https://agentskills.io) 格式的 AI 智能体：
19+
20+
| 平台 | 支持状态 | 说明 |
21+
|------|----------|------|
22+
| **Claude Code** | ✅ 完全支持 | 原生 SKILL.md 格式 |
23+
| **OpenClaw / ClawHub** | ✅ 完全支持 | `metadata.openclaw` 命名空间 |
24+
| **Hermes Agent** | ✅ 完全支持 | `metadata.hermes` 命名空间，category: engineering |
25+
| **Pi-Mo** | ✅ 完全支持 | `metadata.pimo` 命名空间 |
26+
| **OpenAI Codex** | ✅ 完全支持 | `agents/openai.yaml` 侧车文件 |
27+
| **SkillsMP** | ✅ 可索引 | GitHub topics 已配置 |
28+
29+
## 有 skill 与无 skill 的对比
30+
31+
| 能力 | 原生智能体 | 本 skill |
32+
|------|-----------|---------|
33+
| 评估 CLI 是否具备智能体原生特性 | 否 | 是 — 基于 7 项原则的结构化诊断 |
34+
| 设计 stdout JSON 契约 | 不稳定 | 始终 — 带 `ok`、`data`、`error` 的稳定信封 |
35+
| 定义退出码语义 | 临时性 | 是 — 按故障类型文档化、确定性映射 |
36+
| 设计分层 `--help` 和 Schema 自省 | 否 | 是 — 完整自描述模式 |
37+
| 设计 dry-run 预览 | 少见 | 始终 — 不执行操作即可预览请求形态 |
38+
| 定义命令安全分级 | 否 | 是 — 开放 / 警示 / 隐藏三级分层 |
39+
| 设计委托式认证 | 否 | 是 — 人类管理认证生命周期；智能体使用 token |
40+
| 区分环境变量与 CLI 参数的信任级别 | 否 | 是 — 定向信任模型 |
41+
| 生成优先级重构计划 | 少见 | 始终 — P0 / P1 / P2，含示例 |
42+
| 按 10 项标准对 CLI 评分 | 否 | 是 — 每项 0–2 分，含最终判定 |
43+
44+
## 适用场景
45+
46+
- 评估现有 CLI 是否可被 AI 智能体使用
47+
- 为 API 或 SDK 设计新的 CLI 接口
48+
- 将以人为本的 CLI 重构为机器可读的接口
49+
- 审查 stdout、stderr 和退出码契约设计
50+
- 定义 dry-run、Schema 自省和自描述层
51+
- 为智能体安全设计委托式认证和信任边界
52+
- 从 CLI Schema 生成 SKILL.md 或 skill 文档
53+
54+
## skill 安装
55+
56+
### Claude Code
57+
58+
```bash
59+
# 全局安装（在所有项目中可用）
60+
git clone https://github.com/Agents365-ai/agent-native-cli.git ~/.claude/skills/agent-native-cli
61+
62+
# 项目级安装
63+
git clone https://github.com/Agents365-ai/agent-native-cli.git .claude/skills/agent-native-cli
64+
```
65+
66+
### OpenClaw / ClawHub
67+
68+
```bash
69+
# 通过 ClawHub
70+
clawhub install agent-native-cli
71+
72+
# 手动安装
73+
git clone https://github.com/Agents365-ai/agent-native-cli.git ~/.openclaw/skills/agent-native-cli
74+
75+
# 项目级安装
76+
git clone https://github.com/Agents365-ai/agent-native-cli.git skills/agent-native-cli
77+
```
78+
79+
### Hermes Agent
80+
81+
```bash
82+
git clone https://github.com/Agents365-ai/agent-native-cli.git ~/.hermes/skills/engineering/agent-native-cli
83+
```
84+
85+
或在 `~/.hermes/config.yaml` 中添加：
86+
87+
```yaml
88+
skills:
89+
external_dirs:
90+
- ~/myskills/agent-native-cli
91+
```
92+
93+
### Pi-Mo
94+
95+
```bash
96+
git clone https://github.com/Agents365-ai/agent-native-cli.git ~/.pimo/skills/agent-native-cli
97+
```
98+
99+
### OpenAI Codex
100+
101+
```bash
102+
# 用户级安装
103+
git clone https://github.com/Agents365-ai/agent-native-cli.git ~/.agents/skills/agent-native-cli
104+
105+
# 项目级安装
106+
git clone https://github.com/Agents365-ai/agent-native-cli.git .agents/skills/agent-native-cli
107+
```
108+
109+
### SkillsMP
110+
111+
```bash
112+
skills install agent-native-cli
113+
```
114+
115+
### 安装路径汇总
116+
117+
| 平台 | 全局路径 | 项目路径 |
118+
|------|----------|----------|
119+
| Claude Code | `~/.claude/skills/agent-native-cli/` | `.claude/skills/agent-native-cli/` |
120+
| OpenClaw | `~/.openclaw/skills/agent-native-cli/` | `skills/agent-native-cli/` |
121+
| Hermes Agent | `~/.hermes/skills/engineering/agent-native-cli/` | 通过 `external_dirs` 配置 |
122+
| Pi-Mo | `~/.pimo/skills/agent-native-cli/` | — |
123+
| OpenAI Codex | `~/.agents/skills/agent-native-cli/` | `.agents/skills/agent-native-cli/` |
124+
125+
## 文件说明
126+
127+
- `SKILL.md` — **唯一必需文件**。所有平台均加载此文件作为 skill 指令。
128+
- `agents/openai.yaml` — OpenAI Codex 专用配置（显示名称、策略、能力列表）
129+
- `README.md` — 英文文档
130+
- `README_CN.md` — 本文件（中文）
131+
132+
> **注意：** 只需要 `SKILL.md` 即可使 skill 正常工作，其他文件均为辅助文件。
133+
134+
## GitHub Topics
135+
136+
用于 SkillsMP 索引，本仓库使用以下 topics：
137+
138+
`claude-code` `claude-code-skill` `claude-skills` `agent-skills` `skillsmp` `skill-md` `agent-native-cli` `cli-design` `interface-design` `structured-output` `schema-driven` `dry-run` `exit-codes` `tool-design`
139+
140+
## 开源协议
141+
142+
MIT
143+
144+
## 支持作者
145+
146+
如果这个 skill 对你的工作有帮助，欢迎支持作者：
147+
148+
<table>
149+
<tr>
150+
<td align="center">
151+
<img src="https://raw.githubusercontent.com/Agents365-ai/images_payment/main/qrcode/wechat-pay.png" width="180" alt="微信支付">
152+
<br>
153+
<b>微信支付</b>
154+
</td>
155+
<td align="center">
156+
<img src="https://raw.githubusercontent.com/Agents365-ai/images_payment/main/qrcode/alipay.png" width="180" alt="支付宝">
157+
<br>
158+
<b>支付宝</b>
159+
</td>
160+
<td align="center">
161+
<img src="https://raw.githubusercontent.com/Agents365-ai/images_payment/main/qrcode/buymeacoffee.png" width="180" alt="Buy Me a Coffee">
162+
<br>
163+
<b>Buy Me a Coffee</b>
164+
</td>
165+
</tr>
166+
</table>
167+
168+
## 作者
169+
170+
**Agents365-ai**
171+
172+
- Bilibili: https://space.bilibili.com/441831884
173+
- GitHub: https://github.com/Agents365-ai

0 commit comments

Comments
 (0)