sansan-skill-maker：单个 Skill 制作器
把用户反复遇到的一个问题，制作成经过验证、可以本地安装的单个 Skill。用户明确希望分享时，再提供 GitHub 发布和 npx skills add 安装能力。
核心任务
用户雇用本 Skill，是为了完成下面的进展：
> 将一类反复出现的问题，转化成一个能被 Agent 正确发现、稳定处理并接受验证的 Skill。
本地可用并通过当前证据支持的测试，即构成一次完整交付。GitHub 发布是可选能力，不能成为默认步骤。
不变量
- 从问题开始。 先确定 Skill 反复解决什么问题、在什么情境使用、出现什么证据算完成。
- 保留用户选择。 用户已经给出的名称、目标、平台和边界直接沿用；低风险细节可以透明假设。
- 理论按需进入。 只有理论能够改变判断步骤、适用边界或验证方式时才研究，不为装饰添加人物和术语。
- 直接生成文件。 用户要求制作时，交付真实 Skill 目录；材料足够时不把方案说明冒充成品。
- 主入口保持轻。
SKILL.md保存共同决策、关键流程和停止条件；条件性细节放进references/，重复且确定的工作放进scripts/。 - 用行为验证。 测试可观察输出、工具动作和边界，不要求模型展示隐藏推理。
- 失败驱动修改。 修改必须能够解释一类稳定失败，并检查留出样本和关键回归。
- 外部动作单独授权。 创建远端仓库、push、tag、Release 和公开测试材料，都需要用户明确要求。
- 用户参与需求分析。 默认用户具备基础专业能力。可以使用问题契约、行为契约、边界样本等概念，但要结合当前任务解释它们会改变哪个设计决定。
判断当前状态
每次先读取当前对话、用户提供的文件和目标目录，只处理当前最需要推进的状态。不要强迫用户重新走已经完成的阶段。
| 当前证据 | 当前任务 | 读取 |
|---|---|---|
| 只有一个想法，问题和完成态不清 | 形成问题契约与完成条件 | references/problem-and-goal.md |
| 问题已清楚，关键判断缺少机制支撑 | 研究并筛选可用机制 | references/theory-and-mechanism.md |
| 问题、行为和边界已经清楚 | 生成或补全 Skill 文件 | references/skill-construction.md |
| 已有候选 Skill，尚无行为证据 | 建立样本并测试候选 | references/evaluation.md |
| 已有失败输出或用户反馈 | 归因、提出最小修改并回归 | references/evaluation.md |
| Skill 已通过当前验证 | 完成本地交付并提醒可选发布 | 本文件“本地交付” |
| 用户明确要求发布、分享或生成安装命令 | 准备并验证 GitHub 交付 | references/github-publishing.md |
同一轮可以使用上游已经形成的产物继续完成当前任务。不要把表格中的状态改写成固定问卷或要求用户逐项选择。
输入与提问
优先从当前上下文取得：
- 用户反复遇到的问题；
- 使用这个 Skill 的典型情境；
- 希望 Agent 产生的结果或动作；
- 已有案例、失败输出、文件和约束；
- 目标平台或目录；
- 当前是否只需本地使用。
信息足以决定交付物时直接推进。需求分析本身对 Skill 质量有价值，可以让用户参与核心判断；只有已经能从上下文可靠恢复的信息才不重复追问。将相关缺口合并成尽可能少的问题，说明每个问题将改变哪个设计决定，不发送无关的通用问卷。
从问题到候选 Skill
1．形成问题契约
至少明确：
反复出现的问题：
使用情境：
用户想推进的变化：
Skill 应交付的结果：
完成证据：
不处理的近邻问题：
问题太一次性、成功无法观察、主要结果依赖不可获得的权限或事实时，说明当前不适合沉淀。仍可交付能够复用的局部工具。
2．形成行为契约
把“好用、聪明、专业”等要求改写成可观察行为：
目标任务：
预期使用条件：
输入变化范围：
必须做到：
禁止出现：
允许变化：
关键失败：
3．选择机制
先拆出 Skill 需要完成的判断动作，再决定是否需要理论、行业规则、用户材料或脚本。每个机制都要对应一个动作、一个中间结果和一个失效边界。
4．生成候选
根据实际任务选择最小结构：
skill-name/
├── SKILL.md
├── agents/openai.yaml 可选 UI 元数据
├── references/ 条件性知识或流程
├── scripts/ 重复、确定的操作
└── assets/ 进入最终交付的模板或素材
目录只创建实际需要的部分。新 Skill 默认允许正常自动发现；只有用户明确要求显式调用时，才关闭隐式调用。
创建新目录时可以运行：
python3 scripts/init_skill_project.py <skill-name> --output <父目录> \
--description "<能力与使用条件>" \
--task "<反复解决的问题与交付结果>" \
--workflow "<第 1 个关键动作>" \
--done "<可观察的完成证据>"
脚本只负责生成已带真实内容的初稿。Agent 必须继续写完判断条件、边界和停止条件，并在校验通过后交付。不得把初始骨架或未完成占位符交给用户。
完成文件后运行：
python3 scripts/validate_skill_project.py <skill-directory>
5．分级验证候选
新 Skill 先建立 3～6 个样本，至少覆盖正常正例、边界样本、近邻反例和留出样本。复杂或高风险任务再扩大覆盖。执行者不得提前读取预期答案。
按实际完成的最高等级报告：
| 等级 | 证据 | 允许的表述 |
|---|---|---|
| 1．结构校验 | frontmatter、引用、资源和脚本静态检查通过 | “结构校验通过” |
| 2．行为冒烟 | 候选 Skill 完成至少 1 个真实主要任务 | “行为冒烟测试通过” |
| 3．留出／回归 | 执行者未看预期答案，留出样本通过且无关键回归 | “当前留出与回归样本通过” |
| 4．安装交付 | GitHub 来源可用 npx skills add 安装，并逐项核对资源 |
“GitHub npx 安装与资源校验通过” |
未实际运行行为任务时，只能报告第 1 级。没有留出收益或出现关键回归时，不能宣称 Skill 已经变强。详细记录方式见 references/evaluation.md。
本地交付
完成后报告：
- Skill 名称和绝对路径；
- 解决的问题与主要边界；
- 实际生成的文件；
- 已运行的校验和行为测试；
- 仍未验证的风险；
- 本地安装或调用方式。
需要把生成的 Skill 安装到本地时，直接把生成目录复制到目标平台的技能根目录（例如 ~/.agents/skills/），或按该平台自身的安装方式操作。本 Skill 不绑定任何特定发行版，也不临时生成另一套安装脚本。
本地交付后固定提醒一次：
> Skill 已完成，当前最高验证等级是「{1／2／3／4}」，可以在本地使用。如果你希望分享给别人，我还可以帮你发布到 GitHub，并验证 npx skills add 安装命令。
用户没有要求发布时直接结束，不继续追问，也不创建 GitHub 配置。
GitHub 发布边界
用户明确要求发布、分享或生成 npx 安装命令时，才读取 references/github-publishing.md。
准备仓库不等于获得远端写入授权。执行 gh repo create、git push、创建 tag 或 Release 前，确认用户的明确要求能够覆盖该动作。
对单 Skill 仓库，默认生成的安装命令为：
npx -y skills add <owner>/<repo> -g --all
命令进入 README 后仍需在隔离目录中验证，不能只检查文字是否存在。
停止条件
出现以下情况时结束当前轮次：
- 候选已经完成并通过当前可执行的验证；
- 当前阶段缺少一个会改变设计的用户决定；
- 理论或现实事实连续核实失败，继续搜索不会改变候选；
- 修改开始依赖单个案例补丁；
- 用户只要求方案或明确要求停止；
- GitHub 相关动作尚未获得授权。
语言与安全
- 中文遵循《中文文案排版指北》。
- 不使用空洞的二元反转句式。
- 不读取、复制或发布用户未授权的私密材料。
- 不覆盖现有真实目录；发现同名目标时先检查并说明。
- 不使用
git add .或git add -A；发布时只暂存明确文件。 - 不把本地绝对路径、测试答案、密钥或内部记录写进公开仓库。
完成当前任务后直接结束，不主动追加与当前任务无关的引导。
作者与支持
- 作者：sansan（GitHub 主页）
- 如需加入付费答疑群，可扫码或打开答疑群说明
