Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
feat: agent skills
Greyson LaLonde555ee462a31b
diff --git a/docs/docs.json b/docs/docs.jsonindex 42cf18b10..87fa3182f 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -155,6 +155,7 @@"en/concepts/flows","en/concepts/production-architecture","en/concepts/knowledge",+ "en/concepts/skills","en/concepts/llms","en/concepts/files","en/concepts/processes",@@ -1556,6 +1557,7 @@"en/concepts/flows","en/concepts/production-architecture","en/concepts/knowledge",+ "en/concepts/skills","en/concepts/llms","en/concepts/files","en/concepts/processes",@@ -2053,6 +2055,7 @@"pt-BR/concepts/flows","pt-BR/concepts/production-architecture","pt-BR/concepts/knowledge",+ "pt-BR/concepts/skills","pt-BR/concepts/llms","pt-BR/concepts/files","pt-BR/concepts/processes",@@ -3412,6 +3415,7 @@"pt-BR/concepts/flows","pt-BR/concepts/production-architecture","pt-BR/concepts/knowledge",+ "pt-BR/concepts/skills","pt-BR/concepts/llms","pt-BR/concepts/files","pt-BR/concepts/processes",@@ -3895,6 +3899,7 @@"ko/concepts/flows","ko/concepts/production-architecture","ko/concepts/knowledge",+ "ko/concepts/skills","ko/concepts/llms","ko/concepts/files","ko/concepts/processes",@@ -5290,6 +5295,7 @@"ko/concepts/flows","ko/concepts/production-architecture","ko/concepts/knowledge",+ "ko/concepts/skills","ko/concepts/llms","ko/concepts/files","ko/concepts/processes",diff --git a/docs/en/concepts/skills.mdx b/docs/en/concepts/skills.mdxnew file mode 100644index 000000000..90a7f822d--- /dev/null+++ b/docs/en/concepts/skills.mdx@@ -0,0 +1,115 @@+---+title: Skills+description: Filesystem-based skill packages that inject context into agent prompts.+icon: bolt+mode: "wide"+---++## 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++```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, 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:++```python+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:++```python+from crewai import Crew++crew = Crew(+ agents=[agent],+ tasks=[task],+ skills=["./skills"],+)+```++### Pre-loaded Skills++You can also pass `Skill` objects directly:++```python+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.+diff --git a/docs/ko/concepts/skills.mdx b/docs/ko/concepts/skills.mdxnew file mode 100644index 000000000..a6361bce2--- /dev/null+++ b/docs/ko/concepts/skills.mdx@@ -0,0 +1,114 @@+---+title: 스킬+description: 에이전트 프롬프트에 컨텍스트를 주입하는 파일 시스템 기반 스킬 패키지.+icon: bolt+mode: "wide"+---++## 개요++스킬은 에이전트에게 도메인별 지침, 참조 자료, 에셋을 제공하는 자체 포함 디렉터리입니다. 각 스킬은 YAML 프론트매터와 마크다운 본문이 포함된 `SKILL.md` 파일로 정의됩니다.++스킬은 **점진적 공개**를 사용합니다 — 메타데이터가 먼저 로드되고, 활성화 시에만 전체 지침이 로드되며, 필요할 때만 리소스 카탈로그가 로드됩니다.++## 디렉터리 구조++```+my-skill/+├── SKILL.md # 필수 — 프론트매터 + 지침+├── scripts/ # 선택 — 실행 가능한 스크립트+├── references/ # 선택 — 참조 문서+└── assets/ # 선택 — 정적 파일 (설정, 데이터)+```++디렉터리 이름은 `SKILL.md`의 `name` 필드와 일치해야 합니다.++## SKILL.md 형식++```markdown+---+name: my-skill+description: 이 스킬이 무엇을 하고 언제 사용하는지에 대한 간단한 설명.+license: Apache-2.0 # 선택+compatibility: crewai>=0.1.0 # 선택+metadata: # 선택+ author: your-name+ version: "1.0"+allowed-tools: web-search file-read # 선택, 공백으로 구분+---++에이전트를 위한 지침이 여기에 들어갑니다. 이 마크다운 본문은+스킬이 활성화되면 에이전트의 프롬프트에 주입됩니다.+```++### 프론트매터 필드++| 필드 | 필수 | 제약 조건 |+| :-------------- | :----- | :----------------------------------------------------------------------- |+| `name` | 예 | 1–64자. 소문자 영숫자와 하이픈. 선행/후행/연속 하이픈 불가. 디렉터리 이름과 일치 필수. |+| `description` | 예 | 1–1024자. 스킬이 무엇을 하고 언제 사용하는지 설명. |+| `license` | 아니오 | 라이선스 이름 또는 번들된 라이선스 파일 참조. |+| `compatibility` | 아니오 | 최대 500자. 환경 요구 사항 (제품, 패키지, 네트워크). |+| `metadata` | 아니오 | 임의의 문자열 키-값 매핑. |+| `allowed-tools` | 아니오 | 공백으로 구분된 사전 승인 도구 목록. 실험적. |++## 사용법++### 에이전트 레벨 스킬++에이전트에 스킬 디렉터리 경로를 전달합니다:++```python+from crewai import Agent++agent = Agent(+ role="Researcher",+ goal="Find relevant information",+ backstory="An expert researcher.",+ skills=["./skills"], # 이 디렉터리의 모든 스킬을 검색+)+```++### 크루 레벨 스킬++크루의 스킬 경로는 모든 에이전트에 병합됩니다:++```python+from crewai import Crew++crew = Crew(+ agents=[agent],+ tasks=[task],+ skills=["./skills"],+)+```++### 사전 로드된 스킬++`Skill` 객체를 직접 전달할 수도 있습니다:++```python+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,+)+```++## 스킬 로드 방식++스킬은 점진적으로 로드됩니다 — 각 단계에서 필요한 데이터만 읽습니다:++| 단계 | 로드되는 내용 | 시점 |+| :--------------- | :------------------------------------------------ | :----------------- |+| 검색 | 이름, 설명, 프론트매터 필드 | `discover_skills()` |+| 활성화 | 전체 SKILL.md 본문 텍스트 | `activate_skill()` |++일반적인 에이전트 실행 중에 스킬은 자동으로 검색되고 활성화됩니다. `scripts/`, `references/`, `assets/` 디렉터리는 파일을 직접 참조해야 하는 에이전트를 위해 스킬의 `path`에서 사용할 수 있습니다.diff --git a/docs/pt-BR/concepts/skills.mdx b/docs/pt-BR/concepts/skills.mdxnew file mode 100644index 000000000..1af37f9e2--- /dev/null+++ b/docs/pt-BR/concepts/skills.mdx@@ -0,0 +1,114 @@+---+title: Skills+description: Pacotes de skills baseados em sistema de arquivos que injetam contexto nos prompts dos agentes.+icon: bolt+mode: "wide"+---++## Visão Geral++Skills são diretórios autocontidos que fornecem aos agentes instruções, referências e assets específicos de domínio. Cada skill é definida por um arquivo `SKILL.md` com frontmatter YAML e um corpo em markdown.++Skills usam **divulgação progressiva** — metadados são carregados primeiro, instruções completas apenas quando ativadas, e catálogos de recursos apenas quando necessário.++## Estrutura de Diretório++```+my-skill/+├── SKILL.md # Obrigatório — frontmatter + instruções+├── scripts/ # Opcional — scripts executáveis+├── references/ # Opcional — documentos de referência+└── assets/ # Opcional — arquivos estáticos (configs, dados)+```++O nome do diretório deve corresponder ao campo `name` no `SKILL.md`.++## Formato do SKILL.md++```markdown+---+name: my-skill+description: Descrição curta do que esta skill faz e quando usá-la.+license: Apache-2.0 # opcional+compatibility: crewai>=0.1.0 # opcional+metadata: # opcional+ author: your-name+ version: "1.0"+allowed-tools: web-search file-read # opcional, delimitado por espaços+---++Instruções para o agente vão aqui. Este corpo em markdown é injetado+no prompt do agente quando a skill é ativada.+```++### Campos do Frontmatter++| Campo | Obrigatório | Restrições |+| :-------------- | :---------- | :----------------------------------------------------------------------- |+| `name` | Sim | 1–64 chars. Alfanumérico minúsculo e hifens. Sem hifens iniciais/finais/consecutivos. Deve corresponder ao nome do diretório. |+| `description` | Sim | 1–1024 chars. Descreve o que a skill faz e quando usá-la. |+| `license` | Não | Nome da licença ou referência a um arquivo de licença incluído. |+| `compatibility` | Não | Máx 500 chars. Requisitos de ambiente (produtos, pacotes, rede). |+| `metadata` | Não | Mapeamento arbitrário de chave-valor string. |+| `allowed-tools` | Não | Lista de ferramentas pré-aprovadas delimitada por espaços. Experimental. |++## Uso++### Skills no Nível do Agente++Passe caminhos de diretório de skills para um agente:++```python+from crewai import Agent++agent = Agent(+ role="Researcher",+ goal="Find relevant information",+ backstory="An expert researcher.",+ skills=["./skills"], # descobre todas as skills neste diretório+)+```++### Skills no Nível do Crew++Caminhos de skills no crew são mesclados em todos os agentes:++```python+from crewai import Crew++crew = Crew(+ agents=[agent],+ tasks=[task],+ skills=["./skills"],+)+```++### Skills Pré-carregadas++Você também pode passar objetos `Skill` diretamente:++```python+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,+)+```++## Como as Skills São Carregadas++Skills carregam progressivamente — apenas os dados necessários em cada etapa são lidos:++| Etapa | O que é carregado | Quando |+| :--------------- | :------------------------------------------------ | :------------------ |+| Descoberta | Nome, descrição, campos do frontmatter | `discover_skills()` |+| Ativação | Texto completo do corpo do SKILL.md | `activate_skill()` |++Durante a execução normal do agente, skills são automaticamente descobertas e ativadas. Os diretórios `scripts/`, `references/` e `assets/` estão disponíveis no `path` da skill para agentes que precisam referenciar arquivos diretamente.diff --git a/lib/crewai/pyproject.toml b/lib/crewai/pyproject.tomlindex 80a4976bc..9c4b78ec5 100644--- a/lib/crewai/pyproject.toml+++ b/lib/crewai/pyproject.toml@@ -42,6 +42,7 @@ dependencies = ["mcp~=1.26.0","uv~=0.9.13","aiosqlite~=0.21.0",+ "pyyaml~=6.0","lancedb>=0.29.2",]diff --git a/lib/crewai/src/crewai/agent/core.py b/lib/crewai/src/crewai/agent/core.pyindex 3aa48137d..868c14344 100644--- a/lib/crewai/src/crewai/agent/core.py+++ b/lib/crewai/src/crewai/agent/core.py@@ -3,6 +3,7 @@ from __future__ import annotationsimport asynciofrom collections.abc import Callable, Coroutine, Sequenceimport contextvars+from pathlib import Pathimport shutilimport subprocessimport time@@ -26,6 +27,7 @@ from typing_extensions import Selffrom crewai.agent.planning_config import PlanningConfigfrom crewai.agent.utils import (ahandle_knowledge_retrieval,+ append_skill_context,apply_training_data,build_task_prompt_with_schema,format_task_with_context,@@ -65,6 +67,8 @@ from crewai.mcp import MCPServerConfigfrom crewai.mcp.tool_resolver import MCPToolResolverfrom crewai.rag.embeddings.types import EmbedderConfigfrom crewai.security.fingerprint import Fingerprint+from crewai.skills.loader import activate_skill, discover_skills+from crewai.skills.models import INSTRUCTIONS, Skill as SkillModelfrom crewai.tools.agent_tools.agent_tools import AgentToolsfrom crewai.types.callback import SerializableCallablefrom crewai.utilities.agent_utils import (@@ -278,6 +282,8 @@ class Agent(BaseAgent):if self.allow_code_execution:self._validate_docker_installation()+ self.set_skills()+# Handle backward compatibility: convert reasoning=True to planning_configif self.reasoning and self.planning_config is None:import warnings@@ -321,6 +327,76 @@ class Agent(BaseAgent):except (TypeError, ValueError) as e:raise ValueError(f"Invalid Knowledge Configuration: {e!s}") from e+ def set_skills(+ self,+ resolved_crew_skills: list[SkillModel] | None = None,+ ) -> None:+ """Resolve skill paths and activate skills to INSTRUCTIONS level.++ Path entries trigger discovery and activation. Pre-loaded Skill objects+ below INSTRUCTIONS level are activated. Crew-level skills are merged in+ with event emission so observability is consistent regardless of origin.++ Args:+ resolved_crew_skills: Pre-resolved crew skills (already discovered+ and activated). When provided, avoids redundant discovery per agent.+ """+ from crewai.crew import Crew+ from crewai.events.event_bus import crewai_event_bus+ from crewai.events.types.skill_events import SkillActivatedEvent++ if resolved_crew_skills is None:+ crew_skills: list[Path | SkillModel] | None = (+ self.crew.skills+ if isinstance(self.crew, Crew) and isinstance(self.crew.skills, list)+ else None+ )+ else:+ crew_skills = list(resolved_crew_skills)++ if not self.skills and not crew_skills:+ return++ needs_work = self.skills and any(+ isinstance(s, Path)+ or (isinstance(s, SkillModel) and s.disclosure_level < INSTRUCTIONS)+ for s in self.skills+ )+ if not needs_work and not crew_skills:+ return++ seen: set[str] = set()+ resolved: list[Path | SkillModel] = []+ items: list[Path | SkillModel] = list(self.skills) if self.skills else []++ if crew_skills:+ items.extend(crew_skills)++ for item in items:+ if isinstance(item, Path):+ discovered = discover_skills(item, source=self)+ for skill in discovered:+ if skill.name not in seen:+ seen.add(skill.name)+ resolved.append(activate_skill(skill, source=self))+ elif isinstance(item, SkillModel):+ if item.name not in seen:+ seen.add(item.name)+ activated = activate_skill(item, source=self)+ if activated is item and item.disclosure_level >= INSTRUCTIONS:+ crewai_event_bus.emit(+ self,+ event=SkillActivatedEvent(+ from_agent=self,+ skill_name=item.name,+ skill_path=item.path,+ disclosure_level=item.disclosure_level,+ ),+ )+ resolved.append(activated)++ self.skills = resolved if resolved else None+def _is_any_available_memory(self) -> bool:"""Check if unified memory is available (agent or crew)."""if getattr(self, "memory", None):@@ -442,6 +518,8 @@ class Agent(BaseAgent):self.crew.query_knowledge if self.crew else lambda *a, **k: None,)+ task_prompt = append_skill_context(self, task_prompt)+prepare_tools(self, tools, task)task_prompt = apply_training_data(self, task_prompt)@@ -682,6 +760,8 @@ class Agent(BaseAgent):self, task, task_prompt, knowledge_config)+ task_prompt = append_skill_context(self, task_prompt)+prepare_tools(self, tools, task)task_prompt = apply_training_data(self, task_prompt)@@ -1343,6 +1423,8 @@ class Agent(BaseAgent):),)+ formatted_messages = append_skill_context(self, formatted_messages)+# Build the input dict for the executorinputs: dict[str, Any] = {"input": formatted_messages,diff --git a/lib/crewai/src/crewai/agent/utils.py b/lib/crewai/src/crewai/agent/utils.pyindex fc74db433..88accddf3 100644--- a/lib/crewai/src/crewai/agent/utils.py+++ b/lib/crewai/src/crewai/agent/utils.py@@ -210,6 +210,30 @@ def _combine_knowledge_context(agent: Agent) -> str:return agent_ctx + separator + crew_ctx+def append_skill_context(agent: Agent, task_prompt: str) -> str:+ """Append activated skill context sections to the task prompt.++ Args:+ agent: The agent with optional skills.+ task_prompt: The current task prompt.++ Returns:+ The task prompt with skill context appended.+ """+ if not agent.skills:+ return task_prompt++ from crewai.skills.loader import format_skill_context+ from crewai.skills.models import Skill++ skill_sections = [+ format_skill_context(s) for s in agent.skills if isinstance(s, Skill)+ ]+ if skill_sections:+ task_prompt += "\n\n" + "\n\n".join(skill_sections)+ return task_prompt++def apply_training_data(agent: Agent, task_prompt: str) -> str:"""Apply training data to the task prompt.diff --git a/lib/crewai/src/crewai/agents/agent_builder/base_agent.py b/lib/crewai/src/crewai/agents/agent_builder/base_agent.pyindex 674b15fa8..9949343e2 100644--- a/lib/crewai/src/crewai/agents/agent_builder/base_agent.py+++ b/lib/crewai/src/crewai/agents/agent_builder/base_agent.py@@ -3,6 +3,7 @@ from __future__ import annotationsfrom abc import ABC, abstractmethodfrom copy import copy as shallow_copyfrom hashlib import md5+from pathlib import Pathimport refrom typing import Any, Final, Literalimport uuid@@ -32,6 +33,7 @@ from crewai.memory.memory_scope import MemoryScope, MemorySlicefrom crewai.memory.unified_memory import Memoryfrom crewai.rag.embeddings.types import EmbedderConfigfrom crewai.security.security_config import SecurityConfig+from crewai.skills.models import Skillfrom crewai.tools.base_tool import BaseTool, Toolfrom crewai.types.callback import SerializableCallablefrom crewai.utilities.config import process_config@@ -217,6 +219,11 @@ class BaseAgent(BaseModel, ABC, metaclass=AgentMeta):"If not set, falls back to crew memory."),)+ skills: list[Path | Skill] | None = Field(+ default=None,+ description="Agent Skills. Accepts paths for discovery or pre-loaded Skill objects.",+ min_length=1,+ )@model_validator(mode="before")@classmethod@@ -500,3 +507,6 @@ class BaseAgent(BaseModel, ABC, metaclass=AgentMeta):def set_knowledge(self, crew_embedder: EmbedderConfig | None = None) -> None:pass++ def set_skills(self, resolved_crew_skills: list[Any] | None = None) -> None:+ passdiff --git a/lib/crewai/src/crewai/crew.py b/lib/crewai/src/crewai/crew.pyindex e130dce7b..00fbae78f 100644--- a/lib/crewai/src/crewai/crew.py+++ b/lib/crewai/src/crewai/crew.py@@ -6,6 +6,7 @@ from concurrent.futures import Futurefrom copy import copy as shallow_copyfrom hashlib import md5import json+from pathlib import Pathimport refrom typing import (TYPE_CHECKING,@@ -91,6 +92,7 @@ from crewai.rag.embeddings.types import EmbedderConfigfrom crewai.rag.types import SearchResultfrom crewai.security.fingerprint import Fingerprintfrom crewai.security.security_config import SecurityConfig+from crewai.skills.models import Skillfrom crewai.task import Taskfrom crewai.tasks.conditional_task import ConditionalTaskfrom crewai.tasks.task_output import TaskOutput@@ -294,6 +296,11 @@ class Crew(FlowTrackable, BaseModel):default=None,description="Knowledge for the crew.",)+ skills: list[Path | Skill] | None = Field(+ default=None,+ description="Skill search paths or pre-loaded Skill objects applied to all agents in the crew.",+ )+security_config: SecurityConfig = Field(default_factory=SecurityConfig,description="Security configuration for the crew, including fingerprinting.",@@ -376,7 +383,7 @@ class Crew(FlowTrackable, BaseModel):if self.embedder is not None:from crewai.rag.embeddings.factory import build_embedder- embedder = build_embedder(self.embedder) # type: ignore[arg-type]+ embedder = build_embedder(cast(dict[str, Any], self.embedder))self._memory = Memory(embedder=embedder, root_scope=crew_root_scope)elif self.memory:# User passed a Memory / MemoryScope / MemorySlice instancediff --git a/lib/crewai/src/crewai/crews/utils.py b/lib/crewai/src/crewai/crews/utils.pyindex a432d2fc2..0b50e60bb 100644--- a/lib/crewai/src/crewai/crews/utils.py+++ b/lib/crewai/src/crewai/crews/utils.py@@ -4,6 +4,7 @@ from __future__ import annotationsimport asynciofrom collections.abc import Callable, Coroutine, Iterable, Mapping+from pathlib import Pathfrom typing import TYPE_CHECKING, Anyfrom opentelemetry import baggage@@ -11,6 +12,8 @@ from opentelemetry import baggagefrom crewai.agents.agent_builder.base_agent import BaseAgentfrom crewai.crews.crew_output import CrewOutputfrom crewai.rag.embeddings.types import EmbedderConfig+from crewai.skills.loader import activate_skill, discover_skills+from crewai.skills.models import INSTRUCTIONS, Skill as SkillModelfrom crewai.types.streaming import CrewStreamingOutput, FlowStreamingOutputfrom crewai.utilities.file_store import store_filesfrom crewai.utilities.streaming import (@@ -51,6 +54,30 @@ def enable_agent_streaming(agents: Iterable[BaseAgent]) -> None:agent.llm.stream = True+def _resolve_crew_skills(crew: Crew) -> list[SkillModel] | None:+ """Resolve crew-level skill paths once so agents don't repeat the work."""+ if not isinstance(crew.skills, list) or not crew.skills:+ return None++ resolved: list[SkillModel] = []+ seen: set[str] = set()+ for item in crew.skills:+ if isinstance(item, Path):+ for skill in discover_skills(item):+ if skill.name not in seen:+ seen.add(skill.name)+ resolved.append(activate_skill(skill))+ elif isinstance(item, SkillModel):+ if item.name not in seen:+ seen.add(item.name)+ resolved.append(+ activate_skill(item)+ if item.disclosure_level < INSTRUCTIONS+ else item+ )+ return resolved++def setup_agents(crew: Crew,agents: Iterable[BaseAgent],@@ -67,9 +94,12 @@ def setup_agents(function_calling_llm: Default function calling LLM for agents.step_callback: Default step callback for agents."""+ resolved_crew_skills = _resolve_crew_skills(crew)+for agent in agents:agent.crew = crewagent.set_knowledge(crew_embedder=embedder)+ agent.set_skills(resolved_crew_skills=resolved_crew_skills)if not agent.function_calling_llm: # type: ignore[attr-defined]agent.function_calling_llm = function_calling_llm # type: ignore[attr-defined]if not agent.step_callback: # type: ignore[attr-defined]diff --git a/lib/crewai/src/crewai/events/__init__.py b/lib/crewai/src/crewai/events/__init__.pyindex 36933fc45..bcdafe49a 100644--- a/lib/crewai/src/crewai/events/__init__.py+++ b/lib/crewai/src/crewai/events/__init__.py@@ -88,6 +88,14 @@ from crewai.events.types.reasoning_events import (AgentReasoningStartedEvent,ReasoningEvent,)+from crewai.events.types.skill_events import (+ SkillActivatedEvent,+ SkillDiscoveryCompletedEvent,+ SkillDiscoveryStartedEvent,+ SkillEvent,+ SkillLoadFailedEvent,+ SkillLoadedEvent,+)from crewai.events.types.task_events import (TaskCompletedEvent,TaskEvaluationEvent,@@ -186,6 +194,12 @@ __all__ = ["MethodExecutionFinishedEvent","MethodExecutionStartedEvent","ReasoningEvent",+ "SkillActivatedEvent",+ "SkillDiscoveryCompletedEvent",+ "SkillDiscoveryStartedEvent",+ "SkillEvent",+ "SkillLoadFailedEvent",+ "SkillLoadedEvent","TaskCompletedEvent","TaskEvaluationEvent","TaskFailedEvent",diff --git a/lib/crewai/src/crewai/events/types/skill_events.py b/lib/crewai/src/crewai/events/types/skill_events.pynew file mode 100644index 000000000..f99d6bd70--- /dev/null+++ b/lib/crewai/src/crewai/events/types/skill_events.py@@ -0,0 +1,62 @@+"""Skill lifecycle events for the Agent Skills standard.++Events emitted during skill discovery, loading, and activation.+"""++from __future__ import annotations++from pathlib import Path+from typing import Any++from crewai.events.base_events import BaseEvent+++class SkillEvent(BaseEvent):+ """Base event for skill operations."""++ skill_name: str = ""+ skill_path: Path | None = None+ from_agent: Any | None = None+ from_task: Any | None = None++ def __init__(self, **data: Any) -> None:+ super().__init__(**data)+ self._set_agent_params(data)+ self._set_task_params(data)+++class SkillDiscoveryStartedEvent(SkillEvent):+ """Event emitted when skill discovery begins."""++ type: str = "skill_discovery_started"+ search_path: Path+++class SkillDiscoveryCompletedEvent(SkillEvent):+ """Event emitted when skill discovery completes."""++ type: str = "skill_discovery_completed"+ search_path: Path+ skills_found: int+ skill_names: list[str]+++class SkillLoadedEvent(SkillEvent):+ """Event emitted when a skill is loaded at metadata level."""++ type: str = "skill_loaded"+ disclosure_level: int = 1+++class SkillActivatedEvent(SkillEvent):+ """Event emitted when a skill is activated (promoted to instructions level)."""++ type: str = "skill_activated"+ disclosure_level: int = 2+++class SkillLoadFailedEvent(SkillEvent):+ """Event emitted when skill loading fails."""++ type: str = "skill_load_failed"+ error: strdiff --git a/lib/crewai/src/crewai/skills/__init__.py b/lib/crewai/src/crewai/skills/__init__.pynew file mode 100644index 000000000..e33e98570--- /dev/null+++ b/lib/crewai/src/crewai/skills/__init__.py@@ -0,0 +1,17 @@+"""Agent Skills standard implementation for crewAI.++Provides filesystem-based skill packaging with progressive disclosure.+"""++from crewai.skills.loader import activate_skill, discover_skills+from crewai.skills.models import Skill, SkillFrontmatter+from crewai.skills.parser import SkillParseError+++__all__ = [+ "Skill",+ "SkillFrontmatter",+ "SkillParseError",+ "activate_skill",+ "discover_skills",+]diff --git a/lib/crewai/src/crewai/skills/loader.py b/lib/crewai/src/crewai/skills/loader.pynew file mode 100644index 000000000..78e244f90--- /dev/null+++ b/lib/crewai/src/crewai/skills/loader.py@@ -0,0 +1,184 @@+"""Filesystem discovery and progressive loading for Agent Skills.++Provides functions to discover skills in directories, activate them+for agent use, and format skill context for prompt injection.+"""++from __future__ import annotations++import logging+from pathlib import Path+from typing import TYPE_CHECKING++from crewai.events.event_bus import crewai_event_bus+from crewai.events.types.skill_events import (+ SkillActivatedEvent,+ SkillDiscoveryCompletedEvent,+ SkillDiscoveryStartedEvent,+ SkillLoadFailedEvent,+ SkillLoadedEvent,+)+from crewai.skills.models import INSTRUCTIONS, RESOURCES, Skill+from crewai.skills.parser import (+ SKILL_FILENAME,+ load_skill_instructions,+ load_skill_metadata,+ load_skill_resources,+)+++if TYPE_CHECKING:+ from crewai.agents.agent_builder.base_agent import BaseAgent++_logger = logging.getLogger(__name__)+++def discover_skills(+ search_path: Path,+ source: BaseAgent | None = None,+) -> list[Skill]:+ """Scan a directory for skill directories containing SKILL.md.++ Loads each discovered skill at METADATA disclosure level.++ Args:+ search_path: Directory to scan for skill subdirectories.+ source: Optional event source (agent or crew) for event emission.++ Returns:+ List of Skill instances at METADATA level.+ """+ if not search_path.is_dir():+ msg = f"Skill search path does not exist or is not a directory: {search_path}"+ raise FileNotFoundError(msg)++ skills: list[Skill] = []++ if source is not None:+ crewai_event_bus.emit(+ source,+ event=SkillDiscoveryStartedEvent(+ from_agent=source,+ search_path=search_path,+ ),+ )++ for child in sorted(search_path.iterdir()):+ if not child.is_dir():+ continue+ skill_md = child / SKILL_FILENAME+ if not skill_md.is_file():+ continue+ try:+ skill = load_skill_metadata(child)+ skills.append(skill)+ if source is not None:+ crewai_event_bus.emit(+ source,+ event=SkillLoadedEvent(+ from_agent=source,+ skill_name=skill.name,+ skill_path=skill.path,+ disclosure_level=skill.disclosure_level,+ ),+ )+ except Exception as e:+ _logger.warning("Failed to load skill from %s: %s", child, e)+ if source is not None:+ crewai_event_bus.emit(+ source,+ event=SkillLoadFailedEvent(+ from_agent=source,+ skill_name=child.name,+ skill_path=child,+ error=str(e),+ ),+ )++ if source is not None:+ crewai_event_bus.emit(+ source,+ event=SkillDiscoveryCompletedEvent(+ from_agent=source,+ search_path=search_path,+ skills_found=len(skills),+ skill_names=[s.name for s in skills],+ ),+ )++ return skills+++def activate_skill(+ skill: Skill,+ source: BaseAgent | None = None,+) -> Skill:+ """Promote a skill to INSTRUCTIONS disclosure level.++ Idempotent: returns the skill unchanged if already at or above INSTRUCTIONS.++ Args:+ skill: Skill to activate.+ source: Optional event source for event emission.++ Returns:+ Skill at INSTRUCTIONS level or higher.+ """+ if skill.disclosure_level >= INSTRUCTIONS:+ return skill++ activated = load_skill_instructions(skill)++ if source is not None:+ crewai_event_bus.emit(+ source,+ event=SkillActivatedEvent(+ from_agent=source,+ skill_name=activated.name,+ skill_path=activated.path,+ disclosure_level=activated.disclosure_level,+ ),+ )++ return activated+++def load_resources(skill: Skill) -> Skill:+ """Promote a skill to RESOURCES disclosure level.++ Args:+ skill: Skill to promote.++ Returns:+ Skill at RESOURCES level.+ """+ return load_skill_resources(skill)+++def format_skill_context(skill: Skill) -> str:+ """Format skill information for agent prompt injection.++ At METADATA level: returns name and description only.+ At INSTRUCTIONS level or above: returns full SKILL.md body.++ Args:+ skill: The skill to format.++ Returns:+ Formatted skill context string.+ """+ if skill.disclosure_level >= INSTRUCTIONS and skill.instructions:+ parts = [+ f"## Skill: {skill.name}",+ skill.description,+ "",+ skill.instructions,+ ]+ if skill.disclosure_level >= RESOURCES and skill.resource_files:+ parts.append("")+ parts.append("### Available Resources")+ for dir_name, files in sorted(skill.resource_files.items()):+ if files:+ parts.append(f"- **{dir_name}/**: {', '.join(files)}")+ return "\n".join(parts)+ return f"## Skill: {skill.name}\n{skill.description}"diff --git a/lib/crewai/src/crewai/skills/models.py b/lib/crewai/src/crewai/skills/models.pynew file mode 100644index 000000000..cde2b4f3b--- /dev/null+++ b/lib/crewai/src/crewai/skills/models.py@@ -0,0 +1,175 @@+"""Pydantic data models for the Agent Skills standard.++Defines DisclosureLevel, SkillFrontmatter, and Skill models for+progressive disclosure of skill information.+"""++from __future__ import annotations++from pathlib import Path+from typing import Annotated, Any, Final, Literal++from pydantic import BaseModel, ConfigDict, Field, model_validator++from crewai.skills.validation import (+ MAX_SKILL_NAME_LENGTH,+ MIN_SKILL_NAME_LENGTH,+ SKILL_NAME_PATTERN,+)+++MAX_DESCRIPTION_LENGTH: Final[int] = 1024+ResourceDirName = Literal["scripts", "references", "assets"]+++DisclosureLevel = Annotated[+ Literal[1, 2, 3], "Progressive disclosure levels for skill loading."+]++METADATA: Final[+ Annotated[+ DisclosureLevel, "Only frontmatter metadata is loaded (name, description)."+ ]+] = 1+INSTRUCTIONS: Final[Annotated[DisclosureLevel, "Full SKILL.md body is loaded."]] = 2+RESOURCES: Final[+ Annotated[+ DisclosureLevel,+ "Resource directories (scripts, references, assets) are cataloged.",+ ]+] = 3+++class SkillFrontmatter(BaseModel):+ """YAML frontmatter from a SKILL.md file.++ Attributes:+ name: Unique skill identifier (1-64 chars, lowercase alphanumeric + hyphens).+ description: Human-readable description (1-1024 chars).+ license: Optional license name or reference.+ compatibility: Optional compatibility information (max 500 chars).+ metadata: Optional additional metadata as string key-value pairs.+ allowed_tools: Optional space-delimited list of pre-approved tools.+ """++ model_config = ConfigDict(frozen=True, populate_by_name=True)++ name: str = Field(+ min_length=MIN_SKILL_NAME_LENGTH,+ max_length=MAX_SKILL_NAME_LENGTH,+ pattern=SKILL_NAME_PATTERN,+ )+ description: str = Field(min_length=1, max_length=MAX_DESCRIPTION_LENGTH)+ license: str | None = Field(+ default=None,+ description="SPDX license identifier or free-text license reference, e.g. 'MIT', 'Apache-2.0'.",+ )+ compatibility: str | None = Field(+ default=None,+ max_length=500,+ description="Version or platform constraints for the skill, e.g. 'crewai >= 0.80'.",+ )+ metadata: dict[str, str] | None = Field(+ default=None,+ description="Arbitrary string key-value pairs for custom skill metadata.",+ )+ allowed_tools: list[str] | None = Field(+ default=None,+ alias="allowed-tools",+ description="Pre-approved tool names the skill may use, parsed from a space-delimited string in frontmatter.",+ )++ @model_validator(mode="before")+ @classmethod+ def parse_allowed_tools(cls, values: dict[str, Any]) -> dict[str, Any]:+ """Parse space-delimited allowed-tools string into a list."""+ key = "allowed-tools"+ alt_key = "allowed_tools"+ raw = values.get(key) or values.get(alt_key)+ if isinstance(raw, str):+ values[key] = raw.split()+ return values+++class Skill(BaseModel):+ """A loaded Agent Skill with progressive disclosure support.++ Attributes:+ frontmatter: Parsed YAML frontmatter.+ instructions: Full SKILL.md body text (populated at INSTRUCTIONS level).+ path: Filesystem path to the skill directory.+ disclosure_level: Current disclosure level of the skill.+ resource_files: Cataloged resource files (populated at RESOURCES level).+ """++ frontmatter: SkillFrontmatter = Field(+ description="Parsed YAML frontmatter from SKILL.md.",+ )+ instructions: str | None = Field(+ default=None,+ description="Full SKILL.md body text, populated at INSTRUCTIONS level.",+ )+ path: Path = Field(+ description="Filesystem path to the skill directory.",+ )+ disclosure_level: DisclosureLevel = Field(+ default=METADATA,+ description="Current progressive disclosure level of the skill.",+ )+ resource_files: dict[ResourceDirName, list[str]] | None = Field(+ default=None,+ description="Cataloged resource files by directory, populated at RESOURCES level.",+ )++ @property+ def name(self) -> str:+ """Skill name from frontmatter."""+ return self.frontmatter.name++ @property+ def description(self) -> str:+ """Skill description from frontmatter."""+ return self.frontmatter.description++ @property+ def scripts_dir(self) -> Path:+ """Path to the scripts directory."""+ return self.path / "scripts"++ @property+ def references_dir(self) -> Path:+ """Path to the references directory."""+ return self.path / "references"++ @property+ def assets_dir(self) -> Path:+ """Path to the assets directory."""+ return self.path / "assets"++ def with_disclosure_level(+ self,+ level: DisclosureLevel,+ instructions: str | None = None,+ resource_files: dict[ResourceDirName, list[str]] | None = None,+ ) -> Skill:+ """Create a new Skill at a different disclosure level.++ Args:+ level: The new disclosure level.+ instructions: Optional instructions body text.+ resource_files: Optional cataloged resource files.++ Returns:+ A new Skill instance at the specified disclosure level.+ """+ return Skill(+ frontmatter=self.frontmatter,+ instructions=instructions+ if instructions is not None+ else self.instructions,+ path=self.path,+ disclosure_level=level,+ resource_files=(+ resource_files if resource_files is not None else self.resource_files+ ),+ )diff --git a/lib/crewai/src/crewai/skills/parser.py b/lib/crewai/src/crewai/skills/parser.pynew file mode 100644index 000000000..d935e6ad1--- /dev/null+++ b/lib/crewai/src/crewai/skills/parser.py@@ -0,0 +1,194 @@+"""SKILL.md file parsing for the Agent Skills standard.++Parses YAML frontmatter and markdown body from SKILL.md files,+and provides progressive loading functions for skill data.+"""++from __future__ import annotations++import logging+from pathlib import Path+import re+from typing import Any, Final++import yaml++from crewai.skills.models import (+ INSTRUCTIONS,+ METADATA,+ RESOURCES,+ ResourceDirName,+ Skill,+ SkillFrontmatter,+)+from crewai.skills.validation import validate_directory_name+++_logger = logging.getLogger(__name__)+++SKILL_FILENAME: Final[str] = "SKILL.md"+_CLOSING_DELIMITER: Final[re.Pattern[str]] = re.compile(r"\n---[ \t]*(?:\n|$)")+_MAX_BODY_CHARS: Final[int] = 50_000+++class SkillParseError(ValueError):+ """Error raised when SKILL.md parsing fails."""+++def parse_frontmatter(content: str) -> tuple[dict[str, Any], str]:+ """Split SKILL.md content into frontmatter dict and body text.++ Args:+ content: Raw SKILL.md file content.++ Returns:+ Tuple of (frontmatter dict, body text).++ Raises:+ SkillParseError: If frontmatter delimiters are missing or YAML is invalid.+ """+ if not content.startswith("---"):+ msg = "SKILL.md must start with '---' frontmatter delimiter"+ raise SkillParseError(msg)++ match = _CLOSING_DELIMITER.search(content, pos=3)+ if match is None:+ msg = "SKILL.md missing closing '---' frontmatter delimiter"+ raise SkillParseError(msg)++ yaml_content = content[3 : match.start()].strip()+ body = content[match.end() :].strip()++ try:+ frontmatter = yaml.safe_load(yaml_content)+ except yaml.YAMLError as e:+ msg = f"Invalid YAML in frontmatter: {e}"+ raise SkillParseError(msg) from e++ if not isinstance(frontmatter, dict):+ msg = "Frontmatter must be a YAML mapping"+ raise SkillParseError(msg)++ return frontmatter, body+++def parse_skill_md(path: Path) -> tuple[SkillFrontmatter, str]:+ """Read and parse a SKILL.md file.++ Args:+ path: Path to the SKILL.md file.++ Returns:+ Tuple of (SkillFrontmatter, body text).++ Raises:+ FileNotFoundError: If the file does not exist.+ SkillParseError: If parsing fails.+ """+ content = path.read_text(encoding="utf-8")+ frontmatter_dict, body = parse_frontmatter(content)+ frontmatter = SkillFrontmatter(**frontmatter_dict)+ return frontmatter, body+++def load_skill_metadata(skill_dir: Path) -> Skill:+ """Load a skill at METADATA disclosure level.++ Parses SKILL.md frontmatter only and validates directory name.++ Args:+ skill_dir: Path to the skill directory.++ Returns:+ Skill instance at METADATA level.++ Raises:+ FileNotFoundError: If SKILL.md is missing.+ SkillParseError: If parsing fails.+ ValueError: If directory name doesn't match skill name.+ """+ skill_md_path = skill_dir / SKILL_FILENAME+ frontmatter, body = parse_skill_md(skill_md_path)+ validate_directory_name(skill_dir, frontmatter.name)+ if len(body) > _MAX_BODY_CHARS:+ _logger.warning(+ "SKILL.md body for '%s' is %d chars (threshold: %d). "+ "Large bodies may consume significant context window when injected into prompts.",+ frontmatter.name,+ len(body),+ _MAX_BODY_CHARS,+ )+ return Skill(+ frontmatter=frontmatter,+ path=skill_dir,+ disclosure_level=METADATA,+ )+++def load_skill_instructions(skill: Skill) -> Skill:+ """Promote a skill to INSTRUCTIONS disclosure level.++ Reads the full SKILL.md body text.++ Args:+ skill: Skill at METADATA level.++ Returns:+ New Skill instance at INSTRUCTIONS level.+ """+ if skill.disclosure_level >= INSTRUCTIONS:+ return skill++ skill_md_path = skill.path / SKILL_FILENAME+ _, body = parse_skill_md(skill_md_path)+ if len(body) > _MAX_BODY_CHARS:+ _logger.warning(+ "SKILL.md body for '%s' is %d chars (threshold: %d). "+ "Large bodies may consume significant context window when injected into prompts.",+ skill.name,+ len(body),+ _MAX_BODY_CHARS,+ )+ return skill.with_disclosure_level(+ level=INSTRUCTIONS,+ instructions=body,+ )+++def load_skill_resources(skill: Skill) -> Skill:+ """Promote a skill to RESOURCES disclosure level.++ Catalogs available resource directories (scripts, references, assets).++ Args:+ skill: Skill at any level.++ Returns:+ New Skill instance at RESOURCES level.+ """+ if skill.disclosure_level >= RESOURCES:+ return skill++ if skill.disclosure_level < INSTRUCTIONS:+ skill = load_skill_instructions(skill)++ resource_dirs: list[tuple[ResourceDirName, Path]] = [+ ("scripts", skill.scripts_dir),+ ("references", skill.references_dir),+ ("assets", skill.assets_dir),+ ]+ resource_files: dict[ResourceDirName, list[str]] = {}+ for dir_name, resource_dir in resource_dirs:+ if resource_dir.is_dir():+ resource_files[dir_name] = sorted(+ str(f.relative_to(resource_dir))+ for f in resource_dir.rglob("*")+ if f.is_file()+ )++ return skill.with_disclosure_level(+ level=RESOURCES,+ instructions=skill.instructions,+ resource_files=resource_files,+ )diff --git a/lib/crewai/src/crewai/skills/validation.py b/lib/crewai/src/crewai/skills/validation.pynew file mode 100644index 000000000..78acd7b76--- /dev/null+++ b/lib/crewai/src/crewai/skills/validation.py@@ -0,0 +1,31 @@+"""Validation functions for Agent Skills specification constraints.++Validates skill names and directory structures per the Agent Skills standard.+"""++from __future__ import annotations++from pathlib import Path+import re+from typing import Final+++MAX_SKILL_NAME_LENGTH: Final[int] = 64+MIN_SKILL_NAME_LENGTH: Final[int] = 1+SKILL_NAME_PATTERN: Final[re.Pattern[str]] = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")+++def validate_directory_name(skill_dir: Path, skill_name: str) -> None:+ """Validate that a directory name matches the skill name.++ Args:+ skill_dir: Path to the skill directory.+ skill_name: The declared skill name from frontmatter.++ Raises:+ ValueError: If the directory name does not match the skill name.+ """+ dir_name = skill_dir.name+ if dir_name != skill_name:+ msg = f"Directory name '{dir_name}' does not match skill name '{skill_name}'"+ raise ValueError(msg)diff --git a/lib/crewai/tests/skills/__init__.py b/lib/crewai/tests/skills/__init__.pynew file mode 100644index 000000000..e69de29bbdiff --git a/lib/crewai/tests/skills/fixtures/invalid-name/SKILL.md b/lib/crewai/tests/skills/fixtures/invalid-name/SKILL.mdnew file mode 100644index 000000000..ce075ee0a--- /dev/null+++ b/lib/crewai/tests/skills/fixtures/invalid-name/SKILL.md@@ -0,0 +1,4 @@+---+name: Invalid--Name+description: This skill has an invalid name.+---diff --git a/lib/crewai/tests/skills/fixtures/minimal-skill/SKILL.md b/lib/crewai/tests/skills/fixtures/minimal-skill/SKILL.mdnew file mode 100644index 000000000..2efe9b9ea--- /dev/null+++ b/lib/crewai/tests/skills/fixtures/minimal-skill/SKILL.md@@ -0,0 +1,4 @@+---+name: minimal-skill+description: A minimal skill with only required fields.+---diff --git a/lib/crewai/tests/skills/fixtures/valid-skill/SKILL.md b/lib/crewai/tests/skills/fixtures/valid-skill/SKILL.mdnew file mode 100644index 000000000..f69e7b463--- /dev/null+++ b/lib/crewai/tests/skills/fixtures/valid-skill/SKILL.md@@ -0,0 +1,22 @@+---+name: valid-skill+description: A complete test skill with all optional directories.+license: Apache-2.0+compatibility: crewai>=0.1.0+metadata:+ author: test+ version: "1.0"+allowed-tools: web-search file-read+---++## Instructions++This skill provides comprehensive instructions for the agent.++### Usage++Follow these steps to use the skill effectively.++### Notes++Additional context for the agent.diff --git a/lib/crewai/tests/skills/fixtures/valid-skill/assets/config.json b/lib/crewai/tests/skills/fixtures/valid-skill/assets/config.jsonnew file mode 100644index 000000000..76519fa8c--- /dev/null+++ b/lib/crewai/tests/skills/fixtures/valid-skill/assets/config.json@@ -0,0 +1 @@+{"key": "value"}diff --git a/lib/crewai/tests/skills/fixtures/valid-skill/references/guide.md b/lib/crewai/tests/skills/fixtures/valid-skill/references/guide.mdnew file mode 100644index 000000000..8ef68aeb6--- /dev/null+++ b/lib/crewai/tests/skills/fixtures/valid-skill/references/guide.md@@ -0,0 +1,3 @@+# Reference Guide++This is a reference document for the skill.diff --git a/lib/crewai/tests/skills/fixtures/valid-skill/scripts/setup.sh b/lib/crewai/tests/skills/fixtures/valid-skill/scripts/setup.shnew file mode 100644index 000000000..1178a039d--- /dev/null+++ b/lib/crewai/tests/skills/fixtures/valid-skill/scripts/setup.sh@@ -0,0 +1,2 @@+#!/bin/bash+echo "setup"diff --git a/lib/crewai/tests/skills/test_integration.py b/lib/crewai/tests/skills/test_integration.pynew file mode 100644index 000000000..23004d79e--- /dev/null+++ b/lib/crewai/tests/skills/test_integration.py@@ -0,0 +1,78 @@+"""Integration tests for the skills system."""++from pathlib import Path++import pytest++from crewai.skills.loader import activate_skill, discover_skills, format_skill_context+from crewai.skills.models import INSTRUCTIONS, METADATA+++def _create_skill_dir(parent: Path, name: str, body: str = "Body.") -> Path:+ """Helper to create a skill directory with SKILL.md."""+ skill_dir = parent / name+ skill_dir.mkdir()+ (skill_dir / "SKILL.md").write_text(+ f"---\nname: {name}\ndescription: Skill {name}\n---\n{body}"+ )+ return skill_dir+++class TestSkillDiscoveryAndActivation:+ """End-to-end tests for discover + activate workflow."""++ def test_discover_and_activate(self, tmp_path: Path) -> None:+ _create_skill_dir(tmp_path, "my-skill", body="Use this skill.")+ skills = discover_skills(tmp_path)+ assert len(skills) == 1+ assert skills[0].disclosure_level == METADATA++ activated = activate_skill(skills[0])+ assert activated.disclosure_level == INSTRUCTIONS+ assert activated.instructions == "Use this skill."++ context = format_skill_context(activated)+ assert "## Skill: my-skill" in context+ assert "Use this skill." in context++ def test_filter_by_skill_names(self, tmp_path: Path) -> None:+ _create_skill_dir(tmp_path, "alpha")+ _create_skill_dir(tmp_path, "beta")+ _create_skill_dir(tmp_path, "gamma")++ all_skills = discover_skills(tmp_path)+ wanted = {"alpha", "gamma"}+ filtered = [s for s in all_skills if s.name in wanted]+ assert {s.name for s in filtered} == {"alpha", "gamma"}++ def test_full_fixture_skill(self) -> None:+ fixtures = Path(__file__).parent / "fixtures"+ valid_dir = fixtures / "valid-skill"+ if not valid_dir.exists():+ pytest.skip("Fixture not found")++ skills = discover_skills(fixtures)+ valid_skills = [s for s in skills if s.name == "valid-skill"]+ assert len(valid_skills) == 1++ skill = valid_skills[0]+ assert skill.frontmatter.license == "Apache-2.0"+ assert skill.frontmatter.allowed_tools == ["web-search", "file-read"]++ activated = activate_skill(skill)+ assert "Instructions" in (activated.instructions or "")++ def test_multiple_search_paths(self, tmp_path: Path) -> None:+ path_a = tmp_path / "a"+ path_a.mkdir()+ _create_skill_dir(path_a, "skill-a")++ path_b = tmp_path / "b"+ path_b.mkdir()+ _create_skill_dir(path_b, "skill-b")++ all_skills = []+ for search_path in [path_a, path_b]:+ all_skills.extend(discover_skills(search_path))+ names = {s.name for s in all_skills}+ assert names == {"skill-a", "skill-b"}diff --git a/lib/crewai/tests/skills/test_loader.py b/lib/crewai/tests/skills/test_loader.pynew file mode 100644index 000000000..8303e19df--- /dev/null+++ b/lib/crewai/tests/skills/test_loader.py@@ -0,0 +1,161 @@+"""Tests for skills/loader.py."""++from pathlib import Path++import pytest++from crewai.skills.loader import (+ activate_skill,+ discover_skills,+ format_skill_context,+ load_resources,+)+from crewai.skills.models import INSTRUCTIONS, METADATA, RESOURCES, Skill, SkillFrontmatter+from crewai.skills.parser import load_skill_metadata+++def _create_skill_dir(parent: Path, name: str, body: str = "Body.") -> Path:+ """Helper to create a skill directory with SKILL.md."""+ skill_dir = parent / name+ skill_dir.mkdir()+ (skill_dir / "SKILL.md").write_text(+ f"---\nname: {name}\ndescription: Skill {name}\n---\n{body}"+ )+ return skill_dir+++class TestDiscoverSkills:+ """Tests for discover_skills."""++ def test_finds_valid_skills(self, tmp_path: Path) -> None:+ _create_skill_dir(tmp_path, "alpha")+ _create_skill_dir(tmp_path, "beta")+ skills = discover_skills(tmp_path)+ names = {s.name for s in skills}+ assert names == {"alpha", "beta"}++ def test_skips_dirs_without_skill_md(self, tmp_path: Path) -> None:+ _create_skill_dir(tmp_path, "valid")+ (tmp_path / "no-skill").mkdir()+ skills = discover_skills(tmp_path)+ assert len(skills) == 1+ assert skills[0].name == "valid"++ def test_skips_invalid_skills(self, tmp_path: Path) -> None:+ _create_skill_dir(tmp_path, "good-skill")+ bad_dir = tmp_path / "bad-skill"+ bad_dir.mkdir()+ (bad_dir / "SKILL.md").write_text(+ "---\nname: Wrong-Name\ndescription: bad\n---\n"+ )+ skills = discover_skills(tmp_path)+ assert len(skills) == 1++ def test_empty_directory(self, tmp_path: Path) -> None:+ skills = discover_skills(tmp_path)+ assert skills == []++ def test_nonexistent_path(self, tmp_path: Path) -> None:+ with pytest.raises(FileNotFoundError):+ discover_skills(tmp_path / "nonexistent")++ def test_sorted_by_name(self, tmp_path: Path) -> None:+ _create_skill_dir(tmp_path, "zebra")+ _create_skill_dir(tmp_path, "alpha")+ skills = discover_skills(tmp_path)+ assert [s.name for s in skills] == ["alpha", "zebra"]+++class TestActivateSkill:+ """Tests for activate_skill."""++ def test_promotes_to_instructions(self, tmp_path: Path) -> None:+ _create_skill_dir(tmp_path, "my-skill", body="Instructions.")+ skill = load_skill_metadata(tmp_path / "my-skill")+ activated = activate_skill(skill)+ assert activated.disclosure_level == INSTRUCTIONS+ assert activated.instructions == "Instructions."++ def test_idempotent(self, tmp_path: Path) -> None:+ _create_skill_dir(tmp_path, "my-skill")+ skill = load_skill_metadata(tmp_path / "my-skill")+ activated = activate_skill(skill)+ again = activate_skill(activated)+ assert again is activated+++class TestLoadResources:+ """Tests for load_resources."""++ def test_promotes_to_resources(self, tmp_path: Path) -> None:+ skill_dir = _create_skill_dir(tmp_path, "my-skill")+ (skill_dir / "scripts").mkdir()+ (skill_dir / "scripts" / "run.sh").write_text("#!/bin/bash")+ skill = load_skill_metadata(skill_dir)+ full = load_resources(skill)+ assert full.disclosure_level == RESOURCES+++class TestFormatSkillContext:+ """Tests for format_skill_context."""++ def test_metadata_level(self, tmp_path: Path) -> None:+ fm = SkillFrontmatter(name="test-skill", description="A skill")+ skill = Skill(+ frontmatter=fm, path=tmp_path, disclosure_level=METADATA+ )+ ctx = format_skill_context(skill)+ assert "## Skill: test-skill" in ctx+ assert "A skill" in ctx++ def test_instructions_level(self, tmp_path: Path) -> None:+ fm = SkillFrontmatter(name="test-skill", description="A skill")+ skill = Skill(+ frontmatter=fm,+ path=tmp_path,+ disclosure_level=INSTRUCTIONS,+ instructions="Do these things.",+ )+ ctx = format_skill_context(skill)+ assert "## Skill: test-skill" in ctx+ assert "Do these things." in ctx++ def test_no_instructions_at_instructions_level(self, tmp_path: Path) -> None:+ fm = SkillFrontmatter(name="test-skill", description="A skill")+ skill = Skill(+ frontmatter=fm,+ path=tmp_path,+ disclosure_level=INSTRUCTIONS,+ instructions=None,+ )+ ctx = format_skill_context(skill)+ assert ctx == "## Skill: test-skill\nA skill"++ def test_resources_level(self, tmp_path: Path) -> None:+ fm = SkillFrontmatter(name="test-skill", description="A skill")+ skill = Skill(+ frontmatter=fm,+ path=tmp_path,+ disclosure_level=RESOURCES,+ instructions="Do things.",+ resource_files={+ "scripts": ["run.sh"],+ "assets": ["data.json", "config.yaml"],+ },+ )+ ctx = format_skill_context(skill)+ assert "### Available Resources" in ctx+ assert "**assets/**: data.json, config.yaml" in ctx+ assert "**scripts/**: run.sh" in ctx++ def test_resources_level_empty_files(self, tmp_path: Path) -> None:+ fm = SkillFrontmatter(name="test-skill", description="A skill")+ skill = Skill(+ frontmatter=fm,+ path=tmp_path,+ disclosure_level=RESOURCES,+ instructions="Do things.",+ resource_files={},+ )+ ctx = format_skill_context(skill)+ assert "### Available Resources" not in ctxdiff --git a/lib/crewai/tests/skills/test_models.py b/lib/crewai/tests/skills/test_models.pynew file mode 100644index 000000000..57f15d763--- /dev/null+++ b/lib/crewai/tests/skills/test_models.py@@ -0,0 +1,91 @@+"""Tests for skills/models.py."""++from pathlib import Path++import pytest++from crewai.skills.models import (+ INSTRUCTIONS,+ METADATA,+ RESOURCES,+ Skill,+ SkillFrontmatter,+)+++class TestDisclosureLevel:+ """Tests for DisclosureLevel constants."""++ def test_ordering(self) -> None:+ assert METADATA < INSTRUCTIONS+ assert INSTRUCTIONS < RESOURCES++ def test_values(self) -> None:+ assert METADATA == 1+ assert INSTRUCTIONS == 2+ assert RESOURCES == 3+++class TestSkillFrontmatter:+ """Tests for SkillFrontmatter model."""++ def test_required_fields(self) -> None:+ fm = SkillFrontmatter(name="my-skill", description="A test skill")+ assert fm.name == "my-skill"+ assert fm.description == "A test skill"+ assert fm.license is None+ assert fm.metadata is None+ assert fm.allowed_tools is None++ def test_all_fields(self) -> None:+ fm = SkillFrontmatter(+ name="web-search",+ description="Search the web",+ license="Apache-2.0",+ compatibility="crewai>=0.1.0",+ metadata={"author": "test"},+ allowed_tools=["browser"],+ )+ assert fm.license == "Apache-2.0"+ assert fm.metadata == {"author": "test"}+ assert fm.allowed_tools == ["browser"]++ def test_frozen(self) -> None:+ fm = SkillFrontmatter(name="my-skill", description="desc")+ with pytest.raises(Exception):+ fm.name = "other" # type: ignore[misc]++ def test_invalid_name_rejected(self) -> None:+ with pytest.raises(ValueError):+ SkillFrontmatter(name="Invalid--Name", description="bad")+++class TestSkill:+ """Tests for Skill model."""++ def test_properties(self, tmp_path: Path) -> None:+ fm = SkillFrontmatter(name="test-skill", description="desc")+ skill = Skill(frontmatter=fm, path=tmp_path / "test-skill")+ assert skill.name == "test-skill"+ assert skill.description == "desc"+ assert skill.disclosure_level == METADATA++ def test_resource_dirs(self, tmp_path: Path) -> None:+ skill_dir = tmp_path / "test-skill"+ skill_dir.mkdir()+ fm = SkillFrontmatter(name="test-skill", description="desc")+ skill = Skill(frontmatter=fm, path=skill_dir)+ assert skill.scripts_dir == skill_dir / "scripts"+ assert skill.references_dir == skill_dir / "references"+ assert skill.assets_dir == skill_dir / "assets"++ def test_with_disclosure_level(self, tmp_path: Path) -> None:+ fm = SkillFrontmatter(name="test-skill", description="desc")+ skill = Skill(frontmatter=fm, path=tmp_path)+ promoted = skill.with_disclosure_level(+ INSTRUCTIONS,+ instructions="Do this.",+ )+ assert promoted.disclosure_level == INSTRUCTIONS+ assert promoted.instructions == "Do this."+ assert skill.disclosure_level == METADATAdiff --git a/lib/crewai/tests/skills/test_parser.py b/lib/crewai/tests/skills/test_parser.pynew file mode 100644index 000000000..dab15d175--- /dev/null+++ b/lib/crewai/tests/skills/test_parser.py@@ -0,0 +1,167 @@+"""Tests for skills/parser.py."""++from pathlib import Path++import pytest++from crewai.skills.models import INSTRUCTIONS, METADATA, RESOURCES+from crewai.skills.parser import (+ SkillParseError,+ load_skill_instructions,+ load_skill_metadata,+ load_skill_resources,+ parse_frontmatter,+ parse_skill_md,+)+++class TestParseFrontmatter:+ """Tests for parse_frontmatter."""++ def test_valid_frontmatter_and_body(self) -> None:+ content = "---\nname: test\ndescription: A test\n---\n\nBody text here."+ fm, body = parse_frontmatter(content)+ assert fm["name"] == "test"+ assert fm["description"] == "A test"+ assert body == "Body text here."++ def test_empty_body(self) -> None:+ content = "---\nname: test\ndescription: A test\n---"+ fm, body = parse_frontmatter(content)+ assert fm["name"] == "test"+ assert body == ""++ def test_missing_opening_delimiter(self) -> None:+ with pytest.raises(SkillParseError, match="must start with"):+ parse_frontmatter("name: test\n---\nBody")++ def test_missing_closing_delimiter(self) -> None:+ with pytest.raises(SkillParseError, match="missing closing"):+ parse_frontmatter("---\nname: test\n")++ def test_invalid_yaml(self) -> None:+ with pytest.raises(SkillParseError, match="Invalid YAML"):+ parse_frontmatter("---\n: :\n bad: [yaml\n---\nBody")++ def test_triple_dash_in_body(self) -> None:+ content = "---\nname: test\ndescription: desc\n---\n\nBody with --- inside."+ fm, body = parse_frontmatter(content)+ assert "---" in body++ def test_inline_triple_dash_in_yaml_value(self) -> None:+ content = '---\nname: test\ndescription: "Use---carefully"\n---\n\nBody.'+ fm, body = parse_frontmatter(content)+ assert fm["description"] == "Use---carefully"+ assert body == "Body."++ def test_unicode_content(self) -> None:+ content = "---\nname: test\ndescription: Beschreibung\n---\n\nUnicode: \u00e4\u00f6\u00fc\u00df"+ fm, body = parse_frontmatter(content)+ assert fm["description"] == "Beschreibung"+ assert "\u00e4\u00f6\u00fc\u00df" in body++ def test_non_mapping_frontmatter(self) -> None:+ with pytest.raises(SkillParseError, match="must be a YAML mapping"):+ parse_frontmatter("---\n- item1\n- item2\n---\nBody")+++class TestParseSkillMd:+ """Tests for parse_skill_md."""++ def test_valid_file(self, tmp_path: Path) -> None:+ skill_md = tmp_path / "SKILL.md"+ skill_md.write_text(+ "---\nname: my-skill\ndescription: desc\n---\nInstructions here."+ )+ fm, body = parse_skill_md(skill_md)+ assert fm.name == "my-skill"+ assert body == "Instructions here."++ def test_file_not_found(self, tmp_path: Path) -> None:+ with pytest.raises(FileNotFoundError):+ parse_skill_md(tmp_path / "nonexistent" / "SKILL.md")+++class TestLoadSkillMetadata:+ """Tests for load_skill_metadata."""++ def test_valid_skill(self, tmp_path: Path) -> None:+ skill_dir = tmp_path / "my-skill"+ skill_dir.mkdir()+ (skill_dir / "SKILL.md").write_text(+ "---\nname: my-skill\ndescription: Test skill\n---\nBody"+ )+ skill = load_skill_metadata(skill_dir)+ assert skill.name == "my-skill"+ assert skill.disclosure_level == METADATA+ assert skill.instructions is None++ def test_directory_name_mismatch(self, tmp_path: Path) -> None:+ skill_dir = tmp_path / "wrong-name"+ skill_dir.mkdir()+ (skill_dir / "SKILL.md").write_text(+ "---\nname: my-skill\ndescription: Test skill\n---\n"+ )+ with pytest.raises(ValueError, match="does not match"):+ load_skill_metadata(skill_dir)+++class TestLoadSkillInstructions:+ """Tests for load_skill_instructions."""++ def test_promotes_to_instructions(self, tmp_path: Path) -> None:+ skill_dir = tmp_path / "my-skill"+ skill_dir.mkdir()+ (skill_dir / "SKILL.md").write_text(+ "---\nname: my-skill\ndescription: Test\n---\nFull body."+ )+ skill = load_skill_metadata(skill_dir)+ promoted = load_skill_instructions(skill)+ assert promoted.disclosure_level == INSTRUCTIONS+ assert promoted.instructions == "Full body."++ def test_idempotent(self, tmp_path: Path) -> None:+ skill_dir = tmp_path / "my-skill"+ skill_dir.mkdir()+ (skill_dir / "SKILL.md").write_text(+ "---\nname: my-skill\ndescription: Test\n---\nBody."+ )+ skill = load_skill_metadata(skill_dir)+ promoted = load_skill_instructions(skill)+ again = load_skill_instructions(promoted)+ assert again is promoted+++class TestLoadSkillResources:+ """Tests for load_skill_resources."""++ def test_catalogs_resources(self, tmp_path: Path) -> None:+ skill_dir = tmp_path / "my-skill"+ skill_dir.mkdir()+ (skill_dir / "SKILL.md").write_text(+ "---\nname: my-skill\ndescription: Test\n---\nBody."+ )+ (skill_dir / "scripts").mkdir()+ (skill_dir / "scripts" / "run.sh").write_text("#!/bin/bash")+ (skill_dir / "assets").mkdir()+ (skill_dir / "assets" / "data.json").write_text("{}")++ skill = load_skill_metadata(skill_dir)+ full = load_skill_resources(skill)+ assert full.disclosure_level == RESOURCES+ assert full.instructions == "Body."+ assert full.resource_files is not None+ assert "scripts" in full.resource_files+ assert "run.sh" in full.resource_files["scripts"]+ assert "assets" in full.resource_files+ assert "data.json" in full.resource_files["assets"]++ def test_no_resource_dirs(self, tmp_path: Path) -> None:+ skill_dir = tmp_path / "my-skill"+ skill_dir.mkdir()+ (skill_dir / "SKILL.md").write_text(+ "---\nname: my-skill\ndescription: Test\n---\nBody."+ )+ skill = load_skill_metadata(skill_dir)+ full = load_skill_resources(skill)+ assert full.resource_files == {}diff --git a/lib/crewai/tests/skills/test_validation.py b/lib/crewai/tests/skills/test_validation.pynew file mode 100644index 000000000..982a9d534--- /dev/null+++ b/lib/crewai/tests/skills/test_validation.py@@ -0,0 +1,93 @@+"""Tests for skills validation."""++from pathlib import Path++import pytest++from crewai.skills.models import SkillFrontmatter+from crewai.skills.validation import (+ MAX_SKILL_NAME_LENGTH,+ validate_directory_name,+)+++def _make(name: str) -> SkillFrontmatter:+ """Create a SkillFrontmatter with the given name."""+ return SkillFrontmatter(name=name, description="desc")+++class TestSkillNameValidation:+ """Tests for skill name constraints via SkillFrontmatter."""++ def test_simple_name(self) -> None:+ assert _make("web-search").name == "web-search"++ def test_single_word(self) -> None:+ assert _make("search").name == "search"++ def test_numeric(self) -> None:+ assert _make("tool3").name == "tool3"++ def test_all_digits(self) -> None:+ assert _make("123").name == "123"++ def test_single_char(self) -> None:+ assert _make("a").name == "a"++ def test_max_length(self) -> None:+ name = "a" * MAX_SKILL_NAME_LENGTH+ assert _make(name).name == name++ def test_multi_hyphen_segments(self) -> None:+ assert _make("my-cool-skill").name == "my-cool-skill"++ def test_empty_raises(self) -> None:+ with pytest.raises(ValueError):+ _make("")++ def test_too_long_raises(self) -> None:+ with pytest.raises(ValueError):+ _make("a" * (MAX_SKILL_NAME_LENGTH + 1))++ def test_uppercase_raises(self) -> None:+ with pytest.raises(ValueError):+ _make("MySkill")++ def test_leading_hyphen_raises(self) -> None:+ with pytest.raises(ValueError):+ _make("-skill")++ def test_trailing_hyphen_raises(self) -> None:+ with pytest.raises(ValueError):+ _make("skill-")++ def test_consecutive_hyphens_raises(self) -> None:+ with pytest.raises(ValueError):+ _make("my--skill")++ def test_underscore_raises(self) -> None:+ with pytest.raises(ValueError):+ _make("my_skill")++ def test_space_raises(self) -> None:+ with pytest.raises(ValueError):+ _make("my skill")++ def test_special_chars_raises(self) -> None:+ with pytest.raises(ValueError):+ _make("skill@v1")+++class TestValidateDirectoryName:+ """Tests for validate_directory_name."""++ def test_matching_names(self, tmp_path: Path) -> None:+ skill_dir = tmp_path / "my-skill"+ skill_dir.mkdir()+ validate_directory_name(skill_dir, "my-skill")++ def test_mismatched_names(self, tmp_path: Path) -> None:+ skill_dir = tmp_path / "other-name"+ skill_dir.mkdir()+ with pytest.raises(ValueError, match="does not match"):+ validate_directory_name(skill_dir, "my-skill")diff --git a/uv.lock b/uv.lockindex b9d63dd3d..3ff84ee57 100644--- a/uv.lock+++ b/uv.lock@@ -1115,6 +1115,7 @@ dependencies = [{ name = "pydantic-settings" },{ name = "pyjwt" },{ name = "python-dotenv" },+ { name = "pyyaml" },{ name = "regex" },{ name = "textual" },{ name = "tokenizers" },@@ -1222,6 +1223,7 @@ requires-dist = [{ name = "pydantic-settings", specifier = "~=2.10.1" },{ name = "pyjwt", specifier = ">=2.9.0,<3" },{ name = "python-dotenv", specifier = "~=1.1.1" },+ { name = "pyyaml", specifier = "~=6.0" },{ name = "qdrant-client", extras = ["fastembed"], marker = "extra == 'qdrant'", specifier = "~=1.14.3" },{ name = "regex", specifier = "~=2026.1.15" },{ name = "textual", specifier = ">=7.5.0" },