CLI-Anything 教程 7：第六阶段 Document（完善文档与 SKILL.md 生成）

教程概述

系列目录：CLI-Anything 教程系列索引

Document 是 CLI-Anything 7 阶段流程的第六阶段。这一阶段的核心任务是完善文档，特别是生成 SKILL.md 供 AI Agent 自动发现和使用。

为什么需要 SKILL.md？

flowchart LR
    A[无 SKILL.md] --> B[Agent 不知道 CLI 存在]
    A --> C[Agent 不会正确使用 CLI]

    D[有 SKILL.md] --> E[Agent 自动发现 CLI]
    E --> F[Agent 知道所有命令和参数]
    E --> G[Agent 能正确调用 CLI]

    style A fill:#ffcccc
    style B fill:#ffcccc
    style C fill:#ffcccc
    style D fill:#e8f5e9
    style E fill:#e8f5e9
    style F fill:#e8f5e9
    style G fill:#e8f5e9

SKILL.md 标准格式

# Skill Definition: cli-anything-<software>

## Overview

**CLI Name**: cli-anything-<software>
**Version**: 1.0.0
**Target Software**: <Software Name> <Version>
**Purpose**: Enable AI agents to automate <software> workflows via CLI

## Installation

```bash
pip install cli-anything-<software>

Capabilities

Command Groups

project - Project Management

project new - Create new project
project open - Open existing project
project save - Save current project
project close - Close project

image - Image Operations

image new - Create new image
image scale - Scale image dimensions
image crop - Crop image

… (other command groups)

Usage Patterns

Pattern 1: Create and Edit Project

# 1. Create project
cli-anything-<software> project new --name "MyProject" -o project.json

# 2. Add content
cli-anything-<software> --project project.json image new --width 1920 --height 1080

# 3. Apply operations
cli-anything-<software> --project project.json filter apply-blur --radius 5

# 4. Export
cli-anything-<software> --project project.json export render output.png

Pattern 2: Batch Processing

cli-anything-<software> --project project.json export batch \
  --input "images/*.jpg" \
  --output-dir "output/" \
  --format png

Pattern 3: REPL Interactive Session

# Start REPL
cli-anything-<software>

# Inside REPL
> project new --name "InteractiveProject"
> image new --width 800 --height 600
> layer new --name "Layer1"
> filter gaussian-blur --radius 3
> export render output.jpg
> exit

JSON Output Mode

All commands support --json flag for structured output:

cli-anything-<software> --json project info --project project.json

Response format:

{
  "success": true,
  "command": "project info",
  "data": { ... },
  "error": null
}

Error Handling

Common error types:

E_FILE_NOT_FOUND - File does not exist
E_INVALID_PARAMETER - Invalid parameter value
E_SOFTWARE_NOT_FOUND - Target software not installed

Constraints

Requires >= to be installed
Some commands require X11 display (unless in batch mode)
Large files may require significant memory

Examples

Example 1: Photo Batch Processing

# Process multiple photos
for photo in photos/*.jpg; do
  cli-anything-<software> project new --name "temp"
  cli-anything-<software> image open "$photo"
  cli-anything-<software> filter auto-enhance
  cli-anything-<software> export render "processed/$(basename $photo)"
done

Example 2: Automated Report Generation

# Create document with data
cli-anything-<software> document new --type report
cli-anything-<software> document add-heading "Q1 Results" --level 1
cli-anything-<software> document add-table --data sales.csv
cli-anything-<software> export render report.pdf

Integration Notes

Use --json flag when calling from scripts
Use REPL mode for interactive sessions
Always check success field in JSON output
Save project state after important operations


## 文档生成工具

CLI-Anything 提供自动生成 SKILL.md 的工具：

```python
# cli_anything/utils/skill_generator.py

from jinja2 import Template

SKILL_TEMPLATE = """
# Skill Definition: {{ cli_name }}

## Overview

**CLI Name**: {{ cli_name }}
**Version**: {{ version }}
**Target Software**: {{ target_software }}
**Purpose**: {{ purpose }}

## Capabilities

{% for group in command_groups %}
### {{ group.name }} - {{ group.description }}

{% for cmd in group.commands %}
- `{{ cmd.name }}` - {{ cmd.description }}
{% endfor %}

{% endfor %}

## Usage Patterns

[Auto-generated from command definitions]

## JSON Output Mode

All commands support `--json` flag for structured output.

## Error Handling

{% for error in error_types %}
- `{{ error.code }}` - {{ error.description }}
{% endfor %}

## Examples

[Auto-generated from test cases]
"""


def generate_skill_md(cli_module, output_path):
    """Generate SKILL.md from CLI module."""
    # 提取命令信息
    command_groups = extract_command_groups(cli_module)

    # 渲染模板
    template = Template(SKILL_TEMPLATE)
    content = template.render(
        cli_name=cli_module.__name__,
        version=get_version(cli_module),
        target_software=get_target_software(cli_module),
        purpose=get_purpose(cli_module),
        command_groups=command_groups,
        error_types=get_error_types(cli_module)
    )

    # 写入文件
    with open(output_path, 'w') as f:
        f.write(content)

    return output_path

README.md 标准内容

# cli-anything-<software>

CLI interface for <Software> that enables AI agent automation.

## Features

- ✅ Complete <Software> API coverage
- ✅ REPL mode for interactive use
- ✅ JSON output for agent integration
- ✅ Batch processing support
- ✅ Undo/redo support

## Installation

```bash
pip install cli-anything-<software>

Quick Start

# Create project
cli-anything-<software> project new --name "MyProject"

# Start REPL
cli-anything-<software>

Documentation

SKILL.md - AI Agent skill definition
API Docs - Complete API reference

License

MIT


## 小结

Document 阶段确保 CLI 可被 Agent 发现和使用：

1. **SKILL.md** - AI Agent 技能定义文档
2. **README.md** - 用户文档
3. **自动生成** - 从代码生成文档
4. **使用示例** - 提供常见使用模式

---

**系列导航**：

- ← 上一篇：[教程 6：第五阶段 - 测试编写](/2026/04/cli-anything-phase5-test-write/)
- → 下一篇：[教程 8：第七阶段 - 发布与优化](/2026/04/cli-anything-phase7-publish/)