在 pstack 中编写与修改 Skill 的完整实战指南从 SKILL.md 起草、结构化验证到开 PR 交付【免费下载链接】pluginsCursor plugin specification and official plugins项目地址: https://gitcode.com/GitHub_Trending/plugins125/plugins本篇指南以 pstack 插件中 poteto-mode 的 authoring-a-skill 剧本为核心骨架讲解在 Cursor 插件体系内编写、修改与交付一个 SKILL.md 技能的完整流程先回答写什么再回答怎么写然后进入结构化验证、必要的测试与评估最后以 Opening a PR 剧本收尾并给出标准回复格式。读完你会掌握一套可复制的技能创作 SOP能写出符合 pstack 质量标准、可被校验工具检查、可被其他技能按路径引用的 SKILL.md。一、先理解作者身份与剧本定位authoring-a-skill 剧本的第一句话定义了整个创作流程的前提You own the skills voice.这意味着技能作者对技能最终呈现的语气、信息密度和取舍负全责而不是机械地生成一段 Markdown。pstack 中所有写作类工作都遵循同一原则仓库根目录下的 poteto-mode SKILL.md 明确要求 Write the reply clean as you draft it写作一次成型不靠事后清理。该剧本是 poteto-mode 的 23 个 playbook 之一。从 poteto-mode SKILL.md 可以看到它的触发方式当任务匹配到 Authoring or modifying a skill编写或编辑 SKILL.md时poteto-mode 会打开一个 todo list把该剧本的步骤逐字拷贝进去再按步骤路由到其他技能。这与 pstack 的整体设计一致模式技能负责路由playbook 负责流程原则技能负责决策依据。二、起草阶段用 create-skill 编写 SKILL.md剧本的第一步是使用create-skill技能这是 Cursor 内置的 SKILL.md 创作工具。它负责 frontmatter 的正确生成、文件结构的搭建和草稿的迭代。pstack 不重复造轮子正如 pstack README 明确说明的/create-skill是 Cursor 内置能力not shipped here作者应直接调用内置技能。2.1 SKILL.md 的 frontmatter 结构create-skill 需要产出合法的 frontmatter。仓库内所有技能的 frontmatter 都遵循统一约定例如 principle-encode-lessons-in-structure--- name: principle-encode-lessons-in-structure description: Apply when you catch yourself writing the same instruction a second time, or notice a recurring correction. Encode the rule as a lint, metadata flag, runtime check, or script instead of more text. disable-model-invocation: true ---而 poteto-mode 这类模式级技能还会扩展出更多字段--- name: Poteto Mode description: potetos agent style for concise, detailed responses, deliberate subagents, unslopped prose, simple code, and verified work. Use for poteto, /poteto-mode, or requests to work in this style. disable-model-invocation: true mode: true icon: crown color: yellow reminder: New task? Playbook match or rigor needed - apply /poteto-mode. Casual turn or user opts out - dont. ---从这些真实示例可以看出 frontmatter 的必备要素与可选要素name和description是硬性要求也是剧本第 2 步验证的第一项disable-model-invocation用于关闭模型自行调用mode、icon、color、reminder则用于模式型技能的展示与提醒。2.2 写作原则删减优先只留改变决策的散文剧本对正文写作给出了明确的口径这是全文的核心方法论When in doubt, delete.拿不准就删。技能正文只保留会改变决策的散文。Tell it to do the thing and skip the reason.直接告诉它做什么跳过理由。只有当规则缺少解释会造成困惑时才解释。Match tone to scope.语气与影响范围匹配影响越广的技能措辞越要克制准确。Point at structural sources.指向结构性来源类型、README、配置而不是在技能里复述内容。Delegate to other skills by path. Dont restate.通过路径委托给其他技能绝不重复叙述。A workflow you keep hitting but isnt captured → propose a new skill.反复遇到但尚未被任何技能捕获的工作流应提议创建新技能。指向结构性来源而非复述背后是encode-lessons-in-structure原则的直接体现。该原则技能principle-encode-lessons-in-structure给出完整决策流程当你发现自己第二次写同一条指令时问这能不能变成 lint 规则、元数据标记、运行时检查或脚本能就编码成机制删除文字指令。不能需要判断力就放大这条指令的显著性并补充失败模式示例。它还强调选择最强的机制一个无法编译的非法状态强于 lint 或禁用 API强于规范辅助函数强于运行时检查。原因是 agent 会复制周围代码已有的做法弱防护会成为下一个模板。这条原则同样解释了Dont restate如果一个规则能被结构性机制强制写进技能正文的文字就是冗余的技能里只应保留那些必须依赖判断、无法机制化的内容。2.3 语气与风格红线pstack 对技能文案的写作质量有明确的风格约束创作 SKILL.md 时应一并遵守。仓库中的 unslop 技能列出了具体的禁用模式避免 em dash 过度使用、避免冒号做句中连接符、避免 AI 腔词汇如 additionally、crucial、delve、foster 等、避免虚假的 not just X, but Y 句式、避免口号式结论、避免抽象隐喻名词如 substrate、vector、paradigm、避免被动语态和过度修饰。技能正文应说出它做什么而不是它给人的感觉每句话要么是可执行指令、要么是事实或数字。三、验证阶段结构化校验优先剧本第 2 步规定了验证清单这是所有技能交付前的质量闸门frontmatter 包含name和description。这是机器可读性的基础缺失会导致技能无法被 Cursor 识别与检索。引用的文件真实存在。技能正文中指向类型文件、README、配置、其他技能路径的引用必须可解析禁止悬空引用。跨技能链接可解析。按路径委托其他技能时目标技能必须存在且路径正确。从仓库结构看这种引用完整性校验并非空谈。仓库根目录提供了可对照的自动化校验实现scripts/validate-plugins.mjs 使用 Ajv 按 plugin.schema.json 校验每个插件的.cursor-plugin/plugin.json检查插件源目录存在、manifest 符合 schema、marketplace 名称与插件名称一致。虽然该脚本校验的是插件清单而非单个 SKILL.md 正文但它展示了 pstack 所在仓库的工程态度凡是能机制化校验的都交给脚本而不是靠人眼。作者在本地完成剧本第 2 步时同样应把引用文件存在、跨技能链接可解析当作可机械化检查的项而不依赖记忆。四、测试与评估结构性测试必做主观性测试跳过剧本第 3 步是测试策略Test cases if structural. Skip if subjective.具体展开为如果技能的行为是结构性的例如它规定了一个文件布局、一个命名约定、一个可脚本化校验的流程就必须配套测试用例来验证技能被正确遵循如果技能的产出是主观判断例如语气是否简洁这条规则是否容易理解则跳过测试因为无法用断言表达。仓库内的 eval 剧本 为如何评估一个技能或提示词改动是否真的改变了 agent 行为提供了更严格的盲测方法可用于重要技能的变更验证候选者看到的任何目录、文件名、提示词中不得出现eval、test、judge、experiment、rubric、score、compare、benchmark、candidate、arena等词。候选提示词必须看起来像一个自然的用户请求只陈述目标不暴露元信息。不给候选者任何诱导链式回答的线索不要求它列出用了哪些技能和原则。评审者知道自己在评审但只能看到按消毒标签命名的输出永远看不到模型名。对照两个变体时由同一个评审者用同一套评分标准在一次通过中盲评两组输出。从 transcripts 验证链路而不是相信自述。剧本要求实际读取候选者打开的本地 transcript 文件从它真正读过的文件和代码形态判定它对流程的遵循程度绝不采信候选者自己的声称。这套方法回答了一个核心问题你改了一版技能凭什么认为它更有效pstack 的回答是跑一次受控的盲测让证据说话而不是凭感觉。五、收尾运行 Opening a PR 剧本剧本第 4 步是Run Opening a PR。poteto-mode 的设计中Opening a PR 是每个其他剧本结束时都会被调用的收尾剧本authoring-a-skill 也不例外。技能改动必须以一个就绪的 PR 形式交付而不是停留在工作区。关键交付标准Worktree。从 main 派生 git worktree 工作子 agent 继承同一 worktree。Commits。大量小提交开 PR 前 rebase 成有序的小提交每个提交都是一个未来可独立合入的 PR按时间顺序讲述变更故事。Titles。使用 Conventional Commits 格式type(scope): subjecttype 取feat、fix、docs、refactor、test、chore、perf之一scope 写变更区域如pstack或poteto-modesubject 简短祈使句结尾不加句号。仓库内 pstack README 特别提示/deslop技能来自cursor-team-kit插件需要在提交前单独安装该插件。Descriptions。PR 正文是简报而非实验笔记本按## Why、## Scope、## Tradeoffs、## Blast Radius、## Verification顺序组织无内容的章节直接省略禁止使用## Summary或## Test plan模板。Forge。第一个 PR 操作前解析 forge默认 GitHub CLIgh若originCLI 可用则优先origin pr ...。Ready 而非 draft。每个 PR 以就绪状态打开绝不 draft云 agent 的 PR 工具默认 draft需在每个创建调用上显式设置draft: false。不自动触发 babysit。开 PR 不等于开始 babysit先发布 URL 继续构建完成阶段或整个 stack 后再单独跑 babysit。六、交付后的标准回复格式剧本最后一行规定了作者的回复结构Reply:summary of the skill, key design decisions, validation notes.即每次完成技能创作或修改后回复必须包含三部分技能的摘要。这个技能做什么在什么场景被调用。关键设计决策。为什么这样写为什么这样组织删掉了什么。验证说明。frontmatter、引用完整性、测试与评估的结果分别是什么。这与 poteto-mode 对回复的全局要求一致每个论断在同一句话里携带证据或标签measured、inferred、guessNever hand the human a check you could run不要递给用户一个你自己就能跑的检查。对于技能改动验证说明就是我已经跑过的检查清单而不是你回去试试看。七、技能的持续演进从反复出现的教训到结构编码authoring-a-skill 剧本是技能生命周期的创作端而仓库中的 reflect 技能 展示了另一端如何把一次对话中沉淀的经验路由回技能编辑。reflect 的流程是定位活动 transcript并行派出三个评审视角judgment、tooling、divergent挖掘可复用的经验由综合器产出 Accepted、Rejected、Backlog 三份清单随后按路由字段执行琐碎改动直接由父 agent 完成实质性改动交给create-skill跑 draft/test/iterate 循环描述需要优化的走 description-optimization 循环全新技能则通过create-skill创建。其中第 4 步与 encode-lessons-in-structure 直接联动凡是 lint 规则、脚本、元数据标记或运行时检查能更强制执行的项都从 Accepted 挪到 Backlog因为技能正文是症状结构才是治疗。把创作端与演进端合起来看pstack 对技能的态度是一以贯之的技能不是一次写完就冻结的文档而是持续编码经验的载体。每一次作者发现自己写出重复指令都是启动 authoring-a-skill 流程的信号每一次改动都按起草、验证、测试、开 PR、汇报五步闭环交付。八、可复制的创作检查清单将本指南收拢为一份可直接照做的清单供在 poteto-mode 下创作或修改技能时逐项打勾确认任务匹配 authoring-a-skill 剧本把剧本步骤逐字拷贝进 todo list。调用 Cursor 内置的create-skill起草 SKILL.md。检查 frontmattername和description必填模式类技能补充mode、icon、color、reminder。按删减优先原则裁剪正文只留会改变决策的散文直接说做什么不重复理由。指向结构性来源类型、README、配置按路径委托其他技能不复述其内容。检查所有引用的文件存在、跨技能链接可解析。结构性行为写测试用例主观性判断明确跳过。重要行为变更考虑用 eval 剧本做盲测从 transcripts 验证链路而非自述。运行 Opening a PRworktree 工作、有序小提交、Conventional Commits 标题、Why/Scope/Tradeoffs/Blast Radius/Verification 简报体、以 ready 状态打开。按技能摘要、关键设计决策、验证说明三段式回复。这套流程的价值在于它把写好一个技能从玄学变成了可执行、可验证、可交付的工程动作。严格按它走一遍你产出的 SKILL.md 将同时满足机器可校验frontmatter 与引用完整性、模型可遵循指令直接、无冗余和仓库可维护结构编码优先于文字三个层面的要求。【免费下载链接】pluginsCursor plugin specification and official plugins项目地址: https://gitcode.com/GitHub_Trending/plugins125/plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考