Legionclaw Skill Manager

帮助用户通过交互方式创建、修改和管理 LegionClaw 技能文件包。触发词：创建技能、新建技能、写技能、修改技能、技能开发、skill manager。

LegionSpace-Hackathon@legionspace-hackathon

Install

openclaw skills install @legionspace-hackathon/legionclaw-skill-manager

LegionClaw 技能管理器

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

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

何时使用

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

目标

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

支持两种模式：

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

设计原则

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

精简优先

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

匹配自由度

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

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

渐进式披露

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

元数据（name + description）— 始终在上下文中
SKILL.md 正文 — 技能触发后加载（建议控制在 500 行以内）
捆绑资源（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 规范：

text

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

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

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

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

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

这个技能要支持哪些功能？
用户会怎么说来触发它？（收集 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。

编写顺序

先实现捆绑资源：编写 scripts/、references/、assets/ 中的文件
再完善 SKILL.md：将用户简版信息扩充为完整规范内容
添加的资源引用：在 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：修改已有技能

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

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

场景 D：迭代优化

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

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

执行步骤

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

理解技能：弄清具体使用场景和触发说法；分批追问，避免一次问太多。
规划资源：检索 skills/ 是否已有可复用技能；规划 scripts/、references/、assets/。
收集信息：校验用途、核心流程、接口信息（如涉及 API）；仅追问缺失的必要信息。
初始化：运行 init_skill.py 创建目录和模板（修改已有技能时跳过）。
编写内容：先实现捆绑资源，再扩充 SKILL.md；复用本地技能时写清引用与兜底。
校验完成：运行 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，说明需创建新技能；可提供新名称建议。

三、技能目录结构

text

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
---

主要章节（按顺序）

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

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

五、关键规则（铁律）

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

六、收尾提醒

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

References

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