> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 怎样用 REST API 和 Anthropic Skill 构建 CLI 工具

> 你已经有 REST API, 想让 LLM 帮内部团队跑日常工作。最便宜可行的方式不是 MCP server, 是 CLI + Anthropic Skill 组合。1 个工程师 1 周 ship。

## §0. 30 秒 mental model

```
┌───────────────────────────────────────────┐
│  Layer 2: Anthropic Skill (markdown 文档)  │
│  - 800 tokens 教 LLM "本公司怎么用 CLI"   │
│  - 文件路径: ~/.claude/skills/<name>/SKILL.md
└──────────────────┬────────────────────────┘
                   │ LLM 读完知道
                   ▼
┌───────────────────────────────────────────┐
│  Layer 1: CLI tool (binary)               │
│  - 你已有 (例: gh, aws, dotnet)           │
│  - 或者你 1 周写一个 wrapper (例: yourco)  │
└──────────────────┬────────────────────────┘
                   │ 调用
                   ▼
┌───────────────────────────────────────────┐
│  Layer 0: 你的 internal REST API           │
│  - .NET / Python / Node, 任意 backend     │
└───────────────────────────────────────────┘
```

**关键洞察**: CLI 已经存在,LLM 已经在训练数据里见过 millions 次 — 你只需要补几百 token 的"本公司特殊用法"教学, LLM 就能 ship。

***

## §1. Token economics — 为什么 CLI 完胜个人 dev 场景

| 维度                       | MCP server (`@modelcontextprotocol/server-github`)    | CLI (`gh`)                       |
| ------------------------ | ----------------------------------------------------- | -------------------------------- |
| Token cost (single task) | \~55K tokens (schemas) + per-call overhead            | \~200 tokens (LLM 已知 gh command) |
| Setup time               | 安装 server / 配 config / 测连接 / 重启 client                | `brew install gh` 一行命令           |
| LLM 已知度                  | LLM 需要读 schema 才能知道有哪些 tool                           | LLM training data 里有大量 `gh` 例子   |
| Reliability              | 72% (MCP server crash / version mismatch / schema 改了) | 100% (CLI 是稳定接口)                 |
| Composability            | 不好 unix pipe                                          | `gh pr list \| jq` 直接拼           |
| Debug 难度                 | MCP protocol 出错 hard to inspect                       | shell 直接看 stdout / stderr        |

→ **个人 dev 写代码, LLM 帮忙调 git/GitHub/AWS CLI, CLI 完胜**。这是为什么 Anthropic 自己出了 Skills (本质是 "告诉 LLM 怎么用 CLI" 的 800-token markdown 文件)。

***

## §2. 业界 mature SaaS 都走 "REST API + CLI" 三层

| 公司             | REST API (Layer 4)          | CLI (公司自己写的)                | LLM 用 CLI 的成本    |
| -------------- | --------------------------- | --------------------------- | ---------------- |
| **GitHub**     | api.github.com REST/GraphQL | `gh` CLI (Go 写, 8MB binary) | \~200 tokens     |
| **Stripe**     | api.stripe.com              | `stripe` CLI                | \~300 tokens     |
| **Vercel**     | api.vercel.com              | `vercel` CLI                | \~250 tokens     |
| **Cloudflare** | api.cloudflare.com          | `wrangler` CLI              | \~300 tokens     |
| **Anthropic**  | api.anthropic.com           | (没官方 CLI, 有 SDK)            | (用 SDK 跟 CLI 类似) |

→ **未来 mature SaaS 路径**:

```
Phase 1: build internal REST API + Auth
                     │
                     ▼
Phase 2: 写 yourco CLI wrapping REST API (1 工程师 1 周)
                     │
                     ▼
Phase 3: 写 yourco Anthropic Skill (PM 1 天)
                     │
                     ▼
工程团队 / CS team / sales 全部用 Claude Desktop + yourco CLI + skill
跑日常工作, token 成本几乎为零, 完全不需要建 MCP
```

***

## §3. 实战 — 1 周写一个 CLI on top of REST API

假设你已经有 internal REST API (`https://api.yourco.com/v1/...`), 现在 1 周建一个 `yourco` CLI。

### Step 1 — 选 CLI framework (按团队栈, 不存在"哪个更好")

| 团队栈                   | CLI framework      | API client lib       | 单 binary 打包                       |
| --------------------- | ------------------ | -------------------- | --------------------------------- |
| **Python**            | Typer / Click      | httpx / requests     | PyInstaller / Nuitka              |
| **Node / TypeScript** | oclif / Commander  | axios / native fetch | pkg / ncc + esbuild               |
| **Java / Kotlin**     | picocli            | OkHttp / Retrofit    | GraalVM native-image              |
| **.NET / C#**         | System.CommandLine | HttpClient           | `dotnet publish --self-contained` |
| **Go**                | Cobra / urfave/cli | net/http             | `go build` (天然 single binary)     |
| **Rust**              | clap               | reqwest              | `cargo build --release`           |

→ **选你团队已有栈**, 不要为 CLI 单独引一门语言。**Go / Rust 在 CLI 领域占主导** (gh / kubectl / terraform 都是 Go), 但任何语言都能 ship CLI。

### Step 2 — 写 CLI (1 天, 跨语言通用 pattern)

**核心 5 个 pattern (任何语言都一样)**:

1. **定义 N 个 command** (e.g. `menu`, `sales`, `reviews`, `customer`) — 用 framework 的 command 装饰器 / decorator / annotation
2. **每个 command 接受 args + 调内部 REST API** (用上表的 HTTP client lib)
3. **用 env var 装 auth token** (e.g. `YOURCO_TOKEN`), 不要 hardcode
4. **返回 JSON to stdout** (方便 pipe to `jq` 解析 / LLM 读)
5. **错误时退出码 ≠ 0** + stderr 写错误信息

**Pseudo-code (语言无关)**:

```
cli yourco {
  command "menu" {
    arg location_id
    do: GET ${API_BASE}/menu/${location_id}
        with header "Authorization: Bearer ${env.YOURCO_TOKEN}"
    print: response.body as JSON
  }

  command "sales" {
    arg location_id, date
    do: GET ${API_BASE}/reports/daily-sales?location_id=...&date=...
        with header "Authorization: Bearer ${env.YOURCO_TOKEN}"
    print: response.body as JSON
  }

  // ... reviews / customer / etc
}
```

→ **具体 code 例子见对应 framework 官方 docs** (Typer / oclif / Cobra / picocli / System.CommandLine 都有 1 页 quickstart)。1 周写完这种 5-command CLI 跟语言选择无关。

**打包**: 用上表"单 binary 打包"工具, 让用户 `brew install yourco/tap/yourco` 或下载就能用, 不需要装语言 runtime。

### Step 3 — 写 Anthropic Skill (1 天, \~800 tokens)

`~/.claude/skills/yourco/SKILL.md`:

```markdown
---
name: yourco
description: YourCo POS data lookup. Use when user asks about restaurant menu, sales, reviews for any YourCo-managed location.
---

# YourCo CLI

YourCo is the [行业] SaaS. Use `yourco` CLI to query data.

## Common commands

### Get menu
\`\`\`bash
yourco menu <location_id>
\`\`\`
Returns JSON with all menu items, prices, modifiers, categories.

### Get daily sales
\`\`\`bash
yourco sales <location_id> <YYYY-MM-DD>
\`\`\`
Returns total revenue, top items, hourly distribution, payment methods breakdown.

### Get recent reviews
\`\`\`bash
yourco reviews <location_id> [--days 7]
\`\`\`
Returns Google/Yelp reviews from past N days with rating + text + sentiment.

## When to use which

- "今天 [客户] 卖了多少?" → `yourco sales <id> 2026-05-28`
- "[菜单] 上有几个 vegetarian 选项?" → `yourco menu <id>` 然后 grep
- "[客户] 最近一周差评有哪些?" → `yourco reviews <id> --days 7` 然后 filter rating < 3

## Auth

CLI 已配 `YOURCO_TOKEN` env var, 不需要用户每次输 token。
如果 token 过期 (401 错误), 让用户跑 `yourco auth login`。

## Output format

所有命令都返回 JSON, 可以用 `jq` pipe 解析:
\`\`\`bash
yourco sales loc_123 2026-05-28 | jq '.top_items[0:5]'
\`\`\`
```

### Step 4 — 团队 onboard (1 天)

- 把 `yourco` binary 放进团队的 `brew tap yourco/tap`
- 把 `~/.claude/skills/yourco/` 加进 Claude Code project skill folder
- 写一封 "Hi team, this is how you use yourco CLI with Claude Desktop / Claude Code" 邮件
- 团队成员 `brew install yourco/tap/yourco` + cp skill folder → ship

### Step 5 — 用起来什么样?

PM 在 Claude Desktop 问:

> "Location X 法拉盛店上周卖得最好的菜是什么? 看看 review 里有没有差评?"

Claude 自动执行:

```bash
# Claude 先调
yourco sales loc_x_flushing 2026-05-21  # 周一
yourco sales loc_x_flushing 2026-05-22  # 周二
...  # 一周 7 天
# 然后聚合, 找出 top sellers
yourco reviews loc_x_flushing --days 7
# 然后 LLM 自己 summarize
```

**Token 成本**: SKILL.md 800 tokens load + 每次 CLI 调用返回 JSON (\~500-2000 tokens) + LLM 思考 — total \~5K-10K tokens per task。

**vs MCP server 同样的 task**: \~50K-100K tokens (因为 MCP server schema 一次 load 几万 tokens)。

**Reliability**: CLI 是稳定接口 (你自己写的代码), 100%。MCP server 经常 protocol mismatch / connection drop, 实测 72%。

***

## §4. 现成 CLI 工程团队可以**今天就用** (0 backend 改动)

不需要等你内部 REST API + 自家 CLI ship, 工程团队**今天**就能用 Claude Code + 现成成熟 CLI:

| CLI              | 用途                             | 团队 use case 例子                                |
| ---------------- | ------------------------------ | --------------------------------------------- |
| `gh`             | GitHub (代码 review, PR, issue)  | "帮我 review PR #234, 找潜在 security issue"       |
| `aws`            | AWS CLI (CloudWatch, ECS, IAM) | "看 xpress-service 过去 24 小时 ERROR log 频率"      |
| `dotnet`         | .NET SDK                       | "跑 unit test for OrderService 并解释失败原因"        |
| `mongosh`        | MongoDB shell                  | "查 customers collection 的 schema 和 index 健康度" |
| `docker` / `k9s` | 容器调试                           | "检查 production ECS task 当前状态"                 |
| `wrangler`       | Cloudflare Workers             | "deploy worker 到 staging + 看日志"               |
| `vercel`         | Vercel                         | "promote preview 到 prod + check build status" |
| `stripe`         | Stripe payments                | "查 customer X 最近 10 个 charge"                 |

写几个 Anthropic Skill 教 Claude 怎么用这些 CLI 在**公司 specific scenario** 下 (例: "怎么查 xpress-service 的 ECS task 日志") — 工程团队效率立刻 2-3x。**成本: PM 1 周写完, 工程团队 0 backend 改动**。

***

## §5. 跟其他几个概念的关系

| 概念                                                           | 一句话定义                                               | 你公司什么时候用                                                                                    |
| ------------------------------------------------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| **CLI** (`gh`, `aws`, 未来的 `yourco`)                          | binary 工具, 直接在 shell 跑                              | **今天就用** (现成 CLI) + M7-M8 写 yourco CLI                                                      |
| **Anthropic Skills** (`~/.claude/skills/<name>/SKILL.md`)    | 教 LLM 怎么用 CLI 的 markdown 文档, 800 tokens 起           | **PM 1 周写完几个 skill 教你公司 specific CLI 用法**                                                   |
| **MCP server**                                               | JSON-RPC server 让 LLM 通过 protocol 调用 tool           | Phase 3 才考虑 ([mcp-vs-cli-vs-skills-2026.md](/ai/product/mcp-vs-cli-vs-skills-2026.md) §1.8) |
| **LLM Function Calling** (OpenAI tools / Anthropic tool use) | 你 backend code 里直接告诉 LLM "我有这些 function", LLM 决定调哪个 | 客户在你 SaaS 内部用 AI feature 时用这个                                                               |

**Token cost 排序**: CLI \< Skills \< Function Calling \< MCP。**所以个人/小团队 default CLI, enterprise multi-tenant default MCP, 中间地带 Skills**。

***

## §6. 实战 checklist — 你 SaaS 从 0 到 1 上 CLI

| Step                                                           | 谁做            | 耗时           |
| -------------------------------------------------------------- | ------------- | ------------ |
| 1. Internal REST API 存在 + Auth (OAuth 2.1) 配好                  | Backend team  | 已有 / Phase 1 |
| 2. 选 CLI framework (Typer / Cobra / oclif)                     | Eng lead      | 半天           |
| 3. 实现核心 5-10 个 command (menu / sales / reviews / customer / 等) | 1 Backend dev | 3-5 天        |
| 4. 打包 binary (pyinstaller / go build / pkg)                    | 同上            | 半天           |
| 5. 发布到内部 brew tap 或 internal package registry                  | DevOps        | 半天           |
| 6. 写 SKILL.md 教 Claude 怎么用                                     | PM            | 1 天          |
| 7. 团队 onboard (邮件 + Loom video + Q\&A 1 小时)                    | PM            | 半天           |
| **Total**                                                      |               | **1 周**      |

**Cost**: 1 Backend dev × 1 周 ($5-10K all-in) + 0 ongoing license fee。

**Compare**: 自建 MCP server MVP $25K-50K (5-10 周), production multi-tenant $60K-150K (3-6 月)。

→ **结论**: 你 SaaS 应该**先有 CLI + Skills, 12 个月后客户开始问"能不能在 ChatGPT 接你 SaaS"才考虑 MCP server**。

***

## §7. Sources

- [Anthropic Skills 官方 repo](https://github.com/anthropics/skills)
- [Anthropic Skills API docs](https://platform.claude.com/docs/en/build-with-claude/skills-guide)
- [Anthropic Skills + CLI 完整 guide](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/claude-api-skill)
- [Skills vs MCP Token Efficiency](https://themenonlab.blog/blog/skills-vs-mcp-token-efficiency-ai-agents)
- [Simon Willison: Skills > MCP](https://simonwillison.net/2025/Anthropic-Skills) (referenced in Arize blog)
- [Typer Python CLI framework](https://typer.tiangolo.com/)
- [Cobra Go CLI framework](https://github.com/spf13/cobra)
- [oclif Node CLI framework](https://oclif.io/)
- Related: [mcp-vs-cli-vs-skills-2026.md](/ai/product/mcp-vs-cli-vs-skills-2026.md) — when to choose which