技能

基于文件系统的技能包，可将领域专业知识和指令注入智能体的提示词中。

概述

技能是自包含的目录，为智能体提供领域特定的指令、准则和参考资料。每个技能由 SKILL.md 文件定义，包含 YAML frontmatter 和 markdown 正文。

智能体首先会收到每个已配置技能的名称和描述。当某个描述适用于当前请求时，智能体会在本次执行中加载该技能的完整指令。这样既能将无关指令排除在上下文之外，又能让智能体获得相关专业知识，而无需修改代码。

NOTE

技能不是工具。 这是最常见的混淆点。

技能将指令和上下文注入智能体的提示词中。它们告诉智能体如何思考某个问题。
工具为智能体提供可调用的函数以执行操作（搜索、读取文件、调用 API）。

你通常需要两者：技能提供专业知识，工具提供行动能力。它们独立配置，相互补充。

快速开始

1. 使用 CLI 创建技能

CLI 是受支持的创建技能的方式——它会为你搭建目录结构和一个有效的 SKILL.md：

shell

crewai create skill code-review

在团队项目中（即 pyproject.toml 所在位置）执行此命令会创建 ./skills/code-review/；在项目之外执行则会在当前目录创建 ./code-review/（你可以在 crewai create skill 上使用 --no-project 强制采用后一种行为）：

skills/
└── code-review/
    ├── SKILL.md          # Required — instructions (pre-filled template)
    ├── references/       # Optional — reference docs
    ├── scripts/          # Optional — executable scripts
    └── assets/           # Optional — static files

2. 编写你的 SKILL.md

markdown

---
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. 挂载到智能体

python

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"],                          # Discovers review skills
    tools=[GithubSearchTool(), FileReadTool()],   # Lets agent read code
)

现在智能体同时拥有专业知识（在需要时从相关技能加载）和能力（来自工具）。

技能 + 工具：协同工作

以下常见模式展示了技能与工具如何相互补充：

模式 1：仅技能（领域专业知识，无需操作）

当智能体需要特定指令但不需要调用外部服务时使用：

python

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：仅工具（行动，无特殊专业知识）

当智能体需要执行操作但不需要领域特定指令时使用：

python

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：技能 + 工具（专业知识与行动兼具）

最常见的真实场景模式。技能提供如何开展工作的指导；工具提供智能体能做什么：

python

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：技能 + MCP

技能与 MCP 服务器协同工作的方式，与它们和工具协同工作的方式相同：

python

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：技能 + Apps

技能可以指导智能体如何使用平台集成：

python

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
)

创建、发布和安装技能

技能具有由 CLI 管理的完整生命周期：使用 crewai create skill 创建，使用 crewai skill publish 发布——手工搭建目录适用于本地实验，但 CLI 才是推荐的工作流，它能确保你的技能目录结构和 frontmatter 保持有效。

NOTE

crewai skill create 已弃用，但仍可使用并会给出警告。请改用 crewai create skill。

Create

shell

crewai create skill my-skill

将目录搭建到（团队项目中的 ./skills/ 下），并附带一个模板 SKILL.md，以及空的 scripts/、references/ 和 assets/ 目录。编辑 SKILL.md 来定义指令。

发布

在技能目录内（即 SKILL.md 所在位置）运行：

shell

cd skills/my-skill
crewai skill publish

发布时会从 SKILL.md frontmatter 中读取 name、description 和 metadata.version，并将技能推送到 CrewAI 注册表。已发布的技能始终限定在你的组织范围内——与工具一样，只有发布组织的成员才能查看和安装它们；不存在公开可见性。有用的标志：

标志	作用
`--org <slug>`	在指定组织下发布（覆盖设置）。
`--force`	跳过 git 状态校验（未提交的更改等）。

安装

通过 @org-uuid/name 引用安装已发布的技能：

shell

crewai skill install @your-org-uuid/code-review

NOTE

请使用你组织的 UUID，而不是组织名称——组织名称并不唯一，因此名称可能解析到错误的组织，导致安装失败并报“未找到”错误。运行 crewai org list 查看你所属每个组织的 UUID（ID 列）。

在团队项目中，技能会落到 ./skills/{name}/；在项目之外，则会进入共享缓存 ~/.crewai/skills/{org-uuid}/{name}/。

智能体也可以直接引用注册表中的技能——它们在运行时从本地缓存（或项目的 skills/ 目录）解析：

python

agent = Agent(
    role="Senior Code Reviewer",
    goal="Review pull requests for quality and security issues",
    backstory="Staff engineer with expertise in secure coding practices.",
    skills=["@your-org-uuid/code-review"],  # registry ref, resolved locally
)

固定版本

未固定版本的引用会解析为最新发布的版本，因此发布新版本会改变所有引用它的智能体。请改为追加 @<version> 来固定某个版本：

python

agent = Agent(
    role="Senior Code Reviewer",
    goal="Review pull requests for quality and security issues",
    backstory="Staff engineer with expertise in secure coding practices.",
    skills=["@your-org-uuid/code-review@1.2.0"],  # pinned; a leading "v" also works
)

固定版本的引用会重新下载，除非它找到的副本正是该确切版本—— 固定版本是请求某个特定版本，而不是暗示某个版本。缓存中的技能是按安装时记录的版本进行匹配的，因此其 frontmatter 中无需包含版本信息； skills/ 下的项目本地副本没有此类记录，因此会按其 SKILL.md frontmatter 中的 metadata.version 进行匹配。固定一个未发布的版本会失败，而不会回退到最新版本。

NOTE

来自 Agent Repository 的智能体会自动固定版本：仓库会为其分配的每个技能记录一个版本，运行时在加载智能体时会应用这些固定版本。

列出

shell

crewai skill list

显示已安装的技能，包括来自项目 ./skills/ 目录和全局缓存的技能，并附带其版本和路径。

团队级技能

可以在团队上设置技能，以应用于所有智能体：

python

from crewai import Crew

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

智能体级技能优先——如果同一技能在两个层级都被发现，则使用智能体的版本。

SKILL.md 格式

markdown

---
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 个字符。描述该技能的作用以及何时使用。
`license`	否	许可证名称或对随附许可证文件的引用。
`compatibility`	否	最多 500 个字符。环境要求（产品、包、网络）。
`metadata`	否	任意字符串键值映射。
`allowed-tools`	否	以空格分隔的预先批准工具列表。实验性。

目录结构

my-skill/
├── SKILL.md            # Required — frontmatter + instructions
├── scripts/            # Optional — executable scripts
├── references/         # Optional — reference documents
└── assets/             # Optional — static files (configs, data)

目录名必须与 SKILL.md 中的 name 字段一致。scripts/、references/ 和 assets/ 目录可通过技能的 path 访问，供需要直接引用文件的智能体使用。

预加载技能

如需更多控制，你可以通过编程方式发现并激活技能。传入已激活的技能会使其指令始终生效：

python

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,
)

技能如何加载

技能采用渐进式披露——在每个阶段只加载所需内容：

阶段	加载内容	时机
发现	名称、描述、frontmatter 字段	智能体初始化或 `discover_skills()`
激活	完整的 SKILL.md 正文文本	相关的运行时请求或 `activate_skill()`
资源	资源目录清单	显式调用 `load_resources()`

使用 skills=["./skills"] 时，该目录会在初始化时被发现，但完整指令不会被放入每个提示词中。智能体在每次执行时都会审查元数据，只加载适用的技能。加载的指令限定在本次执行范围内，因此为先前调用选择的技能不会在智能体上累积。

内联技能字符串以及已通过 activate_skill() 激活的 Skill 对象会始终保持生效。当指令应适用于每个请求时，这提供了一个显式的选择加入方式。

技能与知识的区别

技能和知识都会修改智能体的提示词，但它们服务于不同的目的：

维度	技能	知识
提供什么	指令、流程、准则	事实、数据、信息
如何存储	Markdown 文件（SKILL.md）	嵌入到向量存储（ChromaDB）
如何检索	整个正文注入提示词	语义搜索找到相关分块
最适合	方法论、检查清单、风格指南	公司文档、产品信息、参考数据
设置方式	`skills=["./skills"]`	`knowledge_sources=[source]`

经验法则： 如果智能体需要遵循某个流程，请使用技能。如果智能体需要引用数据，请使用知识。

常见问题

我需要同时设置技能和工具吗？

这取决于你的用例。技能和工具是相互独立的 —— 你可以只用其中一个、两个都用，或者都不用。

仅用技能：当智能体需要专业知识但不需要外部操作时（例如按风格指南写作）
仅用工具：当智能体需要执行操作但不需要特殊方法时（例如简单的网页搜索）
两者都用：当智能体既需要专业知识又需要执行操作时（例如安全审计既需要特定检查清单，又需要扫描代码的能力）

技能会自动提供工具吗？

不会。 SKILL.md 中的 allowed-tools 字段只是实验性的元数据 —— 它不会预置或注入任何工具。你必须始终通过 tools=[]、mcps=[] 或 apps=[] 单独设置工具。

如果我在智能体和其团队上都设置了同一个技能，会发生什么？

智能体级别的技能优先。技能按名称去重 —— 智能体的技能先被处理，因此如果同一个技能名称同时出现在两个层级，将使用智能体中的版本。

SKILL.md 正文可以有多大？

在 50,000 个字符时会有软性警告，但没有硬性上限。请让技能保持聚焦和简洁以获得最佳效果 —— 过大的提示词注入会稀释智能体的注意力。

技能

概述

快速开始

1. 使用 CLI 创建技能

2. 编写你的 SKILL.md

3. 挂载到智能体

技能 + 工具：协同工作

模式 1：仅技能（领域专业知识，无需操作）

模式 2：仅工具（行动，无特殊专业知识）

模式 3：技能 + 工具（专业知识与行动兼具）

模式 4：技能 + MCP

模式 5：技能 + Apps

创建、发布和安装技能

Create

发布

安装

固定版本

列出

团队级技能

SKILL.md 格式

Frontmatter 字段

目录结构

预加载技能

技能如何加载

技能与知识的区别

常见问题

友情链接