Product-Manager-Skills v0.81 技术复盘：Skill Input 输入约定、`$ARGUMENTS` 禁用决策与库漂移自动检查

• AI 技能
• AI 插件

导读

本文基于仓库根目录交接文档 04JUL26.md 及配套发布公告 2026-07-04-v0-81-input-sections.md，完整还原 Product-Manager-Skills 库在 v0.81（2026 年 7 月 4 日）的版本状态与三项核心工程决策：为全部 55 个 skill 强制引入## Input输入章节、在技能体内明确禁用 Claude Code 的$ARGUMENTS模板语法、以及新增库漂移检查脚本让文档与仓库内容永远同步。读完你将对这套 "Pedagogic-first（教学优先）" 技能库的 Skill 结构规范、校验脚本链（check-skill-metadata.py→test-a-skill.sh --smoke→check-library-drift.py→ CI 发布流水线）以及"孤儿提交"导致的技能丢失教训有源码级的完整理解。

一、v0.81 版本快照：55 个技能 + 6 个命令的仓库现状

按 04JUL26.md 的记录，v0.81 于 2026 年 7 月 4 日发布，commit、tag、release 资产全部就绪，CI 绿灯。当时技能库规模为55 个 skills，按类型拆分为：

• 23 个 component（组件型）：可复用的 PM 交付物模板，如 user-story、定位声明、PRD 章节等；
• 25 个 interactive（交互型）：通过自适应提问收集上下文并给出推荐，如 discovery-interview-prep；
• 7 个 workflow（工作流型）：编排多个技能的多阶段端到端流程。

外加6 个 commands（命令型能力，位于 commands/）。

发布公告 2026-07-04-v0-81-input-sections.md 交代了这一版的出发点：其他技能库普遍提供INPUTS区块与$ARGUMENTS模板化参数，本库是否在"用户输入引导"上有所缺失？答案是"一半是、一半否"——缺口真实存在（此前没有任何 skill 告诉用户该带什么上下文、以及预置上下文会被如何处理），但其他库采用的修复手段（$ARGUMENTS模板）对本库而言是错误的修复，理解"为什么错"正是这一版最有价值的部分。

二、核心约定一：每个 Skill 的## Input章节（强制、位于 Purpose 与 Key Concepts 之间）

v0.81 最大的结构性变化是：每个 skill 都必须包含一个## Input章节，位置固定于 Purpose 与 Key Concepts 之间，且由校验器强制检查。这不仅作用于 55 个既有技能文件，还同步覆盖了校验脚本、作者向导、模板与贡献者文档。

以 discovery-interview-prep/SKILL.md 的 Input 章节为例，其标准结构如下：

• **Works best with:**（主体）：说明该技能最需要的核心输入。例如"你的研究目标——你需要从客户那里学到什么"；
• **Also useful:**（可选增强）：能让输出更精准的补充上下文，如客户细分、访问约束、已携带的假设；
• inline-input 规则（逐字约定）：随调用提供的任何内容——技能名后的文本、粘贴的上下文转储、或追加的ARGUMENTS:行——都视为"已给出的答案"。技能应直接使用它并跳过已覆盖的部分，不得重新询问；
• **Arriving empty-handed? That works too.**（空手到达兜底）：说明引导式流程会从第一个问题开始带你补齐。以discovery-interview-prep为例："技能会先询问你的首要访谈目标，然后通过追问逐步收窄"；
• 示例调用：给出 1～2 个示范，如Prep interviews to understand why enterprise customers churn after 6 months — I can get 5 interviews in 2 weeks.

2.1 "邀请而非门禁"（Invitation, not Gate）原则

交接文档强调这是承重决策（load-bearing decision）而非偏好：Input 章节是邀请，不是门禁，任何内容都不能被标注为 "Required"。用户读完该章节后必须确信：即使什么都不带，技能也会引导他完成。文档记录了一个具体背景——初稿曾使用 "Provide:" 措辞，被维护者 Dean 明确驳回。

这一原则同时是 v0.75 "Pedagogic-first（教学优先）" 立场的自然延伸：剥离教学脚手架（learning scaffolding）属于缺陷，Input 约定是该原则的扩展而非独立规则。两个教学意图并重：技能既要指导 Agent 执行，也要让人类 PM 看懂"一个规范的请求长什么样"。

2.2 交互型技能的 7 段式 Skill 解剖结构

Input 加入后，技能正文的解剖结构固化为7 个章节、顺序强制：

1. Purpose（目的）
2. Input（输入，v0.81 新增）
3. Key Concepts（核心概念）
4. Application（应用）
5. Examples（示例）
6. Common Pitfalls（常见陷阱）
7. References（参考）

该顺序由 check-skill-metadata.py 的REQUIRED_SECTIONS列表（第 42-50 行）与check_required_sections()（第 84-106 行）验证：先用正则提取全部##二级标题，检查七个章节是否都存在，再验证它们在文档中出现的相对顺序与规定顺序一致（positions != sorted(positions)即报section_order_invalid）。

2.3argument-hintfrontmatter：唯一的"模板语法"豁免

虽然技能体内禁用$ARGUMENTS，但 frontmatter 中的argument-hint字段是唯一获批的例外，专为 Claude Code 的自动补全服务。53 个技能已携带该字段，例如：

• discovery-interview-prep：argument-hint: "[research goal]"
• agent-orchestration-advisor：argument-hint: "[workflow or task to orchestrate]"

Claude Code 用户由此获得/user-story [feature or user need]这类补全提示；其他运行时（Claude Desktop/Web、Codex、Streamlit playground）会无害地忽略该字段。

三、核心约定二：inline-input 规则如何在实战中生效

发布公告给出了一个关键承诺：discovery-interview-prep收到你的目标与约束后，"会从第一个你还没回答的问题开始"。仓库为此提供了完整对话转写示例 workshop-facilitation/examples/inline-input-flow.md，展示 inline-input 规则在真实会话中的落地方式。

3.1 正确示范：先确认已覆盖，再从缺口继续

用户在调用时直接给出完整上下文：

Use discovery-interview-prep: I need to understand why enterprise customers churn after 6 months. I can only get 5 interviews, and I have 2 weeks before the roadmap review.

正确的引导者（facilitator）行为是：

1. 开场说明会更快："通常需要 7-10 分钟和约 6 个问题——但你的请求已回答了大部分上下文问题"；
2. 逐条复述已提取的答案并打勾：研究目标 ✓、约束 ✓、截止驱动因素 ✓，明确标注"这已覆盖 Context Q1、Q3、Q4"；
3. 进度标签保持诚实：直接以Context Q2/6开头（而非从 Q1/6 重新计数），因为 Q1 已被回答；
4. 只追问缺口：仅剩"受访者是谁"与"是否携带假设"两个问题，其余问题全部跳过；
5. 给出的推荐基于已覆盖答案：目标（6 个月企业流失）、约束（5 个访谈、2 周）、两个猜测（onboarding 或集成缺失）被整合进三种方法论选项，并明确标注推荐项。

3.2 反模式：重问已答问题

示例同样记录了必须避免的反面行为：用户已在调用消息中回答了目标问题，引导者却仍从Context Q1/6 — What's your primary goal...开始。文档指出，这种重问会教会用户"提前给上下文是浪费"，进而训练他们藏起信息；每一次多余的重问都是会话不需要的往返。纠正动作：在任何流程提问前，先用问题清单扫描调用文本与粘贴的上下文，明确credit已覆盖部分，然后从第一个真正未答的问题开始。

四、核心约定三：为什么本库刻意不用$ARGUMENTS

$ARGUMENTS是 Claude Code 的输入替换机制：调用/skill-name some text时，token 在模型看到内容之前被展开。许多技能库围绕它构建，本库却刻意不采用，交接文档给出三条理由（与 CONTRIBUTING.md 的 "Why We Don't Use$ARGUMENTS" 一节完全一致）：

1. 可移植性（Portability）：替换只发生在 Claude Code 内。在 Claude Desktop/Web 包、Codex 与 Streamlit playground 中，$ARGUMENTS会以字面的、未经解释的模板语法呈现——读者面前是"破碎的脚手架"；
2. 教学性（Pedagogy）：这些技能同时教导人类 PM。纯语言描述的 Input 章节展示了一个规范请求的样子，并告诉你"可以空手而来、被引导完成"；$ARGUMENTS什么都教不了；
3. 不必要（It's unnecessary）：Claude Code 本就会把输入参数追加到技能内容末尾。一个写着"把内联输入当作已给出的答案"的技能，在每个运行时都能获得相同行为，且无需任何模板语法。

交接文档将这一决策与 v0.75 的教学优先立场归为同一类：便利捷径只会优化单一运行时与单一受众，而本库服务多个运行时与多类受众。因此该约定被命名、写入文档，并从第一天起被机器强制执行，杜绝"善意 PR 一次一次侵蚀它"。

4.1 校验器如何执行$ARGUMENTS禁令

check-skill-metadata.py 中check_forbidden_template_syntax()（第 55-70 行）的实现值得细看：它先用正则剔除全部代码块（```...```）与行内反引号（`...`），再对剩余正文搜索$ARGUMENTS模式（第 52 行FORBIDDEN_TEMPLATE_PATTERN）。这意味着：

• 裸用$ARGUMENTS是硬性校验失败（template_syntax_forbidden）；
• 在反引号中点名提及这一反模式（例如作者技能里教别人"不要写$ARGUMENTS"）是允许的——校验器会先把这些提及剥离。

这解释了交接文档中"backticked mentions naming the anti-pattern are allowed"的表述。贡献者提交的"现代化改造"PR 若引入模板语法，将被要求转换回 Input 约定，而非合并。

五、强制执行地图：四层校验从本地到 CI

交接文档用一张表总结了"什么检查拦住什么问题"，这是理解本库质量体系的钥匙：

5.1 元数据与结构校验：check-skill-metadata.py

check-skill-metadata.py 是结构合规的总闸，逐文件检查：

• YAML frontmatter 合法且存在（split_frontmatter()，第 73-81 行）；
• name必填、小写 kebab-case（^[a-z0-9]+(?:-[a-z0-9]+)*$，第 51 行）、不超过 64 字符；
• description必填且不超过 200 字符（Claude Web 上传限制）；
• intent必填非空；
• type必须为component/interactive/workflow三者之一（第 41 行）；
• 目录名必须与 frontmattername一致（第 150-152 行）；
• 文件必须命名为SKILL.md；
• 七个必需章节存在且顺序正确；
• 无裸$ARGUMENTS（见上文）。

运行方式：不带参数时校验skills/*/SKILL.md（第 173 行），也可显式传入单个文件路径。

5.2 冒烟检查：test-a-skill.sh --smoke

test-a-skill.sh 的--smoke模式针对 Input 章节的内容质量做警告级检查（第 195-204 行）：

• Input 章节中搜索example（含忽略大小写）——缺失则警告 "Input section has no example invocation"；
• 搜索empty-handed|nothing required|provide nothing|no input|with nothing|starting with nothing等措辞——缺失则警告 "Input section never says the user can arrive with nothing (invitation, not gate)"；
• 对 interactive 技能额外检查 Application 章节是否含至少 3 个编号选项与至少 1 个问号（交互引导特征），并调用 check-skill-triggers.py 做触发就绪审计。

本地一键运行：./scripts/test-library.sh --smoke。交接文档注明当前有 3 个既有的冒烟警告（interactive 技能选项数统计类），已知且与本次改动无关。

5.3 库漂移检查：check-library-drift.py（v0.81 新增）

v0.81 发布后补提交了 check-library-drift.py（commit93921da），其文档字符串写明了存在动机：v0.81 修复的两类故障恰好就是它要永久拦截的对象——一个被文档引用数月、却只存在于孤儿提交上的技能（agent-orchestration-advisor），以及一个静默落后技能库 8 个条目的marketplace.json。"文档声称的内容超出仓库实际，会一次一个断链地侵蚀信任"。

它执行三类一致性检查（第 32-75 行）：

1. 每个skills/<name>/目录必须在 .claude-plugin/marketplace.json 中有条目（marketplace_entry_missing）；
2. 每个 marketplace 条目必须指向真实存在的技能目录（marketplace_ghost_entry，杜绝"幽灵条目"）；
3. README.md 与 CLAUDE.md 中提及的skills/<name>/SKILL.md链接必须真实可解析（doc_link_broken），并自动跳过skill-name、new-skill-name、your-skill-name等占位符（第 29 行）。

5.4 CI 发布流水线：validate-skills.sh + build-release.yml

scripts/validate-skills.sh 是发布前的总闸：遍历skills/*/，验证每个SKILL.md存在、以---开头、frontmatter 含name与description，随后调用check-library-drift.py。任何失败都会让脚本以非零退出码结束。

.github/workflows/build-release.yml 把它编排进 CI（第 25-36 行）：checkout（含fetch-depth: 0，确保 git 历史可用于追踪孤儿提交）→validate-skills.sh→check-dist-freshness.py（确认 dist/ 与 catalog/ 与 skills/ 同步）→build-release.sh（打包）。CI 对 PR、main 分支 push、以及v*tag 均触发；tag 触发时通过softprops/action-gh-release@v2自动发布 GitHub Release（第 48-57 行）。

交接文档总结的发布机制因此是：pushv*tag → CI 校验、构建全部 ZIP 包、自动发布 release 资产，tag 之后无需任何手工操作。

六、失而复得：agent-orchestration-advisor与孤儿提交的教训

v0.81 发布前的审计发现了一个隐蔽问题：Phase 6 的第 34 号交互型技能agent-orchestration-advisor（skills/agent-orchestration-advisor/SKILL.md，共 782 行，内容涉及设计多 Agent 工作流的四个编排维度、Agent 边界、启动控制塔监控等）自 2 月起就被 README 和 CLAUDE.md 引用，却只存在于孤儿提交a41415c上，从未合并到 main——文档声称已发布，仓库里却根本没有这个文件。

处理过程与结果：

1. 通过git log --all从 git 历史中找回；
2. 升级到当前标准：trigger-oriented 的 description、intent、theme 元数据，以及必不可少的 Input 章节；
3. 最终发布，技能库总数由此定格为 55。

这个案例沉淀为两条会话经验（Gotchas），写入 04JUL26.md：

• 不要轻信"文档说已发布"——验证 main 分支上路径真实存在；git log --all能找出从未合并的工作；
• marketplace.json 是手工维护的：新技能需手动添加条目（name、source、不带 "Use when..." 从句的 description、取自既有七个类别的 category、tags），漂移检查会提醒你。

此外，README 有三处声明技能数量（badge、ASCII 横幅、tagline），加上.claude-plugin/marketplace.json的metadata.description，四处必须同步变更，且横幅框对宽度敏感。

七、v0.81 的其他交付与后续工作队列

7.1 其他交付

• Streamlit playground 的 "What to bring" 预检：每个技能详情页现在会在开始前，把该技能的 Input 章节渲染进一个 expander，并标注 "all optional"，确保教学意图在 UI 中存续（相关实现见 app/main.py 与 app/STREAMLIT_INTERFACE.md）；
• 示例流程：workshop-facilitation/examples/inline-input-flow.md提供完整转写，含诚实的进度标签（调用即覆盖时显示Context Q2/6）与要避免的重问反模式。

7.2 交接文档列出的开放工作队列（按粗略优先级）

1. Theme 元数据回填：55 个技能中仅 19 个带theme/best_for/scenarios/estimated_timefrontmatter，其余 36 个落入 Streamlit 的 "All other skills" expander；属机械性工作，遵循已打标技能的格式即可；
2. Phase 6 余量（AI PM Orchestrator）：ai-product-evals（Component）、ai-observability-framework（Component）、ai-maintenance-planning（Component）、ai-product-orchestrator（Workflow），源材料列于 CLAUDE.md；
3. v0.80 AI Product Builder Track 简报从未执行：15MAY26.md 与 research/v080-ai-product-builder-execution-brief.md 原计划 v0.80 作为该 Track，实际 v0.80 发布了 stakeholder 套件；简报内容（硬性排除项、源材料、技能计划）仍是未来版本的有效原材料，需与 Dean 决定执行、重编号或退役；
4. docs/Using PM Skills with Claude.md 增加 "以参数调用技能"小节：Input 章节已在每个技能内教学该模式，此小节旨在一次性、通用地教授/skill-name your context写法，属 v0.81 延后的小任务；
5. Streamlit 后续：流式响应、相关技能面板、会话导出、搜索；
6. 潜在 Phase 8：定价与变现套件（7 个技能，清单见 CLAUDE.md）。

7.3 会话经验备忘

• 批量技能编辑：通过 Bash 运行 Python 脚本而非逐文件编辑工具（文件在多次读取之间会漂移）；包含冒号的 YAML description 值需加引号；
• 发布机制：见上文第五节，tag 即触发全自动发布。

八、对贡献者的直接影响

如果你要向本库贡献新技能，v0.81 之后的最低要求是：

1. 七个章节齐全且顺序正确（Purpose → Input → Key Concepts → Application → Examples → Common Pitfalls → References），否则 check-skill-metadata.py 直接判定失败；
2. Input 章节必须位于 Purpose 与 Key Concepts 之间，包含 works-best-with、also-useful、inline-input 规则、空手到达兜底、示例调用五要素，措辞是邀请而非门禁；
3. 正文禁止裸$ARGUMENTS（反引号内点名提及允许）；
4. 提交前本地自检：./scripts/test-a-skill.sh --skill your-skill-name --smoke；
5. 新技能需手动登记到 .claude-plugin/marketplace.json，否则 check-library-drift.py 会报marketplace_entry_missing；
6. README 技能数量相关三处（badge、ASCII 横幅、tagline）与 marketplacemetadata.description需同步更新。

这些约束的共同目标，正如交接文档开篇所强调的：读取 04JUL26.md 前，务必先读 CLAUDE.md（治理与蒸馏协议），因为 Input 约定、$ARGUMENTS禁令与教学优先立场，是这套技能库"既有详实实操、又有源码级强制执行"的设计基石。

• AI 技能
• AI 插件