Back to Details

craft-scaffold

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

craft-scaffold

Craft-Scaffold

Purpose

目的

Turn a rough idea into a structured prompt or skill scaffold that is easy to implement, review, and reuse.
Scaffolding matters because vague requests produce vague artifacts. Separating goals, inputs, workflow, and outputs before writing the artifact makes the resulting prompt or skill far more reusable and far less brittle.
将粗略的想法转化为易于实现、评审和复用的结构化Prompt或Skill脚手架。
脚手架至关重要，因为模糊的需求会产生模糊的成果。在编写成果之前就明确区分目标、输入、工作流和输出，能让最终的Prompt或Skill具备更高的复用性，且更不易失效。

Use this when

适用场景

  • the request is still vague
  • a new skill or prompt family is being started
  • a stable file plan is needed before editing the repo
  • the current artifact mixes goals, constraints, and output shape
  • 需求仍较为模糊时
  • 启动新的Skill或Prompt系列时
  • 在编辑代码库前需要稳定的文件规划时
  • 当前成果混淆了目标、约束和输出形式时

Inputs

输入项

  • brief idea or request
  • intended agent or agents
  • expected outcome
  • constraints
  • existing references if available
  • 简要的想法或需求
  • 目标Agent（一个或多个）
  • 预期成果
  • 约束条件
  • 现有参考资料（如有）

Steps

步骤

  1. Extract the real objective behind the request. Rough wording usually hides a cleaner goal — surface it in one sentence.
  2. Separate goals, constraints, assumptions, and non-goals. Mixing these is the most common source of prompt drift.
  3. Propose a clean structure for the target prompt or skill. Favor the simplest shape that can survive reuse.
  4. Define the expected inputs, steps, and outputs. Be explicit enough that another agent could implement the artifact without guessing.
  5. Suggest files to create or update. A concrete file list converts the scaffold into work.
  6. Call out any unresolved decisions briefly. Only surface decisions that materially change the design.
  1. 提炼需求背后的真实目标。粗略的表述通常隐藏着更清晰的目标——用一句话明确呈现。
  2. 区分目标、约束、假设和非目标。将这些内容混为一谈是Prompt偏离初衷最常见的原因。
  3. 为目标Prompt或Skill提出清晰的结构。优先选择能满足复用需求的最简结构。
  4. 明确定义预期的输入、步骤和输出。表述需足够清晰，确保其他Agent无需猜测即可实现该成果。
  5. 建议需要创建或更新的文件。具体的文件列表能将脚手架转化为可执行的工作。
  6. 简要列出未解决的决策。仅列出会对设计产生实质性影响的决策。

When the target is a skill (vs a prompt)

当目标为Skill（而非Prompt）时

A prompt is a single file; a skill is a folder. That changes what the scaffold must decide:
  1. Shape of the plan.
    • Prompt scaffold = a section plan: which of Role / Context / Task / Rules / Format / Examples to include, in what order, and what each carries.
    • Skill scaffold = a file-tree plan + 
      SKILL.md
      outline. Decide which files exist before any of them are written.
  2. Files list, expanded. For a skill, the "Files to create or update" section should enumerate concretely: 
    • skills/<name>/SKILL.md
      (always required)
    • skills/<name>/references/<file>.md
      (only when detail would push SKILL.md past ~500 lines, or when a topic deserves progressive disclosure)
    • skills/<name>/scripts/<file>.mjs
      (only when the skill repeats deterministic work an agent would otherwise re-derive each invocation)
    • skills/<name>/templates/<file>
      (only when a well-crafted template adds value the agent cannot easily generate) Avoid pre-creating folders "just in case" — empty folders invite bloat. Add them in a later iteration when the need is real.
  3. Frontmatter is a first-class design artifact. A skill's 
    name
    and 
    description
    are its triggering mechanism. The scaffold must draft a 
    description
    that is trigger-oriented (what it does + when to invoke) and covers the non-obvious phrasings users might use. This has no analogue for prompts, which do not self-trigger.
  4. Size budget. Target 
    SKILL.md
    under ~500 lines. If the skill's job plausibly exceeds that, the scaffold should plan the split into 
    references/
    at design time — not discover it mid-write.
  5. Progressive disclosure as a design decision. Decide up front which content loads on every invocation (
    SKILL.md
    body) versus on demand (
    references/
    ). Getting this wrong either inflates every context window or hides load-bearing detail from the agent.
Prompts skip items 2-5 entirely. Items 1 and 6 (open questions) apply to both.
Prompt是单个文件；Skill是一个文件夹。这会改变脚手架需要确定的内容：
  1. 规划形式
    • Prompt脚手架 = 章节规划：确定包含Role/Context/Task/Rules/Format/Examples中的哪些部分、顺序如何，以及各部分承载的内容。
    • Skill脚手架 = 文件树规划 + 
      SKILL.md
      大纲。在编写任何文件之前，先确定需要存在哪些文件。
  2. 扩展文件列表。对于Skill，“需要创建或更新的文件”部分应具体列举： 
    • skills/<name>/SKILL.md
      （必填）
    • skills/<name>/references/<file>.md
      （仅当内容过多会使
      SKILL.md
      超过约500行，或某一主题需要渐进式披露时使用）
    • skills/<name>/scripts/<file>.mjs
      （仅当Skill需重复执行确定性工作，而Agent每次调用都重新推导效率低下时使用）
    • skills/<name>/templates/<file>
      （仅当精心设计的模板能为Agent带来无法轻松生成的价值时使用） 避免“以防万一”预先创建文件夹——空文件夹会导致冗余。当确实有需求时，再在后续迭代中添加。
  3. 前置元数据（Frontmatter）是核心设计成果。Skill的
    name
    和
    description
    是其触发机制。脚手架必须草拟一条
    description
    ，内容需面向触发场景（说明功能+调用时机），并覆盖用户可能使用的至少2种不同表述或别名。Prompt无需自动触发，因此Prompt脚手架可省略此部分。
  4. 篇幅预算。目标是让
    SKILL.md
    保持在约500行以内。如果Skill的功能可能超过这个篇幅，脚手架应在设计阶段就规划好拆分到
    references/
    目录的内容——而非在编写过程中才发现需要拆分。
  5. 将渐进式披露作为设计决策。提前决定哪些内容在每次调用时加载（
    SKILL.md
    主体），哪些内容按需加载（
    references/
    下的文件）。如果决策失误，要么会占用过多上下文窗口，要么会向Agent隐藏关键细节。
Prompt无需考虑第2-5项。第1项和第6项（未解决问题）对两者均适用。

Output format

输出格式

Summary

摘要

A short paragraph describing what is being built and why.
一段简短的段落，说明正在构建的内容及其原因。

Scaffold

脚手架

  • objective
  • target users or agents
  • inputs
  • workflow
  • output format
  • guardrails
  • non-goals
For skill targets, also include a drafted 
description
frontmatter line that (a) names what the skill does, (b) states when to invoke it, and (c) covers ≥ 2 distinct user phrasings or aliases. Prompts do not self-trigger; omit for prompt targets.
  • 目标
  • 目标用户或Agent
  • 输入项
  • 工作流
  • 输出格式
  • 约束规则
  • 非目标
若目标为Skill，还需草拟一条
description
前置元数据，内容需：(a) 说明Skill的功能，(b) 说明调用时机，(c) 覆盖至少2种不同的用户表述或别名。Prompt无需自动触发，因此Prompt脚手架可省略此部分。

Files to create or update

需要创建或更新的文件

A concrete file list with one-line purpose per file. Each purpose names a task-specific responsibility — e.g. 
classification taxonomy
, 
urgency rubric
, 
commit-parse regex
— not generic boilerplate.
具体的文件列表，每个文件附带一行说明其用途。用途需明确任务特定的职责——例如
分类分类法
、
紧急程度准则
、
提交解析正则表达式
——而非通用的模板内容。

Open questions

未解决问题

1–3 items, or write "none — all decisions resolvable from the above" if none remain. Each item must name a decision that would change the architecture (scope cut, target split, reference-file boundary, trigger-criteria choice). Drop implementation nits (naming, format of a subfield, wording choices) — those belong in the eventual artifact, not the scaffold.
1-3项，若没有则写“无——所有决策均可根据上述内容确定”。每项必须指明会改变架构的决策（如范围缩减、目标拆分、参考文件边界、触发条件选择）。忽略实现细节（如命名、子字段格式、措辞选择）——这些属于最终成果的内容，而非脚手架的范畴。

Guardrails

约束规则

  • prefer the simplest structure that can survive reuse
  • do not create too many top-level concepts
  • keep the scaffold implementation-oriented
  • avoid provider lock-in in the core structure
  • 优先选择能满足复用需求的最简结构
  • 不要创建过多顶层概念
  • 保持脚手架以实现为导向
  • 核心结构避免供应商锁定

Failure modes

失败模式

  • writing a scaffold so abstract that nobody knows how to start
  • inventing a plugin system or framework before the asset itself works
  • drowning the user in open questions instead of making reasonable assumptions
  • copying another repo's structure instead of shaping one for the actual task
  • 编写的脚手架过于抽象，导致无人知晓如何启动
  • 在资产本身可用之前就发明插件系统或框架
  • 向用户抛出大量未解决问题，而非做出合理假设
  • 照搬其他代码库的结构，而非根据实际任务定制

Example

示例

Input

输入

Create a reusable skill that helps improve prompts for Claude Code and Codex.
创建一个可复用的Skill，帮助优化Claude Code和Codex的Prompt。

Output

输出

Summary Create a cross-agent tuning skill that revises existing prompts with small, explicit edits.
Scaffold
  • objective: improve prompts without rewriting them from scratch
  • target agents: Claude Code, Codex
  • inputs: current prompt, target improvement, constraints
  • workflow: inspect, critique, edit, summarize changes
  • output format: revised prompt, changelog, risks
  • guardrails: keep intent stable, keep diffs minimal
  • non-goals: provider-specific hacks
Files to create or update
  • skills/craft-tune/SKILL.md
  • README.md
    (add a row to the skill table)
Open questions
  • Should examples live inside each skill file or in a shared examples folder?
摘要 创建一个跨Agent调优Skill，通过细微、明确的修改来优化现有Prompt。
脚手架
  • 目标：无需从头重写即可优化Prompt
  • 目标Agent：Claude Code、Codex
  • 输入项：当前Prompt、目标优化方向、约束条件
  • 工作流：检查、评估、编辑、总结变更
  • 输出格式：优化后的Prompt、变更日志、风险提示
  • 约束规则：保持原有意图不变、最小化差异
  • 非目标：供应商特定的技巧
需要创建或更新的文件
  • skills/craft-tune/SKILL.md
  • README.md
    （在Skill表格中添加一行）
未解决问题
  • 示例应放在每个Skill文件中，还是放在共享的示例文件夹中？