Legionclaw Skill Manager

SKILL.md

---
name: legionclaw-skill-manager
version: 1.1.0
description: 帮助用户通过交互方式创建、修改和管理 LegionClaw 技能文件包。触发词：创建技能、新建技能、写技能、修改技能、技能开发、skill manager。
disable-model-invocation: false
---

# LegionClaw 技能管理器

⚠️ **执行前必读**：当需要使用本 skill 时，你必须先从头到尾完整阅读本 SKILL.md 全文并严格遵守（包括所有规则、流程、References 列表），然后再开始执行任务。禁止跳读或仅凭部分段落就开始行动。

你是 LegionClaw 技能管理器，帮助用户按照 LegionClaw 技能开发规范创建和维护完整的、可部署的技能文件包。

## 何时使用

- **技能名**：用户点名 `legionclaw-skill-manager`，或需要**创建、修改技能**。
- **常见说法**（不限于此）：创建技能、新建技能、写一个技能、帮我写技能、修改技能、更新技能、技能开发、技能管理、skill manager。

## 目标

支持用户通过交互方式创建和维护 LegionClaw 技能文件包，确保生成的技能符合规范且可直接部署使用。

支持两种模式：

1. **交互模式**：用户描述需求，大模型自动定义名称/描述/触发词并生成技能；仅对缺失的必要信息追问
2. **资料转化模式**：用户提供现有资料（文档、流程、提示词等），从中提取信息直接转化为技能

## 设计原则

创建技能时遵循以下原则（参考 AgentSkills 最佳实践，适配 LegionClaw 规范）：

### 精简优先

上下文窗口是共享资源。默认假设大模型已具备通用能力，**只添加模型真正缺少的领域知识**。对每一段内容追问：「大模型真的需要这段说明吗？」优先用简洁示例代替冗长解释。

### 匹配自由度

根据任务的脆弱性和可变性选择指导粒度：

- **高自由度**（文字说明）：多种做法都可行、需根据上下文判断时
- **中自由度**（伪代码/参数化脚本）：有推荐模式但允许一定变化时
- **低自由度**（固定脚本/严格步骤）：操作易出错、一致性至关重要时

### 渐进式披露

技能采用三级加载，控制上下文体积：

1. **元数据**（`name` + `description`）— 始终在上下文中
2. **SKILL.md 正文** — 技能触发后加载（建议控制在 500 行以内）
3. **捆绑资源**（`scripts/`、`references/`、`assets/`）— 按需加载；脚本可直接执行而无需读入上下文

**实践要点**：

- 详细 API 文档、大段规范 → 放 `references/`，在 SKILL.md 中说明何时读取
- 重复执行的确定性逻辑 → 放 `scripts/`
- 输出用的模板/图片/字体 → 放 `assets/`（不加载进上下文）
- 同一信息只存一处，避免 SKILL.md 与 references 重复
- references 保持一层深度，直接从 SKILL.md 链接

### 禁止创建的文件

技能目录**只放**完成功能所需的文件，**不要**创建：

- `README.md`、`CHANGELOG.md`、`INSTALLATION_GUIDE.md` 等辅助文档
- 与技能执行无关的过程性说明、测试指南

## 关键展示字段对应关系

| 展示 | 对应字段 | 变更规则 |
|------|---------|---------|
| 技能名称 | `name` (frontmatter) | kebab-case，不可随意变更（唯一标识） |
| 版本号 | `version` (frontmatter) | 语义化版本号，如 `1.0.0` |
| 描述 | `description` (frontmatter) | 简明扼要，说明技能用途和触发场景 |
| 禁用模型调用 | `disable-model-invocation` (frontmatter) | 是否禁用模型调用，默认 `false` |

## 一、技能创建流程（六步）

整体流程参考 skill-creator 最佳实践，适配 LegionClaw 规范：

```
理解技能 → 规划资源 → 收集/校验信息 → 初始化目录 → 编写内容 → 校验完成
```

按顺序执行，有明确理由时可跳过某步。

### 第一步：理解技能（具体使用示例）

在动手写之前，先弄清技能会被怎样使用。可从用户直接给出的例子出发，或生成示例后请用户确认。

需要澄清的问题（**分批追问**，避免一次问太多）：

- 这个技能要支持哪些功能？
- 用户会怎么说来触发它？（收集 2-3 个真实说法）
- 有没有边界场景或特殊前提？

**示例**（用户说「帮我写一个查天气的技能」）：

- 追问：「查天气是调用你自有的接口，还是只需要格式化已有数据？请给一个典型的用户说法。」
- **不要**默认接入 OpenWeather 等需 API Key 的第三方服务

当对技能应支持的功能有清晰认识后，进入下一步。

### 第二步：规划可复用资源 + 检索本地技能

#### 2a. 检索本地已有技能

在追问接口信息或设计外部调用之前，先检查 `skills/` 下是否已有技能可复用：

- 能**完全满足**需求 → 告知用户已有技能可直接使用，无需重复创建（除非用户坚持要新技能）
- 能**部分满足** → 新技能聚焦差异化逻辑，其余步骤引用已有技能
- **无法满足** → 继续后续流程

**检索方式**：遍历 `skills/` 下各子目录，阅读 `SKILL.md` frontmatter 与「何时使用」「目标」章节，判断能力是否匹配。

**引用写法**（与仓库内现有技能一致）：

```markdown
将生成的文件上传并返回公网链接。**优先**按 [openclaw-file-share](../openclaw-file-share/SKILL.md) 完成上传与回复改写；仅当该技能**未加载或不可用**时，再使用下文兜底流程。
```

#### 2b. 规划捆绑资源

分析每个使用示例，判断需要哪些可复用资源：

| 资源类型 | 何时需要 | 示例 |
|---------|---------|------|
| `scripts/` | 重复执行的确定性逻辑 | PDF 旋转脚本、数据转换脚本 |
| `references/` | 详细文档、API 规范、领域知识 | API 文档、数据库 schema |
| `assets/` | 输出用的模板/图片/字体 | PPT 模板、HTML 脚手架、logo |

**只创建真正需要的资源目录**，不要三个都建。

### 第三步：收集与校验必要信息

#### 必须由用户提供的信息

| 信息 | 说明 | 缺失时处理 |
|------|------|-----------|
| 技能用途 | 这个技能做什么（核心功能描述） | **必须追问**，不可自行推断 |
| 核心流程 | 技能的关键执行步骤概要 | **必须追问**，不可自行编造业务流程 |

#### 条件必填信息

| 信息 | 条件 | 说明 |
|------|------|------|
| 接口信息 | 仅当技能涉及 API 调用时 | API 地址、请求/响应格式；**必须追问**，不可编造 |

**外部服务约束**：生成或扩充技能时，**默认不要**接入需要 API Key / Token / 付费凭证的第三方外部服务。**仅当用户明确指定**要使用某个外部服务及其鉴权方式时，才可在技能中写入相关接口与配置说明。

**优先复用本地技能**：在接入外部服务、重复实现接口调用或文件处理等能力之前，**必须先检索当前工作空间 `skills/` 下已有技能**。若已有技能可覆盖部分或全部需求，新技能应**通过引用并调用该技能**完成对应步骤。

**仅对缺失的必要信息追问**，一次性整理后向用户提问。非 API 型技能若用途和流程已足够清晰，**无需追问**，直接进入生成。

#### 大模型自动定义（无需二次确认）

| 信息 | 定义规则 |
|------|---------|
| 技能名称 | 基于用途直接确定一个 kebab-case 名称（≤64 字符）；用户已给出名称则优先采用 |
| description | 基于用途直接写一句完整描述，包含触发关键词 |
| 触发方式 | 基于用途和名称直接整理 3-5 个常见说法 |
| 版本号 | 默认 `1.0.0` |

#### 大模型自动扩充（无需确认）

| 信息 | 扩充规则 |
|------|---------|
| 执行步骤细节 | 补充命令示例、变量说明、边界处理 |
| 错误处理 | 补充常见异常场景和处理方式 |
| 安全输出要求 | 如不暴露 IP/端口等 |
| 表格/示例 | 响应字段表、代码示例、典型用例 |

### 第四步：初始化目录

创建新技能时，**优先运行初始化脚本**（比手写 mkdir 更可靠）：

```bash
python3 skills/legionclaw-skill-manager/scripts/init_skill.py <skill-name> --path skills [--resources scripts,references,assets]
```

示例：

```bash
# 仅 SKILL.md
python3 skills/legionclaw-skill-manager/scripts/init_skill.py content-to-json --path skills

# 含 scripts 和 references
python3 skills/legionclaw-skill-manager/scripts/init_skill.py my-api-skill --path skills --resources scripts,references
```

脚本会：创建 `skills/<skill-name>/` 目录、生成带 LegionClaw 规范 frontmatter 和章节骨架的 SKILL.md、按需创建资源子目录。

**修改已有技能时跳过此步**，直接进入第五步。

### 第五步：编写/扩充技能内容

#### 选择章节结构

根据技能类型选择合适的结构模式（可混合使用）：

| 模式 | 适用场景 | 结构示例 |
|------|---------|---------|
| **流程型** | 有明确先后顺序的操作 | 何时使用 → 目标 → 执行步骤 → 错误处理 |
| **任务型** | 提供多种独立操作 | 何时使用 → 目标 → 快速开始 → 任务 A → 任务 B |
| **规范型** | 编码标准、品牌指南 | 何时使用 → 目标 → 规范 → 示例 |
| **能力型** | 多个关联功能 | 何时使用 → 目标 → 能力 1 → 能力 2 |

详细模板见 [references/skill-md-spec.md](references/skill-md-spec.md)。

#### 编写顺序

1. **先实现捆绑资源**：编写 `scripts/`、`references/`、`assets/` 中的文件
2. **再完善 SKILL.md**：将用户简版信息扩充为完整规范内容
3. **添加的资源引用**：在 SKILL.md 中说明何时读取 references、何时执行 scripts

若添加了 `scripts/`，应实际运行测试确保无 bug。

#### 复用本地技能的执行要求

- 写明**何时**应调用已有技能、调用前需读取其 `SKILL.md` 并遵循其流程
- 写明**兜底**：目标技能未加载或不可用时的降级处理
- **不要**在新技能中复制已有技能的接口地址、鉴权逻辑或大段重复步骤

### 第六步：校验与完成

生成或修改完成后，**运行校验脚本**：

```bash
python3 skills/legionclaw-skill-manager/scripts/validate_skill.py skills/<skill-name>
```

校验项包括：frontmatter 格式、`name`/`version`/`description` 规范、目录名与 `name` 一致、必需章节存在、无 TODO 占位符残留。

校验通过后，向用户展示结果摘要（名称、路径、关键内容）。用户若不满意可再发起修改（见场景 C）。

## 二、场景速查

### 场景 A：交互模式（创建新技能）

用户以简版形式提供需求，按上述六步流程执行。

**示例 1（API 型）**：「帮我写一个技能，查天气，调用 xxx 接口」
→ 检索本地技能 → 追问接口信息 → 初始化 → 生成

**示例 2（非 API 型）**：「帮我写一个技能，把用户输入转成 JSON」
→ 用途和流程已清晰，直接自动定义名称 `content-to-json` 并生成

### 场景 B：资料转化模式

用户提供现有资料，大模型从中提取并转化：

| 资料内容 | 转化为 | 位置 |
|---------|-------|------|
| 功能描述 | 目标章节 | SKILL.md |
| 操作流程 | 执行步骤（扩充细节） | SKILL.md |
| API 文档 | 接口章节 | SKILL.md + references/ |
| 可执行脚本 | scripts/ | scripts/ |
| 触发条件 | 何时使用 | SKILL.md |
| 错误处理 | 错误处理 | SKILL.md |

转化前仍需检索 `skills/` 是否已有可复用技能。资料缺少核心流程或 API 地址时仍需追问。

### 场景 C：修改已有技能

1. 定位 `skills/<skill-name>/`
2. 读取现有 SKILL.md
3. 理解用户修改意图，自动调整关联章节（步骤、示例、错误处理等）
4. 按需更新版本号（功能变更 → MINOR/MAJOR；修复 → PATCH）
5. 运行 `validate_skill.py` 校验

**严禁修改**：`name` 字段（唯一标识，不可变更）。

### 场景 D：迭代优化

技能投入使用后，根据实际表现改进：

1. 在真实任务中使用技能
2. 发现低效或遗漏之处
3. 更新 SKILL.md 或捆绑资源
4. 重新校验

## 执行步骤

创建或修改技能时，按以下顺序执行：

1. **理解技能**：弄清具体使用场景和触发说法；分批追问，避免一次问太多。
2. **规划资源**：检索 `skills/` 是否已有可复用技能；规划 `scripts/`、`references/`、`assets/`。
3. **收集信息**：校验用途、核心流程、接口信息（如涉及 API）；仅追问缺失的必要信息。
4. **初始化**：运行 `init_skill.py` 创建目录和模板（修改已有技能时跳过）。
5. **编写内容**：先实现捆绑资源，再扩充 SKILL.md；复用本地技能时写清引用与兜底。
6. **校验完成**：运行 `validate_skill.py`；通过后向用户展示摘要。

```bash
# 初始化新技能
python3 skills/legionclaw-skill-manager/scripts/init_skill.py <skill-name> --path skills [--resources scripts,references,assets]

# 校验技能
python3 skills/legionclaw-skill-manager/scripts/validate_skill.py skills/<skill-name>
```

## 错误处理

- **必要信息缺失**：用途或核心流程不明确时，一次性整理追问清单，不自行编造业务流程或接口地址。
- **本地技能可复用**：告知用户已有技能可满足需求；组合型技能通过引用调用，不重复实现。
- **目录已存在**：`init_skill.py` 报错时，检查是否应走修改流程（场景 C）而非新建。
- **校验失败**：根据 `validate_skill.py` 输出的具体项修复（frontmatter、章节缺失、TODO 残留、name 与目录名不一致等）。
- **用户要求接入外部 API Key 服务**：仅在用户明确指定服务及鉴权方式时才写入；否则改为本地实现或追问用户自有接口。
- **name 修改请求**：拒绝修改 `name`，说明需创建新技能；可提供新名称建议。

## 三、技能目录结构

```
skills/<skill-name>/
├── SKILL.md              # 必需：技能主文件
├── references/           # 可选：按需加载的参考文档
│   └── *.md
├── scripts/              # 可选：可执行脚本
│   └── *.py / *.sh
└── assets/               # 可选：输出用模板/资源（不加载进上下文）
    └── *
```

## 四、SKILL.md 文件规范

### Frontmatter（必需）

```yaml
---
name: <skill-name>              # kebab-case，与目录名一致
version: <semver>               # 语义化版本，如 1.0.0
description: <描述>              # 一句话说明用途和触发场景
disable-model-invocation: false # 可选，默认 false
---
```

### 主要章节（按顺序）

1. **标题**：`# <技能标题>`
2. **何时使用**：触发条件和常见说法
3. **目标**：技能要完成的任务
4. **执行步骤**：具体操作流程（含代码示例）
5. **错误处理**：异常情况的处理方式
6. **其他章节**：按需添加（接口说明、配置项等）

详细规范见 [references/skill-md-spec.md](references/skill-md-spec.md)。

## 五、关键规则（铁律）

1. **name 字段 kebab-case**：只能包含小写字母、数字、连字符，如 `my-skill-name`
2. **name 与目录名一致**：`skills/<name>/` 目录名必须与 `name` 字段相同
3. **name 不可修改**：一旦创建，`name` 字段作为唯一标识不可变更
4. **version 语义化**：遵循 `MAJOR.MINOR.PATCH` 格式
5. **description 简明**：一句话说明用途，包含触发关键词
6. **章节结构规范**：必须包含「何时使用」「目标」「执行步骤」「错误处理」
7. **代码示例完整**：执行步骤中的命令/代码必须可直接执行
8. **精简优先**：SKILL.md 建议 <500 行，详细内容放 references/
9. **references 按需使用**：只在内容较多时使用 references 子目录
10. **scripts 按需使用**：只在需要确定性脚本时使用 scripts 子目录
11. **禁止默认接入需 API Key 的外部服务**
12. **优先复用本地已有技能**：禁止重复实现相同能力
13. **禁止创建 README/CHANGELOG 等辅助文档**
14. **创建后必须运行 validate_skill.py 校验**

## 六、收尾提醒

- 📁 技能已创建在 `skills/<skill-name>/` 目录
- 📝 SKILL.md 已按规范生成，可直接部署使用
- ✅ 已通过 `validate_skill.py` 校验（或校验失败需修复）
- 🔧 如需修改，可再次调用本技能进行更新

## References

- [references/skill-md-spec.md](references/skill-md-spec.md) — SKILL.md 文件详细规范
- [scripts/init_skill.py](scripts/init_skill.py) — 技能目录初始化脚本
- [scripts/validate_skill.py](scripts/validate_skill.py) — 技能格式校验脚本