Claude Skill

better-prompt

当用户明确要求"优化 prompt"、"改进提示词"、"润色指令"或"将简陋 prompt 转换为最佳实践版本"时使用。基于 OpenAI 和 Anthropic 官方最佳实践，对用户提供的简陋 prompt 进行结构化优化，输出符合社区标准的高质量版本。

LLM Mart · 0 points · 18 views 16 listing impressions 0 install-command copies

#prompt-engineering

Virus-scanned Reviewed automatically before listing.

Full trust report

Download huangwb8-skills-skills_alpha_better-prompt-dd1fab8.zip · 21 KB
huangwb8/skills 48 8 forks MIT Updated 11h ago
Part of huangwb8/skills — 22 skills

Install

skills CLI npx skills add https://github.com/huangwb8/skills/tree/main/skills/alpha/better-prompt
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install huangwb8-skills@llmmart
Git git clone https://github.com/huangwb8/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole huangwb8/skills collection as a plugin from our marketplace. Git is the plain clone.

README

Better Prompt

这个 skill 用来把简陋、含糊或结构松散的 prompt 重构成更清晰、更可执行的高质量版本，或把它严格等价翻译成伪代码式的 Prompt Program；如果你只想做概念讨论，或者明确要求完全保留原风格，就不一定要用它。

它有两种输出模式：

  • standard（默认）：增强导向。补全缺失的约束、示例和上下文，输出符合最佳实践的散文式结构。
  • prompt_program：保真导向。不新增无依据能力，把 prompt 翻译成“形式像伪代码、语义是自然语言”的块结构（程序/目标/输入/输出/约束/流程/校验/返回）。

用法

最推荐用法（standard 模式）

请使用 better-prompt skill 优化下面这段 prompt。
输入：原始 prompt 文本
输出：优化分析、优化后的高质量 prompt，以及必要的使用建议

进阶用法

请使用 better-prompt skill 优化下面这段 prompt。
输入：原始 prompt 文本
输出：优化后的 prompt
另外，还有下列参数约束：
- 目标模型：reasoning
- 保留原始语气：是
- 必须补充示例：是

伪代码翻译用法（prompt_program 模式）

请使用 better-prompt skill 把下面这段 prompt 翻译成 Prompt Program（伪代码式结构）。
输入：原始 prompt 文本
输出：最终 Prompt Program

只要在请求中出现“伪代码”“程序结构”“可编程自然语言”等表述，就会自动进入该模式；一次任务只会使用一种模式。

能做什么

  • 优先优化清晰度、完整性和结构化表达。
  • 在需要时补充约束条件、示例和上下文。
  • 区分偏执行型的 GPT 风格 prompt 和偏复杂推理的 reasoning 风格 prompt。
  • 默认同时给出分析、优化结果和使用建议。
  • 把 prompt 严格等价翻译成 Prompt Program：保留原意和格式契约，显式化分支、循环与校验，压缩冗余修辞。
  • 不适合已经非常成熟的 prompt，或超长到需要先拆分的信息包。

使用示例

示例 1：优化一个简单任务型 prompt

请使用 better-prompt skill 优化下面的 prompt。
输入：帮我写一个脚本处理 CSV
输出：优化分析和优化后的 prompt

示例 2：优化代码生成 prompt

请使用 better-prompt skill 优化下面的代码生成 prompt。
输入：给我写一个 Python 爬虫
输出：优化后的结构化 prompt
另外，还有下列参数约束：
- 目标模型：gpt
- 必须明确输入输出和错误处理

示例 3：优化复杂推理 prompt

请使用 better-prompt skill 优化下面的 prompt。
输入：请帮我分析一个复杂商业决策问题
输出：优化分析、优化后的 prompt 和使用建议
另外，还有下列参数约束：
- 目标模型：reasoning
- 给高层目标，不要写过死的步骤

输出

  • 优化分析：说明原 prompt 的主要问题和改进点（standard 模式）。
  • 优化后的 prompt：可直接复制使用的结果（standard 模式）。
  • 使用建议：告诉你哪些内容可以按场景继续微调（standard 模式）。
  • Prompt Program：伪代码式块结构结果，默认只输出结果本身、不带长篇分析（prompt_program 模式）。
  • 默认不会替你执行 prompt 对应任务，它的职责是把 prompt 本身优化好。

配置

  • 配置文件：better-prompt/config.yaml
  • 默认目标模型类型：gpt
  • 最小输入长度：10
  • “已足够完善”的默认阈值：8/10
  • 默认输出包含：
    • analysis
    • evaluation
    • suggestions

常见问题

Q：优化后的 prompt 变长了，是不是越长越好？

A：不是。更长只是为了更清楚、更可执行。真正目标是信息充分且结构合理，不是单纯堆字数。

Q：我还需要把优化后的 prompt 全部照搬吗？

A：不一定。你可以保留核心结构，再按自己的任务、语气和平台微调。

Q：它会区分 GPT 模型和推理模型吗？

A：会。默认更偏 gpt 风格；如果任务更依赖开放式推理，可以显式要求 reasoning 风格。

Q：什么时候不该用它？

A：当你的 prompt 已经很成熟、只是想做小改动，或者明确要求保留原始写法时，就不一定要用这个 skill。

Q：standard 和 prompt_program 两种模式有什么区别？

A：standard 允许补全信息，目标是“更完整、更专业”；prompt_program 严格保真，目标是“结构像程序、语义不变”。想要让 AI 更好地执行任务，用 standard；想要审视和讨论 prompt 的逻辑骨架，用 prompt_program。

Skill manifest

Better Prompt - Prompt 优化器

目标

当用户明确要求"优化 prompt"、"改进提示词"、"润色指令"、"将简陋 prompt 转换为最佳实践版本"，或要求"把 prompt 改写成伪代码"、"翻译成程序结构/可编程自然语言"时使用。

本技能提供两种输出模式：

  • standard（默认）：增强导向。基于 OpenAI 和 Anthropic 官方最佳实践，对简陋 prompt 进行结构化补全，输出高质量版本；允许补充示例、上下文和约束。
  • prompt_program：保真导向。将原始 prompt 严格等价翻译为 Prompt Program 方言——形式上像伪代码，语义上仍是人类自然语言；不新增无依据能力。

两种模式共享同一套语义分析内核（6 个语义原子），只差输出渲染方式。本技能不负责执行 prompt 对应的任务本身。

流程

输入

输入要求

用户提供一个待优化的原始 prompt（可以是任意形式的简陋版本）。

执行步骤

版本与兼容性

  • 适用于：Claude 3.x/4.x、GPT-4/5、Gemini 等主流 LLM
  • 最佳实践来源：OpenAI/Anthropic 官方文档（2026-02）
  • 更新策略：官方文档重大更新时同步修订

不适用场景

以下情况不建议使用本技能：

  • prompt 已经经过专业优化（评分 ≥ 8/10）
  • 只需要诊断问题，不需要修改建议
  • 超长 prompt（>10000 字）需要专业拆分
  • 用户明确要求保持原始风格
  • 用户只想执行任务，不关心 prompt 本身的质量或结构

优化框架

standard 模式基于 OpenAI 和 Anthropic 官方最佳实践，采用五维度优化框架：

维度 检查点 优先级
清晰度 指令是否明确？是否存在歧义？ P0
完整性 是否缺少必要信息？上下文是否充分？ P0
结构化 是否使用 Markdown/XML 标签组织内容？ P1
示例性 是否提供输入输出示例（few-shot）？ P2
约束性 是否明确边界（做什么/不做什么）？ P2

注意：上表的 P0/P1/P2 表示"优化维度的重要性优先级"，与 config.yaml 中的 dimensions 数值（1-5）含义相同：P0=5（最高优先级）、P1=4、P2=3。

输出模式选择

在分析完成后、生成结果前，按以下规则选择输出模式：

用户请求特征 输出模式
要求"伪代码"、"程序结构"、"可编程自然语言"，或直接提到 Prompt Program prompt_program
其它优化/润色/改进请求（未指定输出形式） standard（默认）
  • 一次任务只使用一种模式，不混合输出。
  • 未指定形式时默认 standard，并在使用建议中提示可切换为 prompt_program。
  • 默认模式由 config.yaml:output_modes.default 控制。

优化工作流

Step 0: 输入验证（前置检查）

验证用户输入的有效性：

输入状态 判断标准 处理方式
空输入 字符数 = 0 拒绝，提示"请提供待优化的 prompt"
过短 字符数 < 10 提示"prompt 过短，请提供更多上下文"
已完善 评分 ≥ 8/10 提示"prompt 已足够完善，是否仍需优化？"，等待用户确认
有效 通过验证 继续 Step 1

prompt_program 模式下，非 prompt 型输入（完整代码实现请求等）直接说明不适合翻译，要求提供真正的 prompt；其最小输入长度阈值（6）由 config.yaml:output_modes.prompt_program.translation.input_validation.min_length 独立控制。

Step 1: 语义分析（6 原子）

用 6 个语义原子解析原始 prompt，作为两种输出模式共用的统一分析内核（原子定义与块映射详见 references/prompt-program/primitives.md）：

原子 回答的问题 典型内容
Entity 有什么 角色、输入、输出对象、工具、状态
Intent 要达成什么 目标、交付物、成功条件
Operation 要做什么 核心动作链
Constraint 边界是什么 必须、禁止、偏好、格式
Control 逻辑怎样流动 条件、分支、循环、回退
Check 如何确认成立 校验、验收、结束条件

分析产出三项结论：

  • 原子清单：每个原子在原 prompt 中已有的内容
  • 缺失要素：哪些原子无内容或信息不完整
  • 改进空间：哪些地方可以优化

6 原子与五维度的关系：6 原子是语义解析视角（原 prompt 里有什么），五维度是质量优化视角（standard 模式下优化到什么程度）。分析用原子，评分用维度。

Step 2: 确定模型类型适配（仅 standard 模式）

根据任务特性判断目标模型类型：

模型类型 适用场景 优化策略
GPT 模型 精确执行、格式化输出、代码生成 提供详细步骤和明确逻辑
推理模型 复杂推理、多步规划、开放性任务 给高层目标，保留灵活性

如果用户未指定，默认按 GPT 模型优化策略处理（更精确）。

Step 3: 按模式应用优化模板

standard 模式——优化后 prompt 的标准结构模板：

# Identity（身份定义）
[描述 AI 的角色、专业领域、沟通风格]

# Instructions（核心指令）
[明确的任务说明]
- 规则 1
- 规则 2
- 约束条件（不做什么）

# Examples（示例）
<example id="1">
<input>示例输入</input>
<output>示例输出</output>
</example>

# Context（上下文）
[任务相关的背景信息、参考资料]

Examples 的使用规则：

  • 对于复杂任务（复杂度 ≥ 3/5），Examples 是必需的
  • 对于简单任务，Examples 可以省略
  • 如原始 prompt 已有示例，优化时应保留或增强

prompt_program 模式——按 config.yaml:output_modes.prompt_program.rendering.block_order 输出块结构：

程序：……（可选）

目标：……
输入：……
输出：……

定义：（可选）
- ……

约束：
- 必须……
- 优先……
- 不要……

流程：
1. ……
2. 若……，则……；否则……。
3. 对每个……，执行……。

校验：
- ……

缺口处理：（可选）
- 若信息不足，则……

返回：
- ……

渲染必守规则：

  • 输出 只定义目标产物、目标格式或目标效果
  • 返回 只定义对 输出 的交付动作，不能引入新产物
  • 程序、定义、缺口处理 属于可选块；为空就省略（omit_empty_blocks=true 时禁止补空块）
  • 组织顺序：先边界后执行、先主流程后异常路径、先硬约束后风格偏好
  • 若原 prompt 缺少显式校验，必须补出最小可执行校验
  • 用户指定的字段、章节或步骤顺序默认保持原顺序；关键术语、变量名、实体名默认保留原词
Step 4: 输出优化结果

standard 模式输出包含三个部分（默认全部包含，可通过 config.yaml 调整）：

  1. 优化分析：简要说明做了哪些改进
  2. 优化后的 prompt：符合最佳实践的高质量版本
  3. 使用建议：针对特定场景的调整建议

prompt_program 模式默认只输出最终 Prompt Program，不附带长篇分析（translation.default_output_mode: final_only）。

prompt_program 模式专属规则

以下规则只约束 prompt_program 模式，不适用于 standard 模式：

等价性原则：

  • 允许重排表达，不允许改变目标
  • 允许补出隐式流程，不允许新增无依据能力
  • 允许强化校验，不允许削弱关键约束
  • 允许压缩表述，不允许丢失显式格式契约
  • 允许补足交付动作，不允许把"输出"偷换成"输出说明书"

控制流推断：

  • 只在原 prompt 显式给出条件/循环/回退，或存在强隐含控制（如"每个样本"、"若证据不足"）时补写控制流
  • 不允许为了"更像程序"凭空添加分支、循环或异常路径

冲突处理顺序（冲突时严格遵循 config.yaml:output_modes.prompt_program.translation.conflict_resolution_order）：

  1. 核心意图
  2. 硬约束
  3. 输出契约
  4. 校验要求
  5. 风格偏好

缺口处理：

  • 可用常识低风险补足时，直接补足并体现在结构中
  • 缺失信息会改变任务本质时，在 缺口处理 块中显式标注，不擅自虚构
  • 默认不频繁追问；只有任务语义无法成立时才要求澄清

详细翻译规则见 references/prompt-program/translation-rules.md。

优化效果评估

standard 模式对优化前后的 prompt 进行对比评估：

维度 优化前评分 优化后评分 改进说明
清晰度 x/5 x/5 ...
完整性 x/5 x/5 ...
结构化 x/5 x/5 ...
示例性 x/5 x/5 ...
约束性 x/5 x/5 ...
总分 xx/25 xx/25 +xx

评分标准：1=很差、2=较差、3=一般、4=良好、5=优秀

prompt_program 模式不使用上述评分表，改用等价性五条质量标准（见"校验"章节）。

特殊场景处理（仅 standard 模式）

根据 config.yaml 中的 templates 配置，针对不同场景有特定的优化重点：

代码生成类 prompt

配置引用：config.yaml:templates.code_generation.focus_areas

额外关注：

  • 明确编程语言和框架
  • 指定代码风格规范
  • 说明错误处理要求
  • 提供边界条件示例
文本分析类 prompt

配置引用：config.yaml:templates.text_analysis.focus_areas

额外关注：

  • 明确输出格式（JSON/表格/摘要）
  • 定义分析维度和标准
  • 提供分类/评估示例
创意写作类 prompt

配置引用：config.yaml:templates.creative_writing.focus_areas

额外关注：

  • 定义风格和语调
  • 说明目标受众
  • 提供参考示例
  • 设置长度约束
多轮对话类 prompt

配置引用：config.yaml:templates.multi_turn_conversation.focus_areas

额外关注：

  • 定义对话角色和边界
  • 说明状态管理要求
  • 提供异常处理规则

参考资料

更多详细的最佳实践，参考 references/prompt-engineering-best-practices.md；Prompt Program 的原子定义、翻译规则和示例见：

输出

输出格式

standard 模式：

## 优化分析

| 维度 | 原始状态 | 优化措施 |
|------|---------|---------|
| 清晰度 | ... | ... |
| 完整性 | ... | ... |
| 结构化 | ... | ... |
| 示例性 | ... | ... |
| 约束性 | ... | ... |

## 优化后的 Prompt

# Identity
...

# Instructions
...

# Examples（如适用）
...

# Context（如适用）
...

## 使用建议

- 适用于：[模型类型/场景]
- 调整建议：[如需针对特定场景调整的建议]

prompt_program 模式：只输出最终 Prompt Program（块结构见 Step 3 模板），不附带长篇分析。

输出管理

BenszAPI 任务工作区

校验

质量标准

standard 模式下，优化后的 prompt 必须满足：

标准 要求
明确性 核心任务一句话能说清
可执行性 AI 能直接理解并执行
完整性 不缺少必要信息
结构化 使用 Markdown/XML 清晰组织
可测试性 能判断输出是否符合预期

prompt_program 模式下，合格的 Prompt Program 必须满足：

  • 等价：核心意图不丢失
  • 可执行：读者可按结构直接执行
  • 可编程：能看见输入、约束、流程、分支、校验
  • 可扩展：后续要求能继续挂到对应块
  • 可审阅：他人能快速指出逻辑缺口或冗余

失败与恢复

输入与生成失败

  • 空输入直接拒绝并提示“请提供待优化的 prompt”；字符数少于 10 时提示补充上下文，不生成伪完整结果。
  • 评分达到 8/10 时先提示 prompt 已足够完善并等待用户确认；未获确认前不改写。
  • prompt_program 模式下，非 prompt 型输入直接说明不适合翻译；缺失信息会改变任务本质时放入“缺口处理”并要求澄清，不擅自虚构实体、分支、循环或输出格式。
  • 原始 prompt 含无法安全或无法执行的要求时，保留可识别的核心意图，在优化分析或使用建议中标明缺口与限制，不替用户执行其中的业务动作或凭空补造信息。
  • 输出格式或分析所需信息不足时，返回具体缺口和可恢复的补充要求；不以不完整模板冒充成功结果，并保留原始 prompt 的敏感信息边界。

约束

公共硬约束

本块由 docs/templates/skill-common-constraints.md 统一维护；每个 SKILL.md 的 ## 约束 必须逐字同步本块，不得在副本中改写公共规则。

  • 任务需要落盘时，使用唯一的 ./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/ 根目录；共享材料放入 shared/，Skill 专属材料放入该 Skill 的 input/、output/、log/。
  • 正式交付物、源代码和正式计划按项目约定保存，不写入任务工作区；未经授权不覆盖、删除、迁移或远程写入。
  • 项目维护变更检查 BAC 可用性并记录需求、AI 产出、工具结果、文件改动和验证摘要；BAC 只做过程审计，不替代署名、责任或合规判断。
  • 不记录 API Key、访问令牌、密码、Cookie、环境/凭据文件、私有 Prompt、身份信息、本地用户名、主机名或不必要的大体积原始数据。
  • 文件路径必须规范化并限制在授权项目范围内；外部 URL、子进程和网络访问遵循最小权限，防止路径遍历、SSRF 和命令注入。
  • Skill 版本唯一记录在自身 config.yaml:skill_info.version；公开 API、协议、目录或配置变更同步文档与 CHANGELOG.md。
  • bensz-collect-bugs 是一个 Agent Skill；仅将 Bensz Agent Skill 或 Bensz 基础设施本身的设计缺陷交给它。先脱敏写入 ~/.bensz-skills/bugs/，当前任务不中断，只有用户明确要求才公开上报，禁止直接修改用户已安装的 Skill 源码。
Files (skills)
  • references
    • prompt-program
      • examples.md 3.8 KB 
        # Prompt Program 示例

## 示例 1：信息抽取

原始 prompt：

```text
读这份会议纪要，提炼关键决策、待办事项和负责人，如果有不确定的信息就标记出来。
```

Prompt Program：

```text
程序：会议纪要结构化提取

目标：从会议纪要中提炼关键决策、待办事项和负责人，并显式标记不确定信息。
输入：一份会议纪要文本。
输出：结构化摘要，至少包含“决策”“待办”“负责人”“不确定项”。

约束：
- 必须保留证据导向。
- 不要把猜测写成事实。

流程：
1. 识别纪要中的决策、任务和责任归属。
2. 对每个待办事项绑定负责人；若缺失，则标记为未明确。
3. 将结果整理为结构化摘要。

校验：
- 在输出前，核对每个结论是否能在原文中找到依据。

缺口处理：
- 若信息不足，则显式标记“不确定”或“未明确”。

返回：
- 返回结构化摘要。
```

## 示例 2：代码生成要求

原始 prompt：

```text
帮我写个 Python 脚本，把一个目录下面的 CSV 全合并，去掉重复行，坏数据单独记录，最后给个简短报告。
```

Prompt Program：

```text
程序：CSV 批量合并脚本设计

目标：生成一个 Python 脚本，用于批量合并 CSV、去重、记录异常数据，并输出简短报告。
输入：一个包含多个 CSV 文件的目录。
输出：一个可执行的 Python 脚本，以及脚本运行后生成的简短处理报告。

约束：
- 必须显式处理重复行。
- 必须记录异常数据。
- 不要省略最终报告步骤。

流程：
1. 遍历目标目录中的 CSV 文件。
2. 对每个文件读取数据并做基础格式检查。
3. 若行数据有效，则纳入合并结果；否则写入异常记录。
4. 合并全部有效数据后执行去重。
5. 最后生成简短报告，说明处理文件数、保留行数和异常情况。

校验：
- 在输出前，核对主流程是否覆盖“遍历、读取、去重、异常记录、报告”五个环节。

缺口处理：
- 若输入目录为空或文件格式不一致，则要求显式给出处理策略。

返回：
- 返回脚本及其报告产物说明。
```

## 示例 3：文献分析

原始 prompt：

```text
分析这些论文摘要，按主题分组，比较每组方法差异，再总结趋势和空白。
```

Prompt Program：

```text
程序：论文摘要主题比较

目标：基于一组论文摘要完成主题分组、方法比较、趋势总结和空白识别。
输入：多篇论文摘要。
输出：按主题组织的分析结果。

流程：
1. 读取全部摘要并抽取主题线索。
2. 按主题对摘要分组。
3. 对每个主题组比较方法路径、优势和局限。
4. 基于跨组比较总结整体趋势与研究空白。

校验：
- 在输出前，核对每个趋势结论是否来自跨组比较而非单篇印象。

返回：
- 返回按主题组织的综合分析。
```

## 示例 4：保留显式格式契约

原始 prompt：

```text
把下面的产品反馈整理成 JSON，字段必须是 sentiment、issues、quotes、next_actions；如果证据不足，sentiment 要填 unknown。
```

Prompt Program：

```text
程序：产品反馈 JSON 结构化整理

目标：将产品反馈整理为固定字段的 JSON 结果。
输入：一组产品反馈文本。
输出：JSON 对象，字段必须为 `sentiment`、`issues`、`quotes`、`next_actions`。

约束：
- 必须保留指定字段名，不要改写字段。
- 若证据不足，`sentiment` 必须填 `unknown`。

流程：
1. 读取反馈并识别情绪、问题、原话证据和后续动作。
2. 将识别结果映射到指定 JSON 字段。

校验：
- 在输出前，核对字段名是否完整且拼写一致。

返回：
- 返回上述 JSON 输出。
```
      • primitives.md 2.1 KB 
        # Prompt Program 原子与块

Prompt Program 方言不发明真正的编程语言；它只用一组稳定原子，把 prompt 压缩成“可编程的人类自然语言”。

## 六个原子

| 原子 | 回答的问题 | 常见承载内容 | 常见写法 |
|------|------------|--------------|----------|
| `Entity` | 有什么 | 角色、输入、输出对象、工具、受众、状态 | `定义：输入材料为……` |
| `Intent` | 要达成什么 | 目标任务、交付物、成功标准 | `目标：生成……` |
| `Operation` | 要做什么 | 分析、提取、生成、重写、比较、规划 | `先……，再……。` |
| `Constraint` | 边界是什么 | 必须项、禁止项、偏好、格式、长度 | `约束：必须……` |
| `Control` | 逻辑怎样流动 | 条件、循环、顺序、回退、优先级 | `若……，则……；否则……。` |
| `Check` | 如何确认成立 | 校验、异常处理、缺口处理、结束条件 | `在输出前，核对……。` |

## 块与原子的映射

| 渲染块 | 主导原子 |
|--------|---------|
| `程序` | Intent |
| `目标` | Intent |
| `输入` | Entity |
| `输出` | Intent + Entity |
| `定义` | Entity |
| `约束` | Constraint |
| `流程` | Operation + Control |
| `校验` | Check |
| `缺口处理` | Control + Check |
| `返回` | Intent + Check |

## `输出` 与 `返回`

- `输出` 回答“最终要得到什么”。
- `返回` 回答“如何交付这个结果”。
- `返回` 不能新增产物，只能引用、交付或封装 `输出`。
- 如果 `返回` 只是机械复述，可写成 `返回上述输出。`

## 最小合格条件

一个合格的 Prompt Program 至少要让读者看见：

1. 目标是什么
2. 输入从哪里来
3. 输出要长成什么样
4. 主流程怎么走
5. 输出前如何核对

## 块省略规则

- `程序`：任务名没有额外价值时可省略。
- `定义`：没有关键术语、角色或状态绑定时可省略。
- `缺口处理`：不存在高风险缺口时可省略。
- `约束`：可并入 `目标` 或 `流程`，但显式格式契约不能丢。
      • translation-rules.md 1.2 KB 
        # Prompt Program 翻译规则

## 输入验证

- 空输入：拒绝翻译，要求用户提供原始 prompt。
- 过短输入：说明信息不足，不输出伪完整结构。
- 非 prompt 型输入：说明该输入不适合 prompt 优化，要求提供真正的 prompt。

## 控制流推断

- 只在两种情况下补写控制流：
  - 原 prompt 显式给出条件、循环或回退
  - 原 prompt 存在强隐含控制，如“每个样本”“若证据不足”“直到满足要求”
- 不允许为了“更像程序”凭空添加分支、循环或异常路径。

## 输出保真

- 显式格式契约必须保留，如 JSON、表格、字段名、章节顺序、列表结构、字数要求。
- 若原 prompt 显式规定字段、章节或步骤顺序，默认保持该顺序。
- 关键实体名、变量名、数据集名和术语默认保留。
- 只能压缩修辞，不能压缩契约。

## 冲突处理顺序

1. 核心意图
2. 硬约束
3. 输出契约
4. 校验要求
5. 风格偏好

## 块省略

- 默认省略空块。
- `输出` 与 `返回` 必须语义不同：前者定义产物，后者定义交付动作。
- 如果 `返回` 仅是机械复述，可写成 `返回上述输出。`
    • prompt-engineering-best-practices.md 6.6 KB 
      # Prompt 工程最佳实践详解

本文档整理自 OpenAI 和 Anthropic 官方文档，提供详细的 Prompt 优化指南。

## 官方文档来源

- [OpenAI Prompt Engineering Guide](https://platform.openai.com/docs/guides/prompt-engineering)
- [Anthropic Prompt Engineering Overview](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview)

## 核心技术详解

### 1. 清晰直接（Be Clear and Direct）

**原则**：用最简洁的语言表达最明确的意图。

**检查清单**：
- [ ] 核心任务是否一句话能说清？
- [ ] 是否存在可能产生歧义的词汇？
- [ ] 指令是否足够具体？

**优化示例**：

| 原始 | 优化后 |
|------|--------|
| "帮我写点东西" | "请帮我写一封 200 字以内的商务邮件，主题是项目进度汇报" |
| "分析这个数据" | "请分析这份销售数据，重点关注：1）月度趋势；2）top 5 产品；3）异常值" |

### 2. 结构化组织（Use XML Tags / Markdown）

**原则**：使用结构化标记帮助模型理解内容边界和层级。

**推荐结构**：

```markdown
# Identity
[角色定义]

# Instructions
[核心指令]

## Sub-tasks（如需要）
[子任务分解]

# Examples
<example id="1">
<input>...</input>
<output>...</output>
</example>

# Context
<document name="reference">
[参考内容]
</document>
```

**XML 标签使用场景**：

| 场景 | 推荐标签 |
|------|---------|
| 示例 | `<example>`, `<input>`, `<output>` |
| 文档引用 | `<document>`, `<reference>` |
| 思考过程 | `<thinking>`, `<analysis>` |
| 约束条件 | `<constraints>`, `<rules>` |

### 3. Few-shot Learning（示例驱动）

**原则**：通过输入输出示例展示期望的模式。

**最佳实践**：
- 提供 2-5 个高质量示例
- 示例应覆盖典型场景和边界情况
- 输入输出格式保持一致

**示例模板**：

```xml
# Examples

<example id="1">
<input>
客户反馈：这款产品质量很好，但物流太慢了。
</input>
<output>
{"sentiment": "mixed", "aspects": {"quality": "positive", "logistics": "negative"}}
</output>
</example>

<example id="2">
<input>
客户反馈：非常满意，下次还会购买！
</input>
<output>
{"sentiment": "positive", "aspects": {"overall": "positive"}}
</output>
</example>
```

### 4. 角色定义（Give Claude a Role）

**原则**：为 AI 分配明确的角色和专业领域。

**有效角色定义示例**：

```markdown
# Identity

你是一位资深软件架构师，专注于分布式系统设计。你有 15 年的大规模系统开发经验，擅长：
- 微服务架构设计
- 高可用系统构建
- 性能优化和瓶颈分析

你的沟通风格是：简洁、技术性强、注重实际可行性。
```

### 5. 思考链（Chain of Thought）

**原则**：引导模型逐步思考复杂问题。

**触发方式**：

```markdown
# Instructions

请按以下步骤分析：
1. 首先，识别问题的核心要素
2. 然后，分析各要素之间的关系
3. 接着，评估可能的解决方案
4. 最后，给出推荐方案及理由

在给出最终答案前，请展示你的思考过程。
```

### 6. 约束条件（Constraints）

**原则**：明确边界，防止不期望的输出。

**约束类型**：

| 类型 | 示例 |
|------|------|
| **格式约束** | "输出必须是 JSON 格式" |
| **长度约束** | "回答不超过 100 字" |
| **内容约束** | "不要包含代码实现" |
| **风格约束** | "使用正式的商务语气" |
| **边界约束** | "只讨论技术层面，不涉及商业决策" |

## 模型类型适配

### GPT 模型优化策略

GPT 模型（如 gpt-4、gpt-3.5）需要精确指令：

```markdown
# Instructions

任务：将用户输入转换为结构化数据

步骤：
1. 读取用户输入
2. 识别关键实体（人名、地点、时间）
3. 提取关系
4. 输出 JSON 格式

输出格式：
{
  "entities": [...],
  "relations": [...]
}

规则：
- 如果信息不完整，用 null 填充
- 日期统一转换为 YYYY-MM-DD 格式
- 人名使用全称
```

### 推理模型优化策略

推理模型（如 o1、o3）只需高层指导：

```markdown
# Goal

分析用户的问题，找出最佳解决方案。

# Context
[背景信息]

# Success Criteria
- 方案可行且具体
- 考虑了边界情况
- 提供了清晰的执行步骤
```

## 场景专项指南

### 代码生成

```markdown
# Identity
你是一位精通 [语言] 的软件工程师。

# Instructions
请编写一个 [功能描述] 的 [语言] 函数。

## Requirements
- 使用 [框架/库]
- 遵循 [编码规范]
- 包含错误处理
- 添加类型注解

## Constraints
- 不使用第三方库（除非指定）
- 函数长度不超过 50 行
- 必须包含 docstring

# Examples
<example>
<input>实现一个去重函数</input>
<output>
```python
def unique(items: list) -> list:
    """返回列表中的唯一元素，保持原始顺序。"""
    seen = set()
    return [x for x in items if not (x in seen or seen.add(x))]
```
</output>
</example>
```

### 文本分析

```markdown
# Identity
你是一位文本分析专家，专注于情感分析和主题提取。

# Instructions
分析给定文本，输出：
1. 情感倾向（positive/negative/neutral）
2. 主要主题（top 3）
3. 关键词（top 5）

# Output Format
```json
{
  "sentiment": "...",
  "topics": ["...", "...", "..."],
  "keywords": ["...", "...", "...", "...", "..."]
}
```

# Examples
[提供 2-3 个示例]
```

### 创意写作

```markdown
# Identity
你是一位专业文案撰写人，擅长 [领域]。

# Instructions
撰写一篇 [类型] 文案。

## Style Guide
- 语调：[正式/轻松/专业/友好]
- 目标受众：[描述]
- 文案长度：[字数]

## Key Messages
- [要点 1]
- [要点 2]
- [要点 3]

## Constraints
- 避免使用 [禁止词汇/表达]
- 包含 [必要元素]
```

## 常见问题与解决方案

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| 输出格式不稳定 | 格式约束不明确 | 添加明确的输出格式模板和示例 |
| 回答偏离主题 | 任务定义模糊 | 重写 Identity 和 Instructions |
| 信息遗漏 | 上下文不完整 | 补充必要的背景信息 |
| 风格不一致 | 缺少风格约束 | 添加 Style Guide |
| 长度失控 | 缺少长度约束 | 添加明确的字数/行数限制 |

## 质量检查清单

在提交优化后的 prompt 前，确认：

- [ ] Identity 清晰定义了角色和专业领域
- [ ] Instructions 明确说明了任务和规则
- [ ] Examples 提供了足够的参考模式
- [ ] Context 包含了必要的背景信息
- [ ] Constraints 定义了清晰的边界
- [ ] Output Format 明确了期望的格式
- [ ] 整体结构清晰，易于理解
  • CHANGELOG.md 3.3 KB 
    # Changelog

All notable changes to this skill will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [0.3.0] - 2026-09-06

### Added（新增）
- 新增 `prompt_program` 输出模式：将原 beta 源 `prompt-programming` skill 整体融入，把 prompt 严格等价翻译为伪代码式 Prompt Program 方言；原 skill 目录同步删除
- 新增"语义分析原子"：6 个语义原子（Entity/Intent/Operation/Constraint/Control/Check）作为两种输出模式共用的统一分析内核，重构原 Step 1 的三问分析
- 新增"输出模式选择"章节：定义 standard/prompt_program 的触发边界与模式互斥规则
- 新增 prompt_program 模式专属规则：等价性原则、控制流推断、冲突处理顺序、缺口处理
- 新增 `references/prompt-program/`：原子与块定义（primitives.md）、翻译规则（translation-rules.md）、典型示例（examples.md），细节下沉不在 SKILL.md 展开
- config.yaml 新增 `output_modes` 配置节：默认模式与 prompt_program 的 kernel/rendering/translation/quality_bar 参数

### Changed（变更）
- 规范化 `SKILL.md` 正文骨架，补齐输入、输出、校验、失败恢复和公共约束摘要；better-prompt 的既有功能语义保持不变
- `SKILL.md` 的 description 与"目标"章节扩展双模式触发词（伪代码、程序结构、可编程自然语言）
- 输入验证支持 prompt_program 模式的独立阈值（`min_length: 6`）与非 prompt 型输入拒绝
- 校验章节拆分为两种模式各自的质量标准：standard 沿用五维度评分，prompt_program 使用等价性五条标准
- config.yaml 版本号升级：0.2.0 → 0.3.0

## [0.2.0] - 2026-02-18

### Added
- 添加 Step 0 输入验证：定义空输入、过短输入、已完善 prompt 的处理方式
- 添加"版本与兼容性"章节：说明适用的模型和最佳实践来源
- 添加"不适用场景"章节：明确何时不应使用本技能
- 添加"优化效果评估"章节：提供优化前后对比评估表
- 添加 Examples 使用规则：明确复杂任务必须提供示例
- config.yaml 添加 `validation` 配置：输入验证阈值
- config.yaml 添加 `include_evaluation` 配置：控制效果评估输出

### Changed
- 统一优先级系统：在 SKILL.md 中明确说明 P0/P1/P2 与 config.yaml 数值的对应关系
- 修复 Examples "可选"描述：改为"复杂任务必需，简单任务可省略"
- 激活 templates 配置引用：在 SKILL.md 的"特殊场景处理"章节中引用 config.yaml 的模板
- config.yaml 添加完整注释：每个配置项都有说明
- config.yaml 版本号升级：0.1.0 → 0.2.0

### Fixed
- 修复跨文件一致性问题：SKILL.md 与 config.yaml 的优先级描述现在一致
- 修复 output_format 配置与文档的矛盾：现在明确"默认全部包含"

## [0.1.0] - 2026-02-18

### Added
- 初始化 better-prompt 技能
- 实现基于 OpenAI 和 Anthropic 官方最佳实践的优化框架
- 支持五维度优化：清晰度、完整性、结构化、示例性、约束性
- 支持模型类型适配（GPT 模型 vs 推理模型）
- 支持场景专项优化（代码生成、文本分析、创意写作、多轮对话）
- 添加详细的最佳实践参考文档
  • config.yaml 6.1 KB 
    # better-prompt 技能配置文件
#
# 说明：
# - 本文件定义可配置参数，作为"精确端"（单一真相来源）
# - SKILL.md 作为"模糊端"（工作文档），引用本文件的配置

# ============================================================================
# 技能基本信息
# ============================================================================

skill_info:
  name: better-prompt
  version: 0.3.0  # 本次融合 prompt-programming 后版本
  description: "将简陋的 prompt 优化为符合社区最佳实践的高质量版本，或翻译为 Prompt Program 方言"
  author: "Bensz Conan"
  category: "内容优化"

# ============================================================================
# 优化配置
# ============================================================================

optimization:
  # 默认目标模型类型（用户未指定时使用）
  # 可选值：gpt（精确执行）| reasoning（复杂推理）
  default_model_type: "gpt"

  # 优化维度优先级
  # 说明：数值 1-5 对应 SKILL.md 中的 P0/P1/P2（5=P0, 4=P1, 3=P2）
  #       数值越高，优化时越优先关注
  dimensions:
    clarity: 5       # 清晰度（P0）
    completeness: 5  # 完整性（P0）
    structure: 4     # 结构化（P1）
    examples: 3      # 示例性（P2）
    constraints: 3   # 约束性（P2）

  # 输出格式配置
  # 说明：控制输出中是否包含各部分内容
  output_format:
    include_analysis: true    # 包含优化分析表格
    include_evaluation: true  # 包含优化效果评估（新增）
    include_suggestions: true # 包含使用建议

  # 输入验证阈值
  validation:
    min_length: 10          # 最小输入字符数
    quality_threshold: 8    # 已完善 prompt 的评分阈值（/10）

# ============================================================================
# 场景模板配置
# ============================================================================

# 说明：以下模板定义了不同场景下的优化重点
#       在 SKILL.md 的"特殊场景处理"章节中引用

templates:
  code_generation:
    # 代码生成类 prompt 的优化重点
    focus_areas:
      - language_framework  # 编程语言和框架
      - coding_style        # 代码风格规范
      - error_handling      # 错误处理要求
      - edge_cases          # 边界条件示例

  text_analysis:
    # 文本分析类 prompt 的优化重点
    focus_areas:
      - output_format       # 输出格式
      - analysis_dimensions # 分析维度
      - classification_criteria  # 分类标准

  creative_writing:
    # 创意写作类 prompt 的优化重点
    focus_areas:
      - style_tone          # 风格和语调
      - target_audience     # 目标受众
      - length_constraints  # 长度约束

  multi_turn_conversation:
    # 多轮对话类 prompt 的优化重点
    focus_areas:
      - role_definition     # 角色定义
      - state_management    # 状态管理
      - exception_handling  # 异常处理

# ============================================================================
# 输出模式配置
# ============================================================================

# 说明：better-prompt 支持两种输出模式
#   - standard：增强导向，补全缺失要素，输出最佳实践散文结构
#   - prompt_program：保真导向，严格等价翻译，输出伪代码式块结构
#   模式选择规则见 SKILL.md；一次任务只使用一种模式

output_modes:
  # 用户未指定输出形式时的默认模式
  default: "standard"

  # prompt_program 模式：由原 prompt-programming skill 融合而来
  prompt_program:
    kernel:
      dialect_name: "Prompt Program"
      default_language: "zh-CN"
      # 6 个语义原子，同时作为 Step 1 语义分析的统一工具
      semantic_atoms:
        - entity
        - intent
        - operation
        - constraint
        - control
        - check

    rendering:
      block_order:
        - program
        - goal
        - input
        - output
        - definition
        - constraint
        - flow
        - validation
        - gap_handling
        - return
      optional_blocks:
        - program
        - definition
        - gap_handling
      omit_empty_blocks: true
      required_blocks:
        - goal
        - input
        - output
        - flow
        - validation
        - return
      block_semantics:
        output: "目标产物、目标格式或目标效果"
        return: "对 output 的交付动作；不得引入新产物"
      sentence_patterns:
        flow:
          - "执行：把 A 转换为 B。"
          - "先……，再……，最后……。"
          - "若 X 成立，则……；否则……。"
          - "对每个 X，执行……。"
          - "重复……，直到……为止。"
        validation:
          - "在输出前，核对……。"
          - "确认……满足……。"
        gap_handling:
          - "若信息不足，则先……；仍不足时……。"
          - "若存在冲突，则保留冲突并显式标注。"
        return:
          - "返回上述输出。"
          - "最终交付……。"

    translation:
      default_output_mode: "final_only"
      # prompt_program 模式的输入验证；与 optimization.validation 独立
      input_validation:
        min_length: 6
        reject_non_prompt_like_input: true
      infer_low_risk_context: true
      expose_high_risk_gaps: true
      keep_domain_terms: true
      preserve_output_contract: true
      preserve_explicit_format: true
      preserve_sequence_constraints: true
      strip_social_filler: true
      control_inference_policy: "only_when_explicit_or_strongly_implied"
      conflict_resolution_order:
        - core_intent
        - hard_constraints
        - output_contract
        - validation_requirements
        - style_preferences

    quality_bar:
      must_include_control_when_present: true
      must_include_validation: true
      must_preserve_core_intent: true
      max_redundant_constraints: 2
      soft_sentence_budget: 18
      relax_budget_when_complex: true
  • README.md 4.6 KB 
    # Better Prompt

这个 skill 用来把简陋、含糊或结构松散的 prompt 重构成更清晰、更可执行的高质量版本，或把它严格等价翻译成伪代码式的 Prompt Program；如果你只想做概念讨论，或者明确要求完全保留原风格，就不一定要用它。

它有两种输出模式：

- **standard（默认）**：增强导向。补全缺失的约束、示例和上下文，输出符合最佳实践的散文式结构。
- **prompt_program**：保真导向。不新增无依据能力，把 prompt 翻译成“形式像伪代码、语义是自然语言”的块结构（程序/目标/输入/输出/约束/流程/校验/返回）。

## 用法

### 最推荐用法（standard 模式）

```text
请使用 better-prompt skill 优化下面这段 prompt。
输入：原始 prompt 文本
输出：优化分析、优化后的高质量 prompt，以及必要的使用建议
```

### 进阶用法

```text
请使用 better-prompt skill 优化下面这段 prompt。
输入：原始 prompt 文本
输出：优化后的 prompt
另外，还有下列参数约束：
- 目标模型：reasoning
- 保留原始语气：是
- 必须补充示例：是
```

### 伪代码翻译用法（prompt_program 模式）

```text
请使用 better-prompt skill 把下面这段 prompt 翻译成 Prompt Program（伪代码式结构）。
输入：原始 prompt 文本
输出：最终 Prompt Program
```

只要在请求中出现“伪代码”“程序结构”“可编程自然语言”等表述，就会自动进入该模式；一次任务只会使用一种模式。

## 能做什么

- 优先优化清晰度、完整性和结构化表达。
- 在需要时补充约束条件、示例和上下文。
- 区分偏执行型的 GPT 风格 prompt 和偏复杂推理的 reasoning 风格 prompt。
- 默认同时给出分析、优化结果和使用建议。
- 把 prompt 严格等价翻译成 Prompt Program：保留原意和格式契约，显式化分支、循环与校验，压缩冗余修辞。
- 不适合已经非常成熟的 prompt，或超长到需要先拆分的信息包。

## 使用示例

### 示例 1：优化一个简单任务型 prompt

```text
请使用 better-prompt skill 优化下面的 prompt。
输入：帮我写一个脚本处理 CSV
输出：优化分析和优化后的 prompt
```

### 示例 2：优化代码生成 prompt

```text
请使用 better-prompt skill 优化下面的代码生成 prompt。
输入：给我写一个 Python 爬虫
输出：优化后的结构化 prompt
另外，还有下列参数约束：
- 目标模型：gpt
- 必须明确输入输出和错误处理
```

### 示例 3：优化复杂推理 prompt

```text
请使用 better-prompt skill 优化下面的 prompt。
输入：请帮我分析一个复杂商业决策问题
输出：优化分析、优化后的 prompt 和使用建议
另外，还有下列参数约束：
- 目标模型：reasoning
- 给高层目标，不要写过死的步骤
```

## 输出

- `优化分析`：说明原 prompt 的主要问题和改进点（standard 模式）。
- `优化后的 prompt`：可直接复制使用的结果（standard 模式）。
- `使用建议`：告诉你哪些内容可以按场景继续微调（standard 模式）。
- `Prompt Program`：伪代码式块结构结果，默认只输出结果本身、不带长篇分析（prompt_program 模式）。
- 默认不会替你执行 prompt 对应任务，它的职责是把 prompt 本身优化好。

## 配置

- 配置文件：`better-prompt/config.yaml`
- 默认目标模型类型：`gpt`
- 最小输入长度：`10`
- “已足够完善”的默认阈值：`8/10`
- 默认输出包含：
  - `analysis`
  - `evaluation`
  - `suggestions`

## 常见问题

### Q：优化后的 prompt 变长了，是不是越长越好？

A：不是。更长只是为了更清楚、更可执行。真正目标是信息充分且结构合理，不是单纯堆字数。

### Q：我还需要把优化后的 prompt 全部照搬吗？

A：不一定。你可以保留核心结构，再按自己的任务、语气和平台微调。

### Q：它会区分 GPT 模型和推理模型吗？

A：会。默认更偏 `gpt` 风格；如果任务更依赖开放式推理，可以显式要求 `reasoning` 风格。

### Q：什么时候不该用它？

A：当你的 prompt 已经很成熟、只是想做小改动，或者明确要求保留原始写法时，就不一定要用这个 skill。

### Q：standard 和 prompt_program 两种模式有什么区别？

A：standard 允许补全信息，目标是“更完整、更专业”；prompt_program 严格保真，目标是“结构像程序、语义不变”。想要让 AI 更好地执行任务，用 standard；想要审视和讨论 prompt 的逻辑骨架，用 prompt_program。
  • SKILL.md 15.5 KB 
    ---
name: better-prompt
description: 当用户明确要求"优化 prompt"、"改进提示词"、"润色指令"、"将简陋 prompt 转换为最佳实践版本"，或要求"把 prompt 改写成伪代码"、"翻译成程序结构/可编程自然语言"时使用。支持两种输出模式：standard（基于 OpenAI/Anthropic 官方最佳实践做增强优化）与 prompt_program（严格等价翻译为 Prompt Program 方言）。
metadata:
  author: Bensz Conan
  keywords:
    - better-prompt
    - prompt optimization
    - prompt engineering
    - prompt programming
    - 提示词优化
    - 提示词编程
---

# Better Prompt - Prompt 优化器

## 目标

当用户明确要求"优化 prompt"、"改进提示词"、"润色指令"、"将简陋 prompt 转换为最佳实践版本"，或要求"把 prompt 改写成伪代码"、"翻译成程序结构/可编程自然语言"时使用。

本技能提供两种输出模式：

- **standard（默认）**：增强导向。基于 OpenAI 和 Anthropic 官方最佳实践，对简陋 prompt 进行结构化补全，输出高质量版本；允许补充示例、上下文和约束。
- **prompt_program**：保真导向。将原始 prompt 严格等价翻译为 Prompt Program 方言——形式上像伪代码，语义上仍是人类自然语言；不新增无依据能力。

两种模式共享同一套语义分析内核（6 个语义原子），只差输出渲染方式。本技能不负责执行 prompt 对应的任务本身。

## 流程

### 输入

#### 输入要求

用户提供一个待优化的原始 prompt（可以是任意形式的简陋版本）。

### 执行步骤

#### 版本与兼容性

- **适用于**：Claude 3.x/4.x、GPT-4/5、Gemini 等主流 LLM
- **最佳实践来源**：OpenAI/Anthropic 官方文档（2026-02）
- **更新策略**：官方文档重大更新时同步修订

#### 不适用场景

以下情况不建议使用本技能：

- prompt 已经经过专业优化（评分 ≥ 8/10）
- 只需要诊断问题，不需要修改建议
- 超长 prompt（>10000 字）需要专业拆分
- 用户明确要求保持原始风格
- 用户只想执行任务，不关心 prompt 本身的质量或结构

#### 优化框架

standard 模式基于 **OpenAI** 和 **Anthropic** 官方最佳实践，采用五维度优化框架：

| 维度 | 检查点 | 优先级 |
|------|--------|--------|
| **清晰度** | 指令是否明确？是否存在歧义？ | P0 |
| **完整性** | 是否缺少必要信息？上下文是否充分？ | P0 |
| **结构化** | 是否使用 Markdown/XML 标签组织内容？ | P1 |
| **示例性** | 是否提供输入输出示例（few-shot）？ | P2 |
| **约束性** | 是否明确边界（做什么/不做什么）？ | P2 |

> **注意**：上表的 P0/P1/P2 表示"优化维度的重要性优先级"，与 config.yaml 中的 `dimensions` 数值（1-5）含义相同：P0=5（最高优先级）、P1=4、P2=3。

#### 输出模式选择

在分析完成后、生成结果前，按以下规则选择输出模式：

| 用户请求特征 | 输出模式 |
|-------------|---------|
| 要求"伪代码"、"程序结构"、"可编程自然语言"，或直接提到 Prompt Program | prompt_program |
| 其它优化/润色/改进请求（未指定输出形式） | standard（默认） |

- 一次任务只使用一种模式，不混合输出。
- 未指定形式时默认 standard，并在使用建议中提示可切换为 prompt_program。
- 默认模式由 `config.yaml:output_modes.default` 控制。

#### 优化工作流

##### Step 0: 输入验证（前置检查）

验证用户输入的有效性：

| 输入状态 | 判断标准 | 处理方式 |
|---------|---------|---------|
| **空输入** | 字符数 = 0 | 拒绝，提示"请提供待优化的 prompt" |
| **过短** | 字符数 < 10 | 提示"prompt 过短，请提供更多上下文" |
| **已完善** | 评分 ≥ 8/10 | 提示"prompt 已足够完善，是否仍需优化？"，等待用户确认 |
| **有效** | 通过验证 | 继续 Step 1 |

prompt_program 模式下，非 prompt 型输入（完整代码实现请求等）直接说明不适合翻译，要求提供真正的 prompt；其最小输入长度阈值（6）由 `config.yaml:output_modes.prompt_program.translation.input_validation.min_length` 独立控制。

##### Step 1: 语义分析（6 原子）

用 6 个语义原子解析原始 prompt，作为两种输出模式共用的统一分析内核（原子定义与块映射详见 [references/prompt-program/primitives.md](references/prompt-program/primitives.md)）：

| 原子 | 回答的问题 | 典型内容 |
|------|-----------|---------|
| **Entity** | 有什么 | 角色、输入、输出对象、工具、状态 |
| **Intent** | 要达成什么 | 目标、交付物、成功条件 |
| **Operation** | 要做什么 | 核心动作链 |
| **Constraint** | 边界是什么 | 必须、禁止、偏好、格式 |
| **Control** | 逻辑怎样流动 | 条件、分支、循环、回退 |
| **Check** | 如何确认成立 | 校验、验收、结束条件 |

分析产出三项结论：

- **原子清单**：每个原子在原 prompt 中已有的内容
- **缺失要素**：哪些原子无内容或信息不完整
- **改进空间**：哪些地方可以优化

> **6 原子与五维度的关系**：6 原子是**语义解析视角**（原 prompt 里有什么），五维度是**质量优化视角**（standard 模式下优化到什么程度）。分析用原子，评分用维度。

##### Step 2: 确定模型类型适配（仅 standard 模式）

根据任务特性判断目标模型类型：

| 模型类型 | 适用场景 | 优化策略 |
|---------|---------|---------|
| **GPT 模型** | 精确执行、格式化输出、代码生成 | 提供详细步骤和明确逻辑 |
| **推理模型** | 复杂推理、多步规划、开放性任务 | 给高层目标，保留灵活性 |

如果用户未指定，默认按 GPT 模型优化策略处理（更精确）。

##### Step 3: 按模式应用优化模板

**standard 模式**——优化后 prompt 的标准结构模板：

```
# Identity（身份定义）
[描述 AI 的角色、专业领域、沟通风格]

# Instructions（核心指令）
[明确的任务说明]
- 规则 1
- 规则 2
- 约束条件（不做什么）

# Examples（示例）
<example id="1">
<input>示例输入</input>
<output>示例输出</output>
</example>

# Context（上下文）
[任务相关的背景信息、参考资料]
```

> **Examples 的使用规则**：
> - 对于复杂任务（复杂度 ≥ 3/5），Examples 是**必需的**
> - 对于简单任务，Examples 可以省略
> - 如原始 prompt 已有示例，优化时应保留或增强

**prompt_program 模式**——按 `config.yaml:output_modes.prompt_program.rendering.block_order` 输出块结构：

```text
程序：……（可选）

目标：……
输入：……
输出：……

定义：（可选）
- ……

约束：
- 必须……
- 优先……
- 不要……

流程：
1. ……
2. 若……，则……；否则……。
3. 对每个……，执行……。

校验：
- ……

缺口处理：（可选）
- 若信息不足，则……

返回：
- ……
```

渲染必守规则：

- `输出` 只定义目标产物、目标格式或目标效果
- `返回` 只定义对 `输出` 的交付动作，不能引入新产物
- `程序`、`定义`、`缺口处理` 属于可选块；为空就省略（`omit_empty_blocks=true` 时禁止补空块）
- 组织顺序：先边界后执行、先主流程后异常路径、先硬约束后风格偏好
- 若原 prompt 缺少显式校验，必须补出最小可执行校验
- 用户指定的字段、章节或步骤顺序默认保持原顺序；关键术语、变量名、实体名默认保留原词

##### Step 4: 输出优化结果

**standard 模式**输出包含三个部分（默认全部包含，可通过 config.yaml 调整）：

1. **优化分析**：简要说明做了哪些改进
2. **优化后的 prompt**：符合最佳实践的高质量版本
3. **使用建议**：针对特定场景的调整建议

**prompt_program 模式**默认只输出最终 Prompt Program，不附带长篇分析（`translation.default_output_mode: final_only`）。

#### prompt_program 模式专属规则

以下规则只约束 prompt_program 模式，不适用于 standard 模式：

**等价性原则**：

- 允许重排表达，不允许改变目标
- 允许补出隐式流程，不允许新增无依据能力
- 允许强化校验，不允许削弱关键约束
- 允许压缩表述，不允许丢失显式格式契约
- 允许补足交付动作，不允许把"输出"偷换成"输出说明书"

**控制流推断**：

- 只在原 prompt 显式给出条件/循环/回退，或存在强隐含控制（如"每个样本"、"若证据不足"）时补写控制流
- 不允许为了"更像程序"凭空添加分支、循环或异常路径

**冲突处理顺序**（冲突时严格遵循 `config.yaml:output_modes.prompt_program.translation.conflict_resolution_order`）：

1. 核心意图
2. 硬约束
3. 输出契约
4. 校验要求
5. 风格偏好

**缺口处理**：

- 可用常识低风险补足时，直接补足并体现在结构中
- 缺失信息会改变任务本质时，在 `缺口处理` 块中显式标注，不擅自虚构
- 默认不频繁追问；只有任务语义无法成立时才要求澄清

详细翻译规则见 [references/prompt-program/translation-rules.md](references/prompt-program/translation-rules.md)。

#### 优化效果评估

**standard 模式**对优化前后的 prompt 进行对比评估：

| 维度 | 优化前评分 | 优化后评分 | 改进说明 |
|------|-----------|-----------|---------|
| 清晰度 | x/5 | x/5 | ... |
| 完整性 | x/5 | x/5 | ... |
| 结构化 | x/5 | x/5 | ... |
| 示例性 | x/5 | x/5 | ... |
| 约束性 | x/5 | x/5 | ... |
| **总分** | **xx/25** | **xx/25** | **+xx** |

> **评分标准**：1=很差、2=较差、3=一般、4=良好、5=优秀

**prompt_program 模式**不使用上述评分表，改用等价性五条质量标准（见"校验"章节）。

#### 特殊场景处理（仅 standard 模式）

根据 config.yaml 中的 `templates` 配置，针对不同场景有特定的优化重点：

##### 代码生成类 prompt

**配置引用**：`config.yaml:templates.code_generation.focus_areas`

额外关注：
- 明确编程语言和框架
- 指定代码风格规范
- 说明错误处理要求
- 提供边界条件示例

##### 文本分析类 prompt

**配置引用**：`config.yaml:templates.text_analysis.focus_areas`

额外关注：
- 明确输出格式（JSON/表格/摘要）
- 定义分析维度和标准
- 提供分类/评估示例

##### 创意写作类 prompt

**配置引用**：`config.yaml:templates.creative_writing.focus_areas`

额外关注：
- 定义风格和语调
- 说明目标受众
- 提供参考示例
- 设置长度约束

##### 多轮对话类 prompt

**配置引用**：`config.yaml:templates.multi_turn_conversation.focus_areas`

额外关注：
- 定义对话角色和边界
- 说明状态管理要求
- 提供异常处理规则

#### 参考资料

更多详细的最佳实践，参考 [references/prompt-engineering-best-practices.md](references/prompt-engineering-best-practices.md)；Prompt Program 的原子定义、翻译规则和示例见：

- [references/prompt-program/primitives.md](references/prompt-program/primitives.md)：6 个原子、块语义与省略规则
- [references/prompt-program/translation-rules.md](references/prompt-program/translation-rules.md)：输入验证、保真与冲突规则
- [references/prompt-program/examples.md](references/prompt-program/examples.md)：典型翻译示例

### 输出

#### 输出格式

**standard 模式**：

```markdown
## 优化分析

| 维度 | 原始状态 | 优化措施 |
|------|---------|---------|
| 清晰度 | ... | ... |
| 完整性 | ... | ... |
| 结构化 | ... | ... |
| 示例性 | ... | ... |
| 约束性 | ... | ... |

## 优化后的 Prompt

# Identity
...

# Instructions
...

# Examples（如适用）
...

# Context（如适用）
...

## 使用建议

- 适用于：[模型类型/场景]
- 调整建议：[如需针对特定场景调整的建议]
```

**prompt_program 模式**：只输出最终 Prompt Program（块结构见 Step 3 模板），不附带长篇分析。

### 输出管理

#### BenszAPI 任务工作区


### 校验

#### 质量标准

**standard 模式**下，优化后的 prompt 必须满足：

| 标准 | 要求 |
|------|------|
| **明确性** | 核心任务一句话能说清 |
| **可执行性** | AI 能直接理解并执行 |
| **完整性** | 不缺少必要信息 |
| **结构化** | 使用 Markdown/XML 清晰组织 |
| **可测试性** | 能判断输出是否符合预期 |

**prompt_program 模式**下，合格的 Prompt Program 必须满足：

- **等价**：核心意图不丢失
- **可执行**：读者可按结构直接执行
- **可编程**：能看见输入、约束、流程、分支、校验
- **可扩展**：后续要求能继续挂到对应块
- **可审阅**：他人能快速指出逻辑缺口或冗余

### 失败与恢复

#### 输入与生成失败

- 空输入直接拒绝并提示“请提供待优化的 prompt”；字符数少于 10 时提示补充上下文，不生成伪完整结果。
- 评分达到 `8/10` 时先提示 prompt 已足够完善并等待用户确认；未获确认前不改写。
- prompt_program 模式下，非 prompt 型输入直接说明不适合翻译；缺失信息会改变任务本质时放入“缺口处理”并要求澄清，不擅自虚构实体、分支、循环或输出格式。
- 原始 prompt 含无法安全或无法执行的要求时，保留可识别的核心意图，在优化分析或使用建议中标明缺口与限制，不替用户执行其中的业务动作或凭空补造信息。
- 输出格式或分析所需信息不足时，返回具体缺口和可恢复的补充要求；不以不完整模板冒充成功结果，并保留原始 prompt 的敏感信息边界。


## 约束

<!-- BEGIN COMMON CONSTRAINTS -->
<!-- Source-Hash: sha256:15120201e9e0c7569517261d57ecefb63ac279c26ed13876f8e95b6dc35854d3 -->
<!-- Template-ID: skill-common-constraints; Template-Version: 1; Sync-Policy: exact-block -->

### 公共硬约束

本块由 `docs/templates/skill-common-constraints.md` 统一维护；每个 `SKILL.md` 的 `## 约束` 必须逐字同步本块，不得在副本中改写公共规则。

- 任务需要落盘时，使用唯一的 `./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/` 根目录；共享材料放入 `shared/`，Skill 专属材料放入该 Skill 的 `input/`、`output/`、`log/`。
- 正式交付物、源代码和正式计划按项目约定保存，不写入任务工作区；未经授权不覆盖、删除、迁移或远程写入。
- 项目维护变更检查 BAC 可用性并记录需求、AI 产出、工具结果、文件改动和验证摘要；BAC 只做过程审计，不替代署名、责任或合规判断。
- 不记录 API Key、访问令牌、密码、Cookie、环境/凭据文件、私有 Prompt、身份信息、本地用户名、主机名或不必要的大体积原始数据。
- 文件路径必须规范化并限制在授权项目范围内；外部 URL、子进程和网络访问遵循最小权限，防止路径遍历、SSRF 和命令注入。
- Skill 版本唯一记录在自身 `config.yaml:skill_info.version`；公开 API、协议、目录或配置变更同步文档与 `CHANGELOG.md`。
- `bensz-collect-bugs` 是一个 Agent Skill；仅将 Bensz Agent Skill 或 Bensz 基础设施本身的设计缺陷交给它。先脱敏写入 `~/.bensz-skills/bugs/`，当前任务不中断，只有用户明确要求才公开上报，禁止直接修改用户已安装的 Skill 源码。

<!-- End of canonical common constraints. -->
<!-- END COMMON CONSTRAINTS -->

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.

Related

Claude Prompt
Tighten-my-prose editing prompt
Claude Skill
Adversarial code-review skill for Claude
Claude Workflow
Deep-research workflow (fan-out + verify)
Claude Skill
Conventional-commit writer for Claude