skill-creator-flagos

Skill Creator

用于在 FlagOS skills 仓库中创建、改进和验证 skills 的元技能。

概览

本 skill 将指导你完成 skill 开发的完整生命周期：

1. 创建 — 从模板搭建新的 skill，访谈用户，编写 SKILL.md
2. 改进 — 分析现有 skill，找出不足，并使用测试用例迭代
3. 验证 — 检查结构、frontmatter、引用和约定是否合规

用法

/skill-creator-flagos                       # Interactive — asks what you want to do
/skill-creator-flagosmy-new-skill --init    # Scaffold a new skill
/skill-creator-flagosmy-skill --validate    # Validate an existing skill
/skill-creator-flagosmy-skill --eval        # Run test prompts against a skill

执行

步骤 0：解析参数并确定模式

从用户输入中提取：

• {{skill_name}} — 可选的 skill 名称（连字符格式）
• {{mode}} — 以下模式之一：create、improve、validate、eval 或 interactive（默认）

如果未指定模式，请询问用户：

你想做什么？

1. 从头创建一个新的 skill
2. 改进现有 skill
3. 验证 skill 的结构和约定
4. 针对 skill 运行测试用例

-> 告知用户：确认模式和 skill 名称。

---

模式 1：创建新的 Skill

步骤 1：了解意图

首先了解用户想要构建什么。如果当前对话中已包含用户希望记录的工作流（例如“将此转化为 skill”），请先从对话历史中提取答案。

需要澄清的关键问题：

1. 这个 skill 应支持 Agent 执行什么操作？
2. 应在什么情况下触发？（用户用语、上下文、文件类型）
3. 预期输出或最终状态是什么？
4. 这个 skill 是否需要脚本、参考文档或资源文件？
5. 这个 skill 需要访问哪些工具？

根据用户调整沟通风格——不要假设用户熟悉编程术语。留意上下文线索。

-> 告知用户：总结已了解的意图，并在继续之前请用户确认。

步骤 2：初始化 skill 目录

运行 init 脚本来搭建 skill：

python3 {{skill_root}}/scripts/init_skill.py {{skill_name}} --path {{skills_dir}} [--resources scripts,references,assets]

其中：

• {{skill_root}} = 此 skill-creator-flagos 目录的绝对路径
• {{skills_dir}} = skills/ 目录的路径（通常是 {{skill_root}} 的父目录）

该脚本会创建目录，其中包含 SKILL.md 模板、LICENSE.txt 和可选的子目录。

-> 告知用户：展示创建的目录结构。

步骤 3：编写 SKILL.md

根据用户访谈内容，填写以下组件：

Frontmatter（YAML）

字段	必填	指南
name	是	小写字母加连字符，必须与目录名称一致，最多 64 个字符
description	是	用 1-2 句话说明功能及触发时机。描述要具体且略带“积极引导”——宁可触发得太频繁，也不要太少
argument-hint	推荐	展示预期参数
user-invokable	推荐	如果可通过 /skill-name 调用，则为 true
compatibility	可选	环境要求
metadata	推荐	版本、作者、类别、标签
allowed-tools	推荐	带模式的空格分隔工具列表

正文（Markdown）

遵循 references/writing-guide.md 中记录的结构。至少包括：

• 概览 — 解决什么问题，以及何时激活
• 先决条件 — 环境要求
• 执行步骤 — 使用编号步骤，并添加 **-> 告知用户** 进度标记
• 示例 — 至少 2-3 个真实的用法示例
• 故障排除 — 常见问题和解决方法

阅读 references/writing-guide.md，了解渐进式披露、输出格式、领域组织和写作风格的详细模式。

步骤 4：添加辅助资源

根据技能的需求，创建：

• scripts/ — 用于确定性／重复性任务的可执行代码
• references/ — 按需加载到上下文中的详细文档
• assets/ — 输出中使用的文件（模板、图标等）

规则：

• 每个脚本和参考文件都必须在 SKILL.md 中附有使用说明
• 脚本应具有执行权限（chmod +x）
• SKILL.md 应少于 500 行；将详细内容移至 references/
• 对于超过 300 行的参考文件，请添加目录

步骤 5：验证

运行验证，检查是否符合规范：

python3 {{repo_root}}/scripts/validate_skills.py {{skills_dir}}/{{skill_name}}

修复报告的所有问题。请参阅下方的“故障排除”部分。

-> 告知用户：报告验证结果。如果验证失败，请诊断并修复问题。

步骤 6：编写 README 文件

按照现有技能的模式，创建 README.md（英文），并可选创建 README_zh.md（中文）。README 应涵盖：

• 概览／问题说明
• 使用说明
• 目录结构
• 文件说明
• 示例
• 安装说明

-> 告知用户：技能创建完成。展示最终目录树和摘要。

---

模式 2：改进现有技能

步骤 1：分析当前技能

阅读现有的 SKILL.md 和所有辅助文件。找出：

• 描述中不清晰或缺失的触发条件
• 缺失的示例或边缘情况
• 缺少进度报告（**-> 告知用户**）的步骤
• 过长、应拆分到参考文件中的 SKILL.md
• 缺失的故障排除条目
• 未附说明的脚本

-> 告知用户：展示发现的问题和拟议的改进。

步骤 2：起草测试提示词

创建 2-3 个真实的测试提示词，模拟真实用户会说的话。与用户分享并征求确认。

保存到 evals/evals.json：

{
  "skill_name": "{{skill_name}}",
  "evals": [
    {
      "id": 1,
      "prompt": "User's task prompt",
      "expected_output": "Description of expected result",
      "assertions": ["The output includes X", "Step Y was executed"]
    }
  ]
}

完整架构请参阅 references/schemas.md。

步骤 3：迭代

每轮执行以下操作：

1. 改进 SKILL.md 和辅助文件
2. 重新运行验证
3. 根据测试提示词进行检查（在脑海中模拟或启动测试运行）
4. 收集用户反馈
5. 重复以上步骤，直到满意

-> 告知用户：报告每轮所做的更改。

---

模式 3：验证

运行验证脚本：

python3 {{repo_root}}/scripts/validate_skills.py {{skills_dir}}/{{skill_name}}

脚本会检查：

• SKILL.md 是否存在且具有有效的 YAML 前置元数据
• 是否包含必需字段（name、description）
• name 是否与目录名称匹配并符合命名规范
• description 长度是否在限制范围内
• 正文内容是否充足（>100 个字符）
• scripts/ 和 references/ 中引用的文件是否确实存在
• 脚本是否具有执行权限
• 是否存在硬编码路径或凭据

-> 告知用户：按严重程度（错误／警告）报告所有发现的问题。

---

模式 4：运行评测

如果存在 evals/evals.json，则使用该技能运行测试提示词：

python3 {{skill_root}}/scripts/run_eval.py {{skills_dir}}/{{skill_name}}

这会生成一份报告，显示每个测试用例中哪些断言通过或失败。

-> 告知用户：展示结果并提出改进建议。

---

占位符

占位符	推导方式
{{skill_name}}	根据用户输入规范化为连字符格式
{{skill_root}}	此 skill-creator-flagos 目录的绝对路径
{{repo_root}}	仓库根目录的绝对路径（skills/ 的父目录）
{{skills_dir}}	包含所有技能的 skills/ 目录路径

示例

示例 1：从头创建新技能

User says: "/skill-creator-flagospreflight-check --init"
Actions:
  1. Parse → skill_name=preflight-check, mode=create
  2. Interview user about what preflight-check should do
  3. Run init_skill.py to scaffold directory
  4. Write SKILL.md with deployment verification workflow
  5. Add scripts/check_gpu.sh, scripts/check_env.py
  6. Validate and fix any issues
  7. Write README.md
Result: Complete preflight-check skill ready for use

示例 2：改进现有技能

User says: "improve model-migrate-flagos, the description could be better"
Actions:
  1. Read existing SKILL.md and all references
  2. Analyze description — find it's too long and not trigger-friendly
  3. Propose a more concise, trigger-optimized description
  4. Create test prompts to verify triggering
  5. Apply changes, validate
Result: Improved skill with better triggering accuracy

示例 3：验证所有技能

User says: "/skill-creator-flagos--validate"
Actions:
  1. No skill_name provided → validate all skills in skills/
  2. Run validate_skill.py on each skill directory
  3. Report consolidated results
Result: Validation report for all skills

示例 4：将对话工作流转化为技能

User says: "turn what we just did into a skill"
Actions:
  1. Analyze conversation history for the workflow performed
  2. Extract: tools used, sequence of steps, corrections made
  3. Interview user to fill gaps
  4. Scaffold and write the skill
Result: New skill capturing the conversation workflow

故障排除

问题	原因	修复方法
name does not match directory name	Frontmatter 中的 name 与文件夹名称不同	确保两者完全一致
description exceeds 1024 chars	描述过长	将详细信息移至正文；描述控制在 1-2 句话
SKILL.md body is too short	指令不足	添加概述、步骤、示例和故障排除内容
Missing required field	Frontmatter 中缺少 name 或 description	添加缺失的字段
name must be lowercase+hyphens	名称中包含无效字符	仅使用 a-z、0-9 和 -
技能未触发	描述范围过窄或含糊	让描述更具体，并稍微积极地强调触发条件
找不到引用的文件	SKILL.md 中列出了脚本或参考文件，但磁盘上不存在	创建该文件或移除相应引用