AgentSkillsCN

writing-cli-skills

指导开发者编写封装CLI工具的技能。当您需要创建新的CLI技能时，可使用此技能。在审核时，请务必仔细对照“检查清单”部分。

SKILL.md
--- frontmatter
name: writing-cli-skills
description: Guide for writing skills that wrap CLI tools. Use when creating a new CLI skill. For review, run through the Checklist section.

Writing CLI Skills

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

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
# 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/skill/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.

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

Sections

Required

Every CLI skill needs at minimum:

SectionPurpose
Frontmattername, description (with trigger phrases)
InstallationHow to get the binary
UsageThe 80% use cases

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

Writing Good Descriptions

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

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

# Bad  
description: RSS tool.

Organizing Commands

Group by task, not by command name:

markdown
## Usage

### View / List
### Create / Add  
### Edit / Update
### Delete / Remove
### Search

Progressive Disclosure

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

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

Frontmatter Reference

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

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/)

Template

See references/template.md for a complete starting point.