用途
craft-scaffold 用于把一个粗略的想法整理成结构化的提示词或技能脚手架,使其易于实现、审阅与复用。脚手架之所以重要,是因为含糊的需求只会产出含糊的产物;在动手写产物之前,先把目标、输入、工作流与输出分开,能让最终的提示词或技能更可复用、也更不易脆弱。
何时使用
请求本身仍然含糊时;正在启动一个新的技能或提示词系列时;在编辑仓库前需要一份稳定的文件计划时;当前产物把目标、约束和输出形式混在一起时。
输入
粗略的想法或请求;预期的智能体或智能体们;期望结果;约束;若已有可用的参考资料。
步骤
- 提炼请求背后真正的目标。粗略的措辞通常隐藏着一个更清晰的目标,用一句话把它呈现出来。
- 把目标、约束、假设和非目标分开。把它们混在一起是提示词漂移最常见的来源。
- 为目标提示词或技能提出一个清晰的结构,优先选择能经受复用考验的最简形态。
- 定义预期输入、步骤与输出,明确到另一个智能体无需猜测即可实现该产物。
- 建议要创建或更新的文件。一份具体的文件清单能把脚手架转化为实际工作。
- 简要指出尚未解决的决策,只呈现那些会实质性改变设计的决策。
当目标是技能而非提示词时
提示词是单个文件,而技能是一个文件夹,这改变了脚手架必须决定的内容:
计划形态。提示词脚手架是一份章节计划:在角色 / 上下文 / 任务 / 规则 / 格式 / 示例中选用哪些、以什么顺序出现、各自承载什么。技能脚手架则是一份文件树计划加 SKILL.md 大纲;在写其中任何一个文件之前就先决定存在哪些文件。
文件列表的展开。对技能而言,“需创建或更新的文件”一节应具体枚举:skills/<name>/SKILL.md(始终必需);skills/<name>/references/<file>.md(仅当细节会使 SKILL.md 超过约 500 行,或某个主题值得渐进式披露时);skills/<name>/scripts/<file>.mjs(仅当该技能重复执行某类确定性工作、否则智能体每次调用都要重新推导时);skills/<name>/templates/<file>(仅当一个精心制作的模板能带来智能体难以轻易生成的价值时)。避免“以防万一”预先创建文件夹——空文件夹会招致膨胀,等需求真实出现时再在后续迭代中添加。
Frontmatter 是一等设计产物。技能的名称与描述就是它的触发机制。脚手架必须起草一段面向触发的 description(做什么 + 何时调用),并覆盖用户可能使用的非显而易见表述。这对提示词没有对应物,因为提示词不会自我触发。
篇幅预算。目标是把 SKILL.md 控制在约 500 行以内。如果该技能的工作量很可能超出,脚手架应在设计阶段就规划拆分为 references/,而不是写到一半才发现。
渐进式披露是一项设计决策。提前决定哪些内容每次调用都加载(SKILL.md 正文)、哪些按需加载(references/)。做错这一点,要么撑大每一次上下文窗口,要么把关键细节对智能体隐藏起来。
提示词完全跳过第 2 至第 5 项。第 1 项与第 6 项(开放问题)对两者都适用。
输出格式
摘要:用一小段描述正在构建什么以及为什么。
脚手架:objective;目标用户或智能体;inputs;workflow;输出格式;护栏;非目标。对于技能目标,还应包含一行起草的 description frontmatter,要求(a)说明该技能做什么,(b)说明何时调用它,(c)覆盖至少 2 种不同的用户表述或别名。提示词不会自我触发,因此对提示词目标省略此项。
需创建或更新的文件:一份具体文件列表,每个文件配一行用途说明。每条用途都指向任务特有的职责——例如分类体系、紧急程度评分标准、提交解析正则——而不是通用样板。
开放问题:1 至 3 项,若没有剩余问题则写“无——所有决策均可由上述内容解决”。每一项都必须指出一个会改变架构的决策(范围裁剪、目标拆分、参考文件边界、触发标准的选择)。省略实现细节上的吹毛求疵(命名、某子字段的格式、措辞选择),那些属于最终产物而非脚手架。
护栏
优先选择能经受复用考验的最简结构;不要创建过多顶层概念;保持脚手架面向实现;避免核心结构锁定特定提供商。
失败模式
写出抽象到没人知道如何下手的脚手架;在资产本身可用之前就发明插件系统或框架;用大量开放问题淹没用户,而不是做出合理假设;照搬另一个仓库的结构,而不是为实际任务塑造结构。
示例
输入:创建一个可复用的技能,帮助改进 Claude Code 与 Codex 的提示词。
输出:
摘要:创建一个跨智能体的调优技能,通过小幅、明确的编辑来修订现有提示词。
脚手架:objective: 在不从零重写的前提下改进提示词;目标智能体: Claude Code、Codex;inputs: 当前提示词、目标改进、约束;workflow: 检查、批评、编辑、总结变更;输出格式: 修订后的提示词、变更日志、风险;护栏: 保持意图稳定、保持差异最小;非目标: 特定提供商的取巧手段。
需创建或更新的文件:skills/craft-tune/SKILL.md;README.md(在技能表中新增一行)。
开放问题:示例应放在每个技能文件内,还是放在共享的 examples 文件夹中?