Skills

Filesystem-based skill packages that inject context into agent prompts.

Overview

Skills are self-contained directories that provide agents with domain-specific instructions, references, and assets. Each skill is defined by a SKILL.md file with YAML frontmatter and a markdown body.

Skills use progressive disclosure — metadata is loaded first, full instructions only when activated, and resource catalogs only when needed.

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.

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, space-delimited
---

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	Constraints
name	Yes	1–64 chars. Lowercase alphanumeric and hyphens. No leading/trailing/consecutive 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.

Usage

Agent-level Skills

Pass skill directory paths to an agent:

from crewai import Agent

agent = Agent(
    role="Researcher",
    goal="Find relevant information",
    backstory="An expert researcher.",
    skills=["./skills"],  # discovers all skills in this directory
)

Crew-level Skills

Skill paths on a crew are merged into every agent:

from crewai import Crew

crew = Crew(
    agents=[agent],
    tasks=[task],
    skills=["./skills"],
)

Pre-loaded Skills

You can also pass Skill objects directly:

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

skills = discover_skills(Path("./skills"))
activated = [activate_skill(s) for s in skills]

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

How Skills Are Loaded

Skills load progressively — only the data needed at each stage is read:

Stage	What’s loaded	When
Discovery	Name, description, frontmatter fields	discover_skills()
Activation	Full SKILL.md body text	activate_skill()

During normal agent execution, skills are automatically discovered and activated. The scripts/, references/, and assets/ directories are available on the skill’s path for agents that need to reference files directly.