Claude Agent Skills 深度解析：架构设计与实践指南

发表于 2025-12-27 更新于 2026-01-09 分类于 6-AI ， 2_工具阅读次数： Waline：本文字数： 4.4k 阅读时长 ≈ 4 分钟

Claude Agent Skills 将 Claude 从纯对话模型升级为可调用外部工具的智能代理。通过预先定义的工具描述，Claude 能够根据任务需求自主决定何时查询天气、操作电脑、检索数据库或执行其他具体操作。

graph TD
    A["用户请求(User Input)"] --> B["Claude 大脑(核心决策层/Planner)"]
    
    subgraph "Claude 决策闭环"
        B --> C{"是否需要工具?(Reasoning)"}
        C -- "是" --> D["选择技能/构造参数(Tool Call)"]
        C -- "否" --> E["直接回答(Direct Response)"]
    end

    subgraph "执行与反馈层"
        D --> F["外部环境/工具箱(Tools Environment)"]
        F --> G["API 调用(查天气/搜数据库)"]
        F --> H["Computer Use(操作鼠标/键盘)"]
        F --> I["代码解释器(运行 Python)"]
        
        G --> J["执行结果(Observation)"]
        H --> J
        I --> J
    end
    
    J --> B
    E --> K["最终输出给用户(Final Output)"]

    style B fill:#f9f,stroke:#333,stroke-width:2px
    style F fill:#ccf,stroke:#333,stroke-width:2px

1. 核心概念

1.1 定义与架构

Claude Agent Skills 是让 Claude 模型理解并调用外部工具的结构化能力组合。一个 Skill 本质上是包含 SKILL.md 文件的文件夹，通过 YAML frontmatter 定义元数据，通过 Markdown 正文提供详细指令。

核心元数据包括：

name: 技能的唯一标识，必须与文件夹名一致
description: 功能描述，Agent 决策是否激活此技能的关键依据

Agent Skills 采用三层按需加载机制：

第一层：元数据层 (Metadata - LOD-0)
Agent 启动时仅加载所有 Skills 的 name 和 description，消耗极少 Token 即建立全局能力图谱。

第二层：核心指令层 (Core Instructions - LOD-1)
当用户请求与某个 Skill 的 description 匹配时，Agent 完整加载该 SKILL.md 文件，获取详细操作指南。

第三层：支持资源层 (Supporting Resources - LOD-2)
仅在执行需要时才访问外部脚本（scripts/）或参考文档（references/）。执行脚本时，仅输出结果进入上下文，代码本身不占用 Token。

这种分层设计使得 Skills 在扩展性与成本控制之间取得平衡。参考官方示例：SKILL.md

1.2 技术要点

XML 标签偏好

Claude 在 System Prompt 中优先使用 XML 标签（如 <thinking>...</thinking>），而非 JSON。即使官方提供 Tool Use API，在提示词中使用 XML 包裹指令仍能提升推理质量。

思维链可见性

Claude 3.5+ 的 Agent 模式会输出大量 CoT（Chain of Thought）。不应屏蔽这些输出，虽然它们是模型内部的推理过程，但截断会显著降低执行成功率。

1.3 常见错误

工具描述过于模糊

错误示例：工具名 get_data，描述 获取数据
正确示例：工具名 get_stock_price_by_ticker，描述 根据股票代码（如 AAPL）获取当前美股实时价格，单位为美元

在定义工具时，description 字段的重要性甚至超过 parameters。

反馈循环断裂

必须将工具执行结果封装为新的 Message，追加到对话历史中返回给 Claude。例如查询天气得到 25 度，需要让 Claude 基于该结果生成最终回复。

工具过载

一次性加载过多工具（如 50 个）会导致 Agent 注意力分散，增加选错工具或产生幻觉的风险。建议控制在合理数量范围内。

1.4 信息分层设计哲学

Agent Skills 的三层架构借鉴了游戏引擎的 LOD（Level of Detail）技术，通过递进式加载优化性能。

LOD-0：极远视野

类似游戏中远处地平线的低多边形模型，仅勾勒基本轮廓。Agent 启动时仅扫描 Skills 的名称和描述，快速建立能力认知。

LOD-1：中距离细节

飞近营地后可见哨塔、篝火、敌人数量和类型。Agent 加载 Skill 核心文档，足以制定完整行动计划。

LOD-2：近距离精确

潜行至边缘时可见武器样式、纹理细节。Agent 按需查阅最详尽的原始信息，支持精准操作。

执行流程：

Agent收到任务  
    ↓  
1. 扫描所有资源 LOD-0，快速了解全局能力  
    ↓  
2. 识别出 3-5 个可能相关的资源  
    ↓  
3. 按需加载这些资源的 LOD-1，制定核心计划  
    ↓  
4. 在 LOD-1 层面完成大部分任务（80-90%）  
    ↓  
5. 仅在需要时，通过工具从 LOD-2 按需获取精确数据（10-20%）

分形架构
三层系统是可递归嵌套的：

向下展开：LOD-2 的原始信息内部可能包含另一个完整的三层系统
向上收起：完整三层系统对更高层观察者可抽象为单一 LOD-0 元素

2. 技术对比

2.1 Vs MCP

模型上下文协议 (MCP) 是一个开放协议，允许 Claude Code 连接到外部工具和服务，访问外部数据源，执行外部操作，扩展 Claude Code 的能力。

概念类比：Claude 作为操作系统

MCP (Model Context Protocol)：标准接口规范（如 USB-C 或 OpenAPI Spec），定义数据源如何暴露数据、工具如何被调用。不直接提供功能。
Agent Skills：基于 MCP 的具体功能实现。读取日历、发送 Slack 消息、查询数据库的实际代码逻辑。

2.2 Vs Agent

Agent Skills：静态能力，如 tools.calculator() 或 database.query() 函数。等待被调用的能力节点。
Agent：拥有自主决策能力的实体。包含 LLM（大脑）、Memory（记忆）、Planning（规划）及 Skills 调用权限。运行 while(true) 循环，接收任务、思考、调用 Skills。

2.3 Vs n8n

n8n：确定性流程引擎。逻辑通常是预定义的：Trigger -> Step A -> If true -> Step B else Step C。适用于固定 ETL 任务或自动化操作。
Agent Skills：非确定性场景。由 LLM 决定调用时机和参数，执行路径依赖对话上下文，在 Runtime 动态决策。

2.4 生态定位

Skills 会替代 MCP 和 n8n 吗？

与 MCP 关系：2026 年的 Agent Skills 底层连接通过 MCP 实现。MCP 是基础设施层，Skills 是应用层。MCP 普及度越高，Skills 生态越繁荣。
与 n8n 关系：企业级应用要求 100% 逻辑一致性，n8n 等确定性工具不会消失，而是演进为 “Tools for Agents”。

3. 实践指南

3.1 基础使用

1 2	# 安装 Skills 仓库 openskills install anthropics/skills

安装成功后，Cursor、Trae 等工具的文件管理区会出现 .claude/skills 目录。

1 2	# 同步 Skills 到项目配置 openskills sync

该项目下创建的 AGENTS.md 文件将作为 Coding Agent 的 Skill 调用指导。

调用方式：

自动调用：Agent 根据 description 自主选择
手动调用：在提示词中显式指定 Skill 名称

3.2 Opencode 配置

配置路径：

项目配置：.opencode/skill/<name>/SKILL.md
全局配置：~/.config/opencode/skill/<name>/SKILL.md
Claude 兼容（项目）：.claude/skills/<name>/SKILL.md
Claude 兼容（全局）：~/.claude/skills/<name>/SKILL.md

符号链接配置示例：

rm -rf ~/.claude/skills
rm -rf ~/.config/opencode/skill

ln -s ~/workspace/skills ~/.claude/skills
ln -s ~/workspace/skills ~/.config/opencode/skill

3.3 开发实践

如何开发天气查询 Skill？

在 .claude/skills/weather/ 创建 SKILL.md
编写 YAML 元数据（name, description, category 等）
在 Markdown 正文中定义：
- Skill 功能说明
- 参数规范
- 执行步骤
- 错误处理逻辑
在 scripts/ 目录下放置调用天气 API 的实际代码
运行 openskills sync 更新配置

参考： https://github.com/unix2dos/skills/tree/main/query-weather

4. 好用的 Skills

Frontend Design https://github.com/anthropics/claude-code/tree/main/plugins/frontend-design
API Design Principles https://github.com/wshobson/agents/tree/main/plugins/backend-development/skills/api-design-principles
Postgres Table Design https://github.com/wshobson/agents/blob/main/plugins/database-design/skills/postgresql/SKILL.md