## skill 到底是什么 传统的AI的知识锁在模型的参数里，想让模型学习新技能？ | 参数 | 传统方式 | skill | | -------- | ----------------------------------------- | ----------------------------------- | | 处理过程 | 收集数据 → 处理数据 → 参数训练 → 部署 | 编辑SKILL.md 文件 → 下次执行时触发 | | 成本 | ¥10000 - ¥1000000+ | ¥0 | | 周期 | 数周 - 数月 | 即时 | Skill就像是给base model 外挂一个可热插拔的LoRA适配器，但完全不需要训练。编辑Markdown文件，模型的行为就改变了。  技能是一个目录，其中包含一个SKILL.md 文件，该文件包含组织有序的文件夹，其中包含指令、脚本和资源，这些指令、脚本和资源为 Agent 提供额外的功能。 ### Tool vs Skill 的一个关键区分 | 概念 | 本质 | 作用 | 例子 | | ----- | ------------------------ | -------- | -------------------------------------- | | Tool | 模型能**做**什么 | 执行动作 | bash、read_file、write_file、WebSearch | | Skill | 模型知道**怎么做** | 指导决策 | PDF处理、MCP构建、前端设计、代码审查 | > 工具是能力的边界：没有bash工具，模型无法执行命令 > 技能是知识的注入：没有前端设计Skill，模型写出的UI前篇一律 [scode type="lblue"]通用Agent + 优秀的Skill = 特定领域的专家 Agent[/scode] > Skill价值：同一个模型，加载不同的Skill，就变成不同的专家 [scode type="lblue"]Agent能力上限 = 模型能力 + Skill 质量[/scode] 模型能力是基座，Skill质量决定这个基座能发挥到什么程度。一个优秀的Skill，能让通用Agent在特定领域的变现超过没有Skill加持的更强大模型。 ## 判断标准 ### Token效率🫏：段落是否值得它的开销 [collapse status="false" title="Anthropic 官方 skill-creator 规范"] > **Concise is Key.** > The context window is a public good. Skills share the context window with everything else Claude needs: system prompt, conversation history, other Skills' metadata, and the actual user request. > > (Context window 是公共资源。一个 Skill 占用的 token，会挤压其他内容的空间——系统提示、对话历史、其他 Skill 的元数据、用户的实际请求。) > **Default assumption: Claude is already very smart.** > Only add context Claude doesn't already have. Challenge each piece of information: "Does Claude really need this explanation?" and "Does this paragraph justify its token cost?" > > (当你写一段"什么是 PDF"的解释时，你在浪费这个公共资源。Claude 已经知道什么是 PDF。这 100 个 token 本可以用来存放更有价值的信息。) [/collapse] **通过三个问题，判断每段话的价值** 1. 模型真的不知道这个吗？ 2. 删掉它会影响任务完成吗？ 3. 这100个 token 能换来什么价值？ [scode type="lblue"]好 Skill = 专家独有的知识 - 模型已知[/scode] 这个公式是判断Skill价值的根本标准，可以将 Skill 理解为 `专家大脑的压缩文件`：把一个设计师 10 年的审美积累缩成 43 行，把一个文档专家的操作经验压缩成 200 行决策树。`压缩的必须是模型没有的东西，否则就是垃圾压缩` ### ❤️心智模型 vs ⚙️机械步骤：传递的是什么 [collapse status="false" title="Anthropic 官方 Skill 示例，特别是 frontend-design、canvas-design"] ``` Before coding, understand the context and commit to a BOLD aesthetic direction: - **Purpose**: What problem does this interface solve? Who uses it? - **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic... - **Differentiation**: What makes this UNFORGETTABLE? NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto), cliched color schemes (purple gradients on white backgrounds)... ``` 官方最精简的 Skill——frontend-design，只有 43 行。它没有教 Claude 如何写 CSS。它没有解释什么是 flexbox。它没有列出 Step 1、Step 2、Step 3。 它激活的是 `设计师的思维方式`：在动手写代码之前，先想清楚几个关键问题---这是专家和新手的本质区别。 [/collapse] 专家和新手的差异不在于 `会不会操作`，而在于 `如何思考问题`。资深的设计师和初学者都会写CSS，但是设计师在写第一行代码之前，脑子里已经有了清晰的审美方案、用户场景、差异化定位。 [scode type="lblue"]好的 Skill 传递的是思维方式，而不是机械的操作步骤。[/scode] | 维度 | 平庸 Skill | 优秀 Skill | | ---- | ---------------------- | -------------------------- | | 内容 | Step 1、Step 2、Step 3 | 思考框架、决策原则 | | 假设 | Agent 不会做 | Agent 会做，但不知道怎么想 | | 效果 | Agent 照本宣科 | Agent 像专家一样思考 | ### 🧾反模式清单：明确什么不能做 [collapse status="false" title="官方 Skill 都包含明确的"NEVER"清单"] frontend-design： ``` NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns... ``` canvas-design： ``` NEVER lose sight of the idea that this should be art, not something that's cartoony or amateur. ``` [/collapse] 专家知识的一般是 `知道什么能做`，另一半是 `知道什么绝对不能做` [scode type="lblue"]明确的 `NENVER`清单，告诉 Agent 什么是 `垃圾做法`[/scode] ### Description 出发机制：何时被激活 [collapse status="false" title="Anthropic 官方 skill-creator 规范"] ``` This is the primary triggering mechanism for your skill, and helps Claude understand when to use the skill. Include both what the Skill does and specific triggers/contexts for when to use it. Include all "when to use" information here - Not in the body. The body is only loaded after triggering. ``` [/collapse] Skill 分三层加载： ``` Layer 1: Metadata（始终在内存中） 只有 name + description ~100 tokens / skill Layer 2: SKILL.md Body（触发后才加载） 详细指南、代码示例、决策树 < 5000 tokens Layer 3: Resources（按需加载） scripts/, references/, assets/ 无限制 ``` 关键点：`description 是唯一始终可见的部分`，Agent 根据 description 决定是否激活这个 Skill。如果 description 太模糊，Skill 将无法正确的被触发。 **好的 description：** ``` description: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. When Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks" ``` [scode type="lblue"] 1. 描述功能（what it does） 2. 列出出发场景 （when to use） 3. 包含关键词（.docx files, tracked changes）[/scode] ### 自由度校验：与任务错弱度匹配 官方 skill-creator 规范: ``` Match the level of specificity to the task's fragility and variability: High freedom (text-based instructions): Use when multiple approaches are valid, decisions depend on context. Medium freedom (pseudocode or scripts with parameters): Use when a preferred pattern exists, some variation is acceptable. Low freedom (specific scripts, few parameters): Use when operations are fragile and error-prone, consistency is critical. ``` [scode type="lblue"]不同类型的任务需要不同程度的约束[/scode] | 任务类型 | 自由度 | 原因 | 示例 Skill | | ------------ | ------ | -------------------------- | --------------- | | 创意设计 | 高 | 多种方法有效，差异化是价值 | frontend-design | | 代码审查 | 中 | 有原则但需要判断 | 代码审查 Skill | | 文件格式操作 | 低 | 操作脆弱，一致性关键 | docx、xlsx | **如何判断**： 问自己：这个任务容错率高还是低？如果 Agent 做错一步，后果是什么？ 容错率高 ：给原则，不给步骤 容错率低 ：给脚本，少参数 ### 加载出发设计：Reference 能否被正确使用 很多 Skill 有详细的 reference 文档，但 Agent 不读或读太多。假设 Agent 会“聪明的”按需加载是一个错误的认知，必须显示设计加载触发机制。 ``` 加载率太低 ◄─────────────────────────────────────────────► 过度加载 问题： 问题： - Reference 形同虚设 - 浪费上下文空间 - 知识放了跟没放一样 - 无关信息稀释关键内容 - Agent 不知道何时该加载 - Token 开销不必要增加 ``` > 不同的 Agent 对 Skill 机制的训练程度不同 > > * Claude 对Skill 机制有专门的训练，会适时主动加载 > * 大多数 Agent 没有专门训练，不会主动加载 > * 有些 Agent 过于积极，一次性加载太多 在工作流的关键节点嵌入强制加载指令。官方 docx Skill 的做法： ``` ### Creating New Document **MANDATORY - READ ENTIRE FILE**: Before proceeding, you MUST read [`docx-js.md`](docx-js.md) (~500 lines) completely from start to finish. **NEVER set any range limits when reading this file.** ``` "MANDATORY"、"MUST"、"NEVER" 不是装饰词，是确保 Agent 执行的关键信号。 **注意**：这条标准只对有 reference 目录的中等/复杂 Skill 重要。简单型 Skill（如 frontend-design，43 行，无 reference）不需要考虑这个问题。 ## Skill的好坏 ### skill 返例 ``` # PDF 处理技能 ## 什么是 PDF PDF（Portable Document Format，便携式文档格式）是由 Adobe 公司在 1993 年开发的一种文件格式。它可以在不同的操作系统和设备上保持文档的格式不变，包括字体、图像、排版等元素。PDF 文件可以包含文本、图像、超链接、表单字段、视频等多种元素。 ## PDF 的特点 1. 跨平台兼容性 2. 格式保持一致 3. 支持加密和权限控制 4. 文件大小相对较小 ## 如何读取 PDF 要读取 PDF 文件，你可以使用多种方法： ### 方法一：使用 PyPDF2 Step 1: 首先安装 PyPDF2 库 pip install PyPDF2 Step 2: 导入库 from PyPDF2 import PdfReader Step 3: 打开 PDF 文件 reader = PdfReader("document.pdf") Step 4: 读取页面内容 page = reader.pages[0] text = page.extract_text() ### 方法二：使用 pdfplumber ... ``` | 问题 | 具体表现 | 后果 | | ------------ | -------------------------------- | ----------------------------------- | | 解释基础概念 | "什么是 PDF"、"PDF 的特点" | 浪费 200+ token，Claude 已经知道 | | 机械步骤 | Step 1, 2, 3, 4 | Claude 已经会写代码，不需要手把手教 | | 没有决策指导 | 列了两种方法但没说什么时候用哪种 | Agent 不知道如何选择 | | 没有反模式 | 没有说什么情况会出错 | Agent 会踩坑 | | 没有边缘情况 | 没有提到扫描件、加密 PDF 等 | 遇到特殊情况会失败 | ### Skill正例 ``` --- name: pdf-processing description: 处理 PDF 文件。当用户需要读取 PDF 文本、提取表格数据、 填写 PDF 表单、合并或拆分 PDF、将 PDF 转换为图片时使用。 --- **# PDF 处理决策树** 根据任务类型选择工具： | 任务 | 首选工具 | 备选 | 何时用备选 | | ------------ | ------------ | ----------- | -------------------------- | | 读取纯文本 | pdftotext | PyMuPDF | 需要保留布局信息 | | 提取表格 | camelot-py | tabula-py | camelot 失败时 | | 填写表单 | PyMuPDF | pdftk | PyMuPDF 不支持的表单类型 | | 合并/拆分 | PyMuPDF | pdftk | 批量处理大量文件 | | 转换为图片 | pdf2image | PyMuPDF | 需要更高分辨率控制 | **## 常见陷阱** 以下情况需要特殊处理： **扫描件 PDF** • 症状：pdftotext 返回空白或乱码 • 原因：PDF 内容是图片，不是文本 • 解决：先用 OCR（tesseract）处理，再提取文本 **加密 PDF** • 症状：读取时报权限错误 • 解决：PyMuPDF 的 `<span leaf="">open(path, password=xxx)</span>` 或先用 qpdf 解密 **复杂嵌套表格** • 症状：camelot 提取结果混乱 • 解决：考虑 LLM 辅助解析，或转成图片后用视觉模型 **大文件性能** • 超过 100 页的 PDF，避免一次性加载全部页面 • 使用分页处理：`<span leaf="">for page in reader.pages[start:end]</span>` **## 快速参考** # 命令行快速提取文本 pdftotext input.pdf - # 输出到 stdout # 转换为图片（每页一张） pdftoppm -jpeg -r 150 input.pdf output\_prefix ``` | 维度 | 表现 | 价值 | | ---------- | -------------------------- | ------------------ | | 不解释基础 | 没有"什么是 PDF" | 节省 token | | 决策导向 | 决策树告诉你什么情况用什么 | Agent 能做正确选择 | | 常见陷阱 | 扫描件、加密、复杂表格 | 避免踩坑 | | 边缘情况 | 大文件性能问题 | 处理特殊场景 | | 可操作 | 直接给命令，不给教程 | 立即可用 | ### 另一个对比：创意型 Skill **坏的创意型 Skill**： ``` # 前端设计技能 ## 设计原则 1. 保持一致性 2. 注重用户体验 3. 使用合适的颜色 4. 选择易读的字体 5. 做好响应式设计 ## 设计流程 Step 1: 理解需求 Step 2: 制作线框图 Step 3: 选择配色方案 Step 4: 编写 HTML 结构 Step 5: 添加 CSS 样式 Step 6: 实现响应式 Step 7: 测试和优化 ## 常用工具 - Figma - Sketch - Adobe XD ``` 问题：全是废话。"保持一致性"、"注重用户体验"——这些 Claude 早就知道。这个 Skill 没有传递任何 Claude 没有的知识。 **好的创意型 Skill**（官方 frontend-design 风格）： ``` --- name: frontend-design description: 创建独特的、生产级的前端界面。当用户要求构建网页组件、页面、 应用程序、海报、仪表板时使用。生成有创意、有品味的代码和 UI 设计。 --- # 设计思维 在写任何代码之前，先回答这些问题： **Purpose**：这个界面解决什么问题？谁在用它？ **Tone**：选择一个极端方向——极简主义、最大化混乱、复古未来、有机自然、奢华精致、玩具感、杂志感、粗野主义、装饰艺术... **Differentiation**：什么让这个设计令人难忘？用户会记住什么？ **关键**：选择一个清晰的概念方向，然后精确执行。大胆的最大化和精致的极简都可以——关键是意图明确，而不是强度。 ## 绝对不要做的事 以下是典型的"AI 生成感"设计，必须避免： - 滥用 Inter、Roboto、Arial 字体 - 紫色渐变配白色背景 - 所有圆角都是 8px - 千篇一律的卡片布局 - 没有个性的 cookie-cutter 风格 ## 应该追求的 - **字体**：选择有个性的字体。把一个独特的展示字体和精致的正文字体搭配。 - **颜色**：承诺一个连贯的审美。主色调配锐利的强调色，胜过胆怯的平均分配。 - **动效**：聚焦高影响力时刻——一个精心编排的页面加载动画，胜过散落的微交互。 - **空间**：意外的布局。不对称。重叠。对角线流动。打破网格的元素。 - **背景**：创造氛围和深度，而不是默认纯色。渐变网格、噪点纹理、几何图案。 ## 执行原则 **匹配复杂度和愿景**： - 最大化设计 → 需要复杂代码、大量动画和效果 - 极简设计 → 需要克制、精确、细致的间距和字体处理 优雅来自于对愿景的良好执行，而不是堆砌效果。 ``` **为什么好**： | 维度 | 表现 | | ---------- | ------------------------------------- | | 思维框架 | Purpose/Tone/Differentiation 三个问题 | | 明确反模式 | "绝对不要做的事"清单 | | 具体方向 | 字体、颜色、动效、空间、背景各有指导 | | 执行原则 | 复杂度匹配愿景 | | 不教技术 | 没有解释 CSS，Claude 已经会 | --- ### 3.4 第三个对比：代码审查 Skill 这个例子展示如何把一个日常任务变成高质量 Skill。 **坏的代码审查 Skill**： ``` # 代码审查技能 ## 什么是代码审查 代码审查是软件开发过程中，由团队成员对代码变更进行检查和评估的活动。 它可以帮助发现 bug、提高代码质量、分享知识... ## 为什么要做代码审查 1. 发现潜在的 bug 2. 提高代码可读性 3. 促进团队知识共享 4. 确保代码符合规范 ## 如何进行代码审查 Step 1: 阅读代码变更 Step 2: 理解代码的目的 Step 3: 检查是否有 bug Step 4: 检查代码风格 Step 5: 写评论反馈 Step 6: 讨论和修改 ``` 问题：全是废话。Claude 知道什么是代码审查，知道为什么要做。Step 1-6 也是显而易见的流程。这个 Skill 没有传递任何专家独有的知识。 **好的代码审查 Skill**： ``` --- name: code-review description: 审查代码质量和正确性。当用户要求 review PR、检查代码、 找 bug、评估代码质量时使用。 --- # 审查优先级 不是所有问题都同等重要。按以下顺序审查： 1. **安全漏洞**（必须修复） - 注入攻击、权限泄露、敏感数据暴露 2. **逻辑错误**（必须修复） - 边界条件、空值处理、并发问题 3. **性能问题**（建议修复） - N+1 查询、内存泄漏、不必要的重复计算 4. **可维护性**（可选） - 代码风格、命名、注释 # 思维模式 审查每段代码时，问自己： - **理解**：6 个月后的新人能看懂这段代码吗？ - **定位**：如果这里出 bug，能快速定位问题吗？ - **简化**：有没有更简单的写法实现同样功能？ # 绝对不要做 - 一次提 20 个问题（挑最重要的 3-5 个，其他放在"nit"里） - 只说"这里有问题"不说怎么改（要给具体建议或代码示例） - 吹毛求疵（专注真正影响的问题，不要纠结空格和换行） - 用"我觉得"开头（用"建议"或直接说原因） # 评论模板 **必须修复**： > [MUST] 这里存在 SQL 注入风险。用户输入未经转义直接拼接到查询中。 > 建议使用参数化查询：`db.query("SELECT * FROM users WHERE id = ?", [userId])` **建议修复**： > [SUGGEST] 这个循环内有 N+1 查询问题，在数据量大时会很慢。 > 建议改用批量查询：`User.find({ id: { $in: userIds } })` **小问题**： > [NIT] 变量名 `d` 不够清晰，建议改为 `dateCreated`。 ``` **区别总结**： | 维度 | 坏 Skill | 好 Skill | | -------- | ------------------ | ----------------- | | 概念解释 | 解释什么是代码审查 | 直接跳过 | | 流程 | Step 1-6 | 无（Claude 已知） | | 优先级 | 无 | 明确的 4 级优先级 | | 思维方式 | 无 | 3 个核心问题 | | 反模式 | 无 | 4 条"绝对不要" | | 可操作性 | 空泛建议 | 具体评论模板 | 这就是核心公式的体现：`<span leaf="">好 Skill = 专家独有的知识 - Claude 已有的知识</span>`。好的代码审查 Skill 传递的是资深工程师的审查直觉和经验，不是代码审查的定义和流程。 ## 设计检查清单 ``` 基础规范 [ ] 有 YAML frontmatter，包含 name 和 description [ ] description 包含"做什么"和"什么时候用" [ ] SKILL.md < 500 行 内容质量 [ ] 没有解释 Claude 已知的基础概念 [ ] 没有机械的 Step 1, 2, 3 [ ] 有明确的反模式清单（NEVER list） [ ] 有决策树或选择指导（如果有多种路径） [ ] 有常见陷阱和边缘情况 加载机制（仅有 reference 的 Skill） [ ] 每个 reference 有明确的加载触发条件 [ ] 触发条件嵌入在工作流步骤中 [ ] 有防止过度加载的机制 自由度 [ ] 创意任务 → 高自由度（原则而非步骤） [ ] 脆弱操作 → 低自由度（精确脚本） ``` ## 总结 好的 Agent Skill 不是教程，而是 `专家知识的外化形式`。把一个领域专家的思维方式、决策原则、反模式直觉、边缘情况经验，压缩成一个可加载的 Markdown 文件。当 Agent 加载这个文件时，它不是在"学习操作步骤"，它是在**继承一种专家思维**。 写 Skill 之前，问自己： * 这个领域的顶级专家是如何思考的？ * 他们做决策的核心原则是什么？ * 他们踩过什么坑？ * 他们绝对不会做什么？ * 什么知识是模型不知道但必须知道的？ > 好 Skill = 专家独有的知识 - Claude 已有的知识 > 好 Skill = 高压缩比 + 高信息密度 > 垃圾 Skill = 压缩了 Claude 已经知道的东西 > 工具让模型能做事，技能让模型知道怎么做 **相关链接**： shareAI-skills 仓库：https://github.com/shareAI-lab/shareAI-skills skill-judge 评估工具：https://github.com/shareAI-lab/shareAI-skills/tree/main/skills/skill-judge Kode（开源版 Claude Code）：https://github.com/shareAI-lab/Kode Loading... ## skill 到底是什么 传统的AI的知识锁在模型的参数里，想让模型学习新技能？ | 参数 | 传统方式 | skill | | -------- | ----------------------------------------- | ----------------------------------- | | 处理过程 | 收集数据 → 处理数据 → 参数训练 → 部署 | 编辑SKILL.md 文件 → 下次执行时触发 | | 成本 | ¥10000 - ¥1000000+ | ¥0 | | 周期 | 数周 - 数月 | 即时 | Skill就像是给base model 外挂一个可热插拔的LoRA适配器，但完全不需要训练。编辑Markdown文件，模型的行为就改变了。  技能是一个目录，其中包含一个SKILL.md 文件，该文件包含组织有序的文件夹，其中包含指令、脚本和资源，这些指令、脚本和资源为 Agent 提供额外的功能。 ### Tool vs Skill 的一个关键区分 | 概念 | 本质 | 作用 | 例子 | | ----- | ------------------------ | -------- | -------------------------------------- | | Tool | 模型能**做**什么 | 执行动作 | bash、read_file、write_file、WebSearch | | Skill | 模型知道**怎么做** | 指导决策 | PDF处理、MCP构建、前端设计、代码审查 | > 工具是能力的边界：没有bash工具，模型无法执行命令 > 技能是知识的注入：没有前端设计Skill，模型写出的UI前篇一律 <div class="tip inlineBlock info"> 通用Agent + 优秀的Skill = 特定领域的专家 Agent </div> > Skill价值：同一个模型，加载不同的Skill，就变成不同的专家 <div class="tip inlineBlock info"> Agent能力上限 = 模型能力 + Skill 质量 </div> 模型能力是基座，Skill质量决定这个基座能发挥到什么程度。一个优秀的Skill，能让通用Agent在特定领域的变现超过没有Skill加持的更强大模型。 ## 判断标准 ### Token效率🫏：段落是否值得它的开销 <div class="panel panel-default collapse-panel box-shadow-wrap-lg"><div class="panel-heading panel-collapse" data-toggle="collapse" data-target="#collapse-988180bac7e186749958438cc2cda99283" aria-expanded="true"><div class="accordion-toggle"><span style="">Anthropic 官方 skill-creator 规范</span> <i class="pull-right fontello icon-fw fontello-angle-right"></i> </div> </div> <div class="panel-body collapse-panel-body"> <div id="collapse-988180bac7e186749958438cc2cda99283" class="collapse collapse-content"><p></p> > **Concise is Key.** > The context window is a public good. Skills share the context window with everything else Claude needs: system prompt, conversation history, other Skills' metadata, and the actual user request. > > (Context window 是公共资源。一个 Skill 占用的 token，会挤压其他内容的空间——系统提示、对话历史、其他 Skill 的元数据、用户的实际请求。) > **Default assumption: Claude is already very smart.** > Only add context Claude doesn't already have. Challenge each piece of information: "Does Claude really need this explanation?" and "Does this paragraph justify its token cost?" > > (当你写一段"什么是 PDF"的解释时，你在浪费这个公共资源。Claude 已经知道什么是 PDF。这 100 个 token 本可以用来存放更有价值的信息。) <p></p></div></div></div> **通过三个问题，判断每段话的价值** 1. 模型真的不知道这个吗？ 2. 删掉它会影响任务完成吗？ 3. 这100个 token 能换来什么价值？ <div class="tip inlineBlock info"> 好 Skill = 专家独有的知识 - 模型已知 </div> 这个公式是判断Skill价值的根本标准，可以将 Skill 理解为 `专家大脑的压缩文件`：把一个设计师 10 年的审美积累缩成 43 行，把一个文档专家的操作经验压缩成 200 行决策树。`压缩的必须是模型没有的东西，否则就是垃圾压缩` ### ❤️心智模型 vs ⚙️机械步骤：传递的是什么 <div class="panel panel-default collapse-panel box-shadow-wrap-lg"><div class="panel-heading panel-collapse" data-toggle="collapse" data-target="#collapse-100965cd89f69d0655d0505ba93ad0334" aria-expanded="true"><div class="accordion-toggle"><span style="">Anthropic 官方 Skill 示例，特别是 frontend-design、canvas-design</span> <i class="pull-right fontello icon-fw fontello-angle-right"></i> </div> </div> <div class="panel-body collapse-panel-body"> <div id="collapse-100965cd89f69d0655d0505ba93ad0334" class="collapse collapse-content"><p></p> ``` Before coding, understand the context and commit to a BOLD aesthetic direction: - **Purpose**: What problem does this interface solve? Who uses it? - **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic... - **Differentiation**: What makes this UNFORGETTABLE? NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto), cliched color schemes (purple gradients on white backgrounds)... ``` 官方最精简的 Skill——frontend-design，只有 43 行。它没有教 Claude 如何写 CSS。它没有解释什么是 flexbox。它没有列出 Step 1、Step 2、Step 3。 它激活的是 `设计师的思维方式`：在动手写代码之前，先想清楚几个关键问题---这是专家和新手的本质区别。 <p></p></div></div></div> 专家和新手的差异不在于 `会不会操作`，而在于 `如何思考问题`。资深的设计师和初学者都会写CSS，但是设计师在写第一行代码之前，脑子里已经有了清晰的审美方案、用户场景、差异化定位。 <div class="tip inlineBlock info"> 好的 Skill 传递的是思维方式，而不是机械的操作步骤。 </div> | 维度 | 平庸 Skill | 优秀 Skill | | ---- | ---------------------- | -------------------------- | | 内容 | Step 1、Step 2、Step 3 | 思考框架、决策原则 | | 假设 | Agent 不会做 | Agent 会做，但不知道怎么想 | | 效果 | Agent 照本宣科 | Agent 像专家一样思考 | ### 🧾反模式清单：明确什么不能做 <div class="panel panel-default collapse-panel box-shadow-wrap-lg"><div class="panel-heading panel-collapse" data-toggle="collapse" data-target="#collapse-0f67ceca946e2effe430e499079c59f792" aria-expanded="true"><div class="accordion-toggle"><span style="0:title="官方;1:Skill;2:都包含明确的"NEVER"清单";"></span> <i class="pull-right fontello icon-fw fontello-angle-right"></i> </div> </div> <div class="panel-body collapse-panel-body"> <div id="collapse-0f67ceca946e2effe430e499079c59f792" class="collapse collapse-content"><p></p> frontend-design： ``` NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns... ``` canvas-design： ``` NEVER lose sight of the idea that this should be art, not something that's cartoony or amateur. ``` <p></p></div></div></div> 专家知识的一般是 `知道什么能做`，另一半是 `知道什么绝对不能做` <div class="tip inlineBlock info"> 明确的 `NENVER`清单，告诉 Agent 什么是 `垃圾做法` </div> ### Description 出发机制：何时被激活 <div class="panel panel-default collapse-panel box-shadow-wrap-lg"><div class="panel-heading panel-collapse" data-toggle="collapse" data-target="#collapse-3b2c200ff88ae18af3bcf9d6c25d783067" aria-expanded="true"><div class="accordion-toggle"><span style="">Anthropic 官方 skill-creator 规范</span> <i class="pull-right fontello icon-fw fontello-angle-right"></i> </div> </div> <div class="panel-body collapse-panel-body"> <div id="collapse-3b2c200ff88ae18af3bcf9d6c25d783067" class="collapse collapse-content"><p></p> ``` This is the primary triggering mechanism for your skill, and helps Claude understand when to use the skill. Include both what the Skill does and specific triggers/contexts for when to use it. Include all "when to use" information here - Not in the body. The body is only loaded after triggering. ``` <p></p></div></div></div> Skill 分三层加载： ``` Layer 1: Metadata（始终在内存中） 只有 name + description ~100 tokens / skill Layer 2: SKILL.md Body（触发后才加载） 详细指南、代码示例、决策树 < 5000 tokens Layer 3: Resources（按需加载） scripts/, references/, assets/ 无限制 ``` 关键点：`description 是唯一始终可见的部分`，Agent 根据 description 决定是否激活这个 Skill。如果 description 太模糊，Skill 将无法正确的被触发。 **好的 description：** ``` description: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. When Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks" ``` <div class="tip inlineBlock info"> 1. 描述功能（what it does） 2. 列出出发场景 （when to use） 3. 包含关键词（.docx files, tracked changes） </div> ### 自由度校验：与任务错弱度匹配 官方 skill-creator 规范: ``` Match the level of specificity to the task's fragility and variability: High freedom (text-based instructions): Use when multiple approaches are valid, decisions depend on context. Medium freedom (pseudocode or scripts with parameters): Use when a preferred pattern exists, some variation is acceptable. Low freedom (specific scripts, few parameters): Use when operations are fragile and error-prone, consistency is critical. ``` <div class="tip inlineBlock info"> 不同类型的任务需要不同程度的约束 </div> | 任务类型 | 自由度 | 原因 | 示例 Skill | | ------------ | ------ | -------------------------- | --------------- | | 创意设计 | 高 | 多种方法有效，差异化是价值 | frontend-design | | 代码审查 | 中 | 有原则但需要判断 | 代码审查 Skill | | 文件格式操作 | 低 | 操作脆弱，一致性关键 | docx、xlsx | **如何判断**： 问自己：这个任务容错率高还是低？如果 Agent 做错一步，后果是什么？ 容错率高 ：给原则，不给步骤 容错率低 ：给脚本，少参数 ### 加载出发设计：Reference 能否被正确使用 很多 Skill 有详细的 reference 文档，但 Agent 不读或读太多。假设 Agent 会“聪明的”按需加载是一个错误的认知，必须显示设计加载触发机制。 ``` 加载率太低 ◄─────────────────────────────────────────────► 过度加载 问题： 问题： - Reference 形同虚设 - 浪费上下文空间 - 知识放了跟没放一样 - 无关信息稀释关键内容 - Agent 不知道何时该加载 - Token 开销不必要增加 ``` > 不同的 Agent 对 Skill 机制的训练程度不同 > > * Claude 对Skill 机制有专门的训练，会适时主动加载 > * 大多数 Agent 没有专门训练，不会主动加载 > * 有些 Agent 过于积极，一次性加载太多 在工作流的关键节点嵌入强制加载指令。官方 docx Skill 的做法： ``` ### Creating New Document **MANDATORY - READ ENTIRE FILE**: Before proceeding, you MUST read [`docx-js.md`](docx-js.md) (~500 lines) completely from start to finish. **NEVER set any range limits when reading this file.** ``` "MANDATORY"、"MUST"、"NEVER" 不是装饰词，是确保 Agent 执行的关键信号。 **注意**：这条标准只对有 reference 目录的中等/复杂 Skill 重要。简单型 Skill（如 frontend-design，43 行，无 reference）不需要考虑这个问题。 ## Skill的好坏 ### skill 返例 ``` # PDF 处理技能 ## 什么是 PDF PDF（Portable Document Format，便携式文档格式）是由 Adobe 公司在 1993 年开发的一种文件格式。它可以在不同的操作系统和设备上保持文档的格式不变，包括字体、图像、排版等元素。PDF 文件可以包含文本、图像、超链接、表单字段、视频等多种元素。 ## PDF 的特点 1. 跨平台兼容性 2. 格式保持一致 3. 支持加密和权限控制 4. 文件大小相对较小 ## 如何读取 PDF 要读取 PDF 文件，你可以使用多种方法： ### 方法一：使用 PyPDF2 Step 1: 首先安装 PyPDF2 库 pip install PyPDF2 Step 2: 导入库 from PyPDF2 import PdfReader Step 3: 打开 PDF 文件 reader = PdfReader("document.pdf") Step 4: 读取页面内容 page = reader.pages[0] text = page.extract_text() ### 方法二：使用 pdfplumber ... ``` | 问题 | 具体表现 | 后果 | | ------------ | -------------------------------- | ----------------------------------- | | 解释基础概念 | "什么是 PDF"、"PDF 的特点" | 浪费 200+ token，Claude 已经知道 | | 机械步骤 | Step 1, 2, 3, 4 | Claude 已经会写代码，不需要手把手教 | | 没有决策指导 | 列了两种方法但没说什么时候用哪种 | Agent 不知道如何选择 | | 没有反模式 | 没有说什么情况会出错 | Agent 会踩坑 | | 没有边缘情况 | 没有提到扫描件、加密 PDF 等 | 遇到特殊情况会失败 | ### Skill正例 ``` --- name: pdf-processing description: 处理 PDF 文件。当用户需要读取 PDF 文本、提取表格数据、 填写 PDF 表单、合并或拆分 PDF、将 PDF 转换为图片时使用。 --- **# PDF 处理决策树** 根据任务类型选择工具： | 任务 | 首选工具 | 备选 | 何时用备选 | | ------------ | ------------ | ----------- | -------------------------- | | 读取纯文本 | pdftotext | PyMuPDF | 需要保留布局信息 | | 提取表格 | camelot-py | tabula-py | camelot 失败时 | | 填写表单 | PyMuPDF | pdftk | PyMuPDF 不支持的表单类型 | | 合并/拆分 | PyMuPDF | pdftk | 批量处理大量文件 | | 转换为图片 | pdf2image | PyMuPDF | 需要更高分辨率控制 | **## 常见陷阱** 以下情况需要特殊处理： **扫描件 PDF** • 症状：pdftotext 返回空白或乱码 • 原因：PDF 内容是图片，不是文本 • 解决：先用 OCR（tesseract）处理，再提取文本 **加密 PDF** • 症状：读取时报权限错误 • 解决：PyMuPDF 的 `<span leaf="">open(path, password=xxx)</span>` 或先用 qpdf 解密 **复杂嵌套表格** • 症状：camelot 提取结果混乱 • 解决：考虑 LLM 辅助解析，或转成图片后用视觉模型 **大文件性能** • 超过 100 页的 PDF，避免一次性加载全部页面 • 使用分页处理：`<span leaf="">for page in reader.pages[start:end]</span>` **## 快速参考** # 命令行快速提取文本 pdftotext input.pdf - # 输出到 stdout # 转换为图片（每页一张） pdftoppm -jpeg -r 150 input.pdf output\_prefix ``` | 维度 | 表现 | 价值 | | ---------- | -------------------------- | ------------------ | | 不解释基础 | 没有"什么是 PDF" | 节省 token | | 决策导向 | 决策树告诉你什么情况用什么 | Agent 能做正确选择 | | 常见陷阱 | 扫描件、加密、复杂表格 | 避免踩坑 | | 边缘情况 | 大文件性能问题 | 处理特殊场景 | | 可操作 | 直接给命令，不给教程 | 立即可用 | ### 另一个对比：创意型 Skill **坏的创意型 Skill**： ``` # 前端设计技能 ## 设计原则 1. 保持一致性 2. 注重用户体验 3. 使用合适的颜色 4. 选择易读的字体 5. 做好响应式设计 ## 设计流程 Step 1: 理解需求 Step 2: 制作线框图 Step 3: 选择配色方案 Step 4: 编写 HTML 结构 Step 5: 添加 CSS 样式 Step 6: 实现响应式 Step 7: 测试和优化 ## 常用工具 - Figma - Sketch - Adobe XD ``` 问题：全是废话。"保持一致性"、"注重用户体验"——这些 Claude 早就知道。这个 Skill 没有传递任何 Claude 没有的知识。 **好的创意型 Skill**（官方 frontend-design 风格）： ``` --- name: frontend-design description: 创建独特的、生产级的前端界面。当用户要求构建网页组件、页面、 应用程序、海报、仪表板时使用。生成有创意、有品味的代码和 UI 设计。 --- # 设计思维 在写任何代码之前，先回答这些问题： **Purpose**：这个界面解决什么问题？谁在用它？ **Tone**：选择一个极端方向——极简主义、最大化混乱、复古未来、有机自然、奢华精致、玩具感、杂志感、粗野主义、装饰艺术... **Differentiation**：什么让这个设计令人难忘？用户会记住什么？ **关键**：选择一个清晰的概念方向，然后精确执行。大胆的最大化和精致的极简都可以——关键是意图明确，而不是强度。 ## 绝对不要做的事 以下是典型的"AI 生成感"设计，必须避免： - 滥用 Inter、Roboto、Arial 字体 - 紫色渐变配白色背景 - 所有圆角都是 8px - 千篇一律的卡片布局 - 没有个性的 cookie-cutter 风格 ## 应该追求的 - **字体**：选择有个性的字体。把一个独特的展示字体和精致的正文字体搭配。 - **颜色**：承诺一个连贯的审美。主色调配锐利的强调色，胜过胆怯的平均分配。 - **动效**：聚焦高影响力时刻——一个精心编排的页面加载动画，胜过散落的微交互。 - **空间**：意外的布局。不对称。重叠。对角线流动。打破网格的元素。 - **背景**：创造氛围和深度，而不是默认纯色。渐变网格、噪点纹理、几何图案。 ## 执行原则 **匹配复杂度和愿景**： - 最大化设计 → 需要复杂代码、大量动画和效果 - 极简设计 → 需要克制、精确、细致的间距和字体处理 优雅来自于对愿景的良好执行，而不是堆砌效果。 ``` **为什么好**： | 维度 | 表现 | | ---------- | ------------------------------------- | | 思维框架 | Purpose/Tone/Differentiation 三个问题 | | 明确反模式 | "绝对不要做的事"清单 | | 具体方向 | 字体、颜色、动效、空间、背景各有指导 | | 执行原则 | 复杂度匹配愿景 | | 不教技术 | 没有解释 CSS，Claude 已经会 | --- ### 3.4 第三个对比：代码审查 Skill 这个例子展示如何把一个日常任务变成高质量 Skill。 **坏的代码审查 Skill**： ``` # 代码审查技能 ## 什么是代码审查 代码审查是软件开发过程中，由团队成员对代码变更进行检查和评估的活动。 它可以帮助发现 bug、提高代码质量、分享知识... ## 为什么要做代码审查 1. 发现潜在的 bug 2. 提高代码可读性 3. 促进团队知识共享 4. 确保代码符合规范 ## 如何进行代码审查 Step 1: 阅读代码变更 Step 2: 理解代码的目的 Step 3: 检查是否有 bug Step 4: 检查代码风格 Step 5: 写评论反馈 Step 6: 讨论和修改 ``` 问题：全是废话。Claude 知道什么是代码审查，知道为什么要做。Step 1-6 也是显而易见的流程。这个 Skill 没有传递任何专家独有的知识。 **好的代码审查 Skill**： ``` --- name: code-review description: 审查代码质量和正确性。当用户要求 review PR、检查代码、 找 bug、评估代码质量时使用。 --- # 审查优先级 不是所有问题都同等重要。按以下顺序审查： 1. **安全漏洞**（必须修复） - 注入攻击、权限泄露、敏感数据暴露 2. **逻辑错误**（必须修复） - 边界条件、空值处理、并发问题 3. **性能问题**（建议修复） - N+1 查询、内存泄漏、不必要的重复计算 4. **可维护性**（可选） - 代码风格、命名、注释 # 思维模式 审查每段代码时，问自己： - **理解**：6 个月后的新人能看懂这段代码吗？ - **定位**：如果这里出 bug，能快速定位问题吗？ - **简化**：有没有更简单的写法实现同样功能？ # 绝对不要做 - 一次提 20 个问题（挑最重要的 3-5 个，其他放在"nit"里） - 只说"这里有问题"不说怎么改（要给具体建议或代码示例） - 吹毛求疵（专注真正影响的问题，不要纠结空格和换行） - 用"我觉得"开头（用"建议"或直接说原因） # 评论模板 **必须修复**： > [MUST] 这里存在 SQL 注入风险。用户输入未经转义直接拼接到查询中。 > 建议使用参数化查询：`db.query("SELECT * FROM users WHERE id = ?", [userId])` **建议修复**： > [SUGGEST] 这个循环内有 N+1 查询问题，在数据量大时会很慢。 > 建议改用批量查询：`User.find({ id: { $in: userIds } })` **小问题**： > [NIT] 变量名 `d` 不够清晰，建议改为 `dateCreated`。 ``` **区别总结**： | 维度 | 坏 Skill | 好 Skill | | -------- | ------------------ | ----------------- | | 概念解释 | 解释什么是代码审查 | 直接跳过 | | 流程 | Step 1-6 | 无（Claude 已知） | | 优先级 | 无 | 明确的 4 级优先级 | | 思维方式 | 无 | 3 个核心问题 | | 反模式 | 无 | 4 条"绝对不要" | | 可操作性 | 空泛建议 | 具体评论模板 | 这就是核心公式的体现：`<span leaf="">好 Skill = 专家独有的知识 - Claude 已有的知识</span>`。好的代码审查 Skill 传递的是资深工程师的审查直觉和经验，不是代码审查的定义和流程。 ## 设计检查清单 ``` 基础规范 [ ] 有 YAML frontmatter，包含 name 和 description [ ] description 包含"做什么"和"什么时候用" [ ] SKILL.md < 500 行 内容质量 [ ] 没有解释 Claude 已知的基础概念 [ ] 没有机械的 Step 1, 2, 3 [ ] 有明确的反模式清单（NEVER list） [ ] 有决策树或选择指导（如果有多种路径） [ ] 有常见陷阱和边缘情况 加载机制（仅有 reference 的 Skill） [ ] 每个 reference 有明确的加载触发条件 [ ] 触发条件嵌入在工作流步骤中 [ ] 有防止过度加载的机制 自由度 [ ] 创意任务 → 高自由度（原则而非步骤） [ ] 脆弱操作 → 低自由度（精确脚本） ``` ## 总结 好的 Agent Skill 不是教程，而是 `专家知识的外化形式`。把一个领域专家的思维方式、决策原则、反模式直觉、边缘情况经验，压缩成一个可加载的 Markdown 文件。当 Agent 加载这个文件时，它不是在"学习操作步骤"，它是在**继承一种专家思维**。 写 Skill 之前，问自己： * 这个领域的顶级专家是如何思考的？ * 他们做决策的核心原则是什么？ * 他们踩过什么坑？ * 他们绝对不会做什么？ * 什么知识是模型不知道但必须知道的？ > 好 Skill = 专家独有的知识 - Claude 已有的知识 > 好 Skill = 高压缩比 + 高信息密度 > 垃圾 Skill = 压缩了 Claude 已经知道的东西 > 工具让模型能做事，技能让模型知道怎么做 **相关链接**： shareAI-skills 仓库：https://github.com/shareAI-lab/shareAI-skills skill-judge 评估工具：https://github.com/shareAI-lab/shareAI-skills/tree/main/skills/skill-judge Kode（开源版 Claude Code）：https://github.com/shareAI-lab/Kode 最后修改：2026 年 01 月 13 日 © 允许规范转载 赞 1 如果觉得我的文章对你有用，请随意赞赏