名称: cli-skill-creator 描述: 这个技能应用于为 CLI 工具创建技能时使用。当用户要求记录命令行工具、创建 CLI 指南或构建终端命令技能时使用。通过帮助文本、手册页、GitHub 仓库和在线研究，系统性地内省 CLI 工具，然后将发现组织成有效的技能文档，这是必不可少的。

CLI 技能创建器

概述

这个技能指导创建命令行界面 (CLI) 工具的综合技能。它提供了一个系统化的工作流程，通过多个来源（帮助文本、手册页、GitHub 仓库、在线研究）内省 CLI 工具，提取思维模型和命令模式，并使用技能创建器技能将发现组织成有效的技能文档。

何时使用这个技能

在以下情况下调用这个技能：

要求为 CLI 工具创建技能（例如，“为 docker 创建技能”，“记录 kubectl”）
请求全面的 CLI 文档或指导
想要理解 CLI 工具的思维模型和结构
需要为一致使用组织 CLI 知识
询问系统化记录命令行工具

核心工作流程

创建 CLI 技能遵循一个系统化的七步流程，先收集全面信息，然后组织成技能文档。

步骤 1: CLI 识别与可用性检查

目标：

验证 CLI 工具是否已安装或可访问
确定工具版本和变体
识别文档来源
评估开源可用性

操作：

检查安装和版本
```
<cli-tool> --version
which <cli-tool>
```
识别工具特征
- 名称和官方名称（如果不同）
- 当前版本
- 主要用途/领域
- 开源或专有
定位文档来源
- 官方网站/文档
- GitHub 仓库（如果开源）
- 手册页可用性
- 社区资源

输出： 工具概况，包括版本、目的和可用文档来源。

步骤 2: 全面帮助文本内省

目标：

映射命令层次结构和结构
提取所有命令、子命令和标志
从帮助文本中捕获示例
识别命令模式（动词-名词、名词-动词、扁平）

参考： 加载 references/help-text-patterns.md 获取详细解析指导。

操作：

提取顶级帮助

<cli-tool> --help
<cli-tool> -h
<cli-tool> help
<cli-tool>  # （无参数，如果适用）

映射命令层次结构
- 识别所有子命令
- 确定嵌套深度
- 注意命令组织模式

记录每个命令/子命令

# 对于每个发现的命令
<cli-tool> <命令> --help
<cli-tool> <命令> <子命令> --help

提取关键信息
- 命令目的和描述
- 必需与可选参数
- 标志及其描述
- 使用示例
- 默认行为
识别模式
- 标志命名约定
- 参数模式
- 输出格式选项
- 跨命令的常见选项

输出： 结构化的命令参考，包含层次结构、所有命令记录、提取的示例和识别的模式。

步骤 3: GitHub 仓库分析（如果开源）

目标：

理解实现模式
找到真实使用示例
识别常见用户痛点
发现未记录的功能或陷阱

参考： 加载 references/help-text-patterns.md 部分“GitHub 仓库分析”获取详细指导。

操作：

克隆仓库（如果可访问且大小合理）

git clone --depth 1 https://github.com/<组织>/<仓库>

检查文档结构
- README.md - 快速开始、核心概念
- docs/ 或 doc/ - 详细文档
- examples/ - 使用示例
- CONTRIBUTING.md - 开发模式
- man/ - 手册页源文件
分析代码结构
- 使用的 CLI 框架（Cobra、Click、Commander、Clap 等）
- 命令文件组织
- 主入口点
- 子命令实现
审查测试中的使用模式
- 集成测试显示常见工作流程
- 单元测试揭示边界情况
- 测试夹具显示示例输入
- 断言揭示预期输出
挖掘问题和讨论
- 搜索 label:question - 常见用户问题
- 搜索 label:documentation - 文档差距
- 查找“如何做…” - 工作流程问题
- 发现重复问题 - 常见痛点
检查 shell 自动完成（揭示命令结构）
- completions/ 或 scripts/ 目录
- Shell 自动完成文件显示所有命令/标志

输出： 实现洞察、真实使用示例、常见痛点和未记录行为。

步骤 4: 手册页解析（如果可用）

目标：

提取全面的命令文档
捕获正式语法描述
识别相关命令
注意历史背景或设计理由

参考： 加载 references/help-text-patterns.md 部分“手册页解析”获取详细指导。

操作：

检查手册页可用性

man <cli-tool>
man -k <cli-tool>  # 搜索相关页面

提取关键部分
- NAME - 命令标识
- SYNOPSIS - 正式语法
- DESCRIPTION - 详细解释
- OPTIONS - 全面的标志文档
- EXAMPLES - 使用示例
- SEE ALSO - 相关命令
- BUGS - 已知问题

导出以供分析

# 导出到纯文本
man <cli-tool> | col -b > man_<cli-tool>.txt

# 提取特定部分
man <cli-tool> | grep -A 50 "^OPTIONS"
man <cli-tool> | grep -A 30 "^EXAMPLES"

检查子命令手册页
```
man <cli-tool>-<子命令>
```

输出： 正式的命令文档、全面的选项描述和来自手册页的使用示例。

步骤 5: 在线研究与最佳实践

目标：

发现社区最佳实践
找到常见工作流程和模式
识别与其他工具的集成点
从教程和指南中学习

操作：

搜索官方文档
- 官方网站文档
- API 文档（如果 CLI 包装 API）
- 架构指南
- 最佳实践指南
找到社区资源
- 关于高级使用的博客文章
- 教程网站（Medium、Dev.to 等）
- 视频教程（YouTube）
- 会议演讲
检查问答网站
- Stack Overflow 常见问题
- Reddit 讨论
- GitHub 讨论
- 工具特定论坛
识别集成模式
- 它与 Git 如何工作？
- CI/CD 集成模式
- 编辑器/IDE 集成
- 配套工具
查找比较
- “X vs Y”文章（揭示优势/差异）
- 迁移指南（揭示思维模型差异）
- “Awesome X”列表（揭示生态系统）

输出： 社区最佳实践、常见工作流程、集成模式和生态系统理解。

步骤 6: 材料组织与结构设计

目标：

综合发现成连贯的思维模型
识别命令结构模式
按用户任务/工作流程组织内容
确定技能结构（工作流程基、命令基等）

参考： 加载 references/skill-templates.md 获取指导。

操作：

提取核心思维模型
- 什么是基本概念？（资源、操作、状态）
- 工具希望用户如何思考？
- 它使用什么抽象？
- 命令层次结构哲学是什么？
识别命令结构模式
- 扁平（单级命令）
- 名词-动词（资源-动作）
- 动词-名词（动作-资源）
- 混合（模式混合）
映射常见工作流程
- 5-10 个最常见的任务是什么？
- 开始工作流程是什么？
- 高级工作流程是什么？
- 哪些操作是危险/破坏性的？
按类别组织发现
- 核心概念和术语
- 命令参考（逻辑分组）
- 工作流程模式（编号以供参考）
- 配置和设置
- 集成模式
- 故障排除常见问题
选择技能结构（加载 references/skill-templates.md）
- 工作流程基：用于顺序、过程导向的工具
- 命令基：用于具有许多离散操作的工具
- 混合：结合模式（最常见）
决定内容放置
- skill.md：概述、核心概念、常见操作、何时加载参考
- references/<工具>_reference.md：完整的命令参考、所有工作流程、详细示例
- 额外参考文件（如果需要，例如用于 GraphQL API、专用功能）

输出： 按用户任务/工作流程组织的结构化内容大纲、清晰的思维模型摘要和技能结构计划。

步骤 7: 调用技能创建器技能

目标：

生成技能目录结构
创建 skill.md 和参考文档
打包技能以供分发
验证完整性

操作：

为技能创建器准备结构化摘要

将所有收集的材料组织成全面摘要，包括：
- CLI 概况
  - 名称、版本、目的
  - 命令结构模式
  - 开源状态和 GitHub URL
- 核心思维模型
  - 基本概念（2-5 个关键概念）
  - 用户应如何思考工具
  - 关键术语和定义
- 命令参考材料
  - 按类别/领域组织
  - 所有命令和语法及示例
  - 常见标志和选项
  - 命令关系
- 工作流程模式
  - 5-10 个常见工作流程
  - 分步带命令
  - 何时使用每个模式
- 集成点
  - 与之工作的其他工具
  - CI/CD 集成
  - 文件格式、协议
- 配置
  - 配置文件位置
  - 关键设置
  - 环境变量
- 故障排除
  - 常见问题和解决方案
  - 诊断命令
  - 错误模式

调用技能创建器技能

使用技能工具调用技能创建器：

技能: skill-creator

提示: 创建 <cli-tool-name> 的技能，使用以下结构和内容：

[提供步骤 1 的完整结构化摘要]

使用 [工作流程基/命令基/混合] 方法构建技能。

skill.md 应包括：
- 概述和何时使用此技能
- 核心概念：[列出关键概念]
- 常见操作组织按 [类别结构]
- 参考到 references/ 中的全面命令参考

创建 references/<工具>_reference.md 包含：
- 完整的思维模型解释
- 完整命令参考组织按 [组织方案]
- 工作流程模式 1-N
- 配置、集成和故障排除部分

遵循现有 CLI 技能的模式，如 gh、graphite 和 erk。

审查生成的技能
- 检查 skill.md 结构和清晰度
- 验证参考文档完整性
- 确保示例准确
- 如果可能，测试命令
如果需要，迭代
- 改进不清晰部分
- 添加缺失示例
- 改善组织
- 填补文档差距

打包技能（如果准备好分发）

python scripts/package_skill.py .claude/skills/<cli-tool-name>

输出： 完整的、打包的技能，可供使用和分发。

CLI 内省技术

帮助文本解析策略

渐进式帮助发现：

从顶级帮助开始，理解整体结构
枚举所有子命令
获取每个子命令的帮助
识别嵌套子命令
记录所有发现的命令

信息提取：

命令语法：使用行显示必需与可选
描述：每个命令/标志的作用
示例：从帮助文本复制逐字
默认值：注意标志的默认值
别名：注意短形式（例如，-h 对应 --help）

模式识别：

标志命名：单字母与长形式一致性
参数约定：<必需> 对 [可选]
子命令组织：按领域/资源分组
输出选项：--json、--plain、--format

加载 references/help-text-patterns.md 获取全面解析指导，包括正则表达式模式、格式变体和特殊情况。

GitHub 分析策略

快速侦察：

README.md 概述
文档目录结构
示例目录
贡献指南

深度分析：

命令实现文件（揭示结构）
测试文件（揭示使用模式）
问题（揭示痛点）
讨论（揭示社区问题）

框架检测：

不同的 CLI 框架以不同方式揭示结构：

Cobra (Go)：cmd/ 目录，每个命令文件
Click (Python)：函数的装饰器
Commander (Node.js)：流畅的 API 链
Clap (Rust)：结构定义或构建器模式

加载 references/help-text-patterns.md 部分“GitHub 仓库分析”获取详细代码阅读策略。

思维模型提取

在内容组织时问这些问题：

核心抽象：CLI 操作的主要“事物”是什么？
操作模式：它支持什么动词/动作？
状态管理：它跟踪状态吗？在哪里？
层次结构：概念之间有父子关系吗？
工作流程：常见的操作序列是什么？

查找明确的思维模型解释：

README “工作原理”部分
文档“概念”页面
架构图
设计理由文档

从命令结构中推断：

名词-动词表明资源导向模型
动词-名词表明动作导向模型
扁平结构表明简单、单目的工具
深度嵌套表明复杂领域模型

技能结构指导

选择正确的结构

加载 references/skill-templates.md 获取完整模板和示例。

工作流程基（使用时）：

清晰的顺序过程
大多数任务遵循相似步骤
开始焦点重要
示例：部署工具、CI/CD 工具

命令基（使用时）：

许多离散、独立的操作
用户需要命令参考
操作不遵循固定序列
示例：文件操作工具、实用程序

混合（使用时 - 最常见）：

常见工作流程和离散操作的混合
需要开始和全面参考
示例：gh、docker、kubectl、git

内容分发：skill.md 对 references/

skill.md 应包含：

触发技能使用的清晰描述
工具目的概述
核心概念（2-5 个关键概念）
何时加载参考
常见操作（高级指导）
工作流程决策指导
集成概述

references/<工具>_reference.md 应包含：

全面的思维模型
完整命令参考
所有工作流程模式（编号）
完整配置文档
详细故障排除
集成细节
高级使用

额外参考文件（当需要时）：

专用 API 的单独文件（例如，GraphQL）
大型架构参考的单独文件
广泛配置选项的单独文件

组织命令参考

最佳实践：

按领域/资源分组（不按字母顺序）
- 将相关命令分组在一起
- 匹配用户思维模型
- 示例：“拉取请求命令”、“问题命令”
按使用频率排序
- 最常见的操作在前
- 高级功能在后
- 匹配渐进学习
为每个命令包括：
- 目的（一句话）
- 带占位符的语法
- 关键标志（非穷举，链接到帮助）
- 2-3 个示例（简单到复杂）
- 相关命令
使用一致格式：
- 命令的代码块
- 标志参考的表格
- 编号的工作流程
- 清晰的节标题

编写有效的工作流程模式

模式结构：

### 模式 N: <描述性-名称>

**使用案例：** 何时使用此工作流程

**步骤：**

1. <步骤名称>
   <解释>
   ```bash
   <命令>

<下一步> …

完整示例：

# <场景>
<完整工作流程>

变体： 替代方法


**模式最佳实践：**

- 从最常见的工作流程开始
- 显示现实示例（非 foo/bar）
- 包括预期输出
- 注意副作用或状态变化
- 链接到相关模式
- 提及先决条件

加载 `references/skill-templates.md` 获取完整工作流程模式模板和示例。

## 与技能创建器集成

这个技能收集和组织 CLI 材料，然后委托给技能创建器进行实际技能生成。

**工作流程：**

1. **cli-skill-creator**：内省 CLI，提取模式，组织材料
2. **交接**：向技能创建器提供结构化摘要
3. **skill-creator**：生成技能文件，验证，打包

**结构化摘要格式：**

向技能创建器提供：
- CLI 概况（名称、版本、目的、结构模式）
- 核心思维模型（概念、术语）
- 组织好的命令参考材料
- 工作流程模式
- 集成点
- 配置和故障排除

**调用：**

使用技能工具：

技能: skill-creator

创建 <cli-tool> 的技能，使用以下材料： [完整结构化摘要]

使用 [工作流程基/命令基/混合] 结构。遵循 gh/graphite/erk 技能的模式。


**此方法的优势：**

- 将内省与生成分离
- 利用技能创建器的验证和打包
- 与其他技能保持一致
- 允许迭代改进

## 不同 CLI 类型的技巧

### 现代子命令 CLI（gh、docker、kubectl）

**关注：**
- 清晰的命令层次结构
- 工作流程模式（最重要）
- 与生态系统的集成
- 渐进示例

**结构：** 混合（工作流程 + 命令参考）

### 简单实用 CLI（jq、curl、grep）

**关注：**
- 核心功能解释
- 常见用例
- 管道和组合
- 标志组合

**结构：** 命令基或简单工作流程

### API-包装 CLI（aws、gcloud、heroku）

**关注：**
- API 映射
- 认证模式
- JSON 输出处理
- 速率限制

**结构：** 命令基带工作流程模式

### 传统 CLI（tar、find、sed）

**关注：**
- 现代使用模式（非所有历史选项）
- 常见陷阱
- 现代替代背景
- 安全警告

**结构：** 工作流程基（引导远离危险模式）

## 质量检查清单

在完成 CLI 技能之前：

- [ ] 捕获所有主要命令和子命令
- [ ] 记录 5-10 个常见工作流程模式
- [ ] 清晰提取核心思维模型
- [ ] 按用户任务组织（不按字母顺序）
- [ ] 包括现实示例和输出
- [ ] 注意集成点
- [ ] 记录常见陷阱
- [ ] 验证命令实际工作
- [ ] 注意记录的 CLI 版本
- [ ] 链接到权威文档
- [ ] 遵循 gh/graphite/erk 技能的模式
- [ ] skill.md 简洁（<300 行）
- [ ] references/ 包含全面细节

## 常见陷阱

**避免：**

1. **字母顺序组织** - 改为按任务/领域组织
2. **穷举标志文档** - 链接到帮助，仅显示常见标志
3. **缺失思维模型** - 始终解释如何思考工具
4. **无工作流程模式** - 用户需要任务导向指导
5. **未测试示例** - 验证所有命令实际工作
6. **版本无关** - 注意记录的版本
7. **缺失集成点** - 记录与其他工具的工作方式
8. **技能.md 描述差** - 具体说明何时使用技能

## 资源

### references/

这个技能包括两个全面参考文档：

- **help-text-patterns.md** - 解析帮助文本、手册页和 GitHub 仓库的实践指导。在内容组织 CLI 工具时加载，以获取全面信息提取。

- **skill-templates.md** - 技能结构、命令参考、工作流程和部分的可重用模板。在组织材料和构建技能文档时加载。

**加载策略：**

- 在内省步骤（步骤 2-4）期间加载 `help-text-patterns.md`
- 在组织和结构设计步骤（步骤 6）期间加载 `skill-templates.md`

这些参考确保一致、全面的 CLI 技能创建，遵循现代最佳实践。