CLI-First Skill Design

在构建Agent技能（可复用能力）时，存在以下两难抉择：

• API优先设计：将技能设计为函数/类——适配程序化调用，但手动调试与测试难度较高
• GUI优先设计：将技能设计为可视化工具——便于人类操作，但无法被Agent调用

团队最终要么开发两套接口，要么只能优先满足其中一类用户的需求。

所有技能首先设计为CLI工具。设计良好的CLI天然具备双重用途：人类可以从终端调用它，Agent则可以通过Shell命令调用。

graph LR
    A[技能逻辑] --> B[CLI接口]
    B --> C[人类：终端]
    B --> D[Agent：Bash工具]
    B --> E[脚本：自动化]
    B --> F[Cron：定时任务]

核心原则：

1. 单脚本对应单技能：每个能力对应一个独立可执行文件
2. 用子命令实现操作：例如skill.sh list、skill.sh get <id>、skill.sh create
3. 结构化输出：供程序调用时输出JSON格式，针对终端（TTY）环境输出人类可读内容
4. 退出码规范：0表示执行成功，非零值表示执行错误（支持&&链式调用）
5. 环境变量配置：凭证通过环境变量（env vars）传递，禁止硬编码

# 示例：将Trello功能实现为CLI工具
trello.sh boards                    # 列出所有看板
trello.sh cards <BOARD_ID>          # 列出指定看板上的卡片
trello.sh create <LIST_ID> "Title"  # 创建卡片
trello.sh move <CARD_ID> <LIST_ID>  # 移动卡片

# 人类使用示例
$ trello.sh boards
{"id": "abc123", "name": "Personal", "url": "..."}
{"id": "def456", "name": "Work", "url": "..."}

# Agent使用示例（通过Bash工具）
Bash: trello.sh cards abc123 | jq '.[0].name'

技能结构：

~/.claude/skills/
├── trello/
│   └── scripts/
│       └── trello.sh          # 主CLI入口
├── asana/
│   └── scripts/
│       └── asana.sh
├── honeybadger/
│   └── scripts/
│       └── honeybadger.sh
└── priority-report/
    └── scripts/
        └── priority-report.sh  # 组合其他技能

CLI设计检查清单：

• [ ] 带有shebang（#!/bin/bash）的独立可执行文件
• [ ] 支持通过--help或无参数方式查看帮助文本
• [ ] 提供用于CRUD操作的子命令
• [ ] 输出格式为JSON（可通过管道传递给jq工具格式化）
• [ ] 从~/.envrc文件或环境变量读取凭证信息
• [ ] 返回有意义的退出码
• [ ] 错误信息输出至stderr，业务数据输出至stdout

组合示例：

# priority-report.sh 组合多个技能CLI
#!/bin/bash
echo "## GitHub"
gh pr list --search "review-requested:@me"

echo "## Trello"
~/.claude/skills/trello/scripts/trello.sh cards abc123

echo "## Asana"
~/.claude/skills/asana/scripts/asana.sh tasks personal

优势：

• 默认支持双重用途：为人类和Agent提供统一操作接口
• 可调试：可手动运行以测试、检查输出结果
• 可组合：可与Unix工具实现管道传输、链式调用及组合使用
• 可移植：可在任意Shell环境中运行，无运行时依赖
• 透明化：Agent的工具调用以可见的Shell命令形式呈现
• 可测试：易于编写集成测试

劣势：

• Shell局限性：复杂数据结构在Bash中处理较为不便
• 错误处理能力不足：结构化程度远不如异常机制
• 性能短板：与函数调用相比，存在进程启动开销
• 状态管理缺失：多次调用之间无持久化状态
• Windows兼容性受限：需要依赖WSL或Git Bash才能使用

何时选用其他方案：

• 高频率调用场景（>100次/秒）：使用进程内函数
• 处理复杂对象图：使用结构化API
• 实时流处理场景：使用WebSocket/SSE