## 概述 ## 一、模具给下限，货架给分布 上期的八种模式（P1 签名前置、P2 薄入口厚附件、P3 确定性外置、P7 前置检查……）说的是「设计决策」，段落是这些决策落进正文后的「物理形态」。两者不重复：模式告诉你该不该把细节下沉到 references/，段落告诉你下沉之后正文里还剩哪几节、每节该写几行、市场上有多少人根本没写。 把本系列近八十篇拆解里出现过的正文段落归一归，一共七种：**步骤段、边界段、验收段、状态段、移植段、示例段、排障段**。这个清单本身就是第一个发现——七段里前五段在标本中常见，后两段供给稀薄，而稀缺排序几乎精确贴合「事情搞砸之后才需要」的程度。 ```mermaid mindmap root((正文七段)) 装载时就该在 步骤段 边界段 干活时反复回看 验收段 状态段 换机器换宿主时救命 移植段 教用户和教路由器 示例段 出事之后才被翻开 排障段 ``` ## 二、评测口径（诚实边界） ## 三、评测对比表 | 标本 | 功能完整度 | 设计质量 | 实战效果 | 上手难度 | 社区活跃度 | 加权 | |------|------|------|------|------|------|------| | commerce-agents（官方蓝图） | ★★★★★ | ★★★★★ | ★★★★ | ★★★ | ★★★★★ | **4.5** | | sepia（去AI味） | ★★★★ | ★★★★★ | ★★★★ | ★★★★ | ★★★★★ | **4.4** | | stop-that-shit | ★★★★ | ★★★★ | ★★★★ | ★★★★ | ★★★★ | **4.0** | | agent-memory | ★★★★ | ★★★★ | ★★★★ | ★★★ | ★★★★ | **3.9** | | lieflat-gongwen | ★★★★ | ★★★★ | ★★★ | ★★★ | ★★★★ | **3.7** | | anything2explainer | ★★★★ | ★★★ | ★★★★ | ★★★ | ★★★★ | **3.6** | | ffmpeg-skill | ★★★ | ★★ | ★★★ | ★★★★ | ★★★★ | **3.1** | 星值佐证（三日快照纵向）：agent-memory 818→998（两日 +180，七件中爬得最陡）；lieflat-gongwen 669→812；ffmpeg-skill 919→965；commerce-agents 2651→2741。sepia 在 09-10 单日已报 2515。 ## 四、正文七段菜单 **1. 步骤段：供给最足，写法最滥。** 每个技能都有「第一步、第二步」，但多数写成流水账。好步骤段的判据是**每一步都可观察**——本机内置 verify 件的描述是范本：「Verify that a code change actually does what it's supposed to **by running the app and observing behavior**」，动作和验收信号写在一起。本周的 anything2explainer 把整条产线压成一句描述：「Topic in, narrated explainer video out」——入口类型、出口形态一步说清，正文步骤段照此展开即可。dream-loop 的描述同款结构：Blender + image gen + subagent critic，三个工位就是三步。 **2. 边界段：拦截件把它写成了宪法。** stop-that-shit（⭐1915）的描述原文就是一份边界段范文：「拦截 AI coding agent 无需求的哈希、校验和与任务范围膨胀」——三个名词就把「不做清单」钉死。内置件的边界写法更值得抄：claude-api 描述里 TRIGGER/SKIP 双清单分流；simplify 只用一句话——「This does not hunt for bugs; use /code-review for that.」**边界段的最高形态是转介句**：不仅说不，还说清该去找谁。上周 commit-message-zh 最小模板里那句「暂存区为空：提示先 git add，绝不代劳」，就是这个段落的 embryo 形态。 **3. 验收段：中文件跑出了全场最硬范式。** lieflat-gongwen（⭐812，两日 +143）的描述把这一段的存在意义写穿了：「通过102万字语料提炼的公文写作 skill，把公文写作风格变成**可测量、可验收的量化数据**」。验收段就是把「写好了」翻译成数字：字数区间、句式配比、禁用词清单。本机快照里的 pptx-test 是另一个证据——官方 pptx 族生生配了一个专职测试件，说明「验收」值得独占一个位次，哪怕独占成一个独立技能。 **4. 状态段：记忆件把它写成了宣言。** agent-memory（⭐998）描述里的关键词不是「记忆」而是「plain **Markdown as the source of truth**」——状态段的写法要点全在这半句里：状态存哪、以什么格式、谁是权威版本。okf-agent-memory（⭐576）更进一步，「Git-native persistent memory，实现 Google OKF v0.2」——状态可版本化、可回滚。本系列此前拆记忆双雄讲的是功能，这里取的是它们的**文本遗产**：状态段的两个必答项（存储位置、真伪判据）它们都答了。 **5. 移植段：兼容声明正在变成卖点。** sepia（⭐2515）的描述开头就是「for **any Agent Skills-compatible agent**（77+ via the Skills CL…）」——兼容面写进了第一行。anything2explainer 同款：「A Claude Code / Codex skill」，双宿主直接亮在描述里。此前「双宿主新件首拆」讲过它的工程含义，段落层面的推论很朴素：**只要你的技能不依赖特定宿主的私货，就值得一段写明「换机器/换宿主时什么会变、什么不会变」**——这个信息读者装前就要，却几乎没人写。 **6. 示例段：接口层繁荣，正文层萧条。** 有意思的倒挂：描述里放示例已成内置件标配——update-config 的描述里直接开了 Examples 小节，枚举「allow npm install」「set DEBUG=true」这类用户原话，等于给路由器喂正则样本；但**正文级的完整示例段（一个从头跑到尾的输入输出对）在本系列引用统计中出场最少**。原因可以理解：示例段是七段里上下文税最重的，一屏正文换一次「看一眼就会」。折中写法是从业者们还没普及的：只放「最易误解的那一个例子」，不放通用演示。 **7. 排障段：全场最大的空货架。** 七段里唯一在标本中近乎绝迹的。本机约四百条快照里，把 troubleshooting 写进描述的只有 harness 内置的 update-config（「hook troubleshooting」）——而那是平台方给自己留的。社区侧对照更刺眼：ffmpeg-skill 三日 919→965 涨到 ⭐965，描述栏至今是空的。转码失败、编码器缺失、二进制不存在，媒体域是故障率最高的域之一，这件的正文里**有没有**排障段，装前无从验货——上周本栏已提醒过「装前无法验货是高星无描述件的共同代价」，段落视角下这句话有了更准的表述：**星数奖励的是功能承诺，从来不奖励失败分支**。 ## 五、倒挂：段落供给与故障率成反比 把七段按「出事后才需要」的程度排一条轴，供给量大致逐段递减：步骤段人人有，排障段几乎无人有。而故障率恰好沿同一条轴递增——步骤写错的代价是返工一次，排障缺失的代价是整次会话作废。这个倒挂就是本期审计的主结论，也是新作者最容易捡的便宜：**给正文补一段三行的排障段（症状 → 先查什么 → 再执行什么），就能超过货架上大多数同行**。 ## 六、写作决策链 ```mermaid flowchart TB A["主干完成：步骤段加边界段"] --> B{"结果可量化吗"} B -->|"可以"| C["补验收段写死指标"] B -->|"不可以"| D["跳过不硬造指标"] C --> E{"中间产物要跨会话吗"} D --> E E -->|"要"| F["补状态段写明存哪"] E -->|"不要"| G["跳过"] F --> H{"会换宿主或换机器吗"} G --> H H -->|"会"| I["补移植段写明差异"] H -->|"不会"| J["到此收笔"] I --> J J --> K{"脚本会失败吗"} K -->|"会"| L["补排障段症状对动作"] K -->|"不会"| M["发布"] L --> M ``` 读法：步骤段与边界段是入场券，后面五段各由一个问题 gate 住——问题答「否」就果断跳过，段落不是越多越好，每一段都要在装载时付上下文税。 ## 七、给你的第一个 Skill 加两段 以上期 commit-message-zh 为底，按决策链只动两处，即是本期建议的进阶模板： ```markdown ## 验收 - 一行 type(scope): 中文描述，type 只取 feat/fix/docs/refactor/chore - 正文不超过三条要点，每条不超过 40 字 ## 排障 - git diff --cached 报空：回到边界段流程，提示先暂存 - diff 超过两千行：只读 --stat 按文件摘要，不逐行展开 ``` 三条增段规则收束全文：验收段只写**可机判**的指标，写不出数字就别写这一段；排障段只收**出现过至少一次**的症状，想象出来的故障不要录；任何一段能在三行内写完的，不要写成八行——段落税是按触发次数收的。 ## 八、安装与使用 ```bash # 本期标本中值得装回来对照正文的四件 npx skills add lennney/stop-that-shit # 边界段范文 npx skills add larashero3-dotcom/lieflat-gongwen # 验收段范式 npx skills add tigerless-labs/agent-memory # 状态段范本 npx skills add Vincentwei1021/anything2explainer # 步骤段产线写法 # 官方蓝图仓库，抄结构用 git clone https://github.com/anthropics/commerce-agents # 装前先搜同类，看别家正文缺哪段再决定自写 npx skills find 公文 ``` ## 九、推荐排行榜 - **段落供给最全榜**：commerce-agents（官方蓝图，结构即内容）＞ sepia（移植段写进描述第一行）＞ agent-memory（状态段宪法级） - **单段最佳范文榜**：边界段 stop-that-shit＞验收段 lieflat-gongwen＞步骤段 anything2explainer - **空货架痛点榜（补一段即超车）**：排障段（全场空缺）＞ 正文示例段（接口层繁荣、正文层萧条）＞ 移植段（仅头部件声明） - **反面教材榜**：ffmpeg-skill（⭐965 而描述栏全空，验不了货）——星数涨得再快，也替作者写不出那三行排障段 ## 参考来源 ## 九、推荐排行榜 - **整库安装首选**：superpowers 本体——目前生态里完成度最高的流程件集 - **新手第一个学**：brainstorming——立刻改善日常对话质量 - **性价比单件**：verification-before-completion——一个文件治理「假装完成」 - **最难但回报最高**：test-driven-development——团队的工程纪律直接决定收益 - **最值得抄的写法**：systematic-debugging 的红线清单——可迁移到任何领域 - **想自建件库必读**：writing-skills——仓库自我生长的引擎 ## 十、安装 ```bash # 方式一：插件市场安装（Claude Code 内执行） /plugin marketplace add obra/superpowers-marketplace /plugin install superpowers@superpowers-marketplace # 方式二：手动取用（只装本文推荐的件） git clone https://github.com/obra/superpowers cp -r superpowers/skills/brainstorming ~/.claude/skills/ cp -r superpowers/skills/verification-before-completion ~/.claude/skills/ ``` ## 参考来源 1. [obra/superpowers](https://github.com/obra/superpowers) — 本文主拆仓库，全部子件 SKILL.md 原文所在 2. [superpowers README](https://raw.githubusercontent.com/obra/superpowers/main/README.md) — 仓库自述与安装方式的原始出处 3. [anthropics/skills](https://github.com/anthropics/skills) — 官方 Skills 仓库，作为单件写法的对照组 4. [skills.sh](https://skills.sh) — Skills 生态榜单站，观察该仓库热度走势 5. [mcpservers.org/agent-skills](https://mcpservers.org/agent-skills) — Agent Skills 目录，社区精选与安全扫描评级 > [!tip] 51学通信知识星球 > **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 > **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 > **当前规模**：5200 篇主题 / 990 个回答，198 元/年。 > **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 > **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。