如何创建 Skills：关键步骤、限制与示例

学习如何编写贴合具体任务的 Skills，让 Claude 输出更稳定、更有效。

Skills 是一组自定义指令，用来扩展 Claude 在特定任务或领域中的能力。

当你通过 SKILL.md 创建 Skill 时，本质上是在教 Claude 更有效地处理某类场景。Skill 的价值在于：把组织知识写下来，统一输出格式，并承载复杂的多步骤流程，避免每次都重复解释，或者专门搭一个自定义 Agent。

你可以用 Skill Creator 模板，也可以手写 SKILL.md，把 Claude 从通用助手变成适配你工作流的专业助手。初学时建议先从模板开始，再按自己的场景修改。

用 5 步创建一个 Skill

按下面的结构来做，可以让 Skill 更稳定地被触发。

1. 理解核心需求

动笔前先说清楚这个 Skill 要解决什么问题。好的 Skill 面向具体需求，并且结果可衡量。例如“从 PDF 提取财务数据并格式化为 CSV”，就比“帮我处理财务相关内容”更好，因为它明确了输入、操作和输出。

可以先问自己：这个 Skill 完成哪项具体任务？哪些请求应该触发它？成功结果长什么样？有哪些边界情况或限制？

2. 编写名称

一个 Skill 有三个核心部分：name 用来清楚标识，description 说明何时启用，instructions 说明如何执行。其中 name 和 description 是影响触发的关键内容，也就是 Claude 判断是否需要调用这个 Skill 的依据。

名称应该直接、可描述。使用小写和连字符，例如 pdf-editor、brand-guidelines。保持简短清晰。

3. 编写 description 字段

description 决定 Skill 什么时候被激活，因此是最关键的部分。要站在 Claude 的视角写，重点描述触发条件、能力范围和使用场景。

好的 description 会同时说明具体能力、清晰触发条件、相关背景和边界。

较弱的 description：

This skill helps with PDFs and documents.

较强的 description：

Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. When Claude needs to fill in a PDF form or programmatically process, generate, or analyze PDF documents at scale. Use for document workflows and batch operations. Not for simple PDF viewing or basic conversions.

更强的版本给了 Claude 多个判断信号：具体动作、明确用例，以及不要使用的边界。

4. 编写主要 instructions

instructions 应该结构清楚、易扫描、可执行。可以用 Markdown 标题组织内容，用项目符号列出选项，用代码块给出示例。

用清晰层级组织内容：概览、前置条件、执行步骤、示例、错误处理和限制。复杂流程要拆成阶段，并写明每个阶段的输入和输出。

加入具体示例说明正确用法。也要写清楚 Skill 不能做什么，避免误用并管理预期。SKILL.md 还可以引用额外参考文件和资源，让 Agent 被触发后获得更明确的操作指导。

5. 上传你的 Skill

根据你使用的 Claude 入口不同，上传 Skill 的方式也不同：

• Claude.ai（Claude apps）：进入 Settings 添加自定义 Skill。自定义 Skills 需要开启代码执行，并且目前按个人用户管理。

• Claude Code：在插件或项目根目录创建 skills/ 目录，把包含 SKILL.md 的 Skill 文件夹放进去。插件安装后，Claude 会自动发现并使用。

my-project/ ├── skills/ │ └── my-skill/ │ └── SKILL.md

• Claude Developer Platform：通过 Skills API（/v1/skills 端点）上传 Skills，并在请求中带上必需的 beta headers。

curl -X POST "https://api.anthropic.com/v1/skills" \ -H "x-api-key: $ANTHROPIC _API_ KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: skills-2025-10-02" \ -F "display _title=My Skill Name" \ -F "files[]=@my-skill/SKILL.md;filename=my-skill/SKILL.md"

4. 测试与验证

上线前要用真实场景测试 Skill。系统化测试可以暴露 instructions 的缺口、description 的歧义，以及只有实际使用时才会出现的边界情况。

可以建立一个覆盖三类场景的测试矩阵：

• 正常流程：用 Skill 应该完美处理的典型请求来测试。

• 边界情况：用缺失、不完整或异常输入测试，看 Skill 能否优雅处理。

• 范围外请求：用相似但不该触发的任务测试，确保 Skill 不会误触发。

如果想验证得更深入，可以再加入这些测试：

• 触发测试：检查 Skill 是否在该触发时触发、无关时保持不激活。

• 功能测试：检查多次运行的一致性、可用性和文档示例是否符合真实行为。

5. 根据实际使用迭代

观察 Skill 在真实使用中的表现。如果触发不稳定，就调整 description；如果输出波动大，就把 instructions 写得更具体。和 prompts 一样，最好的 Skills 都是在实际应用中迭代出来的。

创建 Skills 的通用最佳实践

这些原则能帮助你创建可维护、可复用、真正有用的 Skills，而不是停留在理论上。

从真实用例出发

不要凭空猜需求来写 Skill。只有当你确实有重复出现的真实任务时，再把它沉淀成 Skill。最好的 Skills 通常来自你经常遇到的问题。

创建前可以问自己：这个任务我已经做过至少五次吗？以后还会再做十次以上吗？如果答案是肯定的，就值得做成 Skill。

定义成功标准，并写进 Skill

告诉 Claude 什么样的输出才算好。如果你在生成财务报告，就写明必需章节、格式标准、校验项和质量门槛，让 Claude 能自查。

使用 Skill-Creator skill

skill-creator skill 会引导你创建结构良好的 Skills：它会提澄清问题，建议如何改进 description，并帮助正确组织 instructions。它适合用来完成前几个 Skills。

Skill 的限制与注意事项

理解 Skills 的工作方式和边界，有助于设计更有效的 Skill，也能设置合理预期。

Skill 触发机制

Claude 会根据你的请求和 Skill description 判断相关性。这不是简单关键词匹配，Claude 会理解语义关系；但 description 太模糊会降低触发准确率。

复杂任务可能同时触发多个 Skills。过于泛化的 description 会导致误触发，漏写用例则会导致该触发时没有触发。

合适的文件大小

写 Skill 时要避免把无关内容塞满上下文窗口。每一段信息都要判断：它是否每次都必须加载，还是只在特定条件下才需要。

可以采用“菜单”式写法：如果 Skill 覆盖多个不同流程或选项，SKILL.md 只说明有哪些内容，并用相对路径指向各自文件。Claude 会按任务需要读取相关文件，其余文件不会进入本轮上下文。

这些独立文件不一定互斥。关键是把内容拆成合理块，让 Claude 根据当前任务选择需要加载的部分。

真实世界的 Skill 示例

Skill 示例 1：docx 创建 Skill

#--- name: docx 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" license: Proprietary. LICENSE.txt has complete terms --- # DOCX creation, editing, and analysis ## Overview A user may ask you to create, edit, or analyze the contents of a .docx file. A .docx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks. ## Workflow Decision Tree ### Reading/Analyzing Content Use "Text extraction" or "Raw XML access" sections below ### Creating New Document Use "Creating a new Word document" workflow ### Editing Existing Document - **Your own document + simple changes** Use "Basic OOXML editing" workflow - **Someone else's document** Use **"Redlining workflow"** (recommended default) - **Legal, academic, business, or government docs** Use **"Redlining workflow"** (required) ## Reading and analyzing content ### Text extraction If you just need to read the text contents of a document, you should convert the document to markdown using pandoc. Pandoc provides excellent support for preserving document structure and can show tracked changes: ```bash # Convert document to markdown with tracked changes pandoc --track-changes=all path-to-file.docx -o output.md # Options: --track-changes=accept/reject/all ``` ### Raw XML access You need raw XML access for: comments, complex formatting, document structure, embedded media, and metadata. For any of these features, you'll need to unpack a document and read its raw XML contents. #### Unpacking a file `python ooxml/scripts/unpack.py <office_file> <output_directory>` #### Key file structures * `word/document.xml` - Main document contents * `word/comments.xml` - Comments referenced in document.xml * `word/media/` - Embedded images and media files * Tracked changes use `<w:ins>` (insertions) and `<w:del>` (deletions) tags ## Creating a new Word document When creating a new Word document from scratch, use **docx-js** , which allows you to create Word documents using JavaScript/TypeScript. ### Workflow 1. **MANDATORY - READ ENTIRE FILE** : Read [ `docx-js.md` ]( docx-js.md ) (~500 lines) completely from start to finish. **NEVER set any range limits when reading this file.** Read the full file content for detailed syntax, critical formatting rules, and best practices before proceeding with document creation. 2. Create a JavaScript/TypeScript file using Document, Paragraph, TextRun components (You can assume all dependencies are installed, but if not, refer to the dependencies section below) 3. Export as .docx using Packer.toBuffer() ## Editing an existing Word document When editing an existing Word document, use the **Document library** (a Python library for OOXML manipulation). The library automatically handles infrastructure setup and provides methods for document manipulation. For complex scenarios, you can access the underlying DOM directly through the library. ### Workflow 1. **MANDATORY - READ ENTIRE FILE** : Read [ `ooxml.md` ]( ooxml.md ) (~600 lines) completely from start to finish. **NEVER set any range limits when reading this file.** Read the full file content for the Document library API and XML patterns for directly editing document files. 2. Unpack the document: `python ooxml/scripts/unpack.py <office_file> <output_directory>` 3. Create and run a Python script using the Document library (see "Document Library" section in ooxml.md) 4. Pack the final document: `python ooxml/scripts/pack.py <input_directory> <office_file>` The Document library provides both high-level methods for common operations and direct DOM access for complex scenarios. ## Redlining workflow for document review This workflow allows you to plan comprehensive tracked changes using markdown before implementing them in OOXML. **CRITICAL** : For complete tracked changes, you must implement ALL changes systematically. **Batching Strategy** : Group related changes into batches of 3-10 changes. This makes debugging manageable while maintaining efficiency. Test each batch before moving to the next. **Principle: Minimal, Precise Edits** When implementing tracked changes, only mark text that actually changes. Repeating unchanged text makes edits harder to review and appears unprofessional. Break replacements into: [unchanged text] + [deletion] + [insertion] + [unchanged text]. Preserve the original run's RSID for unchanged text by extracting the `<w:r>` element from the original and reusing it. Example - Changing "30 days" to "60 days" in a sentence: ```python # BAD - Replaces entire sentence '<w:del><w:r><w:delText>The term is 30 days.</w:delText></w:r></w:del><w:ins><w:r><w:t>The term is 60 days.</w:t></w:r></w:ins>' # GOOD - Only marks what changed, preserves original <w:r> for unchanged text '<w:r w:rsidR="00AB12CD"><w:t>The term is </w:t></w:r><w:del><w:r><w:delText>30</w:delText></w:r></w:del><w:ins><w:r><w:t>60</w:t></w:r></w:ins><w:r w:rsidR="00AB12CD"><w:t> days.</w:t></w:r>' ``` ### Tracked changes workflow 1. **Get markdown representation** : Convert document to markdown with tracked changes preserved: ```bash pandoc --track-changes=all path-to-file.docx -o current.md ``` 2. **Identify and group changes** : Review the document and identify ALL changes needed, organizing them into logical batches: **Location methods** (for finding changes in XML): - Section/heading numbers (e.g., "Section 3.2", "Article IV") - Paragraph identifiers if numbered - Grep patterns with unique surrounding text - Document structure (e.g., "first paragraph", "signature block") - **DO NOT use markdown line numbers** - they don't map to XML structure **Batch organization** (group 3-10 related changes per batch): - By section: "Batch 1: Section 2 amendments", "Batch 2: Section 5 updates" - By type: "Batch 1: Date corrections", "Batch 2: Party name changes" - By complexity: Start with simple text replacements, then tackle complex structural changes - Sequential: "Batch 1: Pages 1-3", "Batch 2: Pages 4-6" 3. **Read documentation and unpack** : - **MANDATORY - READ ENTIRE FILE** : Read [ `ooxml.md` ]( ooxml.md ) (~600 lines) completely from start to finish. **NEVER set any range limits when reading this file.** Pay special attention to the "Document Library" and "Tracked Change Patterns" sections. - **Unpack the document** : `python ooxml/scripts/unpack.py <file.docx> <dir>` - **Note the suggested RSID** : The unpack script will suggest an RSID to use for your tracked changes. Copy this RSID for use in step 4b. 4. **Implement changes in batches** : Group changes logically (by section, by type, or by proximity) and implement them together in a single script. This approach: - Makes debugging easier (smaller batch = easier to isolate errors) - Allows incremental progress - Maintains efficiency (batch size of 3-10 changes works well) **Suggested batch groupings:** - By document section (e.g., "Section 3 changes", "Definitions", "Termination clause") - By change type (e.g., "Date changes", "Party name updates", "Legal term replacements") - By proximity (e.g., "Changes on pages 1-3", "Changes in first half of document") For each batch of related changes: **a. Map text to XML** : Grep for text in `word/document.xml` to verify how text is split across `<w:r>` elements. **b. Create and run script** : Use `get_node` to find nodes, implement changes, then `doc.save()` . See **"Document Library"** section in ooxml.md for patterns. **Note** : Always grep `word/document.xml` immediately before writing a script to get current line numbers and verify text content. Line numbers change after each script run. 5. **Pack the document** : After all batches are complete, convert the unpacked directory back to .docx: ```bash python ooxml/scripts/pack.py unpacked reviewed-document.docx ``` 6. **Final verification** : Do a comprehensive check of the complete document: - Convert final document to markdown: ```bash pandoc --track-changes=all reviewed-document.docx -o verification.md ``` - Verify ALL changes were applied correctly: ```bash grep "original phrase" verification.md # Should NOT find it grep "replacement phrase" verification.md # Should find it ``` - Check that no unintended changes were introduced ## Converting Documents to Images To visually analyze Word documents, convert them to images using a two-step process: 1. **Convert DOCX to PDF** : ```bash soffice --headless --convert-to pdf document.docx ``` 2. **Convert PDF pages to JPEG images** : ```bash pdftoppm -jpeg -r 150 document.pdf page ``` This creates files like `page-1.jpg` , `page-2.jpg` , etc. Options: - `-r 150` : Sets resolution to 150 DPI (adjust for quality/size balance) - `-jpeg` : Output JPEG format (use `-png` for PNG if preferred) - `-f N` : First page to convert (e.g., `-f 2` starts from page 2) - `-l N` : Last page to convert (e.g., `-l 5` stops at page 5) - `page` : Prefix for output files Example for specific range: ```bash pdftoppm -jpeg -r 150 -f 2 -l 5 document.pdf page # Converts only pages 2-5 ``` ## Code Style Guidelines **IMPORTANT** : When generating code for DOCX operations: - Write concise code - Avoid verbose variable names and redundant operations - Avoid unnecessary print statements ## Dependencies Required dependencies (install if not available): - **pandoc** : `sudo apt-get install pandoc` (for text extraction) - **docx** : `npm install -g docx` (for creating new documents) - **LibreOffice** : `sudo apt-get install libreoffice` (for PDF conversion) - **Poppler** : `sudo apt-get install poppler-utils` (for pdftoppm to convert PDF to images) - **defusedxml** : `pip install defusedxml` (for secure XML parsing)

强在哪里：它给 Claude 提供了具体、可执行、边界清楚的信息，而不是泛泛而谈；同时通过示例、流程或质量标准，让复杂任务更容易稳定执行。

Skill 示例 2：品牌规范

#name: brand-guidelines description: Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. license: Complete terms in LICENSE.txt --- # Anthropic Brand Styling ## Overview To access Anthropic's official brand identity and style resources, use this skill. **Keywords** : branding, corporate identity, visual identity, post-processing, styling, brand colors, typography, Anthropic brand, visual formatting, visual design ## Brand Guidelines ### Colors **Main Colors:** - Dark: `#141413` - Primary text and dark backgrounds - Light: `#faf9f5` - Light backgrounds and text on dark - Mid Gray: `#b0aea5` - Secondary elements - Light Gray: `#e8e6dc` - Subtle backgrounds **Accent Colors:** - Orange: `#d97757` - Primary accent - Blue: `#6a9bcc` - Secondary accent - Green: `#788c5d` - Tertiary accent ### Typography - **Headings** : Poppins (with Arial fallback) - **Body Text** : Lora (with Georgia fallback) - **Note** : Fonts should be pre-installed in your environment for best results ## Features ### Smart Font Application - Applies Poppins font to headings (24pt and larger) - Applies Lora font to body text - Automatically falls back to Arial/Georgia if custom fonts unavailable - Preserves readability across all systems ### Text Styling - Headings (24pt+): Poppins font - Body text: Lora font - Smart color selection based on background - Preserves text hierarchy and formatting ### Shape and Accent Colors - Non-text shapes use accent colors - Cycles through orange, blue, and green accents - Maintains visual interest while staying on-brand ## Technical Details ### Font Management - Uses system-installed Poppins and Lora fonts when available - Provides automatic fallback to Arial (headings) and Georgia (body) - No font installation required - works with existing system fonts - For best results, pre-install Poppins and Lora fonts in your environment ### Color Application - Uses RGB color values for precise brand matching - Applied via python-pptx's RGBColor class - Maintains color fidelity across different systems

强在哪里：它给 Claude 提供了具体、可执行、边界清楚的信息，而不是泛泛而谈；同时通过示例、流程或质量标准，让复杂任务更容易稳定执行。

Skill 示例 3：前端设计 Skill

name: frontend-design description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics. license: Complete terms in LICENSE.txt --- This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints. ## Design Thinking 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, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. - **Constraints** : Technical requirements (framework, performance, accessibility). - **Differentiation** : What makes this UNFORGETTABLE? What's the one thing someone will remember? **CRITICAL** : Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity. Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is: - Production-grade and functional - Visually striking and memorable - Cohesive with a clear aesthetic point-of-view - Meticulously refined in every detail ## Frontend Aesthetics Guidelines Focus on: - **Typography** : Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font. - **Color & Theme** : Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. - **Motion** : Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise. - **Spatial Composition** : Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density. - **Backgrounds & Visual Details** : Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays. NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character. Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations. **IMPORTANT** : Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well. Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.

常见问题

怎样写出真正会触发的 description？

重点写能力和场景，不要堆泛泛关键词。加入动作动词、具体文件类型和清晰用例。

Claude 如何决定调用哪些 Skills？

Claude 会用语义理解把你的请求和 Skill description 对齐。它不是关键词匹配，而是在判断上下文相关性；一个请求也可能同时触发多个 Skills。

description 应该写到多细？

建议做单一用途的 Skills。范围要足够聚焦，能指导具体行为；同时也要有一定复用性。

如何在组织内共享 Skills？

无论团队大小，都建议建立一个共享文档库来保存 Skill 规范。

小团队可以使用模板格式，包含 name、description、instructions 和版本信息。

中大型团队应该建立 Skills 治理流程：

• 为每个领域指定 Skill 负责人。

• 维护中央 wiki 或共享盘作为 Skill 库。

• 为每个 Skill 加入使用示例和常见排障说明。

• 对 Skills 做版本管理，并用 changelog 记录变更。

• 定期审查，更新或淘汰过时 Skills。

所有团队规模都适用的最佳实践：

• 记录每个 Skill 的业务目的。

• 明确维护和更新负责人。

• 准备入门材料，教新成员如何使用共享 Skills。

• 跟踪哪些 Skills 最有价值，以便优先维护。

• 使用一致命名，让 Skills 更容易被找到。

企业客户可以与 Anthropic 客户成功团队一起探索更多部署选项和治理框架。

如何调试 Skills？

调试时把“是否触发”和“执行质量”分开看。如果没有触发，拓宽 description 并补充用例；如果结果不稳定，就细化 instructions 并加入验证步骤。

在 Claude.ai 中，Skills 目前按用户个人管理；组织级管理和共享能力还在推进中。与此同时，建议团队先建立共享 Skill 文档库，为后续功能做好准备，也能从现在开始形成治理习惯。

开始使用

准备开始使用 Skills？可以从这里入手：

Claude.ai 用户：

• 在 Settings -> Features 中启用 Skills。

• 在 claude.ai/projects 创建你的第一个项目。

• 在下一次分析任务中，尝试把项目知识和 Skills 结合起来。

API 开发者：

• 阅读文档中的 Skills endpoint。

• 查看 skills cookbook。

Claude Code 用户：

• 通过插件市场安装 Skills。

Agent Skills

现在就开始在 Claude 中使用 Skills，构建更强大的应用。