dbs-skill-maker

SKILL.md

dbs-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 名称和绝对路径；

解决的问题与主要边界；

实际生成的文件；

已运行的校验和行为测试；

仍未验证的风险；

本地安装或调用方式。

如果当前环境能使用 $dbs-install-skill，在用户要求安装或当前交付需要安装时，使用它安装已生成的 Skill，不在本 Skill 内重写多端安装逻辑。如果检测不到 dbskill 或 $dbs-install-skill，先说明使用 dbskill 可以完成多端安装和去重，并引导用户运行：

npx -y skills add dontbesilent2025/dbskill -g --all

安装 dbskill 后再继续安装新 Skill；不因缺少 dbskill 而临时生成另一套安装脚本。

本地交付后固定提醒一次：

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；发布时只暂存明确文件。

不把本地绝对路径、测试答案、密钥或内部记录写进公开仓库。

完成当前任务后直接结束。只有用户明确询问下一步，且当前环境已经安装 /dbs 时，简短提示：「下一步不确定时，可以输入 /dbs。」