CLI Skill Creator Overview This skill guides the creation of comprehensive skills for command-line interface (CLI) tools. It provides a systematic workflow for introspecting CLI tools through multiple sources (help text, manual pages, GitHub repositories, online research), extracting mental models and command patterns, and organizing findings into effective skill documentation using the skill-creator skill. When to Use This Skill Invoke this skill when users: Ask to create a skill for a CLI tool (e.g., "Create a skill for docker", "Document kubectl") Request comprehensive CLI documentation or guidance Want to understand a CLI tool's mental model and structure Need to organize CLI knowledge for consistent use Ask about documenting command-line tools systematically Core Workflow Creating a CLI skill follows a systematic seven-step process that gathers comprehensive information before organizing it into skill documentation. Step 1: CLI Identification & Availability Check Objectives: Verify CLI tool is installed or accessible Determine tool version and variant Identify documentation sources Assess open-source availability Actions: Check installation and version < cli-tool

--version which < cli-tool

Identify tool characteristics Name and official name (if different) Current version Primary purpose/domain Open source or proprietary Locate documentation sources Official website/documentation GitHub repository (if open source) Man pages availability Community resources Output: Tool profile including version, purpose, and available documentation sources. Step 2: Comprehensive Help Text Introspection Objectives: Map command hierarchy and structure Extract all commands, subcommands, and flags Capture examples from help text Identify command patterns (verb-noun, noun-verb, flat) Reference: Load references/help-text-patterns.md for detailed parsing guidance. Actions: Extract top-level help < cli-tool

--help < cli-tool

-h < cli-tool

help < cli-tool

(no args, if applicable)

Map command hierarchy Identify all subcommands Determine nesting depth Note command organization pattern Document each command/subcommand

For each discovered command

< cli-tool

< command

--help < cli-tool

< command

< subcommand

--help Extract key information Command purpose and description Required vs optional arguments Flags and their descriptions Usage examples Default behaviors Identify patterns Flag naming conventions Argument patterns Output format options Common options across commands Output: Structured command reference with hierarchy, all commands documented, examples extracted, and patterns identified. Step 3: GitHub Repository Analysis (if open-source) Objectives: Understand implementation patterns Find real-world usage examples Identify common user pain points Discover undocumented features or gotchas Reference: Load references/help-text-patterns.md section "GitHub Repository Analysis" for detailed guidance. Actions: Clone repository (if accessible and reasonable size) git clone --depth 1 https://github.com/ < org

/ < repo

Examine documentation structure README.md - Quick start, core concepts docs/ or doc/ - Detailed documentation examples/ - Usage examples CONTRIBUTING.md - Development patterns man/ - Man page sources Analyze code structure CLI framework used (Cobra, Click, Commander, Clap, etc.) Command file organization Main entry point Subcommand implementations Review tests for usage patterns Integration tests show common workflows Unit tests reveal edge cases Test fixtures show example inputs Assertions reveal expected outputs Mine issues and discussions Search for label:question - Common user questions Search for label:documentation - Doc gaps Look for "How do I..." - Workflow questions Find repeated issues - Common pain points Check shell completions (reveal command structure) completions/ or scripts/ directory Shell completion files show all commands/flags Output: Implementation insights, real-world usage examples, common pain points, and undocumented behaviors. Step 4: Manual Page Parsing (if available) Objectives: Extract comprehensive command documentation Capture formal syntax descriptions Identify related commands Note historical context or design rationale Reference: Load references/help-text-patterns.md section "Manual Page Parsing" for detailed guidance. Actions: Check man page availability man < cli-tool

man -k < cli-tool

Search for related pages

Extract key sections NAME - Command identity SYNOPSIS - Formal syntax DESCRIPTION - Detailed explanation OPTIONS - Comprehensive flag documentation EXAMPLES - Usage examples SEE ALSO - Related commands BUGS - Known issues Export for analysis

Export to plain text

man < cli-tool

| col -b

man_ < cli-tool

.txt

Extract specific sections

man

<

cli-tool

>

|

grep

-A

50

"^OPTIONS"

man

<

cli-tool

>

|

grep

-A

30

"^EXAMPLES"

Check for subcommand man pages

man

<

cli-tool

>

-

<

subcommand

>

Output:

Formal command documentation, comprehensive option descriptions, and usage examples from man pages.

Step 5: Online Research & Best Practices

Objectives:

Discover community best practices

Find common workflows and patterns

Identify integration points with other tools

Learn from tutorials and guides

Actions:

Search for official documentation

Official website documentation

API documentation (if CLI wraps an API)

Architecture guides

Best practices guides

Find community resources

Blog posts about advanced usage

Tutorial sites (Medium, Dev.to, etc.)

Video tutorials (YouTube)

Conference talks

Check Q&A sites

Stack Overflow common questions

Reddit discussions

GitHub Discussions

Tool-specific forums

Identify integration patterns

How does it work with Git?

CI/CD integration patterns

Editor/IDE integrations

Companion tools

Look for comparisons

"X vs Y" articles (reveals strengths/differences)

Migration guides (reveals mental model differences)

"Awesome X" lists (reveals ecosystem)

Output:

Community best practices, common workflows, integration patterns, and ecosystem understanding.

Step 6: Material Organization & Structure Design

Objectives:

Synthesize findings into coherent mental model

Identify command structure pattern

Organize content by user task/workflow

Determine skill structure (workflow-based, command-based, etc.)

Reference:

Load

references/skill-templates.md

for guidance.

Actions:

Extract core mental model

What are the fundamental concepts? (resources, actions, state)

How does the tool want users to think?

What abstractions does it use?

What's the command hierarchy philosophy?

Identify command structure pattern

Flat (single-level commands)

Noun-Verb (resource-action)

Verb-Noun (action-resource)

Hybrid (mix of patterns)

Map common workflows

What are the 5-10 most common tasks?

What's the getting-started workflow?

What are the advanced workflows?

What operations are risky/destructive?

Organize findings by category

Core concepts and terminology

Command reference (grouped logically)

Workflow patterns (numbered for reference)

Configuration and setup

Integration patterns

Troubleshooting common issues

Choose skill structure

(load

references/skill-templates.md

)

Workflow-based

For sequential, process-oriented tools

Command-based

For tools with many discrete operations

Hybrid

Combine patterns (most common)

Decide what goes where

skill.md

Overview, core concepts, common operations, when to load references

references/_reference.md

Complete command reference, all workflows, detailed examples

Additional reference files if needed (e.g., for GraphQL API, specialized features)

Output:

Structured content outline organized by user task/workflow, clear mental model summary, and skill structure plan.

Step 7: Invoke skill-creator Skill

Objectives:

Generate skill directory structure

Create skill.md and reference documentation

Package skill for distribution

Validate completeness

Actions:

Prepare structured brief for skill-creator

Organize all gathered material into a comprehensive brief including:

CLI Profile

Name, version, purpose

Command structure pattern

Open source status and GitHub URL

Core Mental Model

Fundamental concepts (2-5 key concepts)

How users should think about the tool

Key terminology and definitions

Command Reference Material

Organized by category/domain

All commands with syntax and examples

Common flags and options

Command relationships

Workflow Patterns

5-10 common workflows

Step-by-step with commands

When to use each pattern

Integration Points

Other tools it works with

CI/CD integration

File formats, protocols

Configuration

Config file locations

Key settings

Environment variables

Troubleshooting

Common issues and solutions

Diagnostic commands

Error patterns

Invoke skill-creator skill

Use the Skill tool to invoke skill-creator:

Skill: skill-creator

Prompt: Create a skill for with the following structure and content:

[Provide the complete structured brief from step 1]

Structure the skill using [workflow-based/command-based/hybrid] approach.

The skill.md should include:

- Overview and when to use this skill

- Core concepts: [list key concepts]

- Common operations organized by [category structure]

- Reference to comprehensive command reference in references/

Create references/_reference.md with:

- Complete mental model explanation

- Full command reference organized by [organization scheme]

- Workflow patterns 1-N

- Configuration, integration, and troubleshooting sections

Follow the patterns from existing CLI skills like gh, graphite, and erk.

Review generated skill

Check skill.md structure and clarity

Verify reference documentation completeness

Ensure examples are accurate

Test commands if possible

Iterate if needed

Refine unclear sections

Add missing examples

Improve organization

Fill gaps in documentation

Package skill

(if ready for distribution)

python scripts/package_skill.py .claude/skills/

<

cli-tool-name

>

Output:

Complete, packaged skill ready for use and distribution.

CLI Introspection Techniques

Help Text Parsing Strategies

Progressive help discovery:

Start with top-level help to understand overall structure

Enumerate all subcommands

Get help for each subcommand

Identify nested subcommands

Document all discovered commands

Information extraction:

Command syntax

Usage line shows required vs optional

Descriptions

What each command/flag does

Examples

Copy verbatim from help text

Defaults

Note default values for flags

Aliases

Note short forms (e.g.,

-h

for

--help

)

Pattern recognition:

Flag naming: Single-letter vs long-form consistency

Argument conventions:

vs

[optional]

Subcommand organization: Grouped by domain/resource

Output options:

--json

,

--plain

,

--format

Load

references/help-text-patterns.md

for comprehensive parsing guidance including regex patterns, format variations, and special cases.

GitHub Analysis Strategies

Quick reconnaissance:

README.md overview

Documentation directory structure

Examples directory

Contributing guide

Deep analysis:

Command implementation files (reveals structure)

Test files (reveals usage patterns)

Issues (reveals pain points)

Discussions (reveals community questions)

Framework detection:

Different CLI frameworks reveal structure differently:

Cobra (Go)

:

cmd/

directory with file per command

Click (Python)

Decorators on functions

Commander (Node.js)

Fluent API chains

Clap (Rust)

Struct definitions or builder pattern

Load

references/help-text-patterns.md

section "GitHub Repository Analysis" for detailed code reading strategies.

Mental Model Extraction

Ask these questions while introspecting:

Core abstractions

What are the primary "things" this CLI manipulates?

Action patterns

What verbs/actions does it support?

State management

Does it track state? Where?

Hierarchy

Is there a parent-child relationship between concepts?

Workflows

What are the common sequences of operations? Look for explicit mental model explanations: README "How it works" sections Documentation "Concepts" pages Architecture diagrams Design rationale documents Infer from command structure: Noun-verb suggests resource-oriented model Verb-noun suggests action-oriented model Flat structure suggests simple, single-purpose tool Deep nesting suggests complex domain model Skill Structure Guidance Choosing the Right Structure Load references/skill-templates.md for complete templates and examples. Workflow-based (use when): Clear sequential processes Most tasks follow similar steps Getting-started focus important Example: Deployment tools, CI/CD tools Command-based (use when): Many discrete, independent operations Users need command reference Operations don't follow fixed sequence Example: File manipulation tools, utilities Hybrid (use when - most common): Mix of common workflows and discrete operations Need both getting-started and comprehensive reference Example: gh, docker, kubectl, git Content Distribution: skill.md vs references/ skill.md should contain: Clear description triggering skill use Overview of tool purpose Core concepts (2-5 key concepts) When to load references Common operations (high-level guidance) Workflow decision guidance Integration overview references/_reference.md should contain: Comprehensive mental model Complete command reference All workflow patterns (numbered) Full configuration documentation Detailed troubleshooting Integration details Advanced usage Additional reference files (when needed): Separate file for specialized APIs (e.g., GraphQL) Separate file for large schema references Separate file for extensive configuration options Organizing Command Reference Best practices: Group by domain/resource (not alphabetically) Groups related commands together Matches user mental model Example: "Pull Request Commands", "Issue Commands" Order by frequency of use Most common operations first Advanced features later Matches progressive learning Include for each command: Purpose (one sentence) Syntax with placeholders Key flags (not exhaustive, link to help) 2-3 examples (simple to complex) Related commands Use consistent formatting: Code blocks for commands Tables for flag reference Numbered workflows Clear section headers Writing Effective Workflow Patterns Pattern structure:

Pattern N: ** Use case: ** When to use this workflow ** Steps: ** 1. < Step name

< Explanation

```bash < command

Complete example:

< full-workflow

Variations: Alternative approaches Pattern best practices: - Start with most common workflows - Show realistic examples (not foo/bar) - Include expected output - Note side effects or state changes - Link to related patterns - Mention prerequisites Load references/skill-templates.md for complete workflow pattern template and examples.

Integration with skill-creator

This skill gathers and organizes CLI material, then delegates to skill-creator for actual skill generation. Workflow: 1. cli-skill-creator: Introspects CLI, extracts patterns, organizes material 2. Handoff: Provides structured brief to skill-creator 3. skill-creator: Generates skill files, validates, packages Structured brief format: Provide skill-creator with: - CLI profile (name, version, purpose, structure pattern) - Core mental model (concepts, terminology) - Organized command reference material - Workflow patterns - Integration points - Configuration and troubleshooting Invocation: Use the Skill tool: Skill: skill-creator Create a skill for using the following material: [Complete structured brief] Use [workflow-based/command-based/hybrid] structure. Follow patterns from gh/graphite/erk skills. Advantages of this approach: - Separates introspection from generation - Leverages skill-creator's validation and packaging - Maintains consistency with other skills - Allows iterative refinement

Tips for Different CLI Types

Modern Subcommand CLIs (gh, docker, kubectl)

Focus on: - Clear command hierarchy - Workflow patterns (most important) - Integration with ecosystems - Progressive examples Structure: Hybrid (workflows + command reference)

Simple Utility CLIs (jq, curl, grep)

Focus on: - Core functionality explanation - Common use cases - Piping and composition - Flag combinations Structure: Command-based or simple workflow

API-Wrapper CLIs (aws, gcloud, heroku)

Focus on: - API mapping - Authentication patterns - JSON output handling - Rate limiting Structure: Command-based with workflow patterns

Legacy CLIs (tar, find, sed)

Focus on: - Modern usage patterns (not all historical options) - Common gotchas - Modern alternatives context - Safety warnings Structure: Workflow-based (guide away from dangerous patterns)

Quality Checklist

Before finalizing CLI skill: - [ ] Captured all major commands and subcommands - [ ] Documented 5-10 common workflow patterns - [ ] Extracted core mental model clearly - [ ] Organized by user task (not alphabetically) - [ ] Included realistic examples with output - [ ] Noted integration points - [ ] Documented common gotchas - [ ] Verified commands actually work - [ ] Noted CLI version documented - [ ] Linked to authoritative documentation - [ ] Followed structure of gh/graphite/erk skills - [ ] skill.md is concise (<300 lines) - [ ] references/ contains comprehensive details

Common Pitfalls

Avoid: 1. Alphabetical organization - Organize by task/domain instead 2. Exhaustive flag documentation - Link to help, show common flags only 3. Missing mental model - Always explain how to think about the tool 4. No workflow patterns - Users need task-oriented guidance 5. Untested examples - Verify all commands actually work 6. Version agnostic - Note which version was documented 7. Missing integration points - Document how it works with other tools 8. Poor skill.md description - Be specific about when to use skill

Resources

references/

This skill includes two comprehensive reference documents: - help-text-patterns.md - Practical guidance for parsing help text, man pages, and GitHub repositories. Load when introspecting CLI tools for comprehensive information extraction. - skill-templates.md - Reusable templates for skill structure, command reference, workflows, and sections. Load when organizing material and structuring skill documentation. Loading strategy: - Load help-text-patterns.md during introspection steps (Steps 2-4) - Load skill-templates.md during organization and structure design (Step 6) These references ensure consistent, comprehensive CLI skill creation following modern best practices.