技能剖析——结构与设计模式

8.1 从临时提示到可重复的工作流

这个季度你已经综合了五次客户反馈。每次都是打开Claude Code，输入同一提示的变体，等待结果，意识到忘了指定输出格式，迭代调整，得到能用的东西，然后继续。下个月，你又会再来一次。你不会记得具体什么好用，会花20分钟重新摸索出正确的提示结构。输出结果会和上次略有不同，使得跨季度的比较更加困难。

这就是提示跑步机。你不断重复做同样的工作，却没有从重复中获得复利价值。技能解决了这个问题。

技能是一个文档化的工作流，Claude Code按需执行。你一次性地定义流程：需要什么输入，遵循什么步骤，产生什么输出，什么样算质量合格。然后你按名称调用它。Claude Code按照你文档化的流程执行，产生一致的结果，无论距离你创建它过去了多长时间。

复利价值是显著的。第一次季度反馈综合需要45分钟，包括提示迭代。有了技能，第二次只需10分钟。第三次也是10分钟。到第四个季度，你节省了两小时的工作时间，并且获得了跨时间段的一致性，使趋势分析成为可能。

本章涵盖技能结构和设计模式。第9章提供完整的示例，并手把手带你构建你的第一个技能。掌握这两章，你就能将重复的PM任务从认知负担转化为可靠的流程。

8.2 什么是技能？

技能是一个告诉Claude Code如何执行特定工作流的markdown文件。它存放在项目的.claude/skills/目录（通过git与团队共享）或~/.claude/skills/（个人的，跨所有项目可用）中。当你调用一个技能，或者当Claude Code识别到你的请求与某个技能的描述匹配时，它会遵循文档化的指令，而非即兴发挥。

技能与提示：区分很重要。提示是一次性的指令。你输入它，Claude Code响应，然后提示就消失在会话历史中了。如果你想下周做同样的事，你需要重新写提示（或者翻找历史记录，希望记得你是什么时候运行的）。

技能是持久化的指令集。它以文件形式存在，像其他项目产物一样进行版本控制。当你下周运行该技能时，它执行的是相同的文档化流程。当团队成员运行时，他们获得一致的行为。当你更新技能时，每个人都从改进中受益。

区别在于持久性和可重复性：

方面	提示	技能
持久性	仅限当前会话	仓库中的文件
可重复性	需要回忆	按名称调用
一致性	每次不同	文档化的流程
可共享性	复制粘贴	Git提交
演进	丢失于历史中	版本控制

技能存放位置。Claude Code在两个位置查找技能：

项目级别：当前目录中的.claude/skills/。这些技能是项目特定的，与克隆仓库的团队成员共享。用于与产品绑定的技能：针对你特定数据格式的反馈综合、针对你仓库规范的发布说明、针对你团队检查清单的PRD审计。

个人级别：主目录中的~/.claude/skills/。这些技能跟随你跨所有项目。用于通用的PM工作流：竞品分析模板、用户故事展开模式、会议笔记综合。

每个技能是一个子目录，至少包含一个文件：SKILL.md。目录名成为技能的标识符。复杂的技能可以包含额外的文件：辅助脚本、参考文档、输出模板。

.claude/skills/├── feedback-synthesis/│ └── SKILL.md├── release-notes/│ ├── SKILL.md│ └── resources/│ └── customer-voice-guide.md└── prd-audit/ ├── SKILL.md └── resources/ └── prd-checklist.md

图8.1：技能目录结构——使用此图来组织你的技能，包含必需的SKILL.md文件和可选的辅助资源、脚本及示例文件夹。

技能如何被发现和调用。Claude Code使用技能描述来判断相关性。当你发出请求时，Claude会读取每个技能YAML前置信息中的description字段，并判断是否有任何技能适用。如果你提供反馈CSV并要求"将其综合为主题"，Claude Code会匹配一个描述中提到"反馈综合"的技能并自动激活它。

你也可以将技能作为斜杠命令显式调用。名为feedback-synthesis的技能变为/feedback-synthesis。这种显式调用保证技能会运行，无论你如何措辞你的请求。

自动发现行为很有用，但并非魔法。如果你的技能描述不包含用户实际会说的话，Claude Code就不会匹配。"分析客户情感数据"不会在你输入"总结这份反馈"时触发。包含与自然请求匹配的触发词："综合客户反馈、NPS回复、支持工单主题"。

技能的复利价值。第一次构建一个技能需要30-60分钟。使用一个技能需要5-10分钟。算账很简单：

使用2次：构建60分钟 + 使用20分钟 = 总共80分钟，对比临时方式的90分钟
使用5次：60 + 50 = 110分钟，对比临时方式的225分钟
使用10次：60 + 100 = 160分钟，对比临时方式的450分钟

图8.2：技能复利价值——使用此图为构建技能的初始投资提供理由。临时提示呈线性增长（每次使用45分钟），而技能有更高的初始投入（构建60分钟），但平摊到每次使用仅10分钟。到第五次使用时，技能相比临时方式节省125分钟。

除了时间节省，技能还提供一致性。季度报告遵循相同的结构。反馈主题使用相同的分类标准。PRD审计检查相同的项目。这种一致性使得跨时间段的比较成为可能，并降低了输出成果消费者的认知负担。

8.3 技能组件

一个技能目录包含若干类型的文件。只有SKILL.md是必需的；其他文件为复杂工作流扩展能力。

SKILL.md：指令文件。这是每个技能的核心。它包含用于发现的YAML前置信息和用于执行的markdown指令。Claude Code在技能激活时读取此文件，并遵循文档化的流程。

最小可行SKILL.md：

---name: standup-notesdescription: Generate standup notes from yesterday's git commits. Use when user mentions standup, daily update, or what I did yesterday.---# Standup Notes## PurposeCreate formatted standup notes from recent commits.## Inputs- Git repository with commit history## Process1. Read commits from the past 24 hours2. Group by type (feature, fix, refactor)3. Write in first person, past tense## OutputPrint standup notes to terminal. Do not create a file.

这个最小结构适用于简单的工作流。更复杂的技能需要第8.3节中涵盖的额外部分。

参考文件：数据、评分标准、模板。技能可以包含Claude Code在执行过程中查阅的辅助文件。这些文件存放在resources/子目录中：

feedback-synthesis/├── SKILL.md└── resources/ ├── category-definitions.md ├── output-template.md └── quality-rubric.md

参考文件服务于多种目的：

分类定义：当综合反馈时，Claude Code应该使用什么分类？一次性在category-definitions.md中定义它们，而不是嵌入到SKILL.md指令中。

输出模板：生成产物的精确结构。"遵循resources/output-template.md中的模板"比将模板嵌入到指令中更清晰。

质量标准：评估输出的详细标准。使SKILL.md聚焦于流程，而将评估标准委托给一个参考文件。

风格指南：语气、语调和格式偏好。对生成面向客户内容的技能很有用。

在你的SKILL.md中，显式引用这些文件："使用resources/category-definitions.md中的定义对反馈进行分类。"Claude Code会在到达该指令时读取被引用的文件。

输出模板：一致的格式。如果你的技能产生文档，定义预期结构：

Output FormatGenerate file: `reports/feedback-synthesis-[date].md`Follow this structure:# Feedback Synthesis: [Date Range]## Executive Summary[3-5 bullet points of key findings]## Theme Analysis### Theme 1: [Name]- Frequency: [count] mentions ([percentage]%)- Sentiment: [positive/negative/mixed]- Representative quotes: - "[Quote 1]" - "[Quote 2]"- Implications: [What this means for the product][Repeat for each theme]## Recommendations[Prioritized list of suggested actions]## Methodology[Brief description of data sources and analysis approach]

这个模板确保每个反馈综合报告都具有相同的结构，使得跨时间段比较更加容易，也更容易向预期有固定格式的利益相关者展示。

可选脚本：预处理/后处理。复杂的技能可以包含辅助脚本，用于处理纯对话无法高效完成的任务：

release-notes/├── SKILL.md└── scripts/ └── fetch-jira-tickets.py

SKILL.md引用该脚本："在生成说明之前，运行scripts/fetch-jira-tickets.py --sprint [sprint-name]收集工单数据。"

对于PM技能，脚本很少是必需的。大多数PM工作流涉及文本分析和文档生成，Claude Code可以通过对话方式处理。脚本在以下场景中变得有用：

需要特定认证来调用外部API
处理直接读取会消耗过多token的大数据集
在分析之前转换数据格式

如果你发现需要脚本，考虑MCP集成（第10章）是否更简洁。

skill-name/├── SKILL.md # 必需：核心指令├── resources/ # 可选：参考文档│ ├── template.md│ └── rubric.md├── scripts/ # 可选：辅助脚本│ └── helper.py└── examples/ # 可选：示例输入/输出 ├── sample-input.csv └── expected-output.md

examples/目录对测试和文档说明很有用。包含示例输入及其应产生的输出。这有助于团队成员理解技能的功能，也有助于你在修改后验证技能是否仍然正常工作。

8.4 SKILL.md文件详解

SKILL.md结合了发现元数据和执行指令。理解这两部分有助于你编写在适当时刻激活并可靠执行的技能。

必需：YAML前置信息。每个SKILL.md以---分隔的前置信息开始：

---name: feedback-synthesisdescription: Synthesizes customer feedback into themed reports. Auto-invoke when user mentions feedback analysis, NPS synthesis, support ticket themes, or customer sentiment.---

两个字段是必需的：

name：唯一标识符，小写加连字符。它成为斜杠命令（/feedback-synthesis）和技能的显示名称。保持简洁且具描述性。

description：Claude Code用来决定何时激活技能的发现文本。包含与用户自然措辞请求方式匹配的触发词。要具体："综合客户反馈"比"帮助数据分析"匹配得更可靠。

描述服务于两个目的：帮助Claude Code自动发现技能何时适用，以及帮助人类读者理解技能的功能。为这两类受众编写。

Markdown正文中的必需部分。在前置信息之后，用以下各部分结构化你的SKILL.md：

目的声明。用一两句话解释技能完成什么以及为什么有价值。以用户收益开头，而非流程：

PurposeTransform raw customer feedback into actionable insight reports that product teams can use for prioritization decisions.

这告诉读者他们能得到什么，而不是技能内部如何运作。

输入要求。指定用户必须提供什么：

Expected Inputs- Required: CSV or text file containing customer feedback (one piece of feedback per row)- Optional: Date range for filtering (defaults to last 30 days)- Supports: CSV, JSON, plain text files- Minimum: 10 feedback entries for meaningful analysis

在格式方面要具体。"CSV文件"是模糊的；"反馈文本在名为'feedback'或'comment'列中的CSV文件"告诉Claude Code要寻找什么。

执行步骤。Claude Code遵循的编号步骤：

Process1. Read and validate input file - Confirm file exists and has expected format - Identify the feedback column - Report record count2. Identify themes - Read through all feedback entries - Group by common topics or concerns - Use category definitions from `resources/categories.md` if strict categorization is needed3. Analyze each theme - Count frequency - Assess sentiment (positive, negative, mixed) - Extract representative quotes (verbatim, not paraphrased)4. Generate report - Follow template in `resources/output-template.md` - Include executive summary, theme analysis, and recommendations - Save to `reports/feedback-synthesis-[date].md`5. Quality check - Verify all themes have supporting quotes - Confirm percentages sum to approximately 100% - Check that recommendations are actionable

使用祈使语气（"读取文件"而非"文件应被读取"）。包含决策点（"如果少于10条记录，警告并附上保留声明继续"）。适当时引用外部文件。

输出格式规范。精确定义生成什么：

Output FormatGenerate file: `reports/feedback-synthesis-YYYY-MM-DD.md`Structure:- Executive summary (3-5 bullets)- Theme analysis (one section per theme with frequency, sentiment, quotes, implications)- Recommendations (prioritized list)- Methodology (brief description)See `resources/output-template.md` for detailed structure.

指定文件路径模式可确保一致的输出位置。团队知道在哪里找到反馈报告而不需要询问。

质量标准。成功执行的可测试标准：

Quality Criteria- Every theme has at least 2 supporting quotes- Quotes are verbatim from source data, not paraphrased- Sentiment assessment explains the reasoning- Recommendations tie back to specific themes- File saves successfully to specified path

这些标准让Claude Code在完成前进行自我检查。它们也帮助你评估技能执行是否成功。

可选部分。当能提高清晰度或可靠性时添加这些：

调用示例。展示如何使用该技能：

Usage Examples- Standard: "Run feedback-synthesis on data/customer-feedback-q4.csv"- With date range: "Run feedback-synthesis on feedback.csv for November only"- Quick version: "Run feedback-synthesis, just give me the top 3 themes"

常见失败模式。记录什么会出错以及如何处理：

Edge Cases- Sparse data (<10 entries): Generate report with caveat about limited sample size- Mixed formats: If feedback column isn't obvious, ask user to specify- Very long feedback entries: Summarize individual entries exceeding 500 words- Non-English content: Note language and proceed; don't attempt translation

相关技能。指出与该技能互补的其他技能：

Related Skills- `prd-audit`: Use insights from feedback synthesis to audit PRD completeness- `user-story-expander`: Turn feedback themes into user stories

完整注释示例。以下是反馈综合的完整SKILL.md：

---name: feedback-synthesisdescription: Synthesizes customer feedback into themed reports with actionable insights. Auto-invoke when user mentions feedback analysis, NPS synthesis, support ticket themes, customer sentiment, or voice of customer.---# Feedback Synthesis## PurposeTransform raw customer feedback into actionable insight reports that product teams can use for prioritization decisions.## Expected Inputs- Required: File containing customer feedback (CSV, JSON, or plain text)- Optional: Date range, specific focus areas- Minimum 10 feedback entries for meaningful analysis- Supports feedback from: support tickets, NPS surveys, user interviews, app store reviews## Process1. Read and validate input - Confirm file exists and is readable - Identify feedback content (look for columns: feedback, comment, response, review) - Report total entry count2. Identify themes - Group feedback by common topics - Aim for 4-8 themes (merge if too granular, split if too broad) - Name themes descriptively: "Onboarding Confusion" not "Theme 1"3. Analyze each theme - Count frequency (entries mentioning this theme) - Calculate percentage of total feedback - Assess sentiment: positive, negative, or mixed - Extract 2-3 representative quotes (verbatim) - Identify implications for product decisions4. Synthesize findings - Write executive summary (top 3-5 findings) - Prioritize themes by frequency and business impact - Generate actionable recommendations5. Generate report - Save to reports/feedback-synthesis-YYYY-MM-DD.md - Follow structure in Output Format section6. Quality check - Verify all themes have supporting quotes - Confirm recommendations are specific and actionable - Check that executive summary captures key points## Output FormatGenerate file: reports/feedback-synthesis-YYYY-MM-DD.md# Feedback Synthesis: [Date Range]## Executive Summary- [Key finding 1]- [Key finding 2]- [Key finding 3]## Theme Analysis### [Theme Name]- Frequency: [X] mentions ([Y]% of feedback)- Sentiment: [Positive/Negative/Mixed]- Representative Quotes: - "[Quote 1]" - "[Quote 2]"- Product Implications: [What this means for roadmap/priorities][Repeat for each theme]## Recommendations1. [Specific action tied to theme]2. [Specific action tied to theme]3. [Specific action tied to theme]## Methodology- Source: [File name]- Period: [Date range]- Sample size: [X] feedback entries- Analysis date: [Today's date]## Quality Criteria- Every theme supported by at least 2 verbatim quotes- Quotes are exact text from source, not paraphrased- Percentages sum to approximately 100% (themes can overlap)- Recommendations are specific enough to be actionable- Executive summary is readable in under 30 seconds## Edge Cases- Sparse data (<10 entries): Proceed with caveat about limited sample- Ambiguous feedback column: Ask user to specify which column contains feedback- Multi-language content: Note language distribution; analyze separately if significant- Very long entries (>500 words): Summarize before categorizing## Usage Examples- "Run feedback-synthesis on data/q4-feedback.csv"- "Synthesize the NPS responses in surveys/november.json"- "Analyze customer feedback from support-tickets.txt, focus on billing issues"

这个技能大约600个单词——内容充实但不超过SKILL.md文件的5,000单词限制。对于需要更多细节的技能，将参考材料移到单独的文件中。

8.5 PM技能的设计模式

图8.3：五种PM技能模式——使用此图为你的工作流选择合适的结构。Transform（原始数据→结构化报告）、Investigate（问题→带证据的答案）、Generate（参数→产物）、Sync（外部来源→本地产物）、Audit（现有文档→验证报告）。将你的任务与模式匹配以实现更快的技能开发。

五种模式涵盖大多数PM技能需求。识别你的工作流适合哪种模式，并相应地构建你的技能。

Transform模式：输入→结构化输出。你有非结构化或半结构化的数据。你需要结构化的分析或文档。

示例：- 原始反馈→主题报告 - 访谈记录→洞察摘要 - Git提交→发布说明 - 会议笔记→行动项

结构：

Process1. Read and validate input data2. Apply transformation logic (categorize, summarize, restructure)3. Generate structured output4. Quality check against criteria

Transform技能具有明确的输入和输出。它们是最常见的PM技能模式。

Investigate模式：问题→带证据的答案。你需要通过检查数据或代码库来回答问题，并附上支持证据。

示例：- "为什么转化率下降了？"→带数据引用的根本原因分析 - "功能X是如何工作的？"→带文件引用的解释 - "客户对定价有什么看法？"→带支持引用的总结

结构：

Process1. Understand the question2. Identify relevant data sources3. Analyze sources for answer4. Compile evidence (quotes, references, data points)5. Synthesize answer with supporting evidence

Investigate技能与Transform技能的区别在于输出结构取决于发现了什么，而不是预定的模板。

Generate模式：参数→产物。你提供规格；技能生成与之匹配的文档或产物。

示例：- 功能描述→带验收标准的用户故事 - Sprint目标→状态报告 - 产品领域→竞品分析

结构：

Process1. Accept parameters (feature name, date range, focus area)2. Gather context (from codebase, templates, reference docs)3. Generate artifact following template4. Validate against quality criteria

Generate技能是模板驱动的。输出结构是固定的；内容根据参数而变化。

Sync模式：外部来源→本地产物。你从外部系统拉取数据，并创建或更新本地文档。

示例：- Jira epic→仓库中的PRD部分 - 分析仪表盘→每周指标摘要 - 竞品网站→更新后的竞品档案

结构：

Process1. Connect to external source (via MCP or export)2. Extract relevant data3. Transform to local format4. Create or update local artifact5. Note sync timestamp

Sync技能通常需要MCP连接（第10章）或手动数据导出作为输入。

Audit模式：产物→验证报告。你有一个现存产物。你需要根据标准评估它并报告发现。

示例：- PRD→完整性检查清单 - 用户故事→质量评估 - 文档→针对代码的准确性验证

结构：

Process1. Read artifact to audit2. Load evaluation criteria (from reference file)3. Evaluate artifact against each criterion4. Compile findings (what passes, what fails, what's missing)5. Generate recommendations for improvement

Audit技能对质量门槛很有价值：在工程交接前运行PRD审计，尽早发现差距。

选择合适的模式。问自己：

我是否有需要结构化的数据？→ Transform
我是否在回答一个问题？→ Investigate
我是否在根据规格创建东西？→ Generate
我是否在将外部数据拉入我的仓库？→ Sync
我是否在评估现有工作？→ Audit

有些工作流组合多种模式。季度评审可能先Sync分析数据，再Transform为报告，再Audit报告对比上季度目标。从主要模式开始，然后再扩展。

8.6 确定性与可重复性

给定相似的输入，技能应该产生相似的输出。完全的确定性是不可能的（语言模型具有固有的变异性），但你可以通过技能设计来提高一致性。

为什么一致性对PM工作流很重要。不一致的输出削弱了技能的价值主张：

季度反馈报告应跨季度可比
PRD审计每次应检查相同的标准
发布说明无论何时生成都应遵循相同的格式

如果每次技能执行都产生不同的结构或使用不同的标准，你只是回到了临时提示迭代的老路，只是多了几个步骤。

提高输出可预测性的技巧。

显式模式。不要说"生成一份报告"，而要说"生成一份包含以下确切各部分、按此顺序排列的报告"。你的输出格式越具体，结果就越一致。

Output FormatGenerate with exactly these sections, in this order:1. Executive Summary (3-5 bullets)2. Theme Analysis (one subsection per theme)3. Recommendations (numbered list, max 5 items)4. Methodology (one paragraph)

参考文件锚定。将可变内容移到参考文件中：

ProcessCategorize feedback using exactly the categories defined in`resources/category-definitions.md`. Do not create new categories.

这将技能锚定到固定的标准上。更新参考文件来改变行为；SKILL.md指令保持稳定。

显式质量标准。可测试的标准减少变异性：

Quality Criteria- Executive summary contains exactly 3-5 bullet points- Each theme section includes frequency count and percentage- All quotes are verbatim from source data- Recommendations reference specific themes by name

Claude Code使用这些标准进行自我检查，在输出前捕捉偏差。

约束化解读。限制Claude Code如何处理模糊情况：

Edge Cases- If a feedback entry could fit multiple themes, assign to the most specific theme- If sentiment is unclear, mark as "mixed" rather than guessing- If entry is too short to categorize (<10 words), count it but don't quote it

这些约束减少了Claude Code在边界情况下每次可能做出不同选择的变异性。

测试技能的一致性。在提交技能之前，对相同的输入多次运行它：

在示例数据上运行该技能
保存输出
清除会话（/clear）
对相同数据再次运行该技能
比较输出

完美的一致性不是目标，合理的一致性是。结构应该相同，主题应该相似，确切措辞会有所不同，但实质内容应该稳定。

如果输出差异巨大，你的技能需要更严格的约束。添加更显式的模式、参考文件或质量标准，直到一致性得到改善。

对技能进行版本控制。技能是仓库中的文件。以与代码相同的版本控制纪律对待它们：

用有意义的提交信息提交技能："添加反馈综合技能"或"更新发布说明以包含Jira工单链接"
在合并前审查技能变更（团队依赖于一致的行为）
如果技能被广泛共享，标记发布版本
记录技能行为中的破坏性变更

当你更新技能时，考虑向后兼容性。如果输出格式改变，消费该输出的现有流程会中断吗？将变更传达给依赖该技能的团队成员。

8.7 技能组合

复杂的工作流可以组合多个技能。与其构建一个包罗万象的庞大技能，不如组合那些每个只做好一件事的专注技能。

原子技能 vs. 复合工作流。原子技能处理单个任务：综合反馈、生成发布说明、审计PRD。复合工作流编排多个原子技能以实现更大的目标。

示例复合工作流：季度产品评审 1. 对Q4反馈数据运行feedback-synthesis 2. 对Q4分析导出运行metrics-summary 3. 运行competitive-update刷新竞品档案 4. 运行quarterly-review将上述内容综合为评审文档

每个原子技能独立可用。组合创造了更高层次的价值。

从其他技能中调用技能。一个技能可以指示Claude Code运行另一个技能：

Process1. Run the `feedback-synthesis` skill on the provided feedback file2. Run the `metrics-summary` skill on the provided analytics export3. Synthesize findings from both reports into a quarterly summary4. Generate the quarterly review document

这保持了每个技能的专注，同时支持复杂的工作流。

何时组合 vs. 构建单体技能。以下情况组合：- 组件技能独立有用 - 工作流有自然断点 - 不同的人可能运行不同部分 - 你想在其他工作流中重用组件

以下情况构建单体：- 工作流是真正原子的（没有有用的中间输出） - 组合增加了无益的开销 - 技能足够简单，分解是过度设计

大多数PM工作流从组合中受益。先构建原子技能，然后在模式浮现时进行组合。

你已经理解了技能的结构：包含YAML前置信息和markdown指令的SKILL.md文件、用于模板和标准的参考文件，以及用于组织的目录约定。你了解了五种设计模式（Transform、Investigate、Generate、Sync、Audit）和提高一致性的技巧。第9章提供了基本PM技能的完整示例，并带你一步步从零开始构建你的第一个技能。