Writing Cli Skills

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

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

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:

Recommended

Writing Good Descriptions

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

# 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:

## Usage

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

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

Frontmatter Reference

---
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.

Tool Name

One-sentence description of what this tool does and why you'd use it.

Requirements

What needs to exist before using this tool:

• Required accounts or API keys
• System dependencies
• Other tools that must be installed first

Installation

macOS (Homebrew)

brew install tool-name

Linux

sudo apt install tool-name
# or
cargo install tool-name

Verify

tool-name --version

Quick Start

Get something useful done fast:

tool-name do-the-thing

Usage

View / List

tool-name list                    # List all items
tool-name show <id>               # Show details

Create / Add

tool-name add "name" https://url
tool-name create --name "foo"

Edit / Update

tool-name edit <id>
tool-name update <id> --field value

Delete / Remove

tool-name remove <id>

Search

tool-name search "query"

Output Formats

tool-name list --output json
tool-name list --format "{{.Name}}"

Tips & Gotchas

• Thing that's not obvious
• Platform-specific notes

Troubleshooting

Debug mode

tool-name --verbose command

Common errors

Error: "connection refused"

• Check if the service is running

Error: "authentication failed"

• Verify API key

Reset state

rm -rf ~/.local/share/tool-name/cache

Configuration

Config file

~/.config/tool-name/config.toml

Minimal config

[section]
key = "value"

Environment variables

export TOOL_API_KEY="your-key"

Uninstall

brew uninstall tool-name
rm -rf ~/.config/tool-name
rm -rf ~/.local/share/tool-name

References

• Official docs