Tool集成指南：让Skill真正”能干实事”
学会了写Skill，你可能已经发现一个问题：Skill只能”动嘴皮子”，但实际应用场景中，AI需要：
- 读写文件
- 执行命令
- 查天气
- 发邮件
- 查数据库
这些都需要调用外部工具。这篇文章就是来解决这个问题的。
0. 先来理解：Tool到底是什么
0.1 从一个问题开始
你写了一个”文件助手”Skill：
instructions: |
你是一个文件助手，可以帮助用户读写文件。但实际用户说”帮我读取 config.json 文件”，AI只能回答：
“好的，我来帮你读取 config.json 文件。但是我没有读取文件的能力…”
这就很尴尬了。
Tool就是来解决这个问题的：Tool让Skill具备了”动手能力”。
0.2 Tool在系统中的位置
┌─────────────────────────────────────────────────────────────┐
│ Skills系统 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Skill A │ │ Skill B │ │ Skill C │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ ↓ ↓ ↓ │
│ ┌──────┴─────────────────────────────────────────┐ │
│ │ Tool 调用层 │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │文件系统 │ │网络API │ │数据库 │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ │ │
│ └──────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
0.3 Tool vs Skill：有什么区别
| 方面 | Skill | Tool |
|---|---|---|
| 本质 | 行为定义的配置 | 具体功能的实现 |
| 层次 | 高层（告诉AI做什么） | 底层（实际执行操作） |
| 调用方式 | AI主动选择 | Skill调用 |
| 独立性 | 可独立运行 | 依赖外部系统 |
关系：Skill调用Tool，Tool执行具体操作。
1. MCP工具集成
1.1 MCP是什么
**MCP（Model Context Protocol）**是一种开放标准协议，用于在AI系统和外部工具之间建立标准化的通信接口。
简单说：MCP就是让AI调用工具的”普通话”。
不管你是用文件系统、搜素引擎、还是数据库，只要支持MCP协议，AI就能用统一的方式调用它们。
1.2 MCP的核心组件
┌─────────────────────────────────────────────────────────────┐
│ MCP架构 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ │
│ │ MCP Client │ ← 你的AI应用 │
│ └──────┬──────┘ │
│ │ │
│ ↓ MCP协议 │
│ │ │
│ ┌──────┴──────┐ │
│ │ MCP Server │ ← 工具提供者 │
│ └──────┬──────┘ │
│ │ │
│ ↓ │
│ ┌──────┴──────┐ │
│ │ 真实工具 │ 文件系统、API、数据库... │
│ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
| 组件 | 说明 |
|---|---|
| MCP Server | 提供工具和服务的主机 |
| MCP Client | 连接到Server的客户端 |
| MCP Resources | Server提供的数据资源 |
| MCP Tools | Server提供的可调用工具 |
| MCP Prompts | 预定义的提示模板 |
1.3 在Skill中声明MCP工具
# SKILL.file-helper.md
---
name: file-helper
description: 文件操作助手
tools:
# 声明使用MCP工具
- type: mcp
name: filesystem_read
server: mcp-filesystem
description: 读取文件内容
parameters:
path:
type: string
required: true
description: 要读取的文件路径
encoding:
type: string
default: utf-8
description: 文件编码
---
# 文件操作助手
## 支持的操作
1. 读取文件内容
2. 写入文件内容
3. 创建目录
4. 列出目录内容
5. 删除文件/目录
## 使用限制
- 单次读取最大10MB
- 单次写入最大5MB
- 不支持二进制文件直接操作1.4 MCP工具权限配置
# 工具权限配置
mcp_permissions:
server: mcp-filesystem
# 允许的操作
allowed_operations:
- read
- write
- list
# 禁止的操作
denied_operations:
- delete
- execute
# 路径限制
path_restrictions:
allowed_prefixes:
- /Users/project/src
- /Users/project/tests
denied_prefixes:
- /Users/project/secrets
- /Users/project/.env
# 频率限制
rate_limits:
requests_per_minute: 60
burst_size: 101.5 MCP工具响应处理
# 响应处理配置
tool_response_handling:
success:
format: structured
fields: [result, metadata, timestamp]
error:
format: structured
fields: [error_code, error_message, details]
retry_on_codes:
- network_error
- timeout
- service_unavailable
timeout:
default: 30000
max: 60000
on_timeout: fail_with_message2. API调用集成
2.1 REST API集成
在Skill中集成REST API：
# SKILL.weather-query.md
---
name: weather-query
description: 天气查询助手
tools:
- name: query_weather
type: http_api
config:
base_url: https://api.weather.example.com
method: GET
endpoint: /v1/current
headers:
Authorization: "Bearer {api_key}"
Content-Type: application/json
query_params:
city: "{city_name}"
units: "{temperature_unit}"
response_mapping:
temperature: "$.current.temp"
humidity: "$.current.humidity"
description: "$.current.description"
error_handling:
retry:
max_attempts: 3
backoff: exponential
fallback:
on_failure: return_unknown
---
# 天气查询助手
## 使用方法
用户输入城市名称，返回当前天气信息。
## 示例
用户：今天北京天气怎么样？
AI调用工具 → 查询API → 返回：今天北京晴，气温25度...2.2 GraphQL集成
# GraphQL API配置
tools:
- name: query_graphql
type: graphql
config:
endpoint: https://api.example.com/graphql
headers:
Authorization: "Bearer {token}"
query: |
query GetUser($id: ID!) {
user(id: $id) {
id
name
email
posts {
id
title
}
}
}
variables:
id: "{user_id}"
response_mapping:
user_id: "$.data.user.id"
user_name: "$.data.user.name"
post_count: "count($.data.user.posts)"2.3 API认证管理
方式一：Bearer Token
authentication:
type: bearer_token
config:
token_source: env
env_var: WEATHER_API_KEY
refresh:
enabled: false方式二：OAuth2
authentication:
type: oauth2
config:
client_id: "{client_id}"
client_secret: "{client_secret}"
token_endpoint: https://auth.example.com/oauth/token
scopes:
- read:user
- read:data
token_storage: secure
refresh:
enabled: true
before_expiry: 300 # 提前5分钟刷新3. Function Calling（函数调用）
3.1 Function Calling是什么
Function Calling是让AI模型主动调用预定义函数的能力。不同于Tool（Tool是Skill调用），Function Calling是AI”主动思考”后决定调用哪个函数。
3.2 函数定义格式
# 在Skill中定义可调用的函数
functions:
- name: calculate
description: 执行数学计算
parameters:
type: object
properties:
expression:
type: string
description: 数学表达式，如 "2 + 3 * 4"
precision:
type: integer
description: 小数精度，默认2
default: 2
required: ["expression"]
returns:
type: object
properties:
result:
type: number
description: 计算结果
expression:
type: string
description: 原始表达式
examples:
- input:
expression: "10 / 3"
precision: 4
output:
result: 3.3333
expression: "10 / 3"3.3 函数执行流程
用户：计算 2 + 3 * 4
↓
AI理解：用户想执行数学计算
↓
AI决定：调用 calculate 函数
↓
系统验证：检查参数是否有效
↓
系统执行：执行计算逻辑
↓
返回结果：{ result: 14, expression: "2 + 3 * 4" }
↓
AI整合：把结果整合成自然语言回复
↓
用户：2 + 3 * 4 的结果是 14
3.4 函数调用安全
function_security:
# 沙箱执行
sandbox:
enabled: true
isolation_level: process
# 代码执行限制
code_execution:
allowed_languages: []
blocked_patterns:
- __import__
- eval
- exec
- os.system
# 资源限制
resource_limits:
max_execution_time: 5000
max_memory_mb: 128
max_output_size: 10485764. 内置工具 vs 自定义工具
4.1 常见的内置工具
大多数Skills系统会内置一些常用工具：
| 工具名 | 功能 | 使用场景 |
|---|---|---|
file_reader | 读取文件 | 代码审查、文档处理 |
file_writer | 写入文件 | 生成报告、保存结果 |
terminal | 执行命令 | 运行脚本、编译代码 |
web_search | 网络搜索 | 查资料、获取信息 |
web_fetch | 获取网页内容 | 爬取数据、分析网页 |
clipboard | 读写剪贴板 | 复制粘贴内容 |
4.2 自定义工具的开发
如果内置工具不满足需求，需要开发自定义工具：
# 自定义工具注册
custom_tools:
- name: my_custom_tool
description: 我的自定义工具
category: 业务工具
# 参数定义
parameters:
input_data:
type: string
required: true
options:
type: object
required: false
# 实现位置
implementation:
language: javascript
path: ./tools/my-custom-tool.js开发步骤：
- 在frontmatter的
tools字段中声明 - 在instructions中描述如何使用
- 提供工具的代码实现
5. 外部服务集成
5.1 Webhook集成
Webhook允许外部系统主动向Skills系统推送数据：
# Webhook配置
webhook:
endpoint: /webhook/github
methods: [POST]
authentication:
type: signature
header: X-Hub-Signature-256
secret: "{webhook_secret}"
events:
- push
- pull_request
- issue
payload_transform:
github_event: "{event_type}"
repository: "{repository.full_name}"
action: "{action}"5.2 事件驱动集成
# 事件系统配置
event_system:
type: pubsub
config:
broker: redis
channel_prefix: skills_events
subscriptions:
- event: user.message
handler: SKILL.message-handler
- event: data.updated
handler: SKILL.data-sync
- event: alert.triggered
handler: SKILL.alert-manager
event_format:
schema_version: "1.0"
required_fields: [event_id, event_type, timestamp, data]5.3 异步任务处理
# 异步任务配置
async_tasks:
queue: redis
config:
host: localhost
port: 6379
db: 0
task_types:
- name: long_running_analysis
handler: SKILL.analysis-executor
timeout: 300000 # 5分钟
retry: 3
- name: batch_processing
handler: SKILL.batch-processor
timeout: 600000 # 10分钟
retry: 16. 工具注册与管理
6.1 工具注册表
# 工具元数据存储
tool_registry:
tools:
- id: tool-001
name: file_reader
category: filesystem
version: 1.2.0
owner: platform-team
status: active
capabilities:
- read_text
- read_binary
metadata:
created: 2026-01-01
updated: 2026-04-01
usage_count: 15420
- id: tool-002
name: web_search
category: network
version: 2.1.0
owner: search-team
status: active
capabilities:
- search
- fetch6.2 工具发现机制
# 工具发现配置
tool_discovery:
methods:
- type: registry
description: 从中央注册表发现
- type: file_scan
description: 扫描指定目录
paths:
- ./skills/tools
- ./shared/tools
- type: mcp_discovery
description: 从MCP服务器发现
search:
by_name: true
by_category: true
by_tag: true
by_capability: true6.3 工具版本管理
version_management:
strategy: semantic
deprecation:
notice_period: 30d
graceful_shutdown: true
migration_assistance: true
compatibility:
check_on_load: true
warn_on_version_mismatch: true7. 工具权限控制
7.1 权限模型概述
# 基于角色的权限控制
permission_model:
type: rbac
roles:
- name: admin
permissions: ["*"] # 所有权限
- name: developer
permissions:
- filesystem:read
- filesystem:write
- api:read
- name: viewer
permissions:
- filesystem:read
- name: restricted
permissions:
- api:read7.2 细粒度权限配置
# 给特定Skill配置权限
permissions:
skill: SKILL.code-reviewer
filesystem:
read:
allowed: true
paths:
- /Users/project/src
- /Users/project/tests
write:
allowed: false
delete:
allowed: false
exception:
- pattern: "*.tmp"
allowed: true
network:
allowed_hosts:
- api.github.com
- api.weather.com
blocked_hosts:
- internal.corp.local
rate_limit: 100/minute7.3 审计日志
audit:
enabled: true
level: detailed
logged_events:
- tool_invocation
- permission_denied
- rate_limit_exceeded
- authentication_failure
log_format:
timestamp: ISO8601
skill_id: string
tool_name: string
parameters: object
result: object
duration_ms: integer
user: string
retention:
days: 90
storage: secure8. 实用案例
8.1 案例：带文件操作的代码审查助手
# SKILL.code-reviewer-with-tools.md
---
name: code-reviewer-with-tools
description: 带文件操作能力的代码审查助手
version: 1.0.0
tools:
- file_reader # 读取代码文件
- terminal # 执行lint命令
---
# 代码审查助手（增强版）
## 能力
这个助手不仅能审查代码，还能实际操作文件。
## 工作流程
1. **读取代码**：使用file_reader读取用户指定的文件
2. **执行检查**：使用terminal运行lint工具
3. **综合分析**：结合文件内容和lint结果给出建议
## 使用示例
用户：帮我审查一下 /Users/project/src/index.js
↓
助手调用 file_reader 读取文件
↓
助手调用 terminal 执行 npx eslint index.js
↓
助手综合分析，给出审查报告8.2 案例：带API调用的数据分析师
# SKILL.data-analyst-with-api.md
---
name: data-analyst-with-api
description: 带API能力的分析师
version: 1.0.0
tools:
- http_api: query_database
- http_api: save_report
---
# 数据分析师（增强版）
## 能力
可以查询数据库获取数据，并保存分析报告。
## 工作流程
1. **查询数据**：调用API获取数据
2. **分析数据**：AI进行数据分析
3. **保存报告**：调用API保存分析结果
## 使用示例
用户：分析一下上个月的销售数据
↓
助手调用 query_database 查询销售数据
↓
助手分析数据，生成洞察
↓
助手调用 save_report 保存报告9. 常见问题
Q1: Tool和Function Calling有什么区别？
| 方面 | Tool | Function Calling |
|---|---|---|
| 触发方式 | Skill主动调用 | AI”思考”后决定调用 |
| 调用时机 | 确定需要时调用 | 需要时才调用 |
| 适用场景 | 明确知道需要什么能力 | 不确定需要什么能力 |
Q2: 如何保证工具调用的安全性？
建议：
- 最小权限原则：只授予必要的权限
- 输入验证：严格检查参数
- 沙箱执行：隔离执行环境
- 审计日志：记录所有调用
Q3: 工具调用失败怎么办？
策略：
- 重试：对于临时性错误
- 降级：使用备用方案
- 报错：返回明确的错误信息
Q4: 如何选择REST API还是GraphQL？
| 场景 | 推荐 |
|---|---|
| 数据结构固定 | REST API |
| 需要灵活查询 | GraphQL |
| 简单CRUD操作 | REST API |
| 复杂关联查询 | GraphQL |
10. 总结
- Tool让Skill具备动手能力：读写文件、调用API、执行命令
- MCP是标准化协议：统一不同工具的调用方式
- API集成让Skill连接外部世界：天气、数据库、业务系统
- Function Calling让AI主动决策：AI决定何时调用什么函数
- 权限控制保障安全：最小权限、审计日志
记住：Tool是Skill的手臂，让AI从”只会说”变成”能做”。
下一步
- 想学如何测试工具调用 → Skills测试与优化
- 想学如何排查工具问题 → Skills调试实战
- 想学如何设计Skill组合 → Skills设计模式
相关文档
- Skills基础理论 - Skills核心概念
- SKILL_md语法详解 - SKILL.md格式
- Skills设计模式 - 设计模式
- Skills测试与优化 - 测试策略
- Skills调试实战 - 调试方法
本文档详细介绍了在Skills系统中集成各类工具的方法和最佳实践。