Anthropic Agent Skills 技术解析与实践

前言

Anthropic 在 2025 年 10 月推出了 Agent Skills 框架，这是一个让通用 AI 获得专业技能的机制。本文通过分析这个框架的设计理念，并以 Litho 为例展示如何构建实用的 Agent Skill。

Agent Skills 的核心机制

渐进式信息披露（Progressive Disclosure）设计

根据 Anthropic 官方文档，Agent Skills 的核心创新在于采用了"渐进式信息披露"机制。这个概念虽然源自用户体验设计，但在 AI 系统中有了新的应用维度。
理解 Progressive Disclosure

传统软件中的 Progressive Disclosure 指的是界面设计策略：先展示基本信息，用户有需求时再展示详细功能。在 Agent Skills 中，这个概念被迁移到了认知层面：

三层信息架构详解

官方文档详细说明了这种分层设计的技术实现：
第一层：Metadata 触发层

1. ---
2. name: your-skill-name
3. description: "Clear description of when and how to use this skill"
4. ---

复制代码

• 技术细节：这个 metadata 在 agent 启动时就被加载到系统 prompt 中
  
• 工作原理：Claude 在处理每个请求时，都会检查这些 metadata，判断是否需要激活某个技能
  
• 中文用户的优势：description 可以用中文写，更准确地表达使用场景，帮助中文用户触发正确的技能
  

第二层：Core Instructions 核心指令层

1. # 主 SKILL.md 文件内容
2. ## 工作流程
3. ## 关键决策点  
4. ## 基本使用方法
5. ## 常见模式

复制代码

• 加载时机：只有当 Claude 确认这个技能相关时，才会主动读取完整的 SKILL.md
  
• Context 管理：这一步消耗 tokens，所以内容需要精炼（官方建议保持在合理长度）
  
• 设计要点：应该包含 80% 常见场景的处理逻辑
  

第三层：Reference Materials 参考资源层
以Litho为例，完整描述见 SKILL.md

• 按需加载：Claude 只在实际需要特定细节时才读取这些文件
  
• 无限扩展：理论上可以有无限多的辅助文件，因为不会占用基础 context
  
• 模块化优势：可以将不常使用的内容独立出来，降低主要文档的复杂性
  

Context Window 优化的实际效果

官方文档用了一个具体的例子说明这个过程：

• 初始状态（假设 context 为 4000 tokens）：
  
  
  
  • 系统 prompt：1500 tokens
    
  • 用户消息：200 tokens
    
  • 已加载的所有 skill metadata：约 800 tokens（假设有 10 个技能）
    
  • 剩余可用空间：1500 tokens
    
  
  
• 触发 skill 后：
  
  
  
  • Claude 判断需要某个 skill
    
  • 调用 bash 工具读取该 skill 的 SKILL.md（增加 300 tokens）
    
  • 剩余可用空间：1200 tokens
    
  • 如果还需要特定细节，再调用 bash 工具读取辅助文件（增加 100 tokens）
    
  • 剩余可用空间：1100 tokens
    
  
  

这种机制确保了只在真正需要时才消耗 context 空间。
文件系统即知识网络的设计理念

Agent Skills 的另一个重要设计是将文件系统映射为知识网络结构。这在官方文档中被称为"composable resources"（可组合资源）。
文件组织的设计

参考 the agent skill of litho

1. skill-directory/
2. ├── SKILL.md              # 知识根节点
3. ├── configuration.md      # 配置知识子图
4. ├── examples/             # 实例知识群
5. │   ├── basic-usage.md
6. │   ├── advanced-patterns.md
7. │   └── troubleshooting-examples.md
8. ├── tools/               # 工具知识群
9. │   ├── setup.sh         # 自动化工具
10. │   ├── validate.py      # 验证工具
11. │   └── deploy.yml       # 部署工具
12. └── integration/         # 集成知识群
13.     ├── ci-cd.md         # CI/CD 集成
14.     └── api-clients.md   # 客户端集成

复制代码

这种结构背后有几个关键理念：
1. 文件夹语义化
每个子文件夹代表特定的知识域。这不仅是物理分组，更是概念的分层。Anthropic 的设计让 Claude 能够通过路径语义理解内容的分类。
2. 文件名即导航信号
文件名本身就是重要的导航线索：

• basic-setup.md 暗示这是入门内容
  
• advanced-config.py 暗示这是高级配置工具
  
• emergency-recovery.sh 暗示这是紧急恢复程序
  

3. 目录深度的信息密度控制
较深的层次通常包含：

• 更专业的细节
  
• 更少使用的功能
  
• 更强的上下文依赖
  

可发现性与自文档化原则

官方强调了"self-documenting"的重要性：

• 从外向内的可预测结构
  

参考 the agent skill of litho
用户和 Claude 都应该能够推断在什么地方找到特定类型的信息：

1. skill-name/
2. ├── SKILL.md           # 第一个要读的文档
3. ├── configuration.md   # 配置相关查询会指向这里  
4. ├── troubleshooting.md  # 排错时会指向这里
5. └── scripts/           # 需要执行时会指向这里

复制代码

• 内部引用网络的建立
  在 SKILL.md 中的引用不是简单的链接，而是建立知识图谱的边：
  

1. ## Litho Agent Skill 分析
3. 接下来拿[Litho](https://github.com/sopaco/deepwiki-rs)这个开源项目的Agent Skill实现范例举例
5. ### 首先 介绍一下Litho
7. Litho 是一个基于 Rust 的跨平台、跨技术栈项目知识生成引擎，核心功能是将源代码自动生成Agent可理解的结构化知识。在 Agent Skill 场景下，它的主要价值是：
9. 1. **降低 Coding Agent 的认知负担**
10. 2. **提供预处理的代码知识图谱**
11. 3. **减少推理过程中的 context 消耗**
12. 4. **提高代码理解效率**
14. 具体来说，当一个 Coding Agent 需要操作复杂代码库时：
16. - **传统方式**：AI 需要直接分析大量源代码文件，消耗大量 tokens 并占用推理资源
17. - **Litho 增强方式**：AI 先加载 Litho 生成的架构文档，快速建立系统认知，再针对具体模块进行深度分析
19. ### Skill 结构设计
21. #### Metadata 设计
23. ```yaml
24. name: deepwiki-rs
25. description: "Code analysis tool that pre-generates structured documentation to help AI agents understand complex codebases efficiently, reducing context overhead and improving coding assistance quality."

复制代码

描述突出了在 Agent 使用场景下的价值：降低上下文开销，提高效率。
核心工作流程设计

主 SKILL.md 保持了简洁的结构（87 行）：

1. ## Use Cases
3. 1. **Codebase Pre-analysis**: Generate architecture overview before coding tasks
4. 2. **Context Optimization**: Reduce tokens needed for large project understanding  
5. 3. **Module Mapping**: Understand relationships and dependencies quickly
7. ## Command Patterns
9. - Quick overview: `deepwiki-rs -p ./src --skip-preprocessing`
10. - Full analysis: `deepwiki-rs -p ./project --model-efficient gpt4-mini --model-powerful gpt4-o`

复制代码

辅助文件的按需引用

详细的配置和技术细节移到独立文件：

实际工作流程示例

官方文档提供了一个完整的 PDF 处理技能示例来展示这个机制。我们用 Litho 的场景来展示类似的工作流程：
场景：AI 代理需要为现有项目添加新功能

• 初始请求分析（用户："在项目中添加用户认证功能"）
  1. Context: 4000 tokens
  2. - 系统提示: 1500 tokens
  3. - 所有技能 metadata: 800 tokens
  4. - 用户请求: 50 tokens
  5. - 剩余: 1650 tokens

  复制代码
• 技能激活（Claude 检测到 "项目"、"添加功能" 触发了 Litho skill）
  1. Claude 评估：这个任务需要理解项目架构， Litho skill 相关
  2. 执行：bash -c "read_file ./skill-litho/SKILL.md"

  复制代码
• 加载核心指令（Litho SKILL.md 内容载入）
  1. Context 增加: 300 tokens
  2. 剩余: 1350 tokens
  4. Claude 获取的信息：
  5. - 使用决策树
  6. - 基本命令模式
  7. - 关键注意事项

  复制代码
• 深度需求分析（Claude 发现需要了解特定模块的配置）
  1. Claude 决策：要添加认证功能，需要了解项目的配置结构
  2. 执行：bash -c "read_file ./skill-litho/configuration.md#project-config"

  复制代码
• 获取专业细节（加载配置指南）
  1. Context 增加: 150 tokens
  2. 剩余: 1200 tokens
  4. Claude 获取：项目配置的具体参数和最佳实践

  复制代码
• 执行工具调用（需要生成项目分析）
  1. Claude 决策：先分析现有架构再设计认证集成
  2. 执行：bash -c "deepwiki-rs -p ./src --skip-preprocessing -o ./temp-analysis"

  复制代码
• 基于分析结果进行设计（使用生成的文档进行推理）
  1. [/code]
  2. [/list]Claude 现在有：
  3. [list]
  4. [*]完整的 Litho 使用指导（来自 SKILL.md）
  5. [*]详细的配置选项（来自 configuration.md）
  6. [*]实时的项目架构分析（来自 Litho 输出）
  7. [/list]基于这些信息，Claude 可以设计合适的认证集成方案
  8. [code]这个流程展示了 Agent Skills 如何让 AI 在保持高效的同时，获得深度专业能力。
  10. ### 技术实现的关键细节
  12. #### Bash 工具的智能调用机制
  14. 官方文档特别强调了 Agent Skills 与 Bash 工具的协作方式。这不仅仅是一个简单的文件读取，而是一个智能的决策过程：
  16. **Claude 的决策逻辑**：
  17. ```python
  18. # Claude 内部的简化决策流程
  19. def should_use_skill(user_request, available_skills):
  20. # 1. 分析请求内容，识别关键词和意图
  21. intent = analyze_intent(user_request)
  22. keywords = extract_keywords(user_request)
  24. # 2. 匹配技能 metadata
  25. relevant_skills = []
  26. for skill in available_skills:
  27.      if matches_keywords(skill.description, keywords):
  28.          relevance_score = calculate_relevance(intent, skill.description)
  29.          if relevance_score > threshold:
  30.              relevant_skills.append((skill, relevance_score))
  32. # 3. 选择最相关的技能
  33. if relevant_skills:
  34.      return max(relevant_skills, key=lambda x: x[1])[0]
  35. return None

  复制代码
  文件读取的智能策略：
  1. # Claude 实际执行的命令模式
  2. # 1. 基础技能激活
  3. read_file ./skill-name/SKILL.md
  5. # 2. 按需深度加载
  6. read_file ./skill-name/configuration.md#specific-section
  8. # 3. 工具执行（如果需要）
  9. bash -c "./skill-name/scripts/automation.sh --params"
  11. # 4. 结果验证
  12. read_file ./skill-name/validation-report.md

  复制代码
  安全性和稳定性考虑
  
  官方文档详细讨论了安全性问题，这对中文用户特别重要：
  恶意技能的防护机制：
  
  
  
  • 代码执行限制
    
    
    
    • Agent Skills 可以运行脚本，但需要用户明确授权
      
    • 系统会限制脚本的权限范围
      
    • 网络访问需要额外的安全检查
      
    
    
  • 内容审计要求
    1. 官方建议的审计检查清单：
    2. ✓ 检查所有可执行文件的内容
    3. ✓ 验证网络连接的目标地址
    4. ✓ 确认文件系统的访问权限
    5. ✓ 测试异常情况的处理

    复制代码
  中文用户的特殊注意点：
  
  
  
  • 文件路径可能包含中文字符，需要确保脚本能正确处理
    
  • 错误消息可能需要本地化处理
    
  • 配置文件中的中文注释不能影响程序解析
    
  错误处理和回退机制
  
  官方文档描述了多层错误处理：
  第一层：文件访问错误
  1. # 如果 SKILL.md 读取失败
  2. read_file ./skill-name/SKILL.md
  3. # 错误响应：File not found
  4. # Claude 回退：使用通用知识 + 建议用户检查技能安装

  复制代码
  第二层：内容解析错误
  1. # 如果 SKILL.md 格式错误
  2. # Claude 检测：缺少必需的 YAML frontmatter
  3. # 回退策略：忽略该技能，继续处理其他任务

  复制代码
  第三层：执行失败处理
  1. # 如果脚本执行失败
  2. bash -c "./skill-name/script.sh"
  3. # 错误捕获：检查退出码和标准错误输出
  4. # 智能分析：基于错误信息提供解决方案

  复制代码
  技能与工具链的集成模式
  
  与现有开发工具的协调
  
  官方文档强调了 Agent Skills 需要与传统工具链和谐共存：
  1. IDE 集成模式
  1. // VS Code 扩展示例
  2. {
  3.   "anthropic.skills": {
  4.     "enabled": true,
  5.     "skillsPath": "./skills/",
  6.     "autoLoad": ["litho", "testing", "security"],
  7.     "workspaceContext": {
  8.       "projectType": "rust",
  9.       "buildSystem": "cargo"
  10.     }
  11.   }
  12. }

  复制代码
  2. CI/CD 流水线集成
  1. # GitHub Actions 中的技能使用
  2. - name: Code Analysis with Skills
  3.   uses: anthropic/skills-action@v1
  4.   with:
  5.     skills: "litho,-security-linter"
  6.     project-path: "./src"
  7.     output-format: "markdown"
  8.   env:
  9.     LITHO_API_KEY: ${{ secrets.LITHO_API_KEY }}

  复制代码
  技能间的协作模式
  
  不同技能可以组成技能链（Skill Chain）：
  
  
  
  每个技能可以：
  
  
  
  • 将输出作为下一个技能的输入
    
  • 共享临时文件和缓存
    
  • 协调执行顺序和依赖关系
    
  性能优化考虑
  
  在 Agent Skill 使用场景下，Litho 的配置重点考虑：
  
  
  
  • 响应速度：使用高效模型快速生成基础架构
    
  • 信息密度：生成的文档结构化程度高，便于 AI 快速提取关键信息
    
  • 增量更新：支持 diff 模式，只处理变更部分
    
  • 模块化输出：按功能域分割文档，便于按需加载
    
  可执行脚本的价值
  
  Litho Skill 包含了两个关键脚本：
  quick-start.sh
  1. #!/bin/bash
  2. # 为 AI 代理快速设置代码分析环境
  3. detect_project_structure() {
  4.     # 识别项目类型和结构
  5.     # 选择合适的分析参数
  6. }
  8. setup_optimized_config() {
  9.     # 根据 agent 使用场景优化配置
  10.     # 设置合适的模型组合
  11. }

  复制代码
  ci-integration.sh
  1. #!/bin/bash
  2. # 自动化 CI/CD 中的文档更新
  3. generate_diff_docs() {
  4.     # 只对变更部分重新生成文档
  5.     # 保持文档与代码同步
  6. }

  复制代码
  这些脚本让其他 AI Agent 可以自动化地调用 Litho 的能力，而不是依赖手动操作。
  构建高质量技能的设计原则
  
  官方推荐的技能设计模式
  
  根据 Anthropic 官方文档，好的 Agent Skill 应该遵循几个核心设计原则：
  1. 边界清晰原则（Clear Boundaries）
  
  官方强调每个技能应该有明确的应用边界，避免"大而全"的设计：
  1. # ❌ 官方不推荐的例子
  2. name: development-helper
  3. description: "All-purpose development assistance for everything"
  5. # ✅ 官方推荐的例子  
  6. name: rust-async-patterns
  7. description: "Rust async programming patterns for high-performance backend services. Use when Claude needs to implement async/await, tokio integration, or performance optimization in Rust."

  复制代码
  关键要点：
  
  
  
  • 描述中应该明确"什么时候使用"
    
  • 避免重叠的功能范围
    
  • 保持技能的单一职责
    
  2. 可发现性设计（Discoverability Design）
  
  官方文档详细说明了如何让 Claude 能够准确识别和使用技能：
  Metadata 优化技巧：
  1. # 优化前
  2. description: "Documentation generation tool"
  4. # 优化后（官方建议模式）
  5. description: "Code analysis tool that generates architectural documentation. Use when Claude needs to: 1) understand codebase structure, 2) identify module dependencies, 3) prepare for refactoring, 4) create technical specifications."

  复制代码
  关键词策略：
  
  
  
  • 在 description 中包含核心关键词
    
  • 使用数字或项目符号明确应用场景
    
  • 提供具体的触发条件
    
  3. 渐进式复杂度（Progressive Complexity）
  
  官方推荐的内容组织方式：
  1. # SKILL.md 的内容分层
  3. ## 第一层：核心概念（所有用户都需要）
  4. - 基本使用方法
  5. - 关键决策点
  6. - 常见模式
  8. ## 第二层：深入实践（有经验的用户）
  9. - 高级配置选项
  10. - 性能优化技巧
  11. - 故障排除方法
  13. ## 第三层：专家级内容（按需引用）
  14. - 内部实现原理
  15. - 扩展开发指南
  16. - 贡献者文档

  复制代码
  实现质量保证的官方建议
  
  测试驱动的技能开发
  
  官方文档提出了一个完整的测试框架：
  1. # skills-testing/
  2. ├── unit-tests/              # 功能单元测试
  3. │   ├── test-basic-workflow.py
  4. │   ├── test-error-handling.py
  5. │   └── test-integration.py
  6. ├── integration-tests/       # 集成测试
  7. │   ├── test-context-usage.py
  8. │   └── test-tool-chaining.py
  9. ├── performance-tests/      # 性能测试
  10. │   ├── test-response-time.py
  11. │   └── test-context-efficiency.py
  12. └── user-scenario-tests/    # 用户场景测试
  13.     ├── test-new-user.json
  14.     └── test-expert-user.json

  复制代码
  关键测试指标：
  
  
  
  • 响应时间：技能激活到提供指导的时间 < 2秒
    
  • Context 效率：技能相关内容的 token 密度 > 常规文档
    
  • 任务成功率：在标准测试场景下 > 90%
    
  持续监控和迭代机制
  
  官方建议的监控体系：
  1. # 技能性能监控
  2. class SkillMonitor:
  3.     def track_usage_patterns(self):
  4.         return {
  5.             'activation_frequency': self.count_activations(),
  6.             'context_consumption': self.measure_token_usage(),
  7.             'task_success_rate': self.calculate_success_rate(),
  8.             'user_satisfaction': self.collect_feedback()
  9.         }
  10.    
  11.     def identify_improvement_areas(self):
  12.         if self.context_consumption > threshold:
  13.             return "Consider optimizing content density"
  14.         if self.task_success_rate < 0.8:
  15.             return "Review instruction clarity"

  复制代码
  可组合的 AI 工作流
  
  官方文档展示了技能组合的潜力：
  1. 典型 Rust 开发工作流：
  2. ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
  3. │  Code Req   │───▶│ Litho Skill │───▶│ Rust Skill  │───▶│ Test Skill  │
  4. │  Analysis   │    │  (架构分析)  │    │  (代码实现)  │    │  (测试生成)  │
  5. └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
  6.        │                   │                   │                   │
  7.        ▼                   ▼                   ▼                   ▼
  8.    需求理解           快速建立架构认知     生成符合 Rust     自动化测试
  9.    和拆解             系统整体视图        最佳实践的代码     用例生成

  复制代码
  这种组合让每个技能都能发挥最大价值，形成完整的开发闭环。
  构建建议
  
  基于官方最佳实践的设计原则
  
  根据 Anthropic 官方文档，构建高质量技能应该遵循：
  
  
  
  • 分层信息组织：遵循 Progressive Disclosure 原则，优化 Context 使用效率
    
  • 边界明确：每个 Skill 专注解决特定类型的问题，避免功能重叠
    
  • AI 代理优先：内容设计优先考虑 AI 代理的使用场景，而非人类直接阅读
    
  • 结构化输出：生成的信息应该便于其他 AI 代理解析和使用
    
  • 提供执行接口：包含可执行脚本，便于自动化调用和工具链集成
    
  推荐的文件组织结构
  
  1. your-skill/
  2. ├── SKILL.md                # 核心工作流程（建议 50 ~ 150个token）
  3. ├── configuration.md        # 详细配置参数和环境设置
  4. ├── troubleshooting.md      # 常见问题和解决方案
  5. ├── examples/               # 分层使用案例
  6. │   ├── basic-usage.md
  7. │   ├── advanced-patterns.md
  8. │   └── integration-examples.md
  9. ├── scripts/                # 自动化工具
  10. │   ├── setup.sh           # 环境配置
  11. │   ├── validate.py        # 功能验证
  12. │   └── deploy.yml         # 部署自动化
  13. └── integration/            # 与其他系统的集成
  14.     ├── ci-cd.md           # 持续集成配置
  15.     └── api-clients.md     # API 客户端示例

  复制代码
  未来，随着 AI 在开发流程中的深度集成，Agent Skills 可能成为连接人类专业知识和 AI 执行能力的关键桥梁。掌握这项技术，将帮助团队在 AI 时代保持技术领先优势。
  参考资料：
  
  
  
  • Anthropic Agent Skills 官方文档
    
  • Litho 项目地址
    
   
  
  
  
  本作品由姜萌创作，采用知识共享署名 2.5 中国大陆许可协议进行许可。
  来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
  免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！