SKILL.md 技能定义方法论

学习目标

• 理解 SKILL.md 作为 Agent 可发现、可加载、可执行技能的标准格式
• 掌握从 Click 装饰器自动提取元数据的 skill_generator.py 模式
• 应用 Canonical vs Compatibility 双路径分发策略
• 利用 REPL Banner 与 Skill 路径联动实现启动时技能发现

前置知识

本章涉及 Skill 系统的通用设计，建议先阅读：

• Skill 渐进式知识管理

下文假设你已理解上述概念，直接聚焦 CLI-Anything 的 SKILL.md 生成和分发机制。

---

项目实践

SKILL.md 在 CLI-Anything 中的角色

CLI-Anything 为每个生成的 CLI 自动产出 SKILL.md 文件（Phase 6.5），使 CLI 在 npx skills 生态中可被发现和使用。SKILL.md 是 CLI 的”自描述名片”——AI Agent 无需人类指导即可了解该 CLI 的能力。

skill_generator.py 自动提取模式

skill_generator.py（~500 行）展示了从结构化代码自动生成技能文档的完整模式：

提取的关键信息：

来源文件	提取内容
README.md	软件简介、系统包依赖（如 apt install gimp）
setup.py	版本号、包名、入口点
*_cli.py	Click 命令树（通过 AST 解析 @click.command 装饰器）
命令 help 文本	每个命令组的描述和子命令列表

生成的 SkillMetadata 数据类包含：

• skill_name / skill_description：YAML frontmatter 触发元数据
• software_name / version：版本信息
• command_groups：命令分组（CommandGroup 列表，每个含若干 CommandInfo）
• examples：使用示例（Example 列表，含标题、描述、代码块）

双路径分发

skills/cli-anything-<software>/SKILL.md        ← Canonical（repo-root）
cli_anything/<software>/skills/SKILL.md        ← Compatibility（pip 安装后）

Canonical 路径：在 monorepo 中的统一位置。npx skills add HKUDS/CLI-Anything --list 从这里发现所有技能。

Compatibility 路径：随 pip 包分发的拷贝。setup.py 配置：

package_data={
    "cli_anything.<software>": ["skills/*.md"],
},

ReplSkin 的路径选择逻辑（源码验证 repl_skin.py）：

1. 检查 repo-root canonical path（skills/cli-anything-<software>/SKILL.md）
2. 若不存在，回退到 packaged path（cli_anything/<software>/skills/SKILL.md）
3. REPL Banner 中显示找到的路径，Agent 启动时即可阅读

REPL Banner 与 Skill 路径联动

CLI-Anything 的 REPL 启动时显示 SKILL.md 的绝对路径：

╔══════════════════════════════════════╗
║     cli-anything-gimp v1.0.0        ║
║     GIMP CLI for AI Agents          ║
╚══════════════════════════════════════╝
SKILL: /home/user/CLI-Anything/skills/cli-anything-gimp/SKILL.md

这是技能发现与运行时 UI 的集成——不仅仅是触发时加载，而是在启动时就告知 Agent”这里有一份详细的能力文档，你可以阅读”。

SKILL.md 内容结构

生成的 SKILL.md 包含：

---
name: "cli-anything-gimp"
description: "GIMP image editor CLI for AI agents — project management, layers, filters, and export"
---

Markdown 体：

• 安装前提：系统包（apt install gimp）、pip 安装 CLI
• 命令语法：所有命令组的树形结构
• 使用示例：常见工作流（创建项目 → 添加图层 → 应用滤镜 → 导出）
• Agent 指南：--json 使用、错误处理、程序化调用

npx skills 生态集成

所有 Harness 的 SKILL.md 统一在 skills/ 目录下，使 monorepo 可直接被 npx skills 消费：

npx skills add HKUDS/CLI-Anything --list          # 列出所有 40+ CLI 技能
npx skills add HKUDS/CLI-Anything --skill cli-anything-gimp -g -y  # 安装 GIMP 技能
npx skills add HKUDS/CLI-Anything --skill cli-hub-meta-skill -g -y  # 安装 CLI-Hub 元技能

cli-hub-meta-skill 是一个特殊的元技能——安装后 Agent 可以自主在 CLI-Hub 中浏览、搜索、安装 CLI，无需人类介入。

---

问题与规避

问题	规避策略
SKILL.md 与实际 CLI 不同步	Phase 6.5 在代码实现后自动生成，确保同步
点击装饰器变更未反映到 SKILL.md	skill_generator.py 从实际源码 AST 提取，非手动维护
pip 安装后找不到 SKILL.md	双路径分发 + ReplSkin 回退逻辑
技能描述太宽泛导致误触发	从实际命令提取精确描述，包含软件名和核心能力

设计取舍

自动生成 vs 手动编写 SKILL.md

选择：从 Click 装饰器和 README 自动生成。

原因：

• 40+ CLI，手动维护不可持续
• 自动生成保证与实际代码一致
• 模板化结构（命令组、示例）适合程序提取
• 可定制：通过 templates/SKILL.md.template Jinja2 模板调整格式

代价：自动生成的内容可能缺少人工撰写的 nuanced 指导。因此 CLI-Anything 保留了”Refine”机制，可针对生成的内容做针对性改进。

Canonical vs Compatibility 双路径

选择：维护两份 SKILL.md 拷贝而非仅一份。

原因：

• npx skills 需要 monorepo 中的规范位置（skills/ 目录）
• pip 安装的用户需要随包携带技能文件
• 两者安装路径不同，无法用单一路径满足

代价：需要确保两份拷贝内容一致。skill_generator.py 同时写入两个路径，消除不一致可能。

参考来源

• 源码验证：skill_generator.py（~500 行，CLI-Anything commit 7862c92）
• 源码验证：HARNESS.md Phase 6.5 章节
• npx skills CLI — 社区技能管理工具