writing-cli-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Writing CLI Skills

编写CLI技能

How to write an agent skill for a command-line tool.

如何为命令行工具编写Agent技能。

Quick Start

快速入门

Install the tool and play with it — don't just read docs. If the tool is unavailable, use WebFetch on official docs + man pages, but note this in your skill as "not hands-on verified"
Run
```
--help
```
on every subcommand
Try the common operations yourself
Note what surprises you or isn't obvious
Copy
```
references/template.md
```
to your new skill directory
Fill in sections based on your hands-on experience
Delete sections that don't apply

bash

undefined

安装工具并实际试用 — 不要只阅读文档。如果工具无法获取，可通过WebFetch获取官方文档和man手册，但需在技能中注明“未经过实操验证”
对每个子命令执行
```
--help
```
亲自尝试常见操作
记录让你感到意外或不直观的点
将
```
references/template.md
```
复制到你的新技能目录
根据实操经验填写各个章节
删除不适用的章节

bash

undefined

First: actually use the tool

my-tool --help my-tool subcommand --help my-tool do-something # try it!

Then: create the skill

This will depend on the tool

Claude Code

ln -s "$PWD/skills/my-tool" ~/.claude/skills/my-tool

OpenCode

ln -s "$PWD/skills/my-tool" ~/.config/opencode/skills/my-tool

Clawdbot

ln -s "$PWD/skills/my-tool" ~/clawd/skills/my-tool


**Reading docs is no substitute for hands-on use.** You'll discover defaults, gotchas, and real behavior that docs don't mention.

ln -s "$PWD/skills/my-tool" ~/clawd/skills/my-tool


**阅读文档无法替代实操体验。**你会发现文档中未提及的默认设置、陷阱和实际行为。

What NOT to Do

注意事项

Do not dump
```
--help
```
output verbatim — summarize the useful parts
Do not document every flag — focus on the 80% use cases
Do not include commands you haven't tested
Do not exceed 500 lines — this bloats agent context windows

不要直接照搬
```
--help
```
输出 — 总结有用的部分
不要记录每个标志 — 聚焦80%的常用场景
不要包含未测试过的命令
内容不要超过500行 — 这会占用Agent的上下文窗口

Sections

章节划分

Required

必填章节

Every CLI skill needs at minimum:

Section	Purpose
Frontmatter	name, description (with trigger phrases)
Installation	How to get the binary
Usage	The 80% use cases

每个CLI技能至少需要包含以下章节：

章节	用途
Frontmatter	名称、描述（包含触发短语）
安装	如何获取二进制文件
使用方法	80%的常用场景

Section	When to Include
Requirements	Tool needs accounts, API keys, or dependencies
Quick Start	Tool has a simple "happy path"
Output Formats	Tool can output JSON or custom formats
Tips & Gotchas	Tool has some edge cases or things an agentic LLM should not use
Troubleshooting	Tool has debug modes or common failure modes
Configuration	Tool has config files or env vars
Uninstall	Tool leaves config/data behind
References	When there are useful docs or content that contains more details

章节	适用场景
前置要求	工具需要账户、API密钥或依赖项
快速入门	工具存在简单的“顺畅路径”
输出格式	工具可输出JSON或自定义格式
技巧与陷阱	工具存在一些边缘情况或Agentic LLM不应使用的功能
故障排除	工具具备调试模式或常见故障场景
配置	工具拥有配置文件或环境变量
卸载	工具会遗留配置/数据文件
参考资料	存在包含更多细节的有用文档或内容

Writing Good Descriptions

撰写优质描述

Include trigger phrases so the agent knows when to load the skill:

yaml

undefined

包含触发短语，让Agent知道何时加载该技能：

yaml

undefined

Good

优质示例

description: Monitor RSS feeds for updates. Use when tracking blogs, checking for new posts, or building a feed reader workflow.

description: 监控RSS源更新。用于追踪博客、检查新文章或构建阅读器工作流。

Bad

反面示例

description: RSS tool.

undefined

description: RSS工具。

undefined

Organizing Commands

命令组织

Group by task, not by command name:

markdown

undefined

按任务分组，而非命令名称：

markdown

undefined

Usage

使用方法

View / List

查看/列出

Create / Add

创建/添加

Edit / Update

编辑/更新

Delete / Remove

删除/移除

Search

搜索

undefined

undefined

Progressive Disclosure

渐进式披露

Keep SKILL.md under ~500 lines. Move details to references/:

my-tool/
├── SKILL.md                    # Core usage
├── references/
│   ├── advanced-config.md      # Deep config docs
│   └── api-reference.md        # API details
└── scripts/
    └── helper.sh               # Helper scripts

保持SKILL.md在500行以内。将详细内容移至references/目录：

my-tool/
├── SKILL.md                    # 核心使用说明
├── references/
│   ├── advanced-config.md      # 高级配置文档
│   └── api-reference.md        # API详情
└── scripts/
    └── helper.sh               # 辅助脚本

Frontmatter Reference

Frontmatter参考

yaml

---
name: tool-name                  # Required, matches directory
description: What + when         # Required, include triggers
---

yaml

---
name: tool-name                  # 必填，需与目录名一致
description: 功能+适用场景         # 必填，包含触发短语
---

Checklist

检查清单

Before publishing a CLI skill:

Frontmatter has name + description with trigger phrases
Installation covers target platforms
Includes verification command (
```
tool --version
```
)
Config file locations documented
Required env vars listed
Common operations in usage cover 80% of use cases
Examples show realistic usage with sample output
Output formats documented (if tool supports JSON/etc)
Troubleshooting includes debug mode
Uninstall cleans up config and data
Under 500 lines (details in references/)

发布CLI技能前，请确认：

Frontmatter包含名称和带有触发短语的描述
安装章节涵盖目标平台
包含验证命令（
```
tool --version
```
）
已记录配置文件位置
已列出必填环境变量
使用方法中的常见操作覆盖80%的使用场景
示例展示了真实使用场景及示例输出
已记录输出格式（如果工具支持JSON等格式）
故障排除章节包含调试模式说明
卸载操作可清理配置和数据
内容不超过500行（详细内容放在references/中）

Template

模板

See

references/template.md

for a complete starting point.

完整的起始模板请查看

references/template.md

。

writing-cli-skills

Original

Translation

Writing CLI Skills

编写CLI技能

Quick Start

快速入门

First: actually use the tool

First: actually use the tool

Then: create the skill

Then: create the skill

This will depend on the tool

This will depend on the tool

Claude Code

Claude Code

OpenCode

OpenCode

Clawdbot

Clawdbot

What NOT to Do

注意事项

Sections

章节划分

Required

必填章节

Recommended

推荐章节

Writing Good Descriptions

撰写优质描述

Good

优质示例

Bad

反面示例

Organizing Commands

命令组织

Usage

使用方法

View / List

查看/列出

Create / Add

创建/添加

Edit / Update

编辑/更新

Delete / Remove

删除/移除

Search

搜索

Progressive Disclosure

渐进式披露

Frontmatter Reference

Frontmatter参考

Checklist

检查清单

Template

模板