一、什么是Skill？
1.1 一句话定义
Skill 是 AI 智能体的"能力插件"------就像给手机装App一样，给AI装上特定领域的专业知识或操作能力。
1.2 一个类比帮你理解
| 概念 | 类比 | 说明 |
|---|---|---|
| AI Agent | 一个聪明的助理 | 能理解需求、做决策 |
| Skill | 助理的"专业技能证书" | 让助理能做具体的事（如写代码、查天气、做报表） |
| Tool | 助理手里的工具 | Skill 内部调用的具体函数/API |
1.3 Skill vs Tool vs Plugin
很多人搞混这三个概念，我用一个表格说清楚：
| 概念 | 粒度 | 例子 |
|---|---|---|
| Tool | 最小单位，单个函数 | search_web(query) |
| Skill | 一组相关Tool的集合 | WebSearchSkill（包含搜索、爬取、摘要） |
| Plugin | 第三方Skill的打包分发形式 | @my-company/web-search-plugin |
二、Skill 的核心架构
一个标准的Skill包含四个部分：
text
┌─────────────────────────────────────────┐
│ Skill 定义 │
│ ┌─────────────────────────────────────┐│
│ │ 1. 元数据 (Metadata) ││
│ │ - 名称、描述、版本、作者 ││
│ └─────────────────────────────────────┘│
│ ┌─────────────────────────────────────┐│
│ │ 2. 输入输出 (Input/Output) ││
│ │ - 参数定义、返回格式 ││
│ └─────────────────────────────────────┘│
│ ┌─────────────────────────────────────┐│
│ │ 3. 执行逻辑 (Execution) ││
│ │ - 核心代码实现 ││
│ └─────────────────────────────────────┘│
│ ┌─────────────────────────────────────┐│
│ │ 4. 配置依赖 (Config & Dependencies)││
│ │ - API密钥、环境变量、第三方库 ││
│ └─────────────────────────────────────┘│
└─────────────────────────────────────────┘三、实战：写一个「代码审查Skill」
理论讲完，我们来动手。我要写一个能让AI做代码审查的Skill。
3.1 第一步：定义Skill的元数据和接口
python
python
# code_review_skill.py
from typing import List, Optional, Dict, Any
from pydantic import BaseModel, Field
from enum import Enum
# ============ 1. 定义输入输出模型 ============
class IssueLevel(str, Enum):
ERROR = "error" # 严重问题，必须修复
WARNING = "warning" # 警告，建议修复
SUGGESTION = "suggestion" # 优化建议
class ReviewIssue(BaseModel):
level: IssueLevel
title: str = Field(..., description="问题标题")
description: str = Field(..., description="详细描述")
line_number: Optional[int] = Field(None, description="行号")
suggestion: str = Field(..., description="修复建议")
class CodeReviewInput(BaseModel):
code: str = Field(..., description="待审查的代码")
language: str = Field(..., description="编程语言，如 python, javascript")
focus_areas: Optional[List[str]] = Field(
default=None,
description="重点关注领域：security/performance/bug/style"
)
class CodeReviewOutput(BaseModel):
issues: List[ReviewIssue]
summary: str = Field(..., description="审查总结")
score: int = Field(..., ge=0, le=100, description="代码质量评分(0-100)")
# ============ 2. Skill 元数据 ============
SKILL_METADATA = {
"name": "code_reviewer",
"display_name": "代码审查助手",
"version": "1.0.0",
"author": "Your Name",
"description": "审查代码，发现潜在bug、安全漏洞、性能问题和风格问题",
"tags": ["coding", "review", "quality"],
"input_schema": CodeReviewInput.model_json_schema(),
"output_schema": CodeReviewOutput.model_json_schema(),
}3.2 第二步：实现核心逻辑
python
bash
# ============ 3. 核心执行逻辑 ============
import json
import logging
from typing import Dict, Any
import litellm # 统一LLM调用接口
logger = logging.getLogger(__name__)
# 审查维度的Prompt模板
REVIEW_PROMPT_TEMPLATE = """
你是一位资深代码审查专家。请严格审查以下{language}代码。
【代码】
{code}
text
【审查要求】
请从以下维度逐一检查：
1. 🔴 Bug风险：逻辑错误、边界条件、空指针、类型错误
2. 🟡 安全漏洞：SQL注入、XSS、敏感信息泄露、权限问题
3. 🟢 性能问题：循环嵌套、内存泄漏、不必要的计算
4. 🔵 代码规范：命名、格式、注释、可读性
{focus_areas_hint}
【输出格式】
请只输出JSON，不要有其他内容：
{{
"issues": [
{{
"level": "error/warning/suggestion",
"title": "问题标题",
"description": "详细问题描述",
"line_number": 行号(整数，如果没有则为null),
"suggestion": "具体的修复建议"
}}
],
"summary": "一句话总结代码质量",
"score": 0-100的整数分数
}}
"""
class CodeReviewSkill:
"""代码审查Skill"""
def __init__(self, model: str = "gpt-4", api_key: Optional[str] = None):
self.model = model
if api_key:
litellm.api_key = api_key
@property
def metadata(self) -> Dict[str, Any]:
"""返回Skill元数据，用于自动发现和注册"""
return SKILL_METADATA
async def execute(self, input_data: CodeReviewInput) -> CodeReviewOutput:
"""执行代码审查"""
# 构建focus_areas提示
focus_hint = ""
if input_data.focus_areas:
focus_hint = f"\n【重点关注】{', '.join(input_data.focus_areas)}"
prompt = REVIEW_PROMPT_TEMPLATE.format(
language=input_data.language,
code=input_data.code,
focus_areas_hint=focus_hint
)
try:
# 调用LLM
response = await litellm.acompletion(
model=self.model,
messages=[
{"role": "system", "content": "你是专业的代码审查专家，只输出JSON格式结果。"},
{"role": "user", "content": prompt}
],
temperature=0.3,
response_format={"type": "json_object"}
)
# 解析结果
result = json.loads(response.choices[0].message.content)
return self._parse_result(result)
except Exception as e:
logger.error(f"代码审查失败: {e}")
return self._fallback_output(f"审查失败: {str(e)}")
def _parse_result(self, raw: dict) -> CodeReviewOutput:
"""解析并验证LLM返回结果"""
issues = []
for item in raw.get("issues", []):
try:
issues.append(ReviewIssue(
level=IssueLevel(item["level"]),
title=item["title"],
description=item["description"],
line_number=item.get("line_number"),
suggestion=item["suggestion"]
))
except Exception as e:
logger.warning(f"跳过无效issue: {e}")
return CodeReviewOutput(
issues=issues,
summary=raw.get("summary", "审查完成"),
score=raw.get("score", 50)
)
def _fallback_output(self, error_msg: str) -> CodeReviewOutput:
"""出错时的降级输出"""
return CodeReviewOutput(
issues=[ReviewIssue(
level=IssueLevel.WARNING,
title="审查服务异常",
description=error_msg,
suggestion="请稍后重试或检查API配置",
line_number=None
)],
summary="审查服务暂时不可用",
score=50
)3.3 第三步：提供便捷的函数式调用
除了类接口，Skill通常还需要一个简单的函数入口：
python
bash
# ============ 4. 便捷函数接口 ============
async def review_code(
code: str,
language: str,
focus_areas: Optional[List[str]] = None,
model: str = "gpt-4"
) -> CodeReviewOutput:
"""
快速审查代码的便捷函数
使用示例：
result = await review_code(
code="def add(a,b): return a+b",
language="python",
focus_areas=["bug", "security"]
)
for issue in result.issues:
print(f"{issue.level}: {issue.title}")
"""
skill = CodeReviewSkill(model=model)
input_data = CodeReviewInput(
code=code,
language=language,
focus_areas=focus_areas
)
return await skill.execute(input_data)
3.4 第四步：添加配置和测试
python
# ============ 5. 配置管理 ============
import os
from dotenv import load_dotenv
load_dotenv()
DEFAULT_CONFIG = {
"model": os.getenv("REVIEW_MODEL", "gpt-4"),
"api_key": os.getenv("OPENAI_API_KEY"),
"max_code_length": 10000, # 最大审查代码长度
}
# ============ 6. 单元测试 ============
import pytest
@pytest.mark.asyncio
async def test_code_review_skill():
skill = CodeReviewSkill(model="gpt-3.5-turbo") # 测试用小模型
input_data = CodeReviewInput(
code="""
def divide(a, b):
return a / b
""",
language="python",
focus_areas=["bug"]
)
result = await skill.execute(input_data)
# 应该发现除零风险
assert len(result.issues) >= 1
assert any("零" in issue.description or "zero" in issue.description.lower()
for issue in result.issues)
assert 0 <= result.score <= 100四、如何将Skill接入AI Agent？
写好了Skill，怎么让AI能用它？这里以LangChain和LlamaIndex为例：
4.1 接入LangChain
bash
python
from langchain.tools import StructuredTool
# 将Skill包装成LangChain Tool
code_review_tool = StructuredTool.from_function(
name="code_reviewer",
description="审查代码，发现bug、安全漏洞和性能问题。当用户需要代码审查时使用。",
coroutine=review_code,
args_schema=CodeReviewInput,
)
# 创建Agent使用这个Tool
from langchain.agents import create_openai_tools_agent
tools = [code_review_tool]
agent = create_openai_tools_agent(llm, tools, prompt)
4.2 接入LlamaIndex
python
from llama_index.core.tools import FunctionTool
# 包装成LlamaIndex Tool
review_tool = FunctionTool.from_defaults(
fn=review_code,
name="code_reviewer",
description="审查代码质量，返回问题和建议"
)
# 添加到Agent
from llama_index.core.agent import ReActAgent
agent = ReActAgent.from_tools([review_tool], llm=llm)五、Skill开发的最佳实践
5.1 输入输出设计原则
| 原则 | 说明 | 错误示例 | 正确示例 |
|---|---|---|---|
| 明确性 | 参数含义清晰，无歧义 | data: str |
code: str = Field(..., description="待审查的代码") |
| 容错性 | 有默认值，能处理边界 | focus_areas: List[str] |
focus_areas: Optional[List[str]] = None |
| 结构化 | 输出用Pydantic模型 | 返回dict | 返回CodeReviewOutput |
5.2 错误处理策略
python
bash
async def execute(self, input_data):
try:
# 1. 输入校验
self._validate_input(input_data)
# 2. 核心逻辑
result = await self._do_work(input_data)
# 3. 输出校验
return self._validate_output(result)
except ValidationError as e:
# 输入错误 -> 返回友好提示
return self._error_output(f"参数错误: {e}")
except TimeoutError as e:
# 超时 -> 重试或降级
return await self._retry_or_fallback(input_data)
except Exception as e:
# 未知错误 -> 记录日志，返回降级结果
logger.exception("Unexpected error")
return self._fallback_output()5.3 Skill 的目录结构规范
text
bash
skills/
└── data_analyst/
├── __init__.py # [可选] Python 包标识
├── skill.json # [核心] 元数据：定义技能名称、描述、触发词
├── SKILL.md # [核心] 指令文档：定义 SOP、规则、Few-Shot 示例
└── resources/ # [资源] 存放静态资源
├── tools.py # [可选] 可执行代码/工具函数
├── db_schema.sql # [可选] 参考文档/数据库结构
└── config.yaml # [可选] 配置文件5.4 skill.md样式
bash
---
name: skill的名字，如：前端设计
description: 在什么情况下调用，如：在设计前端页面时调用。
---
正文：你需要描述你的要求，建议一段一段写，每段一个小标题
如：
## 色彩使用
在前端写css或其它有关色彩的内容，请遵循以下描述:
- 不要使用蓝紫色
- 请使用白色，浅色系
## 组件间动画的过渡
在前端在有组件切换时，请遵循以下描述:
- 不要硬切，要使用过渡动画
- 可以带点类似弹簧效果
## 参考文献：如果一个skill要写的过多，就可以分多个文件，按需读取，参考文献不是必写项，文件路径要写出相对路径
agents目录包含专门子代理的指令，需要生成相关子代理人时就读它们：
- `agents/动画.md` --- 前端各组件的切换、过渡
------------------------------------------------
版权声明：本文为CSDN博主「星原望野」的原创文章，遵循CC 4.0 BY-SA版权协议，转载请附上原文出处链接及本声明。
原文链接：https://blog.csdn.net/2302_81095897/article/details/1588538635.5 让Skill可发现（注册机制）
python
cpp
# skill_registry.py
from typing import Dict, Type
class SkillRegistry:
_skills: Dict[str, Type] = {}
@classmethod
def register(cls, name: str):
def decorator(skill_class):
cls._skills[name] = skill_class
return skill_class
return decorator
@classmethod
def get(cls, name: str):
return cls._skills.get(name)
@classmethod
def list_all(cls):
return list(cls._skills.keys())
# 使用装饰器注册
@SkillRegistry.register("code_reviewer")
class CodeReviewSkill:
pass六、总结
6.1 核心要点回顾
-
Skill = 一组相关Tool的集合，让AI获得特定领域能力
-
四个组成部分：元数据、输入输出、执行逻辑、配置依赖
-
设计原则：明确输入、结构化输出、完善的错误处理
-
接入方式：LangChain和LlamaIndex都有标准化的Tool包装
6.2 下一步你可以做什么？
-
写一个你日常需要的Skill（比如：周报生成、SQL优化、日志分析）
-
把Skill发布到社区（LangChain Hub、LlamaHub）
-
组合多个Skill，构建一个垂直领域的AI Agent
6.3 skill推荐
find-skills：该skill可以帮助用户在网上，找到适合自己的skill
skill-creator：这个skill约定了创建skill的规范，可以辅助我们创建skill
frontend-design：这个skill约定了前端的设计风格，避免千篇一律的蓝紫色的ai味网站
anthropics：anthropics官方推出的skill合集，十分实用
The Agent Skills Directory：一个收录了大量skill的网站，几乎都能找到自己想要的skill