Penpot refine-prompt Skill 解析：把模糊需求打磨成可复用、可归档的 Agent Prompt

Penpot refine-prompt Skill 解析：把模糊需求打磨成可复用、可归档的 Agent Prompt

【免费下载链接】penpotPenpot: The open-source design platform for Product teams that need scalable collaboration.项目地址: https://gitcode.com/GitHub_Trending/pe/penpot

Penpot 仓库在.opencode/skills/refine-prompt/SKILL.md中内置了一个专门用于"打磨 Prompt"的 Agent 技能：它接收一段用户草稿 Prompt，依据提示工程最佳实践与 Penpot 项目上下文，输出一份结构更清晰、约束更完整、可直接复用的改写版本，并且明确"只改 Prompt、绝不执行 Prompt"。读完本文，你将理解该技能的触发条件、角色契约、强制前置阅读机制（Penpot 的 memory 体系）、十条提示工程原则、双块输出格式与 kebab-case 文件持久化规范，并能在自己的仓库中复刻这套"Prompt 精加工"流水线。

一、技能定位：只重写，不执行

技能的入口文件是 SKILL.md，采用 YAML frontmatter + Markdown 正文的标准 Skill 结构：

--- name: refine-prompt description: Refine and improve a user-supplied prompt for maximum clarity and effectiveness using prompt-engineering best practices and Penpot project context. Outputs a rewritten prompt (and brief rationale); never executes the prompt. ---

其中description本身就是一份浓缩的契约：目标（最大化清晰度与有效性）、手段（提示工程最佳实践 + Penpot 项目上下文）、产物（改写后的 Prompt 与简要理由），并以内嵌一句 "never executes the prompt" 划定了能力边界。正文再次强调：这是一个"Expert prompt-engineering pass"——把草稿 Prompt 变成可被任意 AI 模型直接使用的版本，但绝不执行该 Prompt 本身。

二、触发条件与反例边界

"何时该用"和"何时不该用"写得同等明确，避免技能被误触发：

应当使用：

• 用户分享了一段 Prompt 并要求 improve / refine / polish / rewrite；
• 用户说"make this prompt better"或"can you clean this up?"；
• 用户想给一段模糊 Prompt 增加结构、约束、示例或输出格式；
• 用户想把 Prompt 适配到特定目标模型、受众或任务类型。

不应当使用：不能拿这个技能去真正回答 Prompt 里的问题、或直接完成 Prompt 要求的任务——它唯一的职责是改写 Prompt 本身。

这种"能力声明 + 反例清单"的写法，是仓库中其它技能（如 planner/SKILL.md 的 "Do not use this skill to actually implement anything — it is read-only"）的共同范式：每个技能都是一个职责单一的"角色"，靠显式的负面清单防止越界。

三、角色定义：不写代码的 Prompt 工程师

技能将执行者设定为"expert Prompt Engineer with strong knowledge of Penpot"，并给出三重排他性约束：

• 不做任务执行（You donotexecute tasks）；
• 不写代码（You donotwrite code）；
• 只做提示词的设计与精化（You only design and refine prompts）。

角色里特意保留了 "strong knowledge of Penpot" 这一点，因为下一节的强制前置阅读要求决定了：当 Prompt 涉及 Penpot 代码库时，改写必须注入项目专有词汇，而不是泛泛的"codebase"。

四、强制前置阅读：Penpot 的 memory 体系

这是该技能最区别于通用"提示词优化器"的部分。SKILL.md 要求改写前完成三步阅读：

1. 读根目录 AGENTS.md——项目级规则与约定；
2. 读 critical-info（memory 体系的入口点）——理解模块布局：frontend、backend、common、render-wasm、exporter、mcp、plugins、library等；
3. 当 Prompt 指向特定模块时，速读该模块的 core memory（mem:frontend/core、mem:backend/core等），以便在精化后的 Prompt 中注入精确的词汇、文件约定与测试命令。

这套机制并非文档杜撰，而是仓库实际存在的 memory 参考图。AGENTS.md 的 "Memory system" 一节（AGENTS.md#L50-L94）定义了渐进式发现模型：

critical-info ← read first (graph root) └─ <section>/core ← top-level memory per section └─ <topic> ← focused memories └─ ... ← deeper memories as needed

mem:foo/bar引用对应文件系统上的.serena/memories/foo/bar.md。例如mem:backend/core实际就是 backend/core.md，其中记录了 RPC 命令的defmethod约定、app.db辅助函数、scripts/nrepl-eval.mjs的用法等——正是 refine-prompt 技能要求"注入精确词汇"的素材来源。而 critical-info.md 则枚举了全部模块及其职责（如frontend/是 ClojureScript + SCSS 设计编辑器、render-wasm/是 Rust 编译到 WebAssembly 的 Skia 渲染器），并给出依赖图：frontend -> common、backend -> common、exporter -> common、frontend -> render-wasm。

因此技能文档特别说明：这一步在用户准备撰写关于 Penpot 代码库的 Prompt 时最关键；对于通用 Prompt，则聚焦提示工程原则本身，只在明显相关时才编织进 Penpot 上下文。

五、精化工作流：分析、追问、重写

SKILL.md 的 "Requirements" 一节定义了四步工作流：

1. 分析原 Prompt：识别意图、目标受众、歧义点、缺失的上下文与结构性弱点；
2. 必要时追问：当意图不清或关键信息缺失（目标模型、期望输出格式、语气、约束）时，一次性集中提出 1–4 个问题，而不是逐个问。文档特别指出：应优先使用question工具提问，以获得结构化的多选 UI；只有当question工具不可用、或问题真正开放时，才退化为纯 Markdown 的## Clarifying questions小节；
3. 按提示工程原则重写（见下一节）；
4. 保留用户原始意图：不得改变底层任务；当用户提供了 Penpot 项目上下文时，把相关约定、模块路径和工具用法编织进去。

六、十条提示工程原则

技能内嵌了一份可直接套用的原则清单，每一条都有明确的操作指向：

其中 "Tool awareness" 与 Penpot 仓库的工具生态直接呼应：AGENTS.md#L114-L129 列出了可被 LLM 直接调用的原生工具（paren-repair修复 Clojure 分隔符、penpot-psql执行 SQL）以及scripts/下的脚本（scripts/ci、scripts/check-commit、scripts/gh.py等），这些工具正是由 penpot.js 插件以@opencode-ai/plugin的tool()形式注册的。一个精化后的 Penpot 相关 Prompt，理想状态就是能把"查一下数据库"这类模糊表述替换为penpot-psql、把"改完 Clojure 代码"细化为"先跑scripts/paren-repair再跑 lint"。

七、约束条款：最短可用、意图守恒

"Constraints" 一节给出了四条硬约束：

• 不执行Prompt 本身；
• 不回答Prompt 内部的问题；
• 不添加不必要的冗余——Prompt 应保持"在完整的前提下尽可能短"；
• 始终保留用户原始意图；若用户提供了 Penpot 项目上下文，优先使用 Penpot 专有词汇（如真实的模块名与mem:引用）替代"the codebase"这类泛称。

八、输出格式契约：两个清晰分离的块

技能对产出格式做了严格规定：

1. Refined prompt——单个 fenced code block，内含可直接复制使用的改写后 Prompt；
2. What changed (brief)——3–7 条 bullet，说明最重要的改动及原因；改动微小时可省略理由块。

此外定义了三种流程分支：

• 若通过question工具提了确认问题：停止并等待回答，在得到回答前不产出精化结果；
• 若question工具不可用、问题改在聊天中提出：把问题列在精化 Prompt上方的Clarifying questions小节并停止，用户回答前不得产出精化结果；
• 若用户明确说"直接改写"（如 "just rewrite it"）：做出合理假设，并在理由块下用Assumptions made小节注明。

这套"先问后写、假设必须声明"的规则，本质上是在防止模型在信息不足时静默脑补。

九、文件持久化：kebab-case 归档到.opencode/prompts/

SKILL.md 的 "File Persistence" 一节要求：每次精化后必须把结果落盘，以便日后复用、进 git 版本管理、并在多个 agent 间共享。落盘规则逐条明确：

• 保存 fenced code block内部的正文（去掉 ``` 围栏本身）到.opencode/prompts/<descriptive-name>.md；
• 文件名用kebab-case且概括任务本身，例如add-error-reports-management-rpc.md、backend-rpc-security-audit.md；禁止空格、禁止大写、禁止带版本号或日期；
• 若.opencode/prompts/目录不存在，先创建再写入；
• 同名文件已存在时直接覆盖（该文件是"精化后的 Prompt"，不是日志）；
• 仅当用户明确拒存（如 "don't save this one"）时才跳过写盘，"存疑时默认存"。

从当前仓库状态看，.opencode/prompts/目录尚未被创建（.opencode/下目前只有commands/、plugins/、skills/三个子目录），这与规则自洽——目录是按需懒创建的。响应体中的 Prompt 与理由块仍然照常输出，文件只是额外产物而非替代品。

十、一个端到端的示例（基于仓库事实构造）

结合仓库实际内容，可以直观感受这套流程的产出。假设用户给出草稿：

帮我看看 error reports 功能，好像有个 rpc。

按技能规则精化后，输出代码块中的 Prompt 大致形如：

Analyze Penpot's error-reports feature in this monorepo. Role: You are a senior backend engineer working on the Penpot codebase. Steps: 1. Read .serena/memories/scripts/error-reports.md and mem:backend/core first. 2. Locate the RPC command implementation under backend/src/app/rpc/commands/ and its corresponding tests under backend/test/backend_tests/. 3. Summarize: the RPC entry point, parameter schema, and how scripts/error-reports.mjs calls the API with token authentication. Output format: a bullet list of file paths with one-line descriptions, then a short call-chain diagram (text). Constraints: do not modify any file; read-only analysis only.

对应的 "What changed" 块会解释：指定了角色、点名了真实模块路径（mem:backend/core、backend/src/app/rpc 目录）、补充了输出格式与只读约束、消除了"好像有个 rpc"这类歧义表述。这正是文档所要求的"用 Penpot 专有词汇替代泛称"的落地形态。

十一、在 Skill 矩阵中的位置与可借鉴模式

refine-prompt 并非孤立存在。从 .opencode/skills/ 目录看，它与其他技能共同构成职责分离的 Agent 工作流：planner/SKILL.md 负责只读的架构分析与计划产出（落盘到.opencode/plans/）、code-review/SKILL.md 负责五维代码评审、create-commit/create-pr/create-issue负责 git/GitHub 工作流（且都要求先读mem:workflow/*记忆）。refine-prompt 处在流水线的最前端：在进入 planner 或执行型 agent 之前，先把任务描述本身打磨到无歧义。

可提炼的复用模式有四条：

1. 单一职责 + 负面清单：每个技能显式声明"不做什么"，比只声明"做什么"更能约束 agent 行为；
2. 记忆图前置阅读：通过critical-info → <module>/core → <topic>的参考图，让精化结果注入项目级精确词汇，而非通用套话；
3. 输出即契约：用固定的分块输出格式（代码块 + 3–7 条理由 + 假设声明）让结果可预期、可解析；
4. 产物落盘且命名规范化：kebab-case 文件名、覆盖而非追加、目录懒创建，使 Prompt 资产可以版本化并在 agent 间流转。

以上全部规则、路径与行为均以 SKILL.md 原文为准，其依赖的项目上下文可在 AGENTS.md 与 .serena/memories/critical-info.md 中逐条验证。

【免费下载链接】penpotPenpot: The open-source design platform for Product teams that need scalable collaboration.项目地址: https://gitcode.com/GitHub_Trending/pe/penpot