技能

概览

Skills 是自包含的目录，向 agents 提供 领域专属的指令、规范和参考材料。每个 skill 由一个带 YAML frontmatter 和 markdown 正文的 SKILL.md 文件定义。

启用后，skill 的指令会直接注入 agent 的任务 prompt 中，无需修改任何代码即可赋予 agent 专业能力。

Note

Skills 不是 tools。 这是最常见的混淆点。

• Skills 会向 agent 的 prompt 注入 指令和上下文。它们告诉 agent 应该如何思考。
• Tools 会给 agent 提供可调用的 函数 来执行动作（搜索、读文件、调用 API）。

你通常需要两者都用：skills 用来提供专业方法，tools 用来执行动作。它们是独立配置、相互补充的。

---

快速开始

1. 创建 Skill 目录

skills/
└── code-review/
    ├── SKILL.md          # 必需 — 指令
    ├── references/       # 可选 — 参考文档
    │   └── style-guide.md
    └── scripts/          # 可选 — 可执行脚本

2. 编写你的 SKILL.md

---
name: code-review
description: Guidelines for conducting thorough code reviews with focus on security and performance.
metadata:
  author: your-team
  version: "1.0"
---

## Code Review Guidelines

When reviewing code, follow this checklist:

1. **Security**: Check for injection vulnerabilities, auth bypasses, and data exposure
2. **Performance**: Look for N+1 queries, unnecessary allocations, and blocking calls
3. **Readability**: Ensure clear naming, appropriate comments, and consistent style
4. **Testing**: Verify adequate test coverage for new functionality

### Severity Levels
- **Critical**: Security vulnerabilities, data loss risks → block merge
- **Major**: Performance issues, logic errors → request changes
- **Minor**: Style issues, naming suggestions → approve with comments

3. 关联到 Agent

from crewai import Agent
from crewai_tools import GithubSearchTool, FileReadTool

reviewer = Agent(
    role="Senior Code Reviewer",
    goal="Review pull requests for quality and security issues",
    backstory="Staff engineer with expertise in secure coding practices.",
    skills=["./skills"],                          # 注入 review 指南
    tools=[GithubSearchTool(), FileReadTool()],   # 让 agent 读取代码
)

现在这个 agent 同时拥有 专业知识（来自 skill）和 执行能力（来自 tools）。

---

Skills + Tools：协同工作

下面是一些常见模式，展示 skills 和 tools 如何互补：

模式 1：仅 Skills（需要领域知识，不需要动作）

适用于 agent 需要特定指令，但不需要调用外部服务的场景：

agent = Agent(
    role="Technical Writer",
    goal="Write clear API documentation",
    backstory="Expert technical writer",
    skills=["./skills/api-docs-style"],  # Writing guidelines and templates
    # No tools needed — agent writes based on provided context
)

模式 2：仅 Tools（需要动作，不需要特殊专业知识）

适用于 agent 需要执行动作，但不需要领域专属指令的场景：

from crewai_tools import SerperDevTool, ScrapeWebsiteTool

agent = Agent(
    role="Web Researcher",
    goal="Find information about a topic",
    backstory="Skilled at finding information online",
    tools=[SerperDevTool(), ScrapeWebsiteTool()],  # Can search and scrape
    # No skills needed — general research doesn't need special guidelines
)

模式 3：Skills + Tools（既有专业知识，又有动作）

这是最常见的真实场景。skill 提供 如何 开展工作；tools 提供 agent 能 做什么：

from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool

analyst = Agent(
    role="Security Analyst",
    goal="Audit infrastructure for vulnerabilities",
    backstory="Expert in cloud security and compliance",
    skills=["./skills/security-audit"],   # Audit methodology and checklists
    tools=[
        SerperDevTool(),                  # Research known vulnerabilities
        FileReadTool(),                   # Read config files
        CodeInterpreterTool(),            # Run analysis scripts
    ],
)

模式 4：Skills + MCPs

Skills 与 MCP servers 的配合方式与 tools 一样：

agent = Agent(
    role="Data Analyst",
    goal="Analyze customer data and generate reports",
    backstory="Expert data analyst with strong statistical background",
    skills=["./skills/data-analysis"],           # Analysis methodology
    mcps=["https://data-warehouse.example.com/sse"],  # Remote data access
)

模式 5：Skills + Apps

Skills 可以指导 agent 如何使用平台集成：

agent = Agent(
    role="Customer Support Agent",
    goal="Respond to customer inquiries professionally",
    backstory="Experienced support representative",
    skills=["./skills/support-playbook"],  # Response templates and escalation rules
    apps=["gmail", "zendesk"],             # Can send emails and update tickets
)

---

Crew 级别的 Skills

Skills 也可以设置在 crew 层面，从而应用到 所有 agents：

from crewai import Crew

crew = Crew(
    agents=[researcher, writer, reviewer],
    tasks=[research_task, write_task, review_task],
    skills=["./skills"],  # All agents get these skills
)

Agent 级别的 skills 优先级更高 - 如果同一个 skill 同时在两个层级被发现，会优先使用 agent 自己的版本。

---

SKILL.md 格式

---
name: my-skill
description: Short description of what this skill does and when to use it.
license: Apache-2.0                    # optional
compatibility: crewai>=0.1.0          # optional
metadata:                              # optional
  author: your-name
  version: "1.0"
allowed-tools: web-search file-read   # optional, experimental
---

Instructions for the agent go here. This markdown body is injected
into the agent's prompt when the skill is activated.

Frontmatter 字段

字段	必需	说明
name	是	1–64 个字符。只能包含小写字母数字和连字符。必须与目录名一致。
description	是	1–1024 个字符。描述这个 skill 做什么，以及何时使用它。
license	否	许可证名称，或指向内置许可证文件的引用。
compatibility	否	最多 500 个字符。环境要求（产品、包、网络）。
metadata	否	任意字符串键值映射。
allowed-tools	否	用空格分隔的预批准工具列表。实验性。

---

目录结构

my-skill/
├── SKILL.md            # 必需 — frontmatter + 指令
├── scripts/            # 可选 — 可执行脚本
├── references/         # 可选 — 参考文档
└── assets/             # 可选 — 静态文件（配置、数据）

目录名必须与 SKILL.md 中的 name 字段一致。scripts/、references/ 和 assets/ 目录会在 skill 的 path 上对需要直接引用文件的 agents 可用。

---

预加载 Skills

如果想要更强的控制，可以通过程序发现并激活 skills：

from pathlib import Path
from crewai.skills import discover_skills, activate_skill

# Discover all skills in a directory
skills = discover_skills(Path("./skills"))

# Activate them (loads full SKILL.md body)
activated = [activate_skill(s) for s in skills]

# Pass to an agent
agent = Agent(
    role="Researcher",
    goal="Find relevant information",
    backstory="An expert researcher.",
    skills=activated,
)

---

Skills 如何加载

Skills 使用 渐进式披露 - 每个阶段只加载所需内容：

阶段	加载内容	何时加载
发现	名称、描述、frontmatter 字段	discover_skills()
激活	完整 SKILL.md 正文	activate_skill()

在正常的 agent 执行过程中（通过 skills=["./skills"] 传入目录路径），skills 会自动被发现并激活。渐进式加载只在使用程序化 API 时才有意义。

---

Skills vs Knowledge

Skills 和 knowledge 都会修改 agent 的 prompt，但用途不同：

方面	Skills	Knowledge
提供什么	指令、流程、规范	事实、数据、信息
如何存储	Markdown 文件（SKILL.md）	存储在向量库（ChromaDB）中
如何检索	整体正文注入 prompt	语义搜索找到相关片段
最适合	方法论、检查清单、风格指南	公司文档、产品信息、参考数据
通过什么设置	skills=["./skills"]	knowledge_sources=[source]

经验法则： 如果 agent 需要遵循 流程，用 skill。如果 agent 需要引用 数据，用 knowledge。

---

常见问题

我需要同时设置 skills 和 tools 吗？

这取决于你的用例。Skills 和 tools 是 独立的 - 你可以使用其中一个、两个都用，或者都不用。

• 只用 Skills：当 agent 需要专业知识，但不需要外部动作时（例如带有风格规范的写作）
• 只用 Tools：当 agent 需要动作，但不需要特殊方法论时（例如简单网页搜索）
• 两者都用：当 agent 既需要专业知识又需要动作时（例如带有特定检查清单且能扫描代码的安全审计）

Skills 会自动提供 tools 吗？

不会。 SKILL.md 里的 allowed-tools 字段只是实验性的元数据 - 它不会自动提供或注入任何 tools。你必须始终通过 tools=[]、mcps=[] 或 apps=[] 单独配置 tools。

如果我在 agent 和 crew 上都设置同一个 skill，会发生什么？

会优先使用 agent 级别的 skill。Skills 会按名称去重 - agent 的 skills 会先被处理，因此如果相同的 skill 名称同时出现在两个层级，会使用 agent 自己的版本。

SKILL.md 正文可以有多大？

有一个 50,000 字符的软警告，但没有硬性上限。为了获得最佳结果，请保持 skills 聚焦且简洁 - 过大的 prompt 注入会削弱 agent 的注意力。