1. 项目概述：从“技能”视角重新理解AI助手的能力边界

如果你和我一样，长期在AI应用开发的一线摸爬滚打，那么看到“技能”这个概念时，第一反应可能和我当初一样：这不就是另一种形式的“提示词工程”或者“工具调用”吗？但当我深入研究了Anthropic开源的 anthropics/skills 仓库，并实际动手创建了几个自定义技能后，我才意识到，这背后其实是一套全新的、系统化的AI能力扩展范式。它试图解决一个核心痛点：如何让像Claude这样的大模型，从一个“什么都知道一点，但什么都不精”的通才，转变为一个能在特定领域、按照你的特定规则、稳定输出专业结果的“专家”。

简单来说，一个“技能”就是一个封装好的指令包。它不仅仅是一段提示词，而是一个包含元数据、操作指南、示例和资源文件的完整文件夹。当Claude加载这个技能时，它就获得了执行某项专门任务的能力。比如，你可以创建一个“公司品牌文档生成”技能，里面详细定义了你的Logo使用规范、品牌色值、字体要求、文案语调，甚至包含一些预设的模板文件。之后，无论哪个部门的同事让Claude帮忙写宣传稿，只要激活这个技能，输出的内容都会自动符合品牌规范，无需反复提醒。

这个仓库的价值在于，它不是一个封闭的黑盒，而是一个开放的“范例库”和“脚手架”。Anthropic不仅提供了技能的技术规范（在 ./spec 目录下），还展示了从创意设计、技术开发到企业通讯等不同领域的技能实例（在 ./skills 目录下）。更关键的是，他们甚至把Claude内部处理Office文档（Word, Excel, PowerPoint, PDF）的核心能力也以“源码可用”的形式分享了出来。这对于我们开发者而言，就像拿到了一份米其林大厨的食谱，不仅能知道菜怎么做，还能窥见其调味和火候的秘诀。

2. 技能系统的核心架构与设计哲学

2.1 技能究竟是什么：超越提示词的工具箱

要理解技能，我们得先把它和几个容易混淆的概念区分开。

技能 vs. 传统提示词： 传统的提示词是线性的、一次性的指令。你告诉AI“用正式的语气写一封邮件”，它照做。但如果你想让AI学会你公司整套的邮件撰写流程（包括查通讯录、引用项目编号、附上特定免责声明），你就需要把一大堆规则塞进一个冗长的提示词里，难以维护，也容易在长对话中丢失上下文。而技能是一个 持久化、模块化 的指令集。它被定义在一个独立的 SKILL.md 文件中，一旦被Claude加载，其内部的指令和规则就会成为Claude思考背景的一部分，持续影响后续的交互，直到技能被卸载。

技能 vs. 函数调用/工具调用： 像OpenAI的Function Calling或LangChain的工具，核心是让AI能够调用外部代码或API来执行它自身无法完成的操作（如查询数据库、发送HTTP请求）。技能当然可以包含调用外部工具的指令，但它的范畴更广。一个技能可以纯粹是“认知性”的，比如“用Socratic问答法辅导学生”，它并不调用任何API，只是改变了AI的推理和回应方式。技能的本质是 教导AI一种方法或流程 ，而工具调用只是实现该流程的一种可能手段。

那么，一个技能到底包含什么？从仓库的结构看，一个标准的技能文件夹通常包含：

• SKILL.md ：核心文件，包含YAML格式的元数据（技能名、描述）和Markdown格式的详细指令。
• resources/ （可选）：存放技能所需的参考文件，如图片、模板、配置文件。
• scripts/ （可选）：存放可执行的脚本，供AI在需要时调用或参考。

这种设计体现了“约定大于配置”的思想。开发者只需遵循简单的文件夹结构，就能创建出功能强大的技能，降低了上手门槛。

2.2 技能仓库的生态解析：从示例到生产级参考

anthropics/skills 仓库本身就是一个精心设计的技能开发生态缩影。它主要分为三大部分：

1. 技能示例库 ( ./skills ) 这是仓库最丰富的部分，按照领域分类，为我们提供了绝佳的灵感来源。

• 创意与设计类 ：例如，可能包含“生成艺术风格说明”、“进行色彩搭配分析”等技能。这些技能展示了如何用自然语言定义主观的、创意性的任务标准。
• 开发与技术类 ：这是我最关注的部分。里面可能有“单元测试生成”、“API代码桩生成”、“MCP服务器脚手架创建”等技能。它们演示了如何让Claude遵循特定的代码规范、测试框架和项目结构来工作，对于提升开发效率有直接帮助。
• 企业与通讯类 ：如“撰写符合某规范的公关稿”、“整理会议纪要并生成行动项”。这类技能是企业内部知识沉淀和流程标准化的重要工具。
• 文档技能 ：这是“王炸”部分。 docx , pdf , pptx , xlsx 这几个文件夹下的技能，是Claude处理Office文档能力的底层实现参考。虽然它们是“源码可用”而非“开源”，但其价值在于揭示了Anthropic如何教会AI理解复杂文件格式、提取信息、进行结构化编辑的“思考过程”。研究它们，你能学到如何设计处理二进制或复杂结构数据的技能。

2. 技能规范 ( ./spec ) 这里定义了Agent Skills的标准。对于想要让自家产品与Claude技能系统深度集成的开发者，或者想确保自定义技能具有最佳兼容性和未来性的团队，这份规范是必读的。它明确了技能元数据的格式、文件结构的约定、以及技能在运行时应该如何被管理和调用。

3. 技能模板 ( ./template ) 这是一个标准的“Hello World”模板，包含了创建技能所需的最小文件集合。对于新手，从这里开始复制粘贴是最快的方式。它清晰地展示了 SKILL.md 中YAML头信息和指令部分的写作框架。

注意： 仓库的免责声明非常重要。这些示例技能主要是为了“演示和教育目的”。这意味着，虽然Claude产品中可能具备类似能力，但其具体实现和行为可能与仓库代码不同。 切勿未经充分测试就直接将示例技能用于生产关键任务。 你应该将这些示例视为“设计模式”和“最佳实践”的参考，在此基础上开发适合自己场景的技能。

3. 深度实操：从零构建你的第一个生产级技能

了解了理论，我们动手创建一个有实用价值的技能。假设我们是一个电商技术团队，经常需要让Claude分析Nginx的访问日志，找出异常请求模式。我们将创建一个“Nginx日志分析器”技能。

3.1 技能设计与元数据定义

首先，创建技能文件夹结构：

my-nginx-log-skill/
├── SKILL.md
└── resources/
    └── sample_access.log

SKILL.md 是核心，我们从YAML头信息开始：

---
name: nginx-log-analyzer
description: |
  专业分析Nginx标准访问日志，识别异常流量模式、统计关键指标，并提供安全与性能洞察。
  当用户上传或粘贴Nginx日志内容，或提及分析服务器日志时，应自动应用此技能。
version: 1.0.0
author: Your-Dev-Team
tags:
  - devops
  - security
  - monitoring
  - nginx
---

这里有几个关键点：

• name ：使用小写和连字符，这是技能的唯一标识符。
• description ：描述必须清晰、完整。它不仅说明技能“做什么”，更要说明“何时用”。Claude会根据描述来决定在对话中是否自动激活该技能。多行描述用 | 符号。
• 我额外添加了 version , author , tags 字段。虽然规范只要求 name 和 description ，但添加这些元数据有利于技能的管理、分类和版本追踪，是良好的实践。

3.2 编写核心指令：教会AI像专家一样思考

YAML头信息之后，就是Markdown格式的指令正文。这是技能的“大脑”。

# Nginx日志分析专家技能

当我被激活时，我将以一名资深运维工程师的视角分析Nginx访问日志。我的核心目标是：从海量日志条目中快速定位问题、发现模式、并提供可操作的见解。

## 我的分析流程
1.  **日志格式识别与解析**：首先确认日志格式是否为Nginx默认组合格式（`$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"`）。如果用户未指明，我会询问或基于常见模式进行推断。
2.  **数据清洗与结构化**：将非结构化的日志行解析为结构化的字段（IP、时间、方法、URL、状态码、字节数、Referer、User-Agent）。
3.  **多维度分析**：我将按以下优先级展开分析：
    - **安全审计**：聚焦`4xx`（客户端错误）和`5xx`（服务器错误）状态码，高频失败请求可能预示扫描或攻击。
    - **流量分析**：统计总请求量、独立IP数、请求速率（QPS），识别流量高峰时段。
    - **资源访问分析**：找出最常访问的URL端点、最耗资源的请求（大`$body_bytes_sent`）。
    - **用户代理分析**：识别爬虫、异常客户端或特定浏览器版本的访问比例。
4.  **异常检测**：基于统计基线（如平均请求频率）或经验规则（如单一IP瞬间高频率请求）标记可疑活动。
5.  **报告生成**：以清晰、层级化的方式呈现分析结果，优先展示最关键的风险和性能问题。

## 输出格式指南
- 始终以**执行摘要**开头，用1-2句话概括核心发现（例如：“发现来自IP X.X.X.X的异常扫描行为，过去一小时触发412次403错误。”）。
- 使用**表格**呈现量化数据（如Top 10访问IP、状态码分布）。
- 对于异常点，提供**原始日志行样例**和**上下文分析**。
- 在最后提供**后续行动建议**，如“建议将IP X.X.X.X加入临时黑名单观察”、“端点 `/api/v1/query` 错误率高达15%，建议检查后端服务”。

## 示例对话
**用户**：帮我分析这段nginx日志，看看有没有奇怪的地方。
**Claude（激活技能）**：“我将以Nginx日志分析专家的身份为您服务。首先，我注意到日志格式为标准组合格式。我已解析了共10,250条记录。**核心发现**：检测到来自 `203.0.113.5` 的潜在爬虫，其在2分钟内对 `/wp-admin` 路径发起了587次请求，均返回404状态码，这可能是针对WordPress站点的目录扫描尝试。

**详细分析如下：**
1.  **安全异常**：
    | 可疑IP | 请求次数 | 目标路径 | 主要状态码 | 风险评级 |
    |---|---|---|---|---|
    | 203.0.113.5 | 587 | `/wp-admin`, `/wp-login.php` | 404 | 高 |
    （附上2条样例日志行...）

2.  **流量概况**：总请求10,250，独立IP 892个，平均QPS约为8.5...
...
**建议**：1. 立即在防火墙或WAF中临时屏蔽 `203.0.113.5`。2. 对 `/wp-admin` 等管理路径实施访问频率限制。...”

## 技能边界与限制
- 我仅分析**访问日志**。错误日志（error log）需要不同的分析技能。
- 我的分析基于日志中呈现的模式，不涉及服务器实时状态监控（如CPU、内存）。
- 对于极其庞大的日志文件（如超过10万行），我可能建议用户先进行时间范围筛选或抽样分析。

这份指令的撰写，是技能成败的关键。我的经验是：

• 角色化 ：明确告诉AI“扮演什么角色”，这能框定其思考的视角和专业范围。
• 流程化 ：将分析过程分解为清晰的步骤。AI擅长遵循流程，这比笼统的指令（“好好分析”）有效得多。
• 结构化输出 ：明确规定输出的格式。这能保证每次技能调用的结果都一致、专业、易于阅读。
• 提供范例 ：示例对话是最直观的“教学”。它展示了技能激活后的理想交互模式。
• 明确边界 ：告诉AI什么不做，可以防止它“越界”产生不相关或错误的输出。

3.3 资源文件的准备与使用

在我们的 resources/sample_access.log 里，可以放一小段真实的（或脱敏生成的）Nginx日志。这个文件有两个作用：

1. 技能测试 ：在开发技能时，你可以用这个样本文件来测试和调试你的指令。
2. AI参考 ：虽然Claude在技能运行时不一定直接读取这个文件，但在技能描述中你可以提及“本技能包含常见日志模式的示例”，这能增强技能的专业可信度。

对于更复杂的技能， resources/ 目录下可以放置JSON Schema文件、配置模板、图片素材等， scripts/ 目录下可以放置Python或Shell脚本，技能指令可以教导AI在特定条件下“参考 scripts/cleanup.py 中的逻辑”或“使用 resources/template.yaml 的格式”。

4. 技能的部署、使用与集成实战

技能创建好后，如何在不同的Claude环境中使用呢？仓库给出了三条路径。

4.1 在Claude Code中安装与使用（开发者场景）

Claude Code是面向开发者的IDE插件。将技能作为插件安装，能让Claude在编码上下文中直接具备相关能力。

安装社区技能：

# 将整个技能仓库添加到插件市场
/plugin marketplace add anthropics/skills

# 或者直接安装特定的技能包
/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

安装后，在Claude Code的对话中，你只需说“用PDF技能提取这个文档的元数据”，Claude就会自动调用已安装的PDF处理技能，无需额外配置。

安装自定义技能： 对于我们自己开发的 nginx-log-analyzer 技能，我们需要将其打包或发布到一个Claude Code能访问的地方（比如GitHub仓库），然后通过类似的 /plugin install 命令进行安装。这实现了开发环境下的技能私有化部署。

4.2 在Claude.ai网页端使用（普通用户场景）

对于Claude.ai的付费用户，仓库中的许多示例技能已经内置可用。更重要的是，你可以上传自定义技能。

1. 在Web界面中，通常会有“管理技能”或“自定义技能”的入口。
2. 将你的技能文件夹（如 my-nginx-log-skill ）压缩为ZIP包。
3. 上传该ZIP包，Claude会解析其中的 SKILL.md 并注册该技能。
4. 在后续对话中，当你的问题匹配技能描述时（如“分析这段日志”），Claude可能会自动建议或应用该技能。你也可以手动通过“@”提及或特定指令来调用它。

这种方式极大降低了非技术用户使用定制化AI能力的门槛。业务人员可以将复杂的报表生成规则、文案审查标准封装成技能，一键上传，团队共享。

4.3 通过Claude API集成（系统集成场景）

这是最强大、最灵活的方式，允许你将技能深度集成到自己的应用程序中。

import anthropic

client = anthropic.Anthropic(api_key="your-api-key")

# 假设你已经将技能内容读入变量 `skill_markdown_content`
skill_definition = {
    "name": "nginx-log-analyzer",
    "content": skill_markdown_content  # 即SKILL.md的完整内容
}

# 1. 创建技能（通常只需一次，或作为应用初始化的一部分）
created_skill = client.skills.create(**skill_definition)
skill_id = created_skill.id

# 2. 在后续的对话中，通过API调用激活该技能
message = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1000,
    skills=[{"id": skill_id}],  # 在请求中指定要使用的技能ID
    messages=[
        {"role": "user", "content": "请分析以下Nginx日志：\n" + log_data}
    ]
)
print(message.content)

通过API，你可以实现：

• 动态技能加载 ：根据用户请求的上下文，实时决定加载哪个技能。
• 技能组合 ：在单个请求中同时激活多个技能（如先调用“数据清洗”技能，再调用“分析可视化”技能）。
• 技能版本管理 ：通过API更新技能内容，实现无缝升级。
• 构建复杂智能体 ：将多个技能作为智能体的“能力模块”，通过业务逻辑编排，完成复杂工作流。

5. 高级模式与避坑指南：打造企业级技能

在开发了数个技能并投入团队使用后，我积累了一些超越基础教程的经验和教训。

5.1 设计可组合与可维护的技能

问题： 早期我们设计了一个“周报生成”技能，里面既包含了抓取JIRA任务、又包含分析Git提交、还要格式化Word文档。技能指令变得极其冗长，且任何一个环节（如JIRA API变更）出问题，整个技能就失效了。

解决方案：遵循单一职责原则，设计技能链。

• 技能原子化： 将大技能拆分成：“JIRA数据提取器”、“Git提交分析器”、“Word文档格式化器”三个独立技能。
• 技能编排： 在更高层的“周报生成工作流”中（可以是另一个技能，或一段外部程序），按顺序调用这三个原子技能，并将上一个技能的输出作为下一个技能的输入。
• 好处： 每个技能易于维护、测试和复用。例如，“Word文档格式化器”技能可以被“会议纪要生成”技能复用。

5.2 处理技能冲突与优先级

问题： 当同时加载了“技术文档编写”技能（要求语言严谨、客观）和“营销文案创作”技能（要求语言活泼、有感染力）时，Claude的输出风格可能会产生冲突，导致不伦不类。

解决方案：在技能指令中明确上下文和优先级。

• 定义作用域： 在每个技能的YAML头信息或指令开头，清晰界定其适用场景。例如，在“技术文档编写”技能中写明：“本技能仅在用户明确要求编写API文档、技术手册等场景下生效。”
• 提供冲突解决指引： 在技能指令中加入如下的“冲突处理”章节：

  ## 与其他技能的协作
  - 如果同时激活了“创意写作”类技能，请优先遵循用户当前请求的**核心意图**。若用户说“为这个API功能写个介绍”，则应用本技能；若用户说“为这个API功能写个吸引人的博客”，则应采用创意写作技能。
  - 本技能专注于内容的准确性与结构性，格式美化请交由“文档格式化”技能处理。
  

• 利用API控制： 在通过API调用时，由你的应用程序逻辑来决定在特定对话轮次中加载哪个技能，实现精细控制。

5.3 技能的性能与成本优化

问题： 复杂的技能指令会消耗大量Tokens，特别是当技能中包含长示例、多个资源文件引用时，这会增加API调用成本并可能触及上下文长度限制。

优化策略：

1. 指令精炼： 反复推敲指令，用最简洁的语言表达规则。多用“要/不要”的肯定句，少用复杂的条件从句。
2. 示例择优： 选择最具代表性、最能说明问题的1-2个示例，而非罗列所有情况。示例的目的是“示范”，而非“枚举”。
3. 外部化资源： 对于大型的参考数据、模板文件，不要将其内容全部写入 SKILL.md 。而是将其放在 resources/ 目录下，在指令中教会AI如何“引用”或“模仿其结构”。例如：“生成报告时，请遵循 resources/report_template.md 中定义的章节结构和标题层级。”
4. 动态技能加载： 不要在所有对话中默认加载所有技能。根据对话历史或用户意图，动态地通过API添加或移除技能，保持上下文清爽。

5.4 技能测试与迭代的实战流程

创建一个技能不是一蹴而就的。我团队的流程如下：

1. 原型测试： 在Claude.ai网页端直接上传技能ZIP包，用少量典型用例进行人工对话测试。快速验证技能的核心逻辑是否跑通。
2. 单元测试集： 为技能创建一份测试用例文档（例如 test_cases.md ），包含各种边界情况、错误输入和期望输出。用这份文档系统性地检验技能。
3. A/B测试（针对重要技能）： 如果某个技能用于替代人工流程，可以设计A/B测试。将相同的任务分别交给“应用技能的Claude”和“未应用技能的Claude”（或原有人工），对比结果的质量、效率。
4. 收集反馈与迭代： 将技能分享给早期用户，收集他们在使用中遇到的困惑、错误或惊喜。这些反馈是优化技能指令最宝贵的材料。技能版本号（如 version: 1.1.0 ）在此刻就派上用场了。

6. 从开源技能中汲取灵感：逆向工程优秀案例

回到 anthropics/skills 仓库，我们如何像阅读优秀代码一样，从这些开源技能中学习高级技巧？以文档处理类技能为例，我们可以进行“逆向工程”。

学习点1：复杂任务的分解艺术 打开 skills/pdf 中的一个技能，你会发现它绝不会写“从PDF中提取所有信息”。相反，它可能会定义多个子任务：

• “识别PDF中的文本层和图像层”
• “提取并结构化文档元数据（作者、标题）”
• “识别表格区域并转换为Markdown表格”
• “解析文档层级结构（标题、段落）” 这教会我们，面对复杂任务时，在技能指令中将其分解为AI可以逐步执行的子步骤，成功率会大大提升。

学习点2：处理模糊性与提供备选方案 在 skills/docx 的技能中，你可能会看到这样的指令：“如果无法确定标题的准确级别，优先根据字体大小和加粗程度进行推断，并在输出中备注‘层级为推断结果’。” 这体现了对现实世界数据不完美的包容性设计。好的技能不是假设输入完美，而是教导AI如何处理不完美。

学习点3：利用外部规范与模式 许多技术类技能会引用外部标准。例如，一个“生成OpenAPI规范”的技能，其指令可能会包含：“确保输出的YAML符合OpenAPI 3.0.3规范。关键字段如 openapi 、 info 、 paths 必须存在且结构正确。可参考 resources/example-openapi.yaml 。” 这相当于让AI“站在巨人的肩膀上”，利用已有的行业标准来保证输出质量。

我个人在开发技能时，会经常浏览这个仓库，不是为了复制代码，而是为了学习Anthropic的工程师是如何将模糊的人类需求，转化为清晰、可执行、健壮的AI指令的。这种“技能思维”，是比任何具体技术细节都更重要的收获。

技能系统的出现，标志着一个转折点：AI应用开发正从“如何调用模型”转向“如何教导模型”。 anthropics/skills 仓库为我们提供了教导所需的语言、范例和工具。真正的挑战和乐趣，在于将你所在领域的专业知识，通过一个个精心设计的技能，转化为AI可以理解和执行的稳定能力。这个过程本身，就是对自身知识体系的一次深度梳理和固化。当你成功创建出第一个被团队频繁使用、真正产生价值的技能时，你会体会到这种“授AI以渔”的独特成就感。