# 附录 *** ## 附录 A 术语表 按首字母排序。 | 英文术语 | 中文术语 | | --- | --- | | Agent | 智能体 | | allowed-tools | 限制可使用的工具 | | brief | 设计简报 | | CDN | 在线公共资源库 | | checklist | 检查清单 | | compatibility | 环境兼容性要求 | | context | 上下文 | | context window | 上下文窗口 | | description | 简介 / 触发开关 | | editorial | 杂志风排版 | | global skill | 全局技能 | | gotchas | 踩坑点 | | hook | 钩子 | | KPI (Key Performance Indicator) | 关键绩效指标 | | license | 开源许可 | | linked files | 关联文件 | | LLM (Large Language Model) | 大语言模型 / 大模型 | | loop | 循环 | | MCP (Model Context Protocol) | 模型上下文协议 / 通用插座 | | metadata | 自定义元数据 | | name | 名称 | | parallel | 并联 | | procedural knowledge | 流程性知识 | | progressive disclosure | 渐进式披露 | | project skill | 项目技能 | | prompt | 提示词 | | regression prevention | 防退化 | | serial | 串联 | | sheet | 工作表 | | Skill | 技能 | | SOP (Standard Operating Procedure) | 标准作业程序 | | sub-agent | 子智能体 | | test case | 测试用例 | | token | 词元 | | tool | 工具 | | version | 版本号 | | workspace skill | 工作区技能 | | YAML frontmatter | YAML 前置信息 / 名片 | *** ## 附录 B 各平台技能安装指南 > ⚠️ **时效提醒**：平台界面和安装命令会随时间变化。本附录只保证方向和原则；具体命令和操作步骤请以在线更新页为准。 技能是一个开放标准，设计上可跨平台使用。以下是主要平台的安装方式。 ### Claude.ai（网页版 / 移动端） 最常用的方式，不需要任何编程知识。 **步骤：** 1. 把技能文件夹压缩成 `.zip` 文件 2. 打开 Claude.ai，进入 Settings（设置） 3. 找到 Features（功能）> Skills（技能）（菜单名称可能随版本变化） 4. 点击“Upload skill”（上传技能） 5. 选择 `.zip` 文件上传 6. 上传成功后，切换开关启用技能 **验证：** 在对话中说一句和技能 description 相关的话，看技能是否自动触发。 **注意事项：** * 压缩时确保 `SKILL.md` 在文件夹的根目录，不要多套一层文件夹 * 如果上传后技能不触发，检查 description 是否写清了触发条件 * 可以同时启用多个技能 **组织级部署：** 如果你是团队管理员，可以通过管理后台将技能推送给全团队成员，无需每人手动上传。 ### Claude Code（命令行工具） 适合开发者和习惯命令行操作的用户。 **步骤：** 1. 找到 Claude Code 的技能目录：个人级 `~/.claude/skills/`，项目级 `项目目录/.claude/skills/` 2. 把技能文件夹直接放进去 3. 重启 Claude Code 会话 **验证：** 在 Claude Code 中输入相关指令，看技能是否被加载。 **注意事项：** * 文件夹名必须是 kebab-case * SKILL.md 必须大写 * 如果技能包含脚本，确保脚本有执行权限（`chmod +x scripts/*.sh`） ### 其他平台 agent skills 已作为开放标准发布。以下平台也支持或正在接入技能格式： | 平台 | 支持方式 | 状态 | | ------------------------ | -------------------- | ----- | | VS Code / GitHub Copilot | 通过扩展集成 | 已支持 | | OpenCode | 类似 Claude Code 的目录结构 | 已支持 | | 其他 AI 平台 | 视各平台实现而定 | 持续扩展中 | 由于平台支持情况变化较快，建议查看 agentskills.io 获取最新的兼容平台列表。 *** ## 附录 C 国内模型 API 平台与部署方案汇总 > ⚠️ **时效提醒**：以下信息随平台迭代会发生变化，请以各平台官网为准。 ### 国内主流模型 API 平台 | 平台 | 官网 | API 文档 | 代表模型 | 特点 | | :------------- | :------------------------- | :--------------------------- | :------------ | :------------------------------------------------------------ | | 阿里云百炼 | bailian.console.aliyun.com | help.aliyun.com/model-studio | Qwen 3.5 Plus | Coding Plan 打包 8 款模型（Qwen、Kimi、GLM 等），首月 7.9 元起，OpenClaw 官方集成 | | Moonshot（KiMi） | platform.moonshot.cn | 同左 | Kimi K2.5 | 支持 256K 超长上下文，提供针对 Kimi Code 的付费订阅计划 | | 智谱 AI（GLM） | bigmodel.cn | docs.bigmodel.cn | GLM-5 | 面向编程和智能体场景优化，提供 GLM Coding Plan | | DeepSeek | platform.deepseek.com | api-docs.deepseek.com | DeepSeek-V3.2 | API 格式完全兼容 OpenAI，注册送免费额度 | | 火山方舟（豆包） | console.volcengine.com/ark | volcengine.com/docs/82379 | 豆包大模型 1.8 | 字节跳动旗下，搭载豆包及业界主流大模型 | ### 什么是 Coding Plan？ Coding Plan 是模型厂商专门为 AI 编程工具（如 OpenClaw、Claude Code 等）推出的订阅套餐。和按 token 用量计费不同，Coding Plan 按月支付固定费用，提供一定额度的请求次数，用完等下个周期自动恢复，不会出现意外的高额账单。对于日常使用智能体的用户来说，Coding Plan 是性价比最高的选择。目前阿里云百炼、Moonshot（KiMi）、智谱 AI (GLM) 都提供了 Coding Plan 或类似服务。 ### OpenClaw 云端一键部署 如果你不想在本地折腾安装，国内几大云厂商都推出了 OpenClaw 一键部署方案：购买一台轻量应用服务器（云端专属电脑），几分钟就能完成部署，全程图形界面操作。核心流程只有 4 步：购买服务器 → 选择模型 → 配置聊天工具 → 开始使用。 | 云厂商 | 方案说明 | 官网 | | :---- | :------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------- | | 腾讯云 | 基于轻量应用服务器 Lighthouse 一键部署，提供 OpenClaw 专属应用镜像（提前配置好所有运行环境的模板），部署后可实现 7×24 小时不间断运行。作为国内第一时间支持 OpenClaw 的云厂商，腾讯的“云上养虾人”（OpenClaw 云端用户的昵称）规模已突破 10 万。 | cloud.tencent.com/act/pro/lighthouse-moltbot | | 阿里云 | 基于轻量应用服务器部署，集成阿里云百炼模型平台（可直接选用各类 AI 模型的一站式平台），支持 Coding Plan 订阅（首月 7.9 元起，打包 Qwen、Kimi、GLM 等 8 款模型）。 | cn.aliyun.com/benefit/scene/moltbot | | 百度智能云 | 轻量应用服务器极简部署方案，集成百度千帆平台，支持文心、Qwen、DeepSeek 等模型一键配置，还提供百度搜索、百度百科等官方技能。 | cloud.baidu.com/product/BCC/moltbot.html | ### OpenClaw 聊天工具接入 OpenClaw 支持通过聊天工具下达指令，就像是给你的服务器配了一个“远程遥控器”，让你随时随地都能给 AI 派活儿。目前已覆盖国内四大主流平台。 | 平台 | 说明 | | :--- | :---------------------------------------------------------------- | | 钉钉 | 配置最简单，支持 Stream 模式（基于 WebSocket 的实时通信通道），无须额外配置公网 IP 和域名，5 分钟即可完成 | | 飞书 | 官方提供完善的飞书频道支持，推荐使用长连接模式，配置流程与钉钉类似 | | 企业微信 | 支持应用消息推送，可按需选配腾讯云语音转文本功能 | | QQ | 通过 QQ 开放平台机器人接入，支持私聊互动 | 云端部署用户可在管理后台直接配置聊天工具，不需要敲命令。本地安装用户可使用社区提供的 openclaw-china 插件包（github.com/BytePioneer-AI/openclaw-china），一键安装钉钉、飞书、QQ、企业微信支持。 ⚠️ **避坑指南：云端一键部署与聊天工具接入的安全注意事项** * **云服务器不是安全沙箱**：你买的轻量应用服务器，本质就是一台专属的云端电脑。OpenClaw 对它拥有完整操作权限，可以直接修改、删除里面的文件。哪怕它不在你手边，也要严格把关它执行的每一条命令。 * **管好你的“远程遥控器”**：聊天工具就是操控这台云端电脑的远程遥控器。当 OpenClaw 在聊天框向你确认“是否执行”时，一定要看清内容再回复。如果把 OpenClaw 拉进多人工作群，记得在管理后台设置操作白名单，只允许你信任的人发指令。 *** ## 附录 D 写作工作流及访谈整理工作流完整版技能 第 5 章用简化模板介绍了素材分析、大纲技能的基本结构。以下是作者在日常写作工作流中实际使用的四个完整技能，供读者参考和借鉴。 对比第 5 章的简化模板和这些完整版本，你会发现完整版多了什么：更细致的分析维度、更具体的输出格式约定、更多的边界情况处理、内置的串联逻辑。这些都是在实际使用中逐步迭代出来的。正如第 6 章所说，技能是“用”出来的，不是“设计”出来的。 **四个技能的串联关系：** ``` 通用写作工作流： 素材 → [D.1 content-analyzer] → 分析报告 ↓ [D.2 outliner] → 多个大纲方案 → 用户选择 ↓ [写作技能] → 文章 访谈写作工作流： 访谈转录稿 → [D.3 interview-analysis] → 素材包 + 大纲 ↓ 人工检查点 [D.4 interview-writing] → 访谈实录 ↑ 加载 writing-style（基调约束） ``` ### D.1 素材分析技能（content-analyzer） 对应第 5 章 5.4.1 节的简化版。完整版增加了内容类型识别、快速摘要、联网检索判断等。 **与简化版的关键差异：** | 维度 | 简化版（第 5 章） | 完整版 | | ----- | ---------------- | -------------------- | | 内容类型 | 不区分 | 区分长文/短内容/视频文稿，调整分析侧重 | | 分析前 | 直接分析 | 先输出快速摘要 | | 分析维度 | 4 个（核心/背景/批判/价值） | 5 个，增加叙事技巧（可选） | | 价值提取 | 3 项 | 5 项，增加内在张力和可用情境 | | 联网检索 | 无 | 明确的检索/不检索判断标准 | | 输出元数据 | 无 | 包含来源、时间、内容类型 | 完整 SKILL.md 如下： ```markdown --- name: content-analyzer description: 素材深度分析技能。当用户提供文章、推文、视频文稿等内容并要求分析时使用。 适用于：(1) 理解素材核心观点和论证逻辑，(2) 批判性评估内容，(3) 为后续写作提取可用素材， (4) 分析内容的传播价值。支持长文、短内容（推文/帖子）、视频文稿等多种内容类型。 --- # 素材分析技能 ## 分析流程 ### 第一步：识别内容类型 根据素材特征判断类型，调整分析侧重： | 类型 | 特征 | 分析侧重 | |------|------|----------| | **长文** | >1000 字，结构完整 | 完整走全部分析维度 | | **短内容** | 推文、帖子、<500 字 | 侧重信息密度、传播点、核心洞察 | | **视频文稿** | 口语化、有时间标记 | 关注节奏、口语表达、关键时刻 | ### 第二步：输出快速摘要 在详细分析前，先输出 3-5 句核心摘要： - 这是什么内容？ - 核心观点是什么？ - 最有价值的点是什么？ --- ## 分析框架 按以下维度逐层分析。若信息不足，说明原因。 ### 一、核心内容 1. **核心论点**：用一句话概括 2. **关键概念**：作者用了哪些关键概念？如何定义？ 3. **文章结构**：论证如何展开？各部分如何衔接？ 4. **证据支撑**：有哪些具体案例、数据或权威引用？ ### 二、背景语境 1. **作者身份**：作者是谁？背景、立场是什么？ 2. **写作背景**：在什么背景下写的？回应什么现象或争论？ 3. **写作目的**：想解决什么问题？想影响谁？ 4. **底层假设**：有哪些没说出来的前提？ ### 三、批判性审视 1. **可能反驳**：主要的反对意见可能是什么？ 2. **论证漏洞**：有没有漏洞、跳跃或偏颇之处？ 3. **适用边界**：观点在什么情况下成立？什么情况下不成立？ 4. **回避问题**：作者有没有刻意回避什么问题？ ### 四、价值提取 1. **思考框架**：有什么可复用的思考框架或方法论？ 2. **核心启发**：对目标读者最大的启发是什么？ 3. **认知改变**：可能改变读者的什么认知？ 4. **内在张力**：素材中有哪些可利用的对立或反差？ - 能力反差（专家 vs 普通人） - 认知反差（预期 vs 现实） - 数字对比（具体的势能差） 5. **可用情境**：这个话题适合什么场景切入？ - 具体场景、具体角色、具体时刻 ### 五、叙事技巧（可选） 仅在用户要求或内容写作技巧突出时分析： 1. **开头策略**：如何开头？能否快速抓住注意力？ 2. **信任建立**：如何拉近与读者距离？ 3. **情绪设计**：共鸣点、好奇点、惊喜点在哪？ 4. **值得学习**：有什么可复用的写作技巧？ --- ## 联网检索 ### 需要检索 - 引用具体数据且存疑 - 引用名人名言且对论证关键 - 涉及重大争议事件 - 作者是公众人物，背景影响理解 - 对关键事实不确定 ### 不需要检索 - 纯观点性质，不涉及可核查事实 - 数据/事件是常识 - 虚构作品或个人随笔 ### 检索原则 - 存疑就检索，不猜测不编造 - 核查结果标注：`[事实核查：原文称"XXX"，经查证为"YYY"]` - 没搜到就说"未找到相关信息" --- ## 执行要求 - 逐一回答每个问题，不跳过 - 回答要具体，引用原文佐证 - 避免空泛概括 - 信息不足时明确说明原因 - **短内容可精简维度二、三，聚焦核心洞察和传播价值** - **开始分析前先评估：是否包含需要核查的事实性声明？** ## 输出格式 ## 快速摘要 [3-5 句核心摘要] ## 一、核心内容 ... ## 二、背景语境 ... ## 三、批判性审视 ... ## 四、价值提取 ... ## 五、叙事技巧（如适用） ... ## 结果保存 分析完成后保存为 `analysis.md`，文件开头添加： --- source: [原素材文件名] analyzed_at: YYYY-MM-DD HH:mm content_type: [长文/短内容/视频文稿] --- ``` ### D.2 大纲技能（outliner） 对应第 5 章 5.4 节的简化版。完整版增加了选题判断、叙事结构选择、情绪曲线标注，并在正文的“步骤 2”中写死了调用 `content-analyzer`。这是第 5 章“写死名字”引用方式的真实案例，因为 `outliner` 强依赖 `content-analyzer` 的特定输出格式。 **与简化版的关键差异：** | 维度 | 简化版（第 5 章） | 完整版 | | ---- | ---------- | ------------------------------------- | | 选题判断 | 无 | 三维评估（专业性/读者兴趣/时间节点），不值得写会告知 | | 叙事结构 | 未指定 | 五种结构可选（故事驱动/问题解决/颠覆重建/情境代入/过程展示） | | 情绪设计 | 无 | 标注共鸣/好奇/共情/借势/升华 | | 串联逻辑 | 在口令中指定 | 正文“步骤 2”写死调用 `content-analyzer` | | 文件管理 | 只约定文件名 | 完整的目录结构规范（`posts/YYYY-MM-DD/[slug]/`） | | 角色定位 | 无 | 明确作者身份和读者画像 | 完整 SKILL.md 如下： ```markdown --- name: outliner description: 科技专栏提纲生成技能。当用户提供素材（文章、推文、视频文稿等） 要求生成写作提纲时使用。生成 3-5 个差异化大纲方案（优先包含故事驱动型）， 每个方案保存独立文件供用户选择。 --- # 大纲技能 ## 角色定位 "我"是"宝玉"，AI 领域资深从业者、自媒体博主。写作风格：把复杂技术讲得明白有趣，像懂行的朋友聊天。 ## 读者画像 技术爱好者，对 AI、编程、互联网话题感兴趣，但不一定有专业背景。 ## 文件管理 所有文件保存到 `posts/YYYY-MM-DD/[slug]/` 目录： posts/2026-01-21/ai-agent-guide/ ├── source-1.md # 素材 ├── analysis.md # 分析结果 ├── outline-a.md # 方案 A ├── outline-b.md # 方案 B └── outline-c.md # 方案 C - `[slug]` 根据主题生成，英文小写 + 连字符 - 目录已存在则换个 slug，不覆盖 --- ## 工作流程 ### 步骤 1：保存素材 收到素材后立即保存： 1. 生成 slug 2. 检查目录是否存在（存在则换 slug） 3. 保存为 `source-1.md`（多份素材依次编号） ### 步骤 2：调用分析技能 调用 `content-analyzer` 进行深度分析，重点关注： - 核心论点和关键概念 - 背景语境和作者立场 - 可复用的框架和价值点 - 内在张力和可用情境 ### 步骤 3：选题判断 分析完成后快速评估： | 维度 | 检查点 | |------|--------| | 专业性 | 这是我的专业领域吗？ | | 读者兴趣 | 读者普遍关心吗？ | | 时间节点 | 为什么是现在写？ | 三者缺一：专业但不感兴趣 → 曲高和寡；有兴趣但不专业 → 流于肤浅；是热点但不专业 → 昙花一现。 **不值得写就直接告知用户，说明原因。** ### 步骤 4：生成 3-5 个提纲方案 #### 叙事结构选择 | 结构 | 适用场景 | 骨架 | |------|---------|------| | **故事驱动** | 观点文、经验分享 | 故事引入 → 问题揭示 → 探索过程 → 解决方案 → 升华 | | **问题解决** | 教程、方案类 | 问题 → 原因 → 方案 → 升华 | | **颠覆重建** | 观点类、思辨类 | 颠覆认知 → 新视角 → 重建理解 | | **情境代入** | 评论文、热点解读 | 情境代入 → 揭示问题 → 分析原因 → 给出判断 | | **过程展示** | 教程、复盘 | 成果展示 → 决策过程 → 迭代细节 → 方法总结 | #### 方案格式 每个方案按以下结构输出： ## 方案 [A/B/C]：[一句话定位] **风格定位**：调性和适合场景 **叙事结构**：采用什么结构 **开头策略**：用什么方式开头 **预估篇幅**：约 xxx 字 ### 正文结构 1. **[小标题]**：要点说明 [情绪标注] 2. **[小标题]**：要点说明 3. ... ### 结尾策略 用什么方式收尾 ### 方案优势 适合场景 / 突出价值 ### 写作提示 重点展开 / 可省略 / 需补充内容 #### 情绪曲线标注 在结构中标注情绪点： - `[共鸣]`：读者想"我也是这样" - `[好奇]`：读者想"然后呢" - `[共情]`：适合插入真实经历、困惑或失败 - `[借势]`：适合引用权威、经典理论 - `[升华]`：点睛之笔 #### 差异化要求 **必须包含一个故事驱动型方案。** 差异化维度（任选 2-3 个）： - 篇幅：精简版 vs 深度版 - 角度：技术版 vs 商业版 vs 普通人视角 - 风格：严肃分析 vs 对话评论 - 受众：专业读者 vs 小白友好 - 开头：信息直入 vs 情境代入 vs 故事引入 #### 故事驱动型要素 1. **具体的人**：不是"有人"，是"我朋友""前同事" 2. **具体的时间地点**："周末""凌晨三点" 3. **具体的冲突**："被裁了""项目延期" 4. **探索过程**：尝试什么，失败什么，转折点 5. **解决方案**：如何解决，带来什么改变 6. **一句话升华**：从个案上升到普遍意义 ### 步骤 5：保存并展示 1. 每个方案保存为独立文件：`outline-a.md`、`outline-b.md`... 2. 展示摘要等待选择： 已生成 X 个提纲方案： - 方案 A（故事驱动版）：[一句话定位] - 方案 B（深度解析版）：[一句话定位] - 方案 C（精简速读版）：[一句话定位] 请选择要写作的方案（可多选，如：A、B） 也可以提出修改意见 --- ## 用户选择后 - **选择方案**：调用写作技能，传入素材、分析结果、选中的提纲 - **修改提纲**：按要求修改后重新展示 - **多选**：为每个选中方案分别启动写作 - **"全部写"**：为所有方案启动写作 ## 特殊情况 - **素材单薄**：最少 3 个方案 - **素材丰富**：可 4-5 个方案 - **素材有错误**：分析阶段指出，询问处理方式 - **观点分散**：建议拆成多篇短文 ``` ### D.3 访谈内容分析技能（interview-analysis） 这是一个专门针对播客/视频访谈的分析技能。与 D.1 的通用素材分析相比，它增加了对话动态分析、金句收集、叙事素材提取等访谈特有的维度，并且在末尾直接生成写作提纲，为下游的 D.4 写作技能做好交接。 这个技能展示了第 5 章的核心概念：它本身是一个独立技能（一个技能做一件事），它的输出会串联给 D.4 使用，两者之间通过文件和格式约定传递信息。 ```markdown --- name: interview-analysis description: 分析播客/视频访谈内容，提取高价值信息点、金句、待验证背景， 并生成详细写作提纲。当用户提供访谈转录稿或整理稿，需要进行内容分析、 素材提取、或准备写作提纲时使用此 skill。 --- # 访谈内容分析 将播客/视频访谈转化为结构化的写作素材包和提纲。 ## 分析框架 ### 1. 核心信息点提取 按主题分类，列出所有有价值的信息点，使用标签标注类型： - **【独家/仅此人】** 首次披露的内部信息、未公开细节，或只有该受访者的 身份、经历、资源才能给出的信息（不一定是首次披露，但普通人无从得知） - **【反常识】** 与公众认知不同的观点或事实 - **【具体数字】** 可量化的细节（时间、金额、比例等） - **【预测】** 关于未来的判断或时间线 对每个关键论点，额外标注： - **新颖度**：已知常识 / 旧观点新角度 / 全新观点 - **可信度**：有数据或案例支撑 / 纯个人推测 / 有明显利益相关性 - **逻辑强度**：论证链条是否完整，薄弱环节在哪里 ### 2. 金句收集 提取可直接引用的原话，筛选标准： - 有画面感或情绪张力 - 能独立传播（脱离上下文仍有冲击力） - 体现受访者独特视角或性格 每条金句标注：原话内容、所属主题、使用建议（适合做标题/开头/论据等） ### 3. 叙事素材提取 除金句外，单独提取以下写作素材： - **类比和比喻**：受访者用来解释复杂概念的比方，标注原文位置和可用于 解释什么概念 - **故事和案例**：受访者讲述的亲身经历、决策内幕、具体场景，标注叙事 完整度（完整故事 / 片段 / 仅提及） - **情绪高点**：受访者明显兴奋、激动、严肃或犹豫的段落，标注情绪类型 和触发话题 ### 4. 对话动态分析 分析访谈的对话结构，而非仅提取嘉宾观点： - **关键追问**：主持人的哪些追问让嘉宾停顿、改口、深入展开或给出意外 回答？摘录问题原文 - **回避与转移**：嘉宾对哪些问题明显回避、模糊处理或转移话题？标注 被回避的问题和可能原因 - **对话转折点**：话题突然深入或方向变化的时刻（往往是最有价值的信息 出现的地方） - **互动质量**：主持人是在引导深入思考，还是仅在铺陈已知信息？ ### 5. 待补充背景 列出需要搜索验证或补充的信息： - 受访者提到的事件/数据的准确性 - 可交叉验证的相关信源 - 与业内其他人判断不同的观点（标注分歧点） ### 6. 值得深挖的点 指出访谈中点到为止但值得追问的地方： - 判断依据缺失：受访者下了结论但没解释为什么 - 潜在推论：这个观点如果成立，意味着什么 - 言外之意：有什么没说出口但可以推断的信息 - 矛盾或存疑：与公开信息或常识冲突的地方 ### 7. 访谈实录提纲 按访谈原始章节顺序生成写作提纲。每个章节包含： - **章节标题**：概括该段讨论的核心话题 - **采访者提问**：保留引出该话题的关键问题原文 - **回复要点**：被采访者在该话题下的核心观点（3-5 个要点） - **可用金句**：该章节中可直接引用的原话 - **背景补充标记**：标注哪些术语、事件需要添加编者注 - 标注格式：`[需补充: XXX的背景]` #### 章节合并与拆分建议 - 某个话题讨论过于零散（多次跳回），建议合并到一个章节 - 某个话题讨论过长（超过访谈时长 20%），建议拆分为子章节 ## 输出要求 - 宁可过度提取，不要遗漏有价值的信息 - 判断和事实分开标注（"受访者认为..."vs"数据显示..."） - 如有明显矛盾或存疑之处，明确指出 - 分析完成后询问用户：提纲是否需要调整？是否需要补充搜索背景资料？ ``` ### D.4 访谈实录写作技能（interview-writing） 这是 D.3 的下游技能。它拿着 `interview-analysis` 产出的素材包和提纲，写成一篇完整的访谈实录文章。它展示了第 5 章的两个核心概念：**串联**（依赖 D.3 的输出）和**基调约束**（开头就声明"写作前必读 `writing-style`"）。 注意它对“整理的边界”的定义：允许做什么、不做什么都写得非常具体。这正是第 7 章强调的“反面清单”思路。 ```markdown --- name: interview-writing description: 将播客/视频访谈的分析素材转化为访谈实录整理文章。按访谈原始 顺序组织，保留问答结构的对话感，补充背景解读，让读者通过文字快速了解 访谈全貌。当用户已完成访谈内容分析（有素材包和提纲），需要撰写正式文章 时使用此 skill。 --- # 访谈实录写作 将分析素材转化为忠实、完整、有背景解读的访谈实录整理文章。 ## 前置依赖 **写作前必读** writing-style 技能，遵循其中的禁止 AI 味规则和输出格式。 以下补充访谈实录写作的特有要求。与 writing-style 冲突时，以本技能为准。 ## 文章定位 访谈实录整理是原始访谈的**结构化文字版**，让读者不看视频/不听播客， 仅通过阅读就能获得访谈的全部信息价值。 - ≠ 逐字转录（去除口语冗余，提炼要点） - ≠ 评论文章（不重组逻辑，不大段介入分析） - ≠ 摘要（不压缩，保留具体细节和论证过程） 核心原则：**按原始顺序，问什么写什么，忠实但精炼。** ## 语言处理原则 目标读者是中文用户，英文不一定好。所有内容必须以中文为主体。 ### 对话内容的中文重写 访谈中的英文对话**必须用中文重写**，而非保留英文原文。 - 忠实传达原意，但用自然流畅的中文表达 - 去除口语冗余，保留实质内容 - **英文俚语和口语不要直译**，找中文等价表达 ### 金句的双语呈现 精选的金句采用**中文翻译在前、英文原文在后**的双语格式。 筛选标准：有画面感、能独立传播、体现独特视角。每个章节 1-2 条足够。 ### 专有名词处理 不常用的专有名词在**首次出现**时必须解释。 判断标准：一个不在科技行业工作的聪明读者，看到这个词会不会卡住？ ## 文章结构 ### 一、开头 三件事：受访者是谁（核心身份 + 为什么值得听）、聊了什么（3-5 个核心 话题）、访谈来源（节目名称、日期、原始链接）。 ### 二、正文：逐章节问答 按访谈讨论顺序划分章节，每个章节对应一个讨论话题。 #### 让回复"好懂"的三个手法 1. **展开论证逻辑链**：受访者脑中的推理过程，替读者拆成可跟随的步骤 2. **拆解抽象概念**：当受访者一口气抛出多个关键词，逐个拆开解释 3. **补充具体场景让观点落地**：当受访者说了抽象判断，补充读者能想象的场景 #### 背景解读（编者注） 当讨论内容涉及读者可能不熟悉的信息时，补充简要解读。 原则：简洁，一两句话解决，不喧宾夺主。 #### 消除语境困惑 中文读者看不到原始视频，缺少画面和语境。注意识别并消除可能让读者困惑 的人物关系、访谈机制、文化背景等。 ### 三、小标题 小标题 = 该章节讨论了什么 + 核心结论是什么。 - ❌ "关于竞争" → ✅ "Google 的技术被别人先商业化了" - ❌ "AI 与能源" → ✅ "330,000 块芯片需要一座核电站的电力" ### 四、结尾 归纳核心观点，指出值得关注的信号，附上原始链接。 ## 写作原则 ### 具体细节保护 数字、时间线、技术名称、公司名称**不可在整理时省略**。 - ❌ "大量芯片需要大量电力" - ✅ "330,000 块 GB300 芯片需要发电端提供整整 1GW 的电力" ### 事实与观点区分 - 受访者的个人判断：用"XX 认为""XX 预测"标注 - 可验证事实：用陈述句表达 ### 对话感的保持 保留让嘉宾停顿、改口、深入展开的关键追问。观点交锋、意见分歧的段落 完整呈现。 ### 整理的边界 实录整理允许： - 去除口语冗余 - 调整语序使表达更流畅 - 合并同一话题的分散讨论 - 补充背景解读 实录整理不做： - 重组论证逻辑 - 大段作者分析或评论 - 替受访者补充他没说的论据 - 美化或弱化受访者的表态 ``` ### D.3 和 D.4 的串联关系 `interview-analysis` → `interview-writing` 是一条典型的串联流水线： ``` 访谈转录稿 → [interview-analysis] → 素材包 + 提纲 → [interview-writing] → 访谈实录文章 ↑ ↑ 人工检查点 加载 writing-style （确认提纲） （基调约束） ``` 这条流水线体现了第 5 章的三个核心原则： * **串联**：分析技能的输出（素材包 + 提纲）是写作技能的输入 * **人工检查点**：分析完成后暂停，用户确认提纲再写，不是所有步骤都要全自动 * **基调约束**：写作技能开头就声明"写作前必读 `writing-style`"，确保风格一致 *** ## 附录 E 技能发布前完整检查清单 做完一个技能，上传之前过一遍这张清单。建议打印出来贴在旁边。 ### 开始之前 * [ ] 明确了 2-3 个具体使用场景 * [ ] 确认了需要哪些工具（内置工具还是 MCP） * [ ] 规划好了文件结构（SKILL.md + 需不需要 scripts/、references/） ### 开发过程中 **文件规范** * [ ] 文件夹名是 kebab-case（小写 + 连字符） * [ ] `SKILL.md` 文件名拼写正确（全大写 + .md） * [ ] 文件夹内没有 `README.md` * [ ] name 字段是 kebab-case，没有空格和大写 * [ ] name 不包含“claude”或“anthropic” **前置信息** * [ ] 有 `---` 分隔符包裹 * [ ] description 写了“做什么” + “什么时候用” * [ ] description 不超过 1024 字符 * [ ] 没有 XML 尖括号 `< >` **正文质量** * [ ] 指令清晰、可操作（不是“请适当处理”而是“按以下步骤”） * [ ] 包含错误处理（输入为空、格式异常怎么办） * [ ] 有具体示例（输入输出的样例） * [ ] 参考文档有明确链接（`references/` 中的文件路径写清楚了） ### 上传之前 **触发测试** * [ ] 用 5 种不同说法测试，该触发的都触发了 * [ ] 用 3 种不相关的说法测试，不该触发的没触发 * [ ] 问智能体“你什么时候会用这个技能？”，回答符合预期 **功能测试** * [ ] 同一个输入跑了 3 遍，结果基本一致 * [ ] 测试了边界情况（空输入、超长输入、格式异常） * [ ] 工具调用正常（如果有 MCP 或脚本） **打包** * [ ] 压缩为 `.zip` 文件 * [ ] 解压后 `SKILL.md` 在根目录（没有多套一层文件夹） ### 上传之后 * [ ] 在真实对话中测试了一次 * [ ] 观察了触发是否正常（过多还是过少） * [ ] 记录了第一次使用中发现的问题 * [ ] 根据反馈做了至少一次迭代 ### 技能触发排查卡 技能不触发时，按以下顺序排查： | 步骤 | 检查项 | 排查方法 | | -- | ----------------- | ---------------------------- | | 1 | 技能装好了吗？ | 问智能体：“你现在有哪些可用的技能？” | | 2 | 重启了吗？ | 终端工具需重启以扫描新技能；扣子刷新页面 | | 3 | description 写对了吗？ | 检查 description 是否包含用户常用的说法 | | 4 | 说法匹配吗？ | 试 3-5 种不同说法，看哪些能触发 | | 5 | 技能冲突了吗？ | 多个技能 description 相似时，智能体可能选错 | **80% 的触发问题出在 description 上。** 先检查第 3 步。 *** ## 附录 F 小红书信息图技能演化过程：从提示词到多文件技能 第 6 章 6.3.2 节提到过这个案例——我的小红书信息图技能从一份日常用的提示词模板起步，经过 20 多次 commit 的迭代，最终长成 641 行主文件加 26 个参考文档的多文件技能。本附录完整记录这段演化。 ### F.1 起点：一份反复使用的提示词模板 做成技能之前，我已经反复用这份提示词一两个月了。每次做小红书图都拿出来手动粘贴。 ``` # 角色定义 你是一位专业的小红书视觉内容策划师，擅长将复杂内容拆解为吸引眼球的卡通风格系列信息图。 # 任务 分析输入内容，将其拆解为 1-10 张小红书风格的系列信息图，并为每张图片输出独立的生成提示词。 # 拆解原则 1. 封面图（第 1 张）：强烈视觉冲击力，包含核心标题和吸引点 2. 内容图（中间）：每张聚焦 1 个核心观点，信息密度适中 3. 结尾图（最后 1 张）：总结/行动号召/金句收尾 # 图片数量判断标准 - 简单观点/单一主题：2-3 张 - 中等复杂度/教程类：4-6 张 - 深度干货/多维度分析：7-10 张 # 视觉风格规范 ## 基础设定 - 图片类型：信息图（Infographic） - 方向比例：竖版，3:4 或 9:16 - 整体风格：卡通风格、手绘风格 ## 背景与配色 - 背景色：莫兰迪色系 / 奶油色 / 米白色 / 浅粉 / 薄荷绿等温柔色调 - 配色柔和统一，符合小红书审美 ## 文字风格 - 必须使用手绘风格文字 - 大标题突出醒目，重点文字加粗放大 - 可使用荧光笔划线效果强调关键词 - 禁止使用写实风格字体 ## 装饰元素 - 加入少量简洁的卡通元素、图标，增强趣味性和视觉记忆 - 可使用：emoji 风格图标、手绘贴纸、便签纸质感、对话气泡等 - 所有图像元素必须是手绘/卡通风格，禁止写实风格图画 ## 排版原则 - 信息精简，突出关键词与核心概念 - 多留白，易于一眼抓住重点 - 要点分条呈现，层次清晰 # 输出格式 对于每张图片，按以下结构输出： --- ### 第 X 张 / 共 N 张 **图片定位**：[封面图 / 内容图 / 结尾图] **核心信息**：[这张图要传达的 1 句话核心] **文字内容**： - 主标题：xxx - 副标题/要点：xxx - 补充说明（如有）：xxx **视觉提示词**： 小红书风格信息图，竖版（3:4），卡通风格，手绘风格文字，[具体背景色]背景。 [具体内容布局描述] 加入简洁的卡通元素和图标增强趣味性和视觉记忆：[具体元素描述] 整体风格：手绘、可爱、清新，信息精简，多留白，重点突出。 所有图像和文字均为手绘风格，无写实元素。 --- # 语言规则 - 除非特别要求，输出语言与输入内容语言保持一致 - 中文内容使用全角标点符号 # 术语表（英文转中文时使用） - Token -> Token - AI Agent -> AI 智能体 - Vibe Coding -> 凭感觉编程 - AI Wrapper -> AI 套壳 ``` ### F.2 转化：让智能体把提示词封装成技能 用烦了手动粘贴之后，我对智能体说： ``` 帮我参考下面的提示词写一个小红书图片生成的 skill，要求： 1. 根据输入的内容先生成 outlines 2. outlines 保存到文章同一目录下 3. 在生成 outline 后，调用图片生成技能一张张挨个生成 [粘贴 F.1 的提示词模板] ``` 注意这个请求的结构：先说要做什么，再说技术要求，最后附上现有的提示词模板。 ### F.3 初版：约 200 行的 SKILL.md 不到 2 分钟，智能体生成了初版 SKILL.md——主要由三块组成： * **多步工作流**：分析内容 → 生成大纲 → 保存大纲 → 逐张生成 → 检查输出 * **视觉风格指南**：竖版 3:4、卡通手绘风、莫兰迪配色（直接搬自原提示词） * **文件管理结构**：每篇文章一个目录，大纲和图片分别存放 审查初版：流程清晰、文件管理合理、关键限制明确。不足之处也有——只支持一种视觉风格、没有生成前的人工确认步骤。但这些都可以接受，第一版的目标是“能跑”，不是“完美”。 立刻用一篇真实文章测试，几分钟后 5 张图片出现在目录下。能跑通。 ### F.4 第一次迭代：保住中间产物 跑通之后立刻发现一个问题：智能体写到一半的图片提示词没有落盘，全丢在对话里，重跑哪张图都找不着。于是： ``` 帮我更新一下 skill，把中间写的 prompt 文件也保留下来 ``` 智能体交回来的改动超出预期——不仅把提示词落了盘，还顺带引入了**会话管理**（session）机制。对应的 commit： ``` feat: implement session management for image generation skills and add session handling functions ``` 每一次运行自动创建一个独立的 session 目录，分析结果、大纲、每张图的提示词、最终图片都有各自固定的存放位置。这个骨架在之后一直没变。后来还有一次相关的加固（`fix: remove notebook style, add backup rules for prompts and images`），补上了“提示词和图片在被覆盖前先自动备份一份”的规则——又是被一次真实的误覆盖逼出来的。 ### F.5 接下来的关键节点 20 多次 commit 里不是每次都值得单独讲，下面挑 5 个真正改变了技能形态的节点。 **分析框架：从“分析内容”到“怎么分析”** 早期 SKILL.md 让智能体“分析输入内容并拆成系列图”，但没规定怎么分析——同一篇文章让它分析两次，切分点可以完全不一样。 ``` feat: add analysis framework for Xiaohongshu content ``` 这次提交把“小红书内容分析”单独抽成一份框架文档（现在的 `workflows/analysis-framework.md`），规定从哪几个维度去看、每个维度看什么、如何判断读者类型。有了框架之后，同一篇文章反复分析出来的结果开始稳定。 **工作流精简：从 6 步到 4 步** 原始流程有 6 步：分析 → 确认分析 → 生成大纲 → 确认大纲 → 生成图 → 确认图。用了一阵子发现中间两次确认大多是多余的，只有方向偏了才需要停一下。 ``` feat: streamline workflow with smart confirm (6→4 steps) ``` 合并为 4 步的同时引入了 smart confirm——低风险环节智能体自己推进，关键节点才停下来等用户拍板。这条经验后来也写进了第 6.2.2 节讲的“可容错”三板斧里。 **首次配置与扩展文件机制** 水印、默认风格、品牌色这些是每个用户都不一样的东西，写死在主技能里显然不对。于是： ``` refactor: enforce blocking first-time setup feat: add XDG config path support for EXTEND.md ``` 第一次运行时，技能会强制走一遍配置流程，把用户的偏好写进 `EXTEND.md`（支持项目级和用户级两档，用户级走 XDG 标准路径）。之后每次运行都先读 EXTEND.md 再执行。这就是第 6.2.3 节讲的**扩展文件机制**在这个技能里的落地。 **架构重构：风格预设 + 色板独立** 主文件里累积的风格定义越写越长，读起来像字典。更麻烦的是——每加一种风格都要动主文件，改的时候还得小心别踩到别的。其中 notebook 风格在加入之后一直出不了好效果，最终撤掉（`feat: add notebook and study-notes styles` → `fix: remove notebook style`）。加加删删几次后，终于下决心彻底拆： ``` feat: add screen-print style and style presets feat: add sketch-notes style, palette system, and new presets ``` 每个风格变成 `presets/` 下的独立文件（最终 12 个），色板（palette）进一步从预设里抽出来放进 `palettes/`（目前 3 个）。加一种新预设只需要写一个文件，不会影响任何已有的组合。 这个拆法对应的就是第 6.2.3 节讲的“用维度组合替代穷举”——实际落地比表 6-2 更细：预设管整体调性（12 种）、色板管具体配色（3 套可替换）、元素库（canvas / typography / decorations / image-effects）提供通用构件。三层正交，改一处不动其他。 **拆出子技能：baoyu-image-cards** 技能规模到某个程度之后，单一职责的边界开始变模糊。小红书“单图”和“系列图文卡片”共享大部分底层逻辑，但交互和输出差别很大。 ``` feat(baoyu-image-cards): add image card series skill migrated from baoyu-xhs-images ``` 系列图文卡片独立成 `baoyu-image-cards`，原技能 `baoyu-xhs-images` 缩回单图本职。两个技能共享底层的元素库和预设（通过引用同一份 references）。这对应 6.3.2 节四阶段里讲的“阶段三：架构重构——过度膨胀的技能拆分为两个独立的技能”。 **剩下的小修小补** 其它十几次 commit 是日常优化：水印位置与透明度（`fix: remove opacity of watermark`）、中英混排时的空格（`fix CJK spacing`）、非交互模式（`--yes` 参数）、Windows PowerShell 兼容（`cross-platform PowerShell support`）、引用图链路提升视觉一致性（`add reference image chain for visual consistency`）、deprecated 路由优化等。每一次都是“使用中发现问题 → 一句话描述给智能体 → 智能体修复”。 ### F.6 最终结构 技能定型。主文件 641 行，另有 26 个引用文件，按职责分六档——总计 27 个文件、3349 行： ``` baoyu-xhs-images/ ├── SKILL.md # 641 行，主流程 + 参数 + 工作流约束 └── references/ ├── style-presets.md # 43 行，预设风格映射与覆盖示例 │ ├── config/ # 首次配置与用户偏好（3 个文件） │ ├── first-time-setup.md # 122 行，首次使用流程 + EXTEND.md 模板 │ ├── preferences-schema.md # 118 行，用户偏好 Schema │ └── watermark-guide.md # 62 行，水印位置、格式与提示词集成 │ ├── elements/ # 通用视觉构件（4 个文件） │ ├── canvas.md # 122 行，比例、安全区、网格、布局 │ ├── typography.md # 96 行，花字、标签、层级、字体风格 │ ├── decorations.md # 152 行，强调标记、背景、涂鸦、边框、贴纸 │ └── image-effects.md # 92 行，抠图、描边、滤镜、纹理、混合 │ ├── palettes/ # 独立色板（3 个文件） │ ├── macaron.md # 33 行，马卡龙 │ ├── neon.md # 32 行，霓虹 │ └── warm.md # 32 行，暖色 │ ├── presets/ # 视觉风格预设（12 个文件） │ ├── bold.md # 72 行，Bold 强对比 │ ├── chalkboard.md # 97 行，Chalkboard 黑板粉笔 │ ├── cute.md # 72 行，Cute 可爱 │ ├── fresh.md # 72 行，Fresh 清新 │ ├── minimal.md # 72 行，Minimal 极简 │ ├── notion.md # 73 行，Notion 笔记 │ ├── pop.md # 72 行，Pop 流行贴纸 │ ├── retro.md # 72 行，Retro 复古 │ ├── screen-print.md # 92 行，Screen-Print 丝网印刷 │ ├── sketch-notes.md # 100 行，Sketch Notes 手绘笔记 │ ├── study-notes.md # 115 行，Study Notes 学习笔记 │ └── warm.md # 72 行，Warm 温暖治愈 │ └── workflows/ # 生成流程（3 个文件） ├── analysis-framework.md # 198 行，小红书内容分析框架 ├── outline-template.md # 247 行，图文卡片大纲与分页结构 └── prompt-assembly.md # 378 行，图片生成提示词组装指南 ``` 六个子目录分别承担六类职责： * `config/` — 用户可定制的东西（扩展文件机制，见 6.2.3 节） * `elements/` — 通用的视觉构件 * `palettes/` — 独立色板，可与任何预设组合 * `presets/` — 12 种风格预设，一个文件一种 * `workflows/` — 生成流程的三个关键步骤 * `style-presets.md` — 位于顶层，维护预设之间的映射关系 SKILL.md 主文件只保留“智能体每次都要加载”的核心流程和关键约束，细节全部外挂到 `references/`。加一种新风格只需要在 `presets/` 下新建一个文件，不会影响其他预设。这就是“对扩展开放，对修改关闭”在技能上的落地。 ### F.7 几点经验 回头看这 20 多次 commit，最大的体会有四条。 1. **起步版本不用完美，够用就行。** 初版只有一种风格、没有 session 目录、没有首次配置、没有分析框架。但它能跑。后面所有的改进都是被真实使用触发的。 2. **每一条约束背后都是一次翻车。** 备份规则来自一次“重跑把旧图覆盖掉”的教训，CJK 空格处理来自中英混排排版错乱的提示词，notebook 风格的撤除来自连续几次效果都不如预期。坐在桌前想不出来这些。 3. **文件拆分是水到渠成的，不是提前规划的。** 我不是一开始就想好“要有 config/、elements/、palettes/、presets/、workflows/ 五个目录”。每一次拆分都发生在“主文件某段开始变化频繁且与主流程不相关”的时刻。硬要一开始就搞一个“完美”的目录结构，只会束手束脚。 4. **技能也会到需要拆分的那一天。** `baoyu-image-cards` 是从这个技能里独立出去的。当一个技能承担的场景多到“单一职责”开始变模糊时，拆分比塞更多东西进去更健康。 *** ## 附录 G 配套资源下载说明 ### 技能模板 本书中出现的所有技能模板，均可直接下载使用： | 技能 | 章节 | 说明 | | ---------- | ----- | ------------------------------------- | | 写作风格模板 | 第 4 章 | 四部分结构：角色、风格要点、禁止清单、参考资料 | | 会议纪要模板 | 第 4 章 | 模板驱动型，固定输出格式 | | 文章配图模板 | 第 4 章 | 五步流程：分析→选风格→写提示词→生成→插入 | | 会议分析模板 | 第 5 章 | 五维度分析：关键决定、待办、争议点、背景、过滤 | | 素材分析模板 | 第 5 章 | 四维框架：核心内容、背景语境、批判审视、素材价值 | | 大纲生成模板 | 第 5 章 | 生成 3-5 个差异化大纲方案 | | 数据分析 V1-V3 | 第 7 章 | 三个版本的完整技能文件，位于 `examples/chapter-07/` | **完整版技能**（作者实际使用的生产版本，见附录 D）： | 技能 | 附录编号 | 说明 | | ------- | ---- | ------------------------------- | | 素材分析完整版 | D.1 | 含内容类型识别、五维度分析、联网检索判断规则 | | 提纲生成完整版 | D.2 | 含选题判断、五种叙事结构、情绪曲线标注、故事驱动型要素 | | 访谈内容分析 | D.3 | 七维度分析框架：信息点、金句、叙事素材、对话动态等 | | 访谈实录写作 | D.4 | 串联 D.3 输出，加载 writing-style 基调约束 | **可选扩展技能**（第 5 章案例中提到，非必需）： | 技能 | 说明 | | -------- | ------------------- | | URL 处理技能 | 将网页链接转为 Markdown 文件 | | 翻译技能 | 自动翻译英文素材 | ### 测试数据 * 模拟会议转录稿（中文，约 2000 字） * 模拟投放数据表（CSV，35 行 10 列；主文件在 `chapters/chapter-07/`，V2 边界测试样例在 `examples/chapter-07/test-data/`） ### 下载方式 所有配套资源托管在 GitHub 仓库，扫描书中二维码或访问仓库链接下载。 *** ## 附录 H 技能文件结构速查表【未在正文引用】 一个技能就是一个文件夹。文件夹里只有一个文件是必须的：`SKILL.md`。其余都是可选的。 ### 标准目录结构 ``` my-skill-name/ ├── SKILL.md ← 必须。技能的核心说明书 ├── scripts/ ← 可选。可执行的脚本 │ ├── format.py │ └── validate.sh ├── references/ ← 可选。参考文档，按需加载 │ ├── style-guide.md │ └── examples/ │ └── sample-output.md └── assets/ ← 可选。二进制资源（字体、图标等） └── logo.png ``` ### 五条铁律 | 规则 | 正确 | 错误 | 后果 | | ---------------- | ----------------------------------- | ---------------------------------------------- | ---------- | | 文件名必须大写 | `SKILL.md` | `skill.md`、`Skill.md`、`SKILL.MD` | 智能体找不到技能 | | 文件夹名用 kebab-case | `my-cool-skill` | `My Cool Skill`、`my_cool_skill` | 上传失败 | | 不要放 README.md | 文件夹内只有 SKILL.md | 文件夹内同时有 README.md | 智能体可能读错文件 | | name 不能含保留词 | `data-analysis` | `claude-helper`、`anthropic-tool` | 上传被拒绝 | | 命名必须一致 | 文件夹名、name 字段、文中引用都叫 `writing-style` | 文件夹叫 `writing-style`，name 写 `my-writing-style` | 触发失败或引用找不到 | ### 不要放的文件 技能是写给智能体看的，不是写给人看的。以下文件不应出现在技能文件夹里： | 不要放的文件 | 原因 | | ------------------------------- | -------------------------------------- | | `README.md`、`CHANGELOG.md`、安装说明 | 智能体不需要人类文档，还可能和 SKILL.md 混淆 | | 智能体本来就会做的事的指令 | 如果不加指令智能体也能做对，那就是多余的，多余的指令反而会占用上下文窗口空间 | | 大段库代码 | 技能里的脚本应该是小而专的工具，大型代码库应该放在项目仓库里，技能只负责调用 | | 测试数据、日志文件 | 测试用的样本和日志不应打包进技能，保持文件夹干净 | 一句话：**只放智能体执行任务时真正需要读或用的文件。** 能少一个文件就少一个。 ### 各目录的用途 | 目录 | 放什么 | 何时加载 | 举例 | | ------------- | -------------- | -------------- | ------------------- | | `SKILL.md` | 核心指令和流程 | 智能体判断需要时（第二层） | 分析步骤、写作规则 | | `scripts/` | 确定性任务的代码 | 执行过程中调用 | 格式化脚本、数据校验 | | `references/` | 智能体需要“读懂”的参考文档 | 执行过程中按需读取（第三层） | HTML 模板、风格库、领域知识、示例 | | `assets/` | 不需要被“理解”的二进制资源 | 执行过程中按需使用 | 字体文件、图标、图片 | ### SKILL.md 建议长度 | 阶段 | 建议长度 | 说明 | | -- | --------- | ---------------------- | | 起步 | 20-50 行 | 能跑就行 | | 成长 | 50-200 行 | 核心流程和规则 | | 成熟 | 200-500 行 | 包含方法论和设计哲学 | | 上限 | 约 5,000 字 | 超过这个长度建议拆到 references/ | *** ## 附录 I YAML 前置信息完整字段说明【未在正文引用】 `SKILL.md` 文件的开头是一段 YAML 前置信息（frontmatter），用三条短横线 `---` 包裹。智能体启动时只读这部分，决定什么时候加载这个技能。 ### 最小格式 只需要两个字段就能跑： ```yaml --- name: my-skill-name description: 这个技能做什么。当用户说"xxx"时使用。 --- ``` ### 全部字段一览 ```yaml --- name: weekly-report description: > 生成格式统一的周报。当用户要求"写周报""工作总结"时使用。 输出固定三列表格：任务、进度、备注。 license: MIT compatibility: 需要 Python 3.8+，用于数据处理脚本 allowed-tools: "Bash(python:*) WebFetch" metadata: author: 你的名字 version: 1.2.0 category: productivity tags: [report, weekly, automation] --- ``` ### 各字段详解 **name**（必填） 技能的唯一标识。 | 规则 | 说明 | | ---- | ------------------------- | | 格式 | kebab-case（小写字母 + 连字符） | | 不能有 | 空格、大写字母、下划线 | | 不能包含 | “claude”或“anthropic”（保留词） | | 建议 | 和文件夹名保持一致 | ```yaml # ✅ 正确 name: data-analysis name: meeting-minutes name: article-illustrator # ❌ 错误 name: Data Analysis # 有空格和大写 name: data_analysis # 有下划线 name: claude-helper # 含保留词 ``` **description**（必填） 智能体判断“要不要用这个技能”的唯一依据。写好这个字段，比写好 SKILL.md 正文更重要。 | 规则 | 说明 | | ---- | ------------------- | | 长度 | 不超过 1024 个字符 | | 必须包含 | “做什么” + “什么时候用” | | 不能包含 | XML 尖括号 `< >`（安全限制） | | 建议 | 写上用户可能说的触发词 | 结构公式：**\[做什么] + \[什么时候用] + \[关键能力]** ```yaml # ✅ 好的 description description: > 分析会议录音转录稿，提取关键决定、待办事项和争议点。 当用户要求"分析会议内容""整理会议要点"时使用。 支持中英文转录稿。 # ❌ 差的 description description: 帮你处理会议相关的事情 # 问题：太模糊，不知道什么时候该触发 ``` 好坏对比案例： | 差的写法 | 问题 | 好的写法 | | -------------------- | ------- | ----------------------------------------------------- | | “处理数据” | 太宽泛 | “分析 Excel/CSV 数据，生成带图表的 HTML 报告。当用户上传数据文件并要求分析时使用。” | | “写作助手” | 不知道何时触发 | “按照用户的写作风格规范润色文章。当用户要求'润色''改稿''优化文章'时使用。” | | “万能工具” | 什么都不是 | “将文章内容自动拆分为小红书风格的系列信息图。当用户说'做小红书图片'时使用。” | | “Generate PPT files” | 没写触发条件 | “根据内容生成 PPT 演示文稿。当用户要求'做 PPT''做演示文稿'或上传大纲要求生成幻灯片时使用。” | **license**（可选） 开源许可证。分享技能时建议填写。 ```yaml license: MIT # 最宽松，随便用 license: Apache-2.0 # 宽松，需保留版权声明 ``` **compatibility**（可选） 环境要求说明，1-500 个字符。 ```yaml compatibility: 需要 Python 3.8+ 和 pandas 库 compatibility: 需要连接 Playwright MCP 服务 compatibility: 仅适用于 Claude Code 环境 ``` **allowed-tools**（可选） 限制技能可以使用的工具，增强安全性。 ```yaml # 只允许执行 Python 和读取网页 allowed-tools: "Bash(python:*) WebFetch" # 只允许读写文件，不允许联网 allowed-tools: "Bash(cat:*) Bash(ls:*)" ``` **metadata**（可选） 自定义字段，放什么都行。 ```yaml metadata: author: 张三 version: 2.1.0 mcp-server: feishu # 配合哪个 MCP 服务 category: productivity tags: [writing, automation] documentation: https://example.com/docs ``` ### 安全限制 | 限制 | 原因 | | ---------------------------- | -------------------------- | | 不能包含 XML 尖括号 `< >` | 前置信息会出现在系统提示中，尖括号可能被当作指令注入 | | name 不能含“claude”或“anthropic” | 保留词，防止冒充官方技能 | | 使用安全 YAML 解析 | 代码不会被执行 | *** ## 附录 J 推荐资源与社区【未在正文引用】 ### 官方资源 | 资源 | 地址 | 说明 | | ----------------- | ---------------------------- | ------------------------- | | agent skills 官方文档 | agentskills.io | 技能规范、最新动态 | | Claude 平台文档 | platform.claude.com | 技能 API、开发者指南 | | 官方技能仓库 | github.com/anthropics/skills | 官方维护的示例技能 | | 合作伙伴技能目录 | agentskills.io/partners | Asana、Figma、Canva 等合作伙伴技能 | ### 社区 | 社区 | 说明 | | ------------------------- | ---------------------- | | Claude Developers Discord | 官方开发者社区，有 Skills 专区 | | GitHub Discussions | 在官方仓库的 Discussions 区交流 | ### 工具 | 工具 | 地址 | 说明 | | --- | ---------------------- | --------------------------------------- | | Git | git-scm.com/book/zh/v2 | 官方文档中文版，零基础可从第 1-2 章入手，了解版本管理的基本概念和常用操作 | ### 学习路径建议 | 阶段 | 推荐做的事 | | --- | ----------------------------------------- | | 刚入门 | 下载官方示例技能（docx、pdf、pptx），跑通看效果 | | 开始写 | 从本书第 4 章的三个模板开始，改成自己的 | | 想进阶 | 读官方技能仓库的源码，看 SKILL.md 怎么写、references 怎么组织 | | 想分享 | 把技能放 GitHub，写清楚 README 和使用截图 | *** ## 附录 K 开发者参考：通过 API 使用技能【未在正文引用】 > 本附录面向有编程经验的开发者。如果你只在 Claude.ai 或 Claude Code 中使用技能，可以跳过。 ### 什么时候用 API | 场景 | 建议方式 | | ------- | ----------------------- | | 个人日常使用 | Claude.ai / Claude Code | | 手动测试和迭代 | Claude.ai / Claude Code | | 应用程序集成 | API | | 大规模生产部署 | API | | 自动化流水线 | API | ### 核心能力 * **`/v1/skills` 端点**：列出和管理技能 * **Messages API 的 `container.skills` 参数**：在对话请求中指定使用哪些技能 * **Claude Console**：通过控制台管理技能的版本 * **Agent SDK**：在自定义智能体中集成技能 ### 注意事项 * 通过 API 使用技能需要启用 Code Execution Tool（代码执行工具） * API 方式适合需要程序化控制的场景，比如批量处理、自动化流水线 * 详细的 API 文档和示例代码，请参考 platform.claude.com 的技能 API 章节 *** ## 附录 L 常见问题与故障排查【未在正文引用】 ### 技能相关 | 问题 | 原因 | 解决方法 | | --------------- | ----------------- | --------------------------- | | 技能不触发 | description 没写好 | 见附录 E“技能触发排查卡” | | 技能触发了但输出不对 | SKILL.md 正文指令不够清晰 | 加具体示例和检查清单 | | 装了多个技能互相打架 | description 过于相似 | 让每个技能的 description 更具体，减少重叠 | | SKILL.md 修改后没生效 | 终端工具需要重启 | 退出并重新启动智能体 | ### 脚本相关 | 问题 | 原因 | 解决方法 | | ----------- | -------- | ----------------------------- | | 脚本权限不足 | 缺少执行权限 | 运行 `chmod +x scripts/*.sh` | | Python 脚本报错 | 缺少依赖包 | 让智能体帮你安装：`pip install pandas` | | 脚本执行但结果不对 | 输入文件路径错误 | 检查 SKILL.md 中引用的文件路径是否正确 | ### 文件相关 | 问题 | 原因 | 解决方法 | | ------------------- | -------------- | --------------------- | | 输出文件覆盖了原文件 | 输出路径和输入路径相同 | 在技能中指定不同的输出目录 | | zip 上传后技能不出现 | SKILL.md 不在根目录 | 解压检查，确保 SKILL.md 在第一层 | | allowed-tools 配置不生效 | 语法写错 | 参考附录 I 的格式说明 | ### 平台相关 | 问题 | 原因 | 解决方法 | | ----------------- | -------- | -------------------------- | | 安装命令报错 | 命令可能已更新 | 查看在线更新页获取最新安装方式 | | 网页版不支持某些功能 | 平台差异 | 检查附录 B 的平台安装指南 | | 技能在 A 平台能用，B 平台不行 | 平台支持程度不同 | 查看 agentskills.io 获取最新兼容信息 | *** ## 附录 M PPT 大纲提示词模板【未在正文引用】 第 6 章介绍了“从提示词到技能”的方法。以下是一份 PPT 大纲生成提示词模板（已精简），可作为练手素材，尝试将其封装为技能。 ``` # 角色定义 你是一位世界级的演示文稿设计师和故事讲述者。你创作的幻灯片在视觉上令人震撼、 极其精美，并能有效地传达复杂的信息。你的特点是：既精通设计，又极具讲故事的天赋。 你制作的幻灯片能根据源素材和目标受众进行调整。凡事皆有故事，而你要找到最佳的 讲述方式。 # 设计定位 本幻灯片主要设计用于**阅读和分享**。其结构应当不言自明，即便没有演讲者也能轻松 理解。叙事逻辑和所有有用的数据都应包含在幻灯片的文本和视觉元素中。幻灯片应包含 足够的语境，以便任何视觉图像都能被独立理解。如果有助于叙事，你可以添加某些包含 更密集信息（从源素材中提取）的幻灯片。 # 任务 你现在正在为下述幻灯片演示编写一份**大纲**。我们将把这份大纲提供给一位专家级 设计师，由其制作最终的实际演示文稿。 幻灯片内容应使用中文。占位符应保留中文。 # 工作流程 **首先**，在编写幻灯片大纲之前，你必须根据内容主题和用户请求生成一个全局性的 **风格指令（STYLE INSTRUCTIONS）**块。这应该被包裹在代码块中。 风格指令示例： Design Aesthetic: 一种受建筑蓝图和高端技术期刊启发的干净、精致、极简主义的编辑 风格。整体感觉是精准、清晰和充满智慧的优雅。 Background Color: 一种微妙的、有纹理的灰白色，十六进制代码 #F8F7F5，让人联想到 高质量的绘图纸。 Primary Font: Neue Haas Grotesk Display Pro。用于所有幻灯片标题和主要标题。 应使用粗体渲染，以增强冲击力和清晰度。 Secondary Font: Tiempos Text。用于所有正文、副标题和注释。其高可读性和经典感 与干净的无衬线标题形成专业的对比。 Color Palette: Primary Text Color: 深板岩灰，#2F3542。 Primary Accent Color (用于高光、图表和关键元素): 充满活力的智能蓝，#007AFF。 Visual Elements: 一致使用精细、准确的线条、示意图和干净的矢量图形。视觉效果是 概念性和抽象的，旨在阐述想法而非描绘写实场景。布局空间感强且结构化，优先考虑 信息层级和可读性。不包含页码、页脚、Logo 或页眉。 # 画图提示词模板 使用以下结构为每张幻灯片生成画图提示词，根据具体的叙事动态调整美学、字体和颜色： 你是架构师（The Architect），一个旨在将指令可视化为高端蓝图风格数据展示的精密 AI。你的输出是精确、分析性且美学上精美的。 核心指令： 1. 分析用户提示词的结构、意图和关键要素。 2. 将指令转化为干净、结构化的视觉隐喻（蓝图、展示图、原理图）。 3. 使用特定的、克制的调色板和字体系列，以获得最大的清晰度和专业影响力。 4. 所有视觉输出必须严格保持 16:9 的长宽比。 5. 以三联画（triptych）或基于网格的布局呈现信息，保持文本和视觉的平衡。 风格指令： Design Aesthetic: [描述整体风格] Background Color: [描述及十六进制代码] Primary Font: [标题字体名称] Secondary Font: [正文字体名称] Color Palette: Primary Text Color: [十六进制代码] Primary Accent Color: [十六进制代码] Visual Elements: [描述线条、形状、图像风格等] 绘制内容： [具体幻灯片内容] # 自定义指令 对于本次特定的幻灯片演示，内容侧重于： {用户输入，描述想要创建的幻灯片，默认为：添加高层级大纲，或引导受众、风格和 重点} # 大纲编写规则 * 专注于演示文稿的大纲以及每张幻灯片应涵盖的内容。 * 每张幻灯片的描述必须全面且结构严谨。 * 第 1 页必须是封面页，最后一页必须是封底页。这两张幻灯片的视觉风格和布局应与 内部内容页截然不同（例如，使用"海报式"布局、醒目的排版或满版出血图像）。 * 对于每一张幻灯片，必须严格按照以下 4 个部分输出内容： // NARRATIVE GOAL (叙事目标) 解释这张幻灯片在整个故事弧光中的具体叙事目的 // KEY CONTENT (关键内容) 列出标题、副标题和正文/要点。每一个具体数据点都必须能追溯到源材料。 // VISUAL (视觉画面) 描述支持该观点所需的图像、图表、图形或抽象视觉元素。 // LAYOUT (布局结构) 描述构图、层级、空间安排或焦点。 * 保留源素材中的关键要素。每一个具体的数据点都必须能直接追溯到源素材。 * 所有细节都需要提及，因为设计师之后将无法访问源内容。 * 假设听众比你想象的更专业、更感兴趣、更聪明。 # 限制条件 * 生成的幻灯片切勿超过 20 页。 * 避免使用"标题：副标题"的格式作为标题。应通过叙事性的主题句将整个演示文稿 串联起来。 * 避免陈词滥调的"AI 废话"模式。切勿使用诸如"不仅仅是 X，而是 Y"之类的短语。 * 使用直接、自信、主动的语言。 * 切勿包含供作者插入姓名、日期等的占位符幻灯片。 * 切勿要求包含知名人物的逼真照片。 * 切勿以通用的"有任何问题吗？"或"谢谢"幻灯片结尾。封底应为经过设计的结束语、 有意义的引用或强有力的视觉总结。 ``` *** ## 注释 ### 前言 [^1]: LL.M. 为法学硕士的标准缩写，源自拉丁语 *Legum Magister*，对应英文 Master of Laws。其中 LL 代表“法律”的复数形式，M 代表“硕士”，故写作 LL.M.。 [^2]: 在本书中，你会看到“做技能”“创建技能”“封装技能”“开发技能”等多种说法。这并非术语不统一，而是为了在不同场景下更贴合实际的手感。“做成技能”是最口语化的表达，而更专业的说法是“封装成技能”。需要明确的是，**我们做成技能的是做事的步骤、流程和经验，而非事情本身**。为了表达简洁，后文经常会说成“某事、某任务做成技能”，大家心领神会即可。 [^3]: 在本书中，AI 智能体和智能体可互换使用。 [^4]: 开源地址：github.com/JimLiu/baoyu-skills。 [^5]: 术语详解请见附录 A。 ### 第 1 章 [^6]: 本书标注的阅读时长，按每分钟 300 字的阅读速度估算，尾数取整为 5 或 0。该数据仅为参考值，并非严格标准。—— 编者注 [^7]: 在本书中，我们将大语言模型（large language model，LLM）和多模态大模型（multimodal large language model，MLLM）简称为大模型。通常，大家会省略“大”字，直接说“模型”，因为什么样才算“大”会随时间变化。本书看具体语境使用“模型”与“大模型”。 [^8]: 模型 API 平台即提供模型 API 接口，供第三方工具调用的平台。本书提到的大部分模型 API 平台实际上是模型平台，提供的远不止 API 接口服务，还有其他各种服务。 [^9]: 这条路径需要用到电脑“终端”（输入命令的窗口），适合懂一点电脑操作、想深度折腾技能的程序员，零基础新手可跳过，先把扣子用熟再说。 [^10]: OpenClaw 作为一款开源工具，需在终端完成安装与配置操作，存在一定的门槛，更适合热衷动手探索的玩家群体。但值得注意的是，当前 OpenClaw 热度很高，深受各类用户喜爱，主流模型平台均支持其一键部署，因此普通用户也可以轻松上手体验（建议大家选自己喜欢的方式“云端一键部署”或“聊天工具接入”试试）。 [^11]: IM（Instant Messaging，即时通信）。为了简单和通俗起见，在大部分情况下，后文将 IM 渠道直接称为聊天工具。 [^12]: skill-creator 本质上就是一个创建技能的技能，它可以引导智能体创建适合智能体和符合技能规范的技能。扣子提供等价功能，在“技能”选项卡即可一键生成，无须手动安装 skill‑creator。 [^13]: 如果你对相关的操作不熟悉，可以前往图灵社区本书主页（ituring.cn/book/3616）下载随书附赠的操作截图参考。——编者注 ### 第 2 章 [^14]: 鉴于本书的主题是技能，我们将跟技能紧密相关的一切都纳入技能世界。技能世界其实就是智能体世界。 [^15]: 请注意，打比方是为了方便大家快速理解相关概念。打比方不能代替严格的学术定义或概念本身，无法做到与真实技术细节一一对应。我们只需抓住两者足够相似的特征，从而形象地理解抽象概念即可。 [^16]: 这里说 AI 聊天机器人，是为了区别 ChatGPT 诞生之前的普通聊天机器人。在通常情况下，大家会直接说聊天机器人，都可以理解。 [^17]: 这里可以简单理解：现在市面上的主流 AI 产品，基本都可以看作智能体；而在 2022 年刚出现时，那时候的 AI 只是单纯的聊天机器人。为什么可以这么划分，读完这一章你自然就清楚了。 [^18]: 在当前的 AI 行业里，关于智能体最权威、被引用最多的定义，来自于翁荔（Lilian Weng）：agent = LLM + memory + planning + tool use（智能体 = 大模型 + 记忆 + 规划 + 工具使用）。本书给出的公式与该权威定义在工程落地层面基本对应。 [^19]: 当前主流 AI 产品已普遍支持语音输入、文字输入等多种交互方式，直接通过对话形式向 AI 传递指令（提示词）已成为主流交互模式。为了便于表述，本书中不再严格区分打字输入与语音对话输入，统一以“说”指代向 AI 传递提示词的各类输入行为。 [^20]: 严格来说，代码世界里的大模型并没有真的长出“手脚”。当它需要联网搜索时，它其实只是发出了一条机器指令（技术上叫“函数调用”），真正动手干活的是智能体框架（agent harness）。为了简单和形象，我们在正文中把“大模型下指令”和“系统去执行”揉在了一起，统称为“厨师在动手”。 [^21]: 词元（token）是模型计算文本长度的单位。在中文环境中，1 个汉字大约消耗 0.5～2 个词元，具体取决于模型使用的分词器，本文中为了估算方便我们取 1.3 个词元。你不需要精确理解词元，把它当成台面上的格子数就行，其中每个格子能放几个字。 ### 第 3 章 [^22]: 大模型的核心优势是“自然语言理解与生成”，是基于海量数据的模式识别与推理，所以擅长分析意图、组织结构、创意发散。它的短板是“精准执行固定规则”：数学计算、格式转换、固定文本替换需要 100% 无误差的规则落地，而大模型偶尔会出现“幻觉”或微小偏差。 [^23]: 技能里的脚本，就是把“执行规则”类操作写成的固定代码片段——像给智能体定死的“全自动操作手册”，只要触发就 100% 按规矩执行，比如数据清洗、格式校验这类要求零误差的活儿，比靠提示词约束模型更精准、更稳定。 ### 第 4 章 [^24]: 技能文本可能含代码与配置，为保持技术规范及便于复制，对于技能文本及相关的提示词中的引号，本书统一使用直引号。——编者注 [^25]: 由于模型输出具有随机性，结果通常不会完全一致，只要输出的结构、关键信息和核心逻辑稳定即可。 [^26]: 假设历史对话没有超出模型上下文窗口的最大词元数限制。 ### 第 6 章 [^27]: 参见 Anthropic 的 Claude Code 团队工程师 Thariq（@trq212）的文章“Lessons from Building Claude Code: How We Use Skills”。 [^28]: 参见 baoyu-skills 项目中名为 baoyu-cover-image 的技能，地址：。本章提到的小红书信息图技能（baoyu-xhs-images）也在其中。 [^29]: baoyu-skills 项目地址：，本章提到的小红书信息图技能（baoyu-xhs-images）和封面图生成技能（baoyu-cover-image）均在其中。 [^30]: MVP（minimum viable product，最小可行产品），产品设计与软件开发中的概念。MVP 的思想是：做产品的时候，只做核心功能，够用就上线，先跑通，后续再慢慢迭代。 [^31]: Anthropic 的技能评测文档：，OpenAI 的技能评测博客：。 ### 第 7 章 [^32]: 实际上，进行思考的是大模型（智能体的“大脑”，读过第 2 章的话，你会秒懂）。为了方便起见，本章只在必要的场景加以区分。