激活契约
当需要为Pi或其他智能体运行时创建或更新可复用的AI技能时，使用此技能。
在以下情况创建技能：
- 工作流或约定在多个会话中重复使用；
- 通用智能体行为需要项目特定的约束；
- 决策树有助于智能体安全选择；
- 示例、模板或参考能使未来的执行更可靠。
不要为一次性任务、通用文档或属于代码/测试的规则创建技能。
硬性规则
- 遵循
docs/skill-style-guide.md作为技能结构和风格的规范来源。 - 技能是LLM运行时的契约，而非面向人类的文档。
- 保持
SKILL.md简洁：目标180–450个标记，最多1000个。 - 使用祈使句指令和具体门控；避免教程和背景描述。
- 前置数据中的
description必须为一行并且符合YAML安全格式，且首先包含触发词。 - 不要添加
Keywords部分；将必要的触发词放在description中。 - 将模板、模式（schema）和生成的示例放在
assets/目录下。 - 将长篇解释或本地文档链接放在
references/目录下。 - 更改项目技能后，如果可用，使用
/skill-registry:refresh刷新注册表。
决策门
| 需求 | 操作 |
|---|---|
| 小型可复用行为 | 仅创建 skills/{skill-name}/SKILL.md |
| 模板、模式、固定示例 | 添加 skills/{skill-name}/assets/ |
| 较长的解释或边缘情况 | 添加 skills/{skill-name}/references/ |
| 已有技能覆盖 | 更新已有技能 |
| 技能影响委托发现 | 确保 description 中包含触发词 |
执行步骤
- 在创建或更新技能之前，先阅读
docs/skill-style-guide.md。 - 检查现有技能，确认新技能不与任何已有技能重复。
- 选择与用户触发词匹配的kebab-case名称。
- 创建或更新如下目录结构：
skills/{skill-name}/
├── SKILL.md
├── assets/ # 可选
└── references/ # 可选
- 使用以下前置数据格式：
---
name: {skill-name}
description: "Trigger: {用户或智能体会说的短语}。{此技能的功能}。"
license: Apache-2.0
metadata:
author: gentleman-programming
version: "1.0"
---
- 按以下顺序编写章节：激活契约、硬性规则、决策门、执行步骤、输出契约、参考。
- 如果这是打包的
gentle-pi技能，将其添加到scripts/verify-package-files.mjs。 - 刷新或记录技能注册表更新路径。
输出契约
返回：
- 创建或修改的文件。
- 创建的是新技能还是更新了已有技能。
- 添加的任何支持性
assets/或references/文件。 - 是否需要包验证或技能注册表刷新。
参考
docs/skill-style-guide.md— 规范的、优先面向LLM的技能样式指南。skills/skill-registry/SKILL.md— 注册表刷新和索引契约。