Appearance
第27天：Skills标准深度解析
学习目标
- 深入理解Skills标准的设计理念
- 掌握Skills标准的核心概念
- 了解Skills的目录结构
- 能够分析Skills标准规范
- 理解Skills与MCP的关系
核心内容
Skills标准的起源和发展
Skills标准是Anthropic在2025年推出的开放标准，旨在为AI能力定义提供统一的文档驱动方法。Skills标准的核心理念是"文档即代码"，通过结构化的Markdown文档来定义AI能力，实现能力的自动发现和加载。
发展历程
- 2024年底：MCP协议发布，解决了AI与外部工具的通信问题
- 2025年初：AI Agent兴起，需要更灵活的能力定义方式
- 2025年10月：Anthropic发布Skills标准
- 2025年底：Skills生态初步形成
设计目标
Skills标准的设计目标包括：
- 文档驱动：通过文档定义能力，提高可读性和可维护性
- 自动发现：实现能力的自动发现和加载
- 可组合性：支持能力的组合和复用
- 跨平台：不依赖特定平台或框架
- 易于扩展：支持自定义能力和扩展
Skills标准的核心概念
1. Skill（技能）
Skill是Skills标准的基本单元，代表一个独立的AI能力。每个Skill通过一个skill.md文件定义，包含技能的描述、参数、示例等信息。
2. skill.md（技能文档）
skill.md是Skills标准的核心文件，使用Markdown格式编写，包含以下部分：
- Front Matter：元数据（技能名称、版本、作者等）
- 描述：技能的功能描述
- 参数：技能的输入参数定义
- 返回值：技能的返回值定义
- 示例：技能使用示例
- 实现：技能的代码实现
3. 能力发现（Capability Discovery）
能力发现是Skills标准的重要特性，通过解析skill.md文件，自动发现和加载技能。能力发现包括：
- 静态发现：扫描目录，解析skill.md文件
- 动态加载：根据需要加载技能
- 版本管理：支持多版本技能
- 依赖管理：处理技能间的依赖关系
4. 文档驱动开发（Documentation-Driven Development）
文档驱动开发是Skills标准的核心理念，强调先编写文档，再编写代码。这种方式的优势包括：
- 提高可读性：文档即代码，易于理解
- 便于维护：文档和代码同步更新
- 自动生成：可以自动生成代码框架
- 版本控制：文档纳入版本控制
Skills的目录结构
Skills标准定义了标准的目录结构，便于组织和管理技能。
基本目录结构
my-skill/
├── skill.md # 技能定义文件
├── README.md # 技能说明文档
├── LICENSE # 许可证
├── src/ # 源代码目录
│ ├── __init__.py
│ └── main.py
├── tests/ # 测试目录
│ └── test_skill.py
└── examples/ # 示例目录
└── example.py多技能目录结构
my-skills/
├── skills/ # 技能目录
│ ├── skill-1/
│ │ ├── skill.md
│ │ ├── src/
│ │ └── tests/
│ └── skill-2/
│ ├── skill.md
│ ├── src/
│ └── tests/
├── README.md # 项目说明
└── requirements.txt # 依赖列表Skills的文档规范
Front Matter
Front Matter是skill.md文件的元数据部分，使用YAML格式：
yaml
---
name: "file-reader"
version: "1.0.0"
author: "Your Name"
description: "Read and parse files"
tags: ["file", "io", "parsing"]
license: "MIT"
dependencies:
- python>=3.8
- pandas>=1.3.0
---描述部分
描述部分详细说明技能的功能和用途：
markdown
## Description
The file-reader skill provides the ability to read and parse various file formats including CSV, JSON, and plain text files. It supports both local file paths and remote URLs.
### Features
- Read local files
- Read remote files via URL
- Parse CSV files
- Parse JSON files
- Parse plain text files
- Handle encoding issues参数定义
参数定义使用结构化的Markdown表格：
markdown
## Parameters
| Parameter | Type | Required | Description | Default |
|-----------|------|----------|-------------|---------|
| file_path | string | Yes | Path to the file or URL | - |
| encoding | string | No | File encoding | utf-8 |
| delimiter | string | No | CSV delimiter (for CSV files) | , |
| skip_rows | integer | No | Number of rows to skip | 0 |返回值定义
返回值定义说明技能的输出格式：
markdown
## Returns
Returns a dictionary containing:
- `success` (boolean): Whether the operation was successful
- `data` (any): The parsed file content
- `metadata` (object): File metadata including size, type, etc.
- `error` (string): Error message if failed
### Example Response
```json
{
"success": true,
"data": [
{"name": "Alice", "age": 30},
{"name": "Bob", "age": 25}
],
"metadata": {
"size": 1024,
"type": "csv",
"rows": 2
}
}
#### 示例代码
示例代码展示如何使用技能：
```markdown
## Examples
### Example 1: Read a CSV file
```python
from my_skill import FileReader
reader = FileReader()
result = reader.read(
file_path="data.csv",
encoding="utf-8",
delimiter=","
)
print(result["data"])Example 2: Read a JSON file
python
from my_skill import FileReader
reader = FileReader()
result = reader.read(
file_path="data.json"
)
print(result["data"])
### Skills的架构设计
#### 架构层次
Skills标准采用分层架构：┌─────────────────────────┐ │ Application Layer │ 应用层 ├─────────────────────────┤ │ Skills Runtime │ 运行时层 ├─────────────────────────┤ │ Skills Discovery │ 发现层 ├─────────────────────────┤ │ Skills Definition │ 定义层 └─────────────────────────┘
#### 工作流程
Skills的工作流程如下：
1. **定义**：编写skill.md文件，定义技能
2. **发现**：扫描目录，解析skill.md文件
3. **加载**：动态加载技能代码
4. **执行**：调用技能，执行功能
5. **返回**：返回结果给调用者
### Skills与MCP的关系
Skills和MCP是互补的技术：
- **Skills**：定义AI能力，强调文档驱动
- **MCP**：定义通信协议，强调标准化通信
#### 协同使用
Skills可以与MCP协同使用：
1. **Skills定义能力**：使用Skills定义AI能力
2. **MCP提供服务**：使用MCP提供能力服务
3. **Claude Desktop集成**：将Skills集成到Claude Desktop
#### 示例架构┌─────────────────────────┐ │ Claude Desktop │ ├─────────────────────────┤ │ MCP Client │ ├─────────────────────────┤ │ Skills Runtime │ ├─────────────────────────┤ │ MCP Server │ └─────────────────────────┘
## 实践任务
### 任务1：分析Skills标准规范
访问Anthropic官方文档，阅读Skills标准规范，理解其设计理念和核心概念。
**步骤**：
1. 访问Anthropic官方文档
2. 阅读Skills标准规范
3. 理解skill.md文件格式
4. 分析示例Skills项目
**输出**：
- Skills标准规范分析报告
- skill.md文件格式总结
- 示例Skills项目分析
### 任务2：设计Skill目录结构
设计一个文件操作Skill的目录结构。
**步骤**：
1. 确定Skill的功能
2. 设计目录结构
3. 创建必要的文件
4. 编写README.md
**输出**：
- Skill目录结构
- README.md文件
- 基本文件框架
### 任务3：编写简单的skill.md
编写一个简单的skill.md文件，定义一个文件读取Skill。
**步骤**：
1. 编写Front Matter
2. 编写描述部分
3. 定义参数
4. 定义返回值
5. 编写示例
**输出**：
- 完整的skill.md文件
- 参数定义表格
- 示例代码
## 代码示例
### 示例1：完整的skill.md文件
```yaml
---
name: "file-reader"
version: "1.0.0"
author: "Your Name"
description: "Read and parse files"
tags: ["file", "io", "parsing"]
license: "MIT"
dependencies:
- python>=3.8
- pandas>=1.3.0
---
# File Reader Skill
## Description
The file-reader skill provides the ability to read and parse various file formats including CSV, JSON, and plain text files.
## Parameters
| Parameter | Type | Required | Description | Default |
|-----------|------|----------|-------------|---------|
| file_path | string | Yes | Path to the file or URL | - |
| encoding | string | No | File encoding | utf-8 |
| delimiter | string | No | CSV delimiter | , |
## Returns
Returns a dictionary containing:
- `success` (boolean): Whether the operation was successful
- `data` (any): The parsed file content
- `metadata` (object): File metadata
## Examples
### Example 1: Read a CSV file
```python
from my_skill import FileReader
reader = FileReader()
result = reader.read(
file_path="data.csv",
encoding="utf-8"
)
print(result["data"])
### 示例2：Skill实现代码
```python
import pandas as pd
import json
from pathlib import Path
from typing import Dict, Any, Union
import requests
class FileReader:
def read(self, file_path: str, encoding: str = "utf-8",
delimiter: str = ",") -> Dict[str, Any]:
try:
if file_path.startswith(("http://", "https://")):
return self._read_remote_file(file_path, encoding)
else:
return self._read_local_file(file_path, encoding, delimiter)
except Exception as e:
return {
"success": False,
"data": None,
"metadata": {},
"error": str(e)
}
def _read_local_file(self, file_path: str, encoding: str,
delimiter: str) -> Dict[str, Any]:
path = Path(file_path)
if not path.exists():
raise FileNotFoundError(f"File not found: {file_path}")
suffix = path.suffix.lower()
if suffix == ".csv":
data = pd.read_csv(file_path, encoding=encoding,
delimiter=delimiter).to_dict("records")
elif suffix == ".json":
with open(file_path, "r", encoding=encoding) as f:
data = json.load(f)
else:
with open(file_path, "r", encoding=encoding) as f:
data = f.read()
return {
"success": True,
"data": data,
"metadata": {
"size": path.stat().st_size,
"type": suffix[1:] if suffix else "unknown"
},
"error": None
}
def _read_remote_file(self, url: str, encoding: str) -> Dict[str, Any]:
response = requests.get(url)
response.raise_for_status()
content_type = response.headers.get("content-type", "")
if "json" in content_type:
data = response.json()
else:
data = response.text
return {
"success": True,
"data": data,
"metadata": {
"size": len(response.content),
"type": content_type
},
"error": None
}示例3：Skill测试代码
python
import unittest
from my_skill import FileReader
import tempfile
import json
import os
class TestFileReader(unittest.TestCase):
def setUp(self):
self.reader = FileReader()
self.temp_dir = tempfile.mkdtemp()
def tearDown(self):
import shutil
shutil.rmtree(self.temp_dir)
def test_read_csv_file(self):
csv_file = os.path.join(self.temp_dir, "test.csv")
with open(csv_file, "w") as f:
f.write("name,age\nAlice,30\nBob,25\n")
result = self.reader.read(csv_file)
self.assertTrue(result["success"])
self.assertEqual(len(result["data"]), 2)
self.assertEqual(result["data"][0]["name"], "Alice")
def test_read_json_file(self):
json_file = os.path.join(self.temp_dir, "test.json")
data = {"name": "Alice", "age": 30}
with open(json_file, "w") as f:
json.dump(data, f)
result = self.reader.read(json_file)
self.assertTrue(result["success"])
self.assertEqual(result["data"]["name"], "Alice")
def test_read_nonexistent_file(self):
result = self.reader.read("nonexistent.csv")
self.assertFalse(result["success"])
self.assertIsNotNone(result["error"])
if __name__ == "__main__":
unittest.main()总结
Skills标准是Anthropic推出的文档驱动的AI能力标准，通过skill.md文件定义AI能力，实现能力的自动发现和加载。Skills标准的核心理念是"文档即代码"，通过结构化的Markdown文档来定义AI能力，提高可读性和可维护性。
本节我们学习了：
- Skills标准的起源和发展
- Skills标准的核心概念
- Skills的目录结构
- Skills的文档规范
- Skills与MCP的关系
下一步，我们将学习Skills vs MCP vs SubAgent，理解三者的区别和应用场景。