Legionclaw Skill Manager

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 等辅助文档
• 与技能执行无关的过程性说明、测试指南

关键展示字段对应关系

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

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

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

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

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

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

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

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

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

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

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

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

2a. 检索本地已有技能

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

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

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

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

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

2b. 规划捆绑资源

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

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

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

必须由用户提供的信息

条件必填信息

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

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

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

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

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

第四步：初始化目录

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

python3 skills/legionclaw-skill-manager/scripts/init_skill.py  --path skills [--resources scripts,references,assets]

示例：

# 仅 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// 目录、生成带 LegionClaw 规范 frontmatter 和章节骨架的 SKILL.md、按需创建资源子目录。

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

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

选择章节结构

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

详细模板见 references/skill-md-spec.md。

编写顺序

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

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

复用本地技能的执行要求

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

第六步：校验与完成

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

python3 skills/legionclaw-skill-manager/scripts/validate_skill.py skills/

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

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

二、场景速查

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

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

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

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

场景 B：资料转化模式

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

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

场景 C：修改已有技能

1. 定位 skills//
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；通过后向用户展示摘要。

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

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

错误处理

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

三、技能目录结构

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

四、SKILL.md 文件规范

Frontmatter（必需）

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

主要章节（按顺序）

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

详细规范见 references/skill-md-spec.md。

五、关键规则（铁律）

1. name 字段 kebab-case：只能包含小写字母、数字、连字符，如 my-skill-name
2. name 与目录名一致：skills// 目录名必须与 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.md 已按规范生成，可直接部署使用
• ✅ 已通过 validate_skill.py 校验（或校验失败需修复）
• 🔧 如需修改，可再次调用本技能进行更新

References

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