Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
refactor(skills): move Skills Repository to experimental + CREWAI_EXPERIMENTAL gate
Greyson LaLondeed91100a0f5a
diff --git a/lib/cli/src/crewai_cli/cli.py b/lib/cli/src/crewai_cli/cli.pyindex 6364dfdc3..f1a8b20ba 100644--- a/lib/cli/src/crewai_cli/cli.py+++ b/lib/cli/src/crewai_cli/cli.py@@ -17,6 +17,7 @@ from crewai_cli.crew_chat import run_chatfrom crewai_cli.deploy.main import DeployCommandfrom crewai_cli.enterprise.main import EnterpriseConfigureCommandfrom crewai_cli.evaluate_crew import evaluate_crew+from crewai_cli.experimental.skills.main import SkillCommandfrom crewai_cli.install_crew import install_crewfrom crewai_cli.kickoff_flow import kickoff_flowfrom crewai_cli.organization.main import OrganizationCommand@@ -26,7 +27,6 @@ from crewai_cli.replay_from_task import replay_task_commandfrom crewai_cli.reset_memories_command import reset_memories_commandfrom crewai_cli.run_crew import run_crewfrom crewai_cli.settings.main import SettingsCommand-from crewai_cli.skills.main import SkillCommandfrom crewai_cli.task_outputs import load_task_outputsfrom crewai_cli.tools.main import ToolCommandfrom crewai_cli.train_crew import train_crew@@ -544,8 +544,19 @@ def tool_publish(is_public: bool, force: bool) -> None:@crewai.group()+def experimental() -> None:+ """Experimental, unstable commands. Subject to change without notice."""+ import os++ if os.environ.get("CREWAI_EXPERIMENTAL") != "1":+ raise click.UsageError(+ "Experimental commands are gated. Set CREWAI_EXPERIMENTAL=1 to enable."+ )++[email protected](name="skill")def skill() -> None:- """Skill Repository related commands."""+ """Skill Repository related commands (experimental)."""@skill.command(name="create")diff --git a/lib/cli/src/crewai_cli/skills/__init__.py b/lib/cli/src/crewai_cli/experimental/__init__.pysimilarity index 100%rename from lib/cli/src/crewai_cli/skills/__init__.pyrename to lib/cli/src/crewai_cli/experimental/__init__.pydiff --git a/lib/cli/src/crewai_cli/experimental/skills/__init__.py b/lib/cli/src/crewai_cli/experimental/skills/__init__.pynew file mode 100644index 000000000..e69de29bbdiff --git a/lib/cli/src/crewai_cli/skills/main.py b/lib/cli/src/crewai_cli/experimental/skills/main.pysimilarity index 96%rename from lib/cli/src/crewai_cli/skills/main.pyrename to lib/cli/src/crewai_cli/experimental/skills/main.pyindex 16d705bfb..81f9b3fc5 100644--- a/lib/cli/src/crewai_cli/skills/main.py+++ b/lib/cli/src/crewai_cli/experimental/skills/main.py@@ -23,9 +23,10 @@ console = Console()_SKILL_MD_TEMPLATE = """\---name: {name}-version: 0.1.0description: |A short description of what this skill does.+metadata:+ version: 0.1.0---## Instructions@@ -147,7 +148,7 @@ class SkillCommand(BaseCommand, PlusAPIMixin):)else:try:- from crewai.skills.cache import SkillCacheManager+ from crewai.experimental.skills.cache import SkillCacheManagercache = SkillCacheManager()cache.store(org, name, version, archive_bytes)@@ -191,7 +192,10 @@ class SkillCommand(BaseCommand, PlusAPIMixin):raise SystemExit(1) from excname = frontmatter.get("name")- version = frontmatter.get("version")+ raw_metadata = frontmatter.get("metadata")+ version = (+ raw_metadata.get("version") if isinstance(raw_metadata, dict) else None+ )description = frontmatter.get("description")if not name:@@ -362,10 +366,13 @@ class SkillCommand(BaseCommand, PlusAPIMixin):return resultdef _read_version(self, skill_md: Path) -> str | None:- """Read the version field from a SKILL.md file, or None."""+ """Read the version from a SKILL.md file's metadata, or None."""try:fm = self._parse_frontmatter(skill_md.read_text())- return fm.get("version")+ raw_metadata = fm.get("metadata")+ if isinstance(raw_metadata, dict):+ return raw_metadata.get("version")+ return Noneexcept Exception:return Nonediff --git a/lib/cli/tests/experimental/__init__.py b/lib/cli/tests/experimental/__init__.pynew file mode 100644index 000000000..e69de29bbdiff --git a/lib/cli/tests/experimental/skills/__init__.py b/lib/cli/tests/experimental/skills/__init__.pynew file mode 100644index 000000000..e69de29bbdiff --git a/lib/cli/tests/skills/test_main.py b/lib/cli/tests/experimental/skills/test_main.pysimilarity index 94%rename from lib/cli/tests/skills/test_main.pyrename to lib/cli/tests/experimental/skills/test_main.pyindex f66c5b90a..f302754d9 100644--- a/lib/cli/tests/skills/test_main.py+++ b/lib/cli/tests/experimental/skills/test_main.py@@ -36,7 +36,7 @@ def skill_command():TokenManager().save_tokens("test-token", (datetime.now() + timedelta(seconds=36000)).timestamp())- from crewai_cli.skills.main import SkillCommand+ from crewai_cli.experimental.skills.main import SkillCommandcmd = SkillCommand()yield cmd@@ -142,7 +142,7 @@ class TestSkillPublish:mock_resp.status_code = 200mock_resp.json.return_value = {}mock_client.publish_skill.return_value = mock_resp- with patch("crewai_cli.skills.main.Settings") as mock_settings_cls:+ with patch("crewai_cli.experimental.skills.main.Settings") as mock_settings_cls:mock_settings_cls.return_value.org_name = Nonemock_settings_cls.return_value.enterprise_base_url = Nonewith pytest.raises(SystemExit):@@ -151,14 +151,14 @@ class TestSkillPublish:def test_publish_calls_api(self, skill_command):with in_temp_dir():Path("SKILL.md").write_text(- "---\nname: my-skill\nversion: 1.0.0\ndescription: A test skill.\n---\nInstructions."+ "---\nname: my-skill\ndescription: A test skill.\nmetadata:\n version: 1.0.0\n---\nInstructions.")mock_resp = MagicMock()mock_resp.is_success = Truemock_resp.status_code = 200mock_resp.json.return_value = {}skill_command.plus_api_client.publish_skill = MagicMock(return_value=mock_resp)- with patch("crewai_cli.skills.main.Settings") as mock_settings_cls:+ with patch("crewai_cli.experimental.skills.main.Settings") as mock_settings_cls:mock_settings_cls.return_value.org_name = "acme"mock_settings_cls.return_value.enterprise_base_url = Nonediff --git a/lib/crewai/src/crewai/agent/core.py b/lib/crewai/src/crewai/agent/core.pyindex 0295a2a6c..73020f115 100644--- a/lib/crewai/src/crewai/agent/core.py+++ b/lib/crewai/src/crewai/agent/core.py@@ -472,7 +472,7 @@ class Agent(BaseAgent):for item in items:if isinstance(item, str):- from crewai.skills.registry import (+ from crewai.experimental.skills.registry import (is_registry_ref,parse_registry_ref,resolve_registry_ref,diff --git a/lib/crewai/src/crewai/events/types/skill_events.py b/lib/crewai/src/crewai/events/types/skill_events.pyindex 322c053e3..aab625dda 100644--- a/lib/crewai/src/crewai/events/types/skill_events.py+++ b/lib/crewai/src/crewai/events/types/skill_events.py@@ -60,20 +60,3 @@ class SkillLoadFailedEvent(SkillEvent):type: Literal["skill_load_failed"] = "skill_load_failed"error: str---class SkillDownloadStartedEvent(SkillEvent):- """Event emitted when a registry skill download begins."""-- type: Literal["skill_download_started"] = "skill_download_started"- registry_ref: str- version: str | None = None---class SkillDownloadCompletedEvent(SkillEvent):- """Event emitted when a registry skill download completes."""-- type: Literal["skill_download_completed"] = "skill_download_completed"- registry_ref: str- version: str | None = None- cache_path: Path | None = Nonediff --git a/lib/crewai/src/crewai/experimental/skills/__init__.py b/lib/crewai/src/crewai/experimental/skills/__init__.pynew file mode 100644index 000000000..aef3d4ed5--- /dev/null+++ b/lib/crewai/src/crewai/experimental/skills/__init__.py@@ -0,0 +1,23 @@+"""Experimental Skills Repository — registry refs, global cache, downloads.++This package contains the registry-backed pieces of the skills feature+(`@org/name` refs, `~/.crewai/skills/` cache, download events). The stable+filesystem-based skill loader still lives in `crewai.skills`.+"""++from crewai.experimental.skills.cache import SkillCacheManager+from crewai.experimental.skills.registry import (+ SkillNotCachedError,+ is_registry_ref,+ parse_registry_ref,+ resolve_registry_ref,+)+++__all__ = [+ "SkillCacheManager",+ "SkillNotCachedError",+ "is_registry_ref",+ "parse_registry_ref",+ "resolve_registry_ref",+]diff --git a/lib/crewai/src/crewai/experimental/skills/_flag.py b/lib/crewai/src/crewai/experimental/skills/_flag.pynew file mode 100644index 000000000..beca1d270--- /dev/null+++ b/lib/crewai/src/crewai/experimental/skills/_flag.py@@ -0,0 +1,24 @@+"""Experimental feature gate for the Skills Repository."""++from __future__ import annotations++import os+++ENV_VAR = "CREWAI_EXPERIMENTAL"+++class ExperimentalFeatureDisabledError(RuntimeError):+ """Raised when an experimental feature is used without the flag set."""+++def is_enabled() -> bool:+ return os.environ.get(ENV_VAR) == "1"+++def require_experimental_skills() -> None:+ if not is_enabled():+ raise ExperimentalFeatureDisabledError(+ "The Skills Repository (registry refs, cache, downloads) is "+ f"experimental. Set {ENV_VAR}=1 to enable it."+ )diff --git a/lib/crewai/src/crewai/skills/cache.py b/lib/crewai/src/crewai/experimental/skills/cache.pysimilarity index 100%rename from lib/crewai/src/crewai/skills/cache.pyrename to lib/crewai/src/crewai/experimental/skills/cache.pydiff --git a/lib/crewai/src/crewai/experimental/skills/events.py b/lib/crewai/src/crewai/experimental/skills/events.pynew file mode 100644index 000000000..c97632281--- /dev/null+++ b/lib/crewai/src/crewai/experimental/skills/events.py@@ -0,0 +1,30 @@+"""Download lifecycle events for registry-backed skills.++These events are emitted only by the experimental Skills Repository+(`@org/name` resolution + global cache). Local-file skill events still+live in `crewai.events.types.skill_events`.+"""++from __future__ import annotations++from pathlib import Path+from typing import Literal++from crewai.events.types.skill_events import SkillEvent+++class SkillDownloadStartedEvent(SkillEvent):+ """Event emitted when a registry skill download begins."""++ type: Literal["skill_download_started"] = "skill_download_started"+ registry_ref: str+ version: str | None = None+++class SkillDownloadCompletedEvent(SkillEvent):+ """Event emitted when a registry skill download completes."""++ type: Literal["skill_download_completed"] = "skill_download_completed"+ registry_ref: str+ version: str | None = None+ cache_path: Path | None = Nonediff --git a/lib/crewai/src/crewai/skills/registry.py b/lib/crewai/src/crewai/experimental/skills/registry.pysimilarity index 96%rename from lib/crewai/src/crewai/skills/registry.pyrename to lib/crewai/src/crewai/experimental/skills/registry.pyindex 991fbcde2..fa502c4f0 100644--- a/lib/crewai/src/crewai/skills/registry.py+++ b/lib/crewai/src/crewai/experimental/skills/registry.py@@ -11,7 +11,7 @@ from pathlib import Pathimport sysfrom typing import Any-from crewai.skills.cache import SkillCacheManager+from crewai.experimental.skills.cache import SkillCacheManager_logger = logging.getLogger(__name__)@@ -100,9 +100,11 @@ def resolve_registry_ref(Raises:SkillNotCachedError: When not cached and running in non-interactive mode."""+ from crewai.experimental.skills._flag import require_experimental_skillsfrom crewai.skills.loader import activate_skillfrom crewai.skills.parser import load_skill_metadata+ require_experimental_skills()org, name = parse_registry_ref(ref)local_path = Path.cwd() / "skills" / name@@ -152,7 +154,7 @@ def download_skill(try:from crewai.events.event_bus import crewai_event_bus- from crewai.events.types.skill_events import (+ from crewai.experimental.skills.events import (SkillDownloadCompletedEvent,SkillDownloadStartedEvent,)diff --git a/lib/crewai/src/crewai/skills/__init__.py b/lib/crewai/src/crewai/skills/__init__.pyindex a045581d2..e33e98570 100644--- a/lib/crewai/src/crewai/skills/__init__.py+++ b/lib/crewai/src/crewai/skills/__init__.py@@ -3,20 +3,15 @@Provides filesystem-based skill packaging with progressive disclosure."""-from crewai.skills.cache import SkillCacheManagerfrom crewai.skills.loader import activate_skill, discover_skillsfrom crewai.skills.models import Skill, SkillFrontmatterfrom crewai.skills.parser import SkillParseError-from crewai.skills.registry import is_registry_ref, resolve_registry_ref__all__ = ["Skill",- "SkillCacheManager","SkillFrontmatter","SkillParseError","activate_skill","discover_skills",- "is_registry_ref",- "resolve_registry_ref",]diff --git a/lib/crewai/src/crewai/skills/models.py b/lib/crewai/src/crewai/skills/models.pyindex 2cf6beb78..8c23773bd 100644--- a/lib/crewai/src/crewai/skills/models.py+++ b/lib/crewai/src/crewai/skills/models.py@@ -49,6 +49,7 @@ class SkillFrontmatter(BaseModel):license: Optional license name or reference.compatibility: Optional compatibility information (max 500 chars).metadata: Optional additional metadata as string key-value pairs.+ Conventional keys include 'version' (skill semantic version).allowed_tools: Optional space-delimited list of pre-approved tools."""@@ -71,17 +72,14 @@ class SkillFrontmatter(BaseModel):)metadata: dict[str, str] | None = Field(default=None,- description="Arbitrary string key-value pairs for custom skill metadata.",+ description="Arbitrary string key-value pairs for custom skill metadata. "+ "Conventional keys include 'version' for the skill's semantic version.",)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.",)- version: str | None = Field(- default=None,- description="Semantic version of the skill, e.g. '1.0.0'. Optional for local skills.",- )@model_validator(mode="before")@classmethoddiff --git a/lib/crewai/tests/experimental/skills/__init__.py b/lib/crewai/tests/experimental/skills/__init__.pynew file mode 100644index 000000000..e69de29bbdiff --git a/lib/crewai/tests/experimental/skills/conftest.py b/lib/crewai/tests/experimental/skills/conftest.pynew file mode 100644index 000000000..40baddaad--- /dev/null+++ b/lib/crewai/tests/experimental/skills/conftest.py@@ -0,0 +1,6 @@+import pytest++[email protected](autouse=True)+def _enable_experimental_skills(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("CREWAI_EXPERIMENTAL", "1")\ No newline at end of filediff --git a/lib/crewai/tests/skills/test_cache.py b/lib/crewai/tests/experimental/skills/test_cache.pysimilarity index 98%rename from lib/crewai/tests/skills/test_cache.pyrename to lib/crewai/tests/experimental/skills/test_cache.pyindex 4316cb9b9..8b458bb3e 100644--- a/lib/crewai/tests/skills/test_cache.py+++ b/lib/crewai/tests/experimental/skills/test_cache.py@@ -8,7 +8,7 @@ import jsonimport tarfilefrom pathlib import Path-from crewai.skills.cache import SkillCacheManager+from crewai.experimental.skills.cache import SkillCacheManagerdef _make_tar_gz(files: dict[str, str]) -> bytes:diff --git a/lib/crewai/tests/experimental/skills/test_flag.py b/lib/crewai/tests/experimental/skills/test_flag.pynew file mode 100644index 000000000..9295de678--- /dev/null+++ b/lib/crewai/tests/experimental/skills/test_flag.py@@ -0,0 +1,30 @@+"""Tests for the CREWAI_EXPERIMENTAL gate on Skills Repository."""++from __future__ import annotations++import pytest++from crewai.experimental.skills._flag import (+ ExperimentalFeatureDisabledError,+ require_experimental_skills,+)+from crewai.experimental.skills.registry import resolve_registry_ref+++def test_require_raises_without_flag(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.delenv("CREWAI_EXPERIMENTAL", raising=False)+ with pytest.raises(ExperimentalFeatureDisabledError):+ require_experimental_skills()+++def test_resolve_registry_ref_raises_without_flag(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ monkeypatch.delenv("CREWAI_EXPERIMENTAL", raising=False)+ with pytest.raises(ExperimentalFeatureDisabledError):+ resolve_registry_ref("@acme/my-skill")+++def test_require_passes_with_flag(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("CREWAI_EXPERIMENTAL", "1")+ require_experimental_skills()\ No newline at end of filediff --git a/lib/crewai/tests/experimental/skills/test_models_version.py b/lib/crewai/tests/experimental/skills/test_models_version.pynew file mode 100644index 000000000..e3bf7048a--- /dev/null+++ b/lib/crewai/tests/experimental/skills/test_models_version.py@@ -0,0 +1,32 @@+"""Tests for the 'version' metadata key on SkillFrontmatter.++Per the agentskills.io spec, `version` lives under `metadata`, not as a+top-level frontmatter field.+"""++from __future__ import annotations++from crewai.skills.models import SkillFrontmatter+++class TestSkillFrontmatterVersion:+ def test_no_metadata_by_default(self) -> None:+ fm = SkillFrontmatter(name="my-skill", description="A skill.")+ assert fm.metadata is None++ def test_version_via_metadata(self) -> None:+ fm = SkillFrontmatter(+ name="my-skill",+ description="A skill.",+ metadata={"version": "1.2.3"},+ )+ assert fm.metadata is not None+ assert fm.metadata["version"] == "1.2.3"++ def test_metadata_accepts_other_keys(self) -> None:+ fm = SkillFrontmatter(+ name="my-skill",+ description="A skill.",+ metadata={"version": "1.0.0", "author": "acme"},+ )+ assert fm.metadata == {"version": "1.0.0", "author": "acme"}diff --git a/lib/crewai/tests/skills/test_registry.py b/lib/crewai/tests/experimental/skills/test_registry.pysimilarity index 81%rename from lib/crewai/tests/skills/test_registry.pyrename to lib/crewai/tests/experimental/skills/test_registry.pyindex 5f588ccf7..84067dc73 100644--- a/lib/crewai/tests/skills/test_registry.py+++ b/lib/crewai/tests/experimental/skills/test_registry.py@@ -5,7 +5,7 @@ from __future__ import annotationsfrom pathlib import Pathfrom unittest.mock import MagicMock, patch-from crewai.skills.registry import (+from crewai.experimental.skills.registry import (SkillNotCachedError,is_registry_ref,parse_registry_ref,@@ -75,11 +75,11 @@ class TestResolveRegistryRef:mock_cache.get_cached_path.return_value = Nonewith (- patch("crewai.skills.registry._is_noninteractive", return_value=False),+ patch("crewai.experimental.skills.registry._is_noninteractive", return_value=False),patch.object(Path, "cwd", return_value=tmp_path),- patch("crewai.skills.registry.SkillCacheManager", return_value=mock_cache),+ patch("crewai.experimental.skills.registry.SkillCacheManager", return_value=mock_cache),):- from crewai.skills.registry import resolve_registry_ref+ from crewai.experimental.skills.registry import resolve_registry_refskill = resolve_registry_ref("@acme/my-skill")assert skill.name == "my-skill"@@ -90,11 +90,11 @@ class TestResolveRegistryRef:mock_cache.get_cached_path.return_value = Nonewith (- patch("crewai.skills.registry._is_noninteractive", return_value=True),+ patch("crewai.experimental.skills.registry._is_noninteractive", return_value=True),patch.object(Path, "cwd", return_value=tmp_path),- patch("crewai.skills.registry.SkillCacheManager", return_value=mock_cache),+ patch("crewai.experimental.skills.registry.SkillCacheManager", return_value=mock_cache),):- from crewai.skills.registry import resolve_registry_ref+ from crewai.experimental.skills.registry import resolve_registry_refwith pytest.raises(SkillNotCachedError) as exc_info:resolve_registry_ref("@acme/ghost-skill")assert "@acme/ghost-skill" in str(exc_info.value)@@ -112,11 +112,11 @@ class TestResolveRegistryRef:# tmp_path has no ./skills/ directorywith (- patch("crewai.skills.registry._is_noninteractive", return_value=False),+ patch("crewai.experimental.skills.registry._is_noninteractive", return_value=False),patch.object(Path, "cwd", return_value=tmp_path),- patch("crewai.skills.registry.SkillCacheManager", return_value=mock_cache),+ patch("crewai.experimental.skills.registry.SkillCacheManager", return_value=mock_cache),):- from crewai.skills.registry import resolve_registry_ref+ from crewai.experimental.skills.registry import resolve_registry_refskill = resolve_registry_ref("@acme/cached-skill")assert skill.name == "cached-skill"diff --git a/lib/crewai/tests/skills/test_models_version.py b/lib/crewai/tests/skills/test_models_version.pydeleted file mode 100644index 262ca2a82..000000000--- a/lib/crewai/tests/skills/test_models_version.py+++ /dev/null@@ -1,32 +0,0 @@-"""Tests for the version field added to SkillFrontmatter."""--from __future__ import annotations--import pytest-from pydantic import ValidationError--from crewai.skills.models import SkillFrontmatter---class TestSkillFrontmatterVersion:- def test_version_defaults_to_none(self) -> None:- fm = SkillFrontmatter(name="my-skill", description="A skill.")- assert fm.version is None-- def test_version_can_be_set(self) -> None:- fm = SkillFrontmatter(name="my-skill", description="A skill.", version="1.2.3")- assert fm.version == "1.2.3"-- def test_existing_frontmatter_without_version_still_valid(self) -> None:- """Backward compat: existing SKILL.md files without version must still parse."""- fm = SkillFrontmatter(name="old-skill", description="Old skill without version.")- assert fm.version is None-- def test_version_is_optional_string(self) -> None:- fm = SkillFrontmatter(name="my-skill", description="Desc.", version=None)- assert fm.version is None-- def test_frontmatter_is_frozen(self) -> None:- fm = SkillFrontmatter(name="my-skill", description="A skill.", version="1.0.0")- with pytest.raises(ValidationError):- fm.version = "2.0.0" # type: ignore[misc]