Back to Details

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

快速入门

  1. 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"
  2. Run 
    --help
    on every subcommand
  3. Try the common operations yourself
  4. Note what surprises you or isn't obvious
  5. Copy 
    references/template.md
    to your new skill directory
  6. Fill in sections based on your hands-on experience
  7. Delete sections that don't apply
bash
undefined
  1. 安装工具并实际试用 — 不要只阅读文档。如果工具无法获取，可通过WebFetch获取官方文档和man手册，但需在技能中注明“未经过实操验证”
  2. 对每个子命令执行
    --help
  3. 亲自尝试常见操作
  4. 记录让你感到意外或不直观的点
  5. 将
    references/template.md
    复制到你的新技能目录
  6. 根据实操经验填写各个章节
  7. 删除不适用的章节
bash
undefined

First: actually use the tool

First: actually use the tool

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

Then: create the skill

Then: create the skill

This will depend on the tool

This will depend on the tool

Claude Code

Claude Code

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

OpenCode

OpenCode

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

Clawdbot

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:
SectionPurpose
Frontmattername, description (with trigger phrases)
InstallationHow to get the binary
UsageThe 80% use cases
每个CLI技能至少需要包含以下章节：
章节用途
Frontmatter名称、描述（包含触发短语）
安装如何获取二进制文件
使用方法80%的常用场景

Recommended

推荐章节

SectionWhen to Include
RequirementsTool needs accounts, API keys, or dependencies
Quick StartTool has a simple "happy path"
Output FormatsTool can output JSON or custom formats
Tips & GotchasTool has some edge cases or things an agentic LLM should not use
TroubleshootingTool has debug modes or common failure modes
ConfigurationTool has config files or env vars
UninstallTool leaves config/data behind
ReferencesWhen 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
。