> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Skills
> Filesystem-based skill packages that inject domain expertise and instructions into agent prompts.
## Overview
Skills are self-contained directories that provide agents with **domain-specific instructions, guidelines, and reference material**. Each skill is defined by a `SKILL.md` file with YAML frontmatter and a markdown body.
Agents first receive each configured skill's name and description. When a
description applies to the current request, the agent loads that skill's full
instructions for that execution. This keeps unrelated instructions out of the
context while giving the agent the relevant expertise without code changes.
**Skills are NOT tools.** This is the most common point of confusion.
* **Skills** inject *instructions and context* into the agent's prompt. They tell the agent *how to think* about a problem.
* **Tools** give the agent *callable functions* to take action (search, read files, call APIs).
You often need **both**: skills for expertise, tools for action. They are configured independently and complement each other.
***
## Quick Start
### 1. Create a Skill with the CLI
The CLI is the supported way to create a skill — it scaffolds the directory layout and a valid `SKILL.md` for you:
```shell Terminal theme={null}
crewai skill create code-review
```
Inside a crew project (where `pyproject.toml` lives) this creates `./skills/code-review/`; outside a project it creates `./code-review/` in the current directory (you can force that behavior with `--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. Write Your SKILL.md
```markdown theme={null}
---
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. Attach to an Agent
```python theme={null}
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
)
```
The agent now has both **expertise** (loaded from the relevant skill when
needed) and **capabilities** (from the tools).
***
## Skills + Tools: Working Together
Here are common patterns showing how skills and tools complement each other:
### Pattern 1: Skills Only (Domain Expertise, No Actions Needed)
Use when the agent needs specific instructions but doesn't need to call external services:
```python theme={null}
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
)
```
### Pattern 2: Tools Only (Actions, No Special Expertise)
Use when the agent needs to take action but doesn't need domain-specific instructions:
```python theme={null}
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
)
```
### Pattern 3: Skills + Tools (Expertise AND Actions)
The most common real-world pattern. The skill provides *how* to approach the work; tools provide *what* the agent can do:
```python theme={null}
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
],
)
```
### Pattern 4: Skills + MCPs
Skills work alongside MCP servers the same way they work with tools:
```python theme={null}
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
)
```
### Pattern 5: Skills + Apps
Skills can guide how an agent uses platform integrations:
```python theme={null}
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
)
```
***
## Creating, Publishing, and Installing Skills
Skills have a full lifecycle managed by the CLI: **create them with `crewai skill create`, publish them with `crewai skill publish`** — hand-rolling directories works for local experiments, but the CLI is the intended workflow and keeps your skill layout and frontmatter valid.
### Create
```shell Terminal theme={null}
crewai skill create my-skill
```
Scaffolds the directory (into `./skills/` inside a crew project) with a template `SKILL.md`, plus empty `scripts/`, `references/`, and `assets/` directories. Edit `SKILL.md` to define the instructions.
### Publish
Run from inside the skill directory (where `SKILL.md` is):
```shell Terminal theme={null}
cd skills/my-skill
crewai skill publish
```
Publishing reads `name`, `description`, and `metadata.version` from the `SKILL.md` frontmatter and pushes the skill to the CrewAI registry. **Published skills are always scoped to your organization** — like tools, only members of the publishing org can see and install them; there is no public visibility. Useful flags:
| Flag | Effect |
| :------------- | :---------------------------------------------------------- |
| `--org ` | Publish under a specific organization (overrides settings). |
| `--force` | Skip git-state validation (uncommitted changes, etc.). |
### Install
Install a published skill by its `@org/name` reference:
```shell Terminal theme={null}
crewai skill install @acme/code-review
```
Inside a crew project the skill lands in `./skills/{name}/`; outside a project it goes to the shared cache at `~/.crewai/skills/{org}/{name}/`.
Agents can also reference registry skills directly — they resolve from the local cache (or project `skills/` directory) at runtime:
```python theme={null}
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=["@acme/code-review"], # registry ref, resolved locally
)
```
### Pin a Version
An unpinned reference resolves to the newest published version, so publishing a
new version changes every agent that references it. Append `@` to pin
one instead:
```python theme={null}
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=["@acme/code-review@1.2.0"], # pinned; a leading "v" also works
)
```
A pinned reference re-downloads unless the copy it finds is that exact version —
a pin asks for a specific version rather than hinting at one. A cached skill is
matched on the version recorded when it was installed, so it needs nothing in
its frontmatter; a project-local copy under `skills/` has no such record, so it
is matched on `metadata.version` in its `SKILL.md` frontmatter. Pinning an
unpublished version fails rather than falling back to the latest.
Agents from the **Agent Repository** are pinned automatically: the repository
records a version alongside each skill it assigns, and the runtime applies those
pins when it loads the agent.
### List
```shell Terminal theme={null}
crewai skill list
```
Shows installed skills from both the project `./skills/` directory and the global cache, with their versions and paths.
***
## Crew-Level Skills
Skills can be set on a crew to apply to **all agents**:
```python theme={null}
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-level skills take priority — if the same skill is discovered at both levels, the agent's version is used.
***
## SKILL.md Format
```markdown theme={null}
---
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 Fields
| Field | Required | Description |
| :-------------- | :------- | :------------------------------------------------------------------------- |
| `name` | Yes | 1–64 chars. Lowercase alphanumeric and hyphens. Must match directory name. |
| `description` | Yes | 1–1024 chars. Describes what the skill does and when to use it. |
| `license` | No | License name or reference to a bundled license file. |
| `compatibility` | No | Max 500 chars. Environment requirements (products, packages, network). |
| `metadata` | No | Arbitrary string key-value mapping. |
| `allowed-tools` | No | Space-delimited list of pre-approved tools. Experimental. |
***
## Directory Structure
```
my-skill/
├── SKILL.md # Required — frontmatter + instructions
├── scripts/ # Optional — executable scripts
├── references/ # Optional — reference documents
└── assets/ # Optional — static files (configs, data)
```
The directory name must match the `name` field in `SKILL.md`. The `scripts/`, `references/`, and `assets/` directories are available on the skill's `path` for agents that need to reference files directly.
***
## Pre-loading Skills
For more control, you can discover and activate skills programmatically.
Passing an activated skill makes its instructions always-on:
```python theme={null}
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,
)
```
***
## How Skills Are Loaded
Skills use **progressive disclosure** — only loading what's needed at each stage:
| Stage | What's loaded | When |
| :--------- | :------------------------------------ | :--------------------------------------------- |
| Discovery | Name, description, frontmatter fields | Agent setup or `discover_skills()` |
| Activation | Full SKILL.md body text | Relevant runtime request or `activate_skill()` |
| Resources | Resource directory catalog | Explicit `load_resources()` call |
With `skills=["./skills"]`, the directory is discovered at setup but the full
instructions are not placed in every prompt. The agent reviews the metadata on
each execution and loads only a skill that applies. The loaded instructions are
scoped to that execution, so skills selected for earlier calls do not accumulate
on the agent.
Inline skill strings and `Skill` objects already activated with
`activate_skill()` remain always-on. This provides an explicit opt-in when the
instructions should apply to every request.
***
## Skills vs Knowledge
Both skills and knowledge modify the agent's prompt, but they serve different purposes:
| Aspect | Skills | Knowledge |
| :--------------------- | :------------------------------------ | :----------------------------------------- |
| **What it provides** | Instructions, procedures, guidelines | Facts, data, information |
| **How it's stored** | Markdown files (SKILL.md) | Embedded in vector store (ChromaDB) |
| **How it's retrieved** | Entire body injected into prompt | Semantic search finds relevant chunks |
| **Best for** | Methodology, checklists, style guides | Company docs, product info, reference data |
| **Set via** | `skills=["./skills"]` | `knowledge_sources=[source]` |
**Rule of thumb:** If the agent needs to follow a *process*, use a skill. If the agent needs to reference *data*, use knowledge.
***
## Common Questions
It depends on your use case. Skills and tools are **independent** — you can use either, both, or neither.
* **Skills alone**: When the agent needs expertise but no external actions (e.g., writing with style guidelines)
* **Tools alone**: When the agent needs actions but no special methodology (e.g., simple web search)
* **Both**: When the agent needs expertise AND actions (e.g., security audit with specific checklists AND ability to scan code)
**No.** The `allowed-tools` field in SKILL.md is experimental metadata only — it does not provision or inject any tools. You must always set tools separately via `tools=[]`, `mcps=[]`, or `apps=[]`.
The agent-level skill takes priority. Skills are deduplicated by name — the agent's skills are processed first, so if the same skill name appears at both levels, the agent's version is used.
There's a soft warning at 50,000 characters, but no hard limit. Keep skills focused and concise for best results — large prompt injections can dilute the agent's attention.