Skills

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.

Note

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:

crewai create skill 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 on crewai create skill):

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

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

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:

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:

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:

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:

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:

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 create skill, 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.

Note

crewai skill create is deprecated and still works with a warning. Use crewai create skill instead.

Create

crewai create skill 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):

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 <slug>`	Publish under a specific organization (overrides settings).
`--force`	Skip git-state validation (uncommitted changes, etc.).

Install

Install a published skill by its @org-uuid/name reference:

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

Note

Use your organization's UUID, not its name — organization names are not unique, so a name can resolve to the wrong organization and the install fails with a "not found" error. Run crewai org list to see the UUID (the ID column) of every organization you belong to.

Inside a crew project the skill lands in ./skills/{name}/; outside a project it goes to the shared cache at ~/.crewai/skills/{org-uuid}/{name}/.

Agents can also reference registry skills directly — they resolve from the local cache (or project skills/ directory) at runtime:

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
)

Pin a Version

An unpinned reference resolves to the newest published version, so publishing a new version changes every agent that references it. Append @<version> to pin one instead:

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
)

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.

Note

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

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:

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

---
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:

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.

Overview

Quick Start

1. Create a Skill with the CLI

2. Write Your SKILL.md

3. Attach to an Agent

Skills + Tools: Working Together

Pattern 1: Skills Only (Domain Expertise, No Actions Needed)

Pattern 2: Tools Only (Actions, No Special Expertise)

Pattern 3: Skills + Tools (Expertise AND Actions)

Pattern 4: Skills + MCPs

Pattern 5: Skills + Apps

Creating, Publishing, and Installing Skills

Create

Publish

Install

Pin a Version

List

Crew-Level Skills

SKILL.md Format

Frontmatter Fields

Directory Structure

Pre-loading Skills

How Skills Are Loaded

Skills vs Knowledge

Common Questions

Do I need to set skills AND tools?

Do skills automatically provide tools?

What happens if I set the same skill on both an agent and its crew?

How large can a SKILL.md body be?