大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



很多人写的 Skills 无法被触发，根本原因就是 Description 不是文档，而是触发器。Claude 在启动时扫描 Descriptions 来决定何时使用 Skill。如果 Description 模糊或被动，Skill 会保持休眠。我这里为大家整理了一份完整的 Claude Code Skills 编写**实践指南。这份指南基于官方文档和社区实践，希望对大家有所帮助。

上下文窗口是公共资源。你的 Skill 与以下内容共享上下文：

• 系统提示词
• 对话历史
• 其他 Skills 元数据
• 用户的实际请求

关键假设：Claude 已经非常聪明，只添加 Claude 不具备的上下文。

根据任务的脆弱性和可变性匹配具体程度：

类比思维：

• 狭窄的桥梁两侧是悬崖：只有一条安全路径 → 低自由度
• 开阔的田野无障碍：多条路径通向成功 → 高自由度

不同模型需要不同级别的指导：

• Claude Haiku：是否提供了足够的指导？
• Claude Sonnet：指令是否清晰高效？
• Claude Opus：是否避免了过度解释？

---

命名**实践：

• ✅ 推荐（动名词形式）：processing-pdfs, analyzing-spreadsheets
• ✅ 可接受：pdf-processing, analyze-spreadsheets
• ❌ 避免：helper, utils, tools（过于宽泛）

关键原则：Description 是触发器，不是文档

写作要点：

1. 使用第三人称（系统提示会注入）
2. 包含动作动词和具体文件类型
3. 说明”做什么”和”何时用”
4. 包含关键术语以便语义匹配

---

SKILL.md 作为目录，指向详细资料，仅在需要时加载。

目录结构示例：

pdf-skill/ ├── SKILL.md # 主要指令（被触发时加载） ├── FORMS.md # 表单填写指南（按需加载） ├── reference.md # API 参考（按需加载） ├── examples.md # 使用示例（按需加载） └── scripts/

├── analyze_form.py # 工具脚本（执行，不加载） └── fill_form.py

markdown

# PDF 处理 

快速开始

使用 pdfplumber 提取文本：

import pdfplumber with pdfplumber.open("file.pdf") as pdf: text = pdf.pages[0].extract_text() 

高级功能

表单填写：参见 FORMS.md API 参考：参见 REFERENCE.md 示例：参见 EXAMPLES.md

bigquery-skill/ ├── SKILL.md └── reference/

├── finance.md # 收入、计费指标 ├── sales.md # 机会、管道 ├── product.md # API 使用、功能 └── marketing.md # 营销活动、归因

SKILL.md 导航：

markdown

 可用数据集 

财务：收入、ARR、计费 → 见 reference/finance.md 销售：机会、管道、账户 → 见 reference/sales.md

markdown

# DOCX 处理

创建文档

使用 docx-js 创建新文档。见 DOCX-JS.md

编辑文档

简单编辑直接修改 XML。

跟踪修订：见 REDLINING.md OOXML 细节：见 OOXML.md

综合比较三种模式如下：

❌ 避免深度嵌套引用：

# 不好：太深 SKILL.md → advanced.md → details.md → actual_info.md

✅ 保持一级深度：

# 好：一级引用 SKILL.md → advanced.md

 → reference.md → examples.md

为长文件添加目录（>100 行）：

markdown

# API 参考 

目录

• 认证和设置
• 核心方法（创建、读取、更新、删除）
• 高级功能（批量操作、Webhooks）
• 错误处理模式

  ---

  示例：研究综合工作流

  markdown

   研究综合工作流

  为复杂操作提供清晰的步骤，并提供 Claude 可以复制和勾选的检查清单。

复制此检查清单并跟踪进度：

研究进度：

• 步骤 1：阅读所有源文档
• 步骤 2：识别关键主题
• 步骤 3：交叉引用声明
• 步骤 4：创建结构化摘要
• 步骤 5：验证引用

 步骤 1：阅读所有源文档 审查 sources/ 目录中的每个文档。注意主要论点和支持证据。

步骤 2：识别关键主题 寻找跨来源的模式。哪些主题反复出现？来源在哪里一致或不一致？

…（详细步骤）

常见模式：运行验证器 → 修复错误 → 重复

示例：文档编辑流程

markdown

 文档编辑流程

1. 编辑 word/document.xml
2. 立即验证：python ooxml/scripts/validate.py unpacked_dir/
3. 如果验证失败：
   • 仔细审查错误消息
   • 修复 XML 中的问题
   • 再次运行验证
4. 仅在验证通过时继续
5. 重建：python ooxml/scripts/pack.py unpacked_dir/ output.docx
6. 测试输出文档

   ---

   markdown

   如果你在 2025 年 8 月之前执行此操作，使用旧 API。 2025 年 8 月之后，使用新 API。

   ✅ 正确（使用”旧模式”部分）：

   markdown

    当前方法 使用 v2 API 端点：api.example.com/v2/messages

   ❌ 错误（会过时）：

旧模式

旧版 v1 API（2025-08 弃用）

v1 API 使用：api.example.com/v1/messages 此端点不再支持。

✅ 一致：始终使用 “API endpoint”、”field”、”extract” ❌ 不一致：混用 “API endpoint”、”URL”、”API route”、”path”

---

严格要求（如 API 响应）：

 报告结构

始终使用此确切模板结构：

# [分析标题] 执行摘要 [关键发现的一段概述] 主要发现 - 发现 1 及支持数据 - 发现 2 及支持数据 

灵活指导（需要适应时）：

markdown

 报告结构 这是一个合理的默认格式，但根据分析使用**判断： [模板...] 根据特定分析类型调整章节。

markdown

 提交消息格式 按照以下示例生成提交消息： 示例 1： 输入：添加了使用 JWT 令牌的用户认证 输出：

feat(auth): 实现基于 JWT 的认证

添加登录端点和令牌验证中间件

示例 2： 输入：修复报告中日期显示不正确的错误 输出：

fix(reports): 修正时区转换中的日期格式，在报告生成中一致使用 UTC 时间戳。

markdown

 文档修改工作流 1. 确定修改类型： 创建新内容？ → 遵循下面的"创建工作流" 编辑现有内容？ → 遵循下面的"编辑工作流" 2. 创建工作流： - 使用 docx-js 库 - 从头构建文档 - 导出为 .docx 格式 3. 编辑工作流： - 解包现有文档 - 直接修改 XML - 每次更改后验证 - 完成时重新打包

---

评估驱动开发流程：

1. 识别差距：在没有 Skill 的情况下运行任务，记录具体失败
2. 创建评估：构建三个测试这些差距的场景
3. 建立基线：测量没有 Skill 时的性能
4. 编写最小指令：创建刚好足够通过评估的内容
5. 迭代：执行评估，与基线比较，优化

评估结构示例：

json

{ "skills": ["pdf-processing"], "query": "从此 PDF 文件中提取所有文本并保存到 output.txt", "files": ["test-files/document.pdf"], "expected_behavior": [ "使用适当的 PDF 处理库或命令行工具成功读取 PDF 文件", "从文档的所有页面提取文本内容，不遗漏任何页面", "将提取的文本以清晰可读的格式保存到名为 output.txt 的文件" ] }

最有效的模式：用 Claude A 创建 Skill，用 Claude B 测试

创建新 Skill 流程：

1. 不使用 Skill 完成任务：与 Claude A 正常工作，观察你反复提供的上下文
2. 识别可复用模式：任务完成后，确定对类似任务有用的上下文
3. 请 Claude A 创建 Skill："创建一个捕获我们刚使用的 BigQuery 分析模式的 Skill"
4. 审查简洁性：检查是否添加了不必要的解释
5. 改进信息架构："将表架构放在单独的参考文件中，我们以后可能会添加更多表"
6. 在类似任务上测试：在 Claude B 上使用 Skill 测试相关用例
7. 基于观察迭代：如果 Claude B 有问题，返回 Claude A 优化

迭代现有 Skills：

1. 在真实工作流中使用 Skill：给 Claude B 实际任务
2. 观察 Claude B 的行为：注意它在哪里挣扎、成功或做出意外选择
3. 返回 Claude A 改进：分享当前 SKILL.md 并描述观察到的情况
4. 审查建议：Claude A 可能建议重组、使用更强语言或重构工作流
5. 应用和测试更改：更新 Skill 并再次测试
6. 基于使用重复：继续观察-优化-测试循环

---

✅ 正确（显式处理错误）：

python

def process_file(path): """处理文件，如果不存在则创建""" try: with open(path) as f: return f.read() except FileNotFoundError: print(f"文件 {path} 未找到，创建默认文件") with open(path, 'w') as f: f.write('') return '' except PermissionError: print(f"无法访问 {path}，使用默认值") return ''

❌ 错误（推卸给 Claude）：

python

def process_file(path): # 只是失败，让 Claude 想办法 return open(path).read()

工具脚本的优势：

• 比生成的代码更可靠
• 节省 tokens（无需在上下文中包含代码）
• 节省时间（无需代码生成）
• 确保跨用途的一致性

示例：

markdown

 工具脚本 analyze_form.py：从 PDF 中提取所有表单字段 bash python scripts/analyze_form.py input.pdf > fields.json 

输出格式：

{ "field_name": {"type": "text", "x": 100, "y": 200}, "signature": {"type": "sig", "x": 150, "y": 500} } 

计划-验证-执行模式：

为什么有效：

• 提前捕获错误
• 机器可验证
• 可逆规划
• 清晰调试

---

• ✅ 正确：scripts/helper.py, reference/guide.md
• ❌ 避免：scripts\helper.py, reference\guide.md

❌ 错误（混乱）：

markdown

"你可以使用 pypdf，或 pdfplumber，或 PyMuPDF，或 pdf2image，或..."

✅ 正确（提供默认值和逃生口）：

markdown

"使用 pdfplumber 提取文本： python import pdfplumber 

对于需要 OCR 的扫描 PDF，改用 pdf2image 配合 pytesseract。”

---

• Description 具体且包含关键术语
• Description 包含”做什么”和”何时用”
• SKILL.md 正文少于 500 行
• 额外细节在单独文件中
• 无时间敏感信息
• 术语一致
• 示例具体而非抽象
• 文件引用保持一级深度
• 适当使用渐进式披露
• 工作流有清晰步骤

• 脚本解决问题而非推卸
• 错误处理明确且有帮助
• 无”巫毒常数”（所有值都有说明）
• 所需包在说明中列出并验证可用
• 脚本有清晰文档
• 无 Windows 风格路径
• 关键操作有验证/核查步骤
• 质量关键任务包含反馈循环

• 至少创建三个评估
• 使用 Haiku、Sonnet 和 Opus 测试
• 使用真实使用场景测试
• 纳入团队反馈（如适用）

---

1. Description 是触发器：模糊的描述 = Skill 不会被触发
2. 简洁至关重要：默认假设 Claude 已经知道
3. 渐进式披露：SKILL.md 作为目录，按需加载细节
4. 评估驱动：先构建评估，再编写内容
5. 与 Claude 协作：用 Claude A 构建，用 Claude B 测试
6. 工具脚本 > 生成代码：预制脚本更可靠、更高效
7. 反馈循环：验证 → 修复 → 重复 = 高质量输出
8. 一致性胜于聪明：使用相同术语，避免混淆

---

1. 选择一个你经常重复的任务
2. 完成一次任务，记录你提供的上下文
3. 让 Claude 将其转换为 Skill
4. 删除不必要的解释
5. 测试并迭代

1. 在共享文档库中创建 Skills 规范
2. 使用一致的命名约定
3. 为企业级 Skills 建立治理实践
4. 定期审查和更新

1. 观察 Claude 如何使用你的 Skills
2. 收集团队反馈
3. 基于实际使用模式迭代
4. 保持评估更新

#ai##ai编程##让AI触手可及##ClaudeCode#