writing-cli-skills

Original：🇺🇸 English

Translated

Guide for writing skills that wrap CLI tools. Use when creating a new CLI skill. For review, run through the Checklist section.

1installs

Sourcecachemoney/agent-toolkit

Added on2026-02-20

NPX Install

npx skill4agent add cachemoney/agent-toolkit writing-cli-skills

SKILL.md Content

View Translation Comparison →

Writing CLI Skills

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

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

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

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

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

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

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