refactor(skills): move Skills Repository to experimental + CREWAI_EXPERIMENTAL gate#5963
Merged
Merged
Conversation
…ERIMENTAL gate Moves the registry/cache pieces of PR #5867 under crewai.experimental.skills and the CLI commands under `crewai experimental skill`. The stable local-file skills feature (loader, parser, validation, models) stays in crewai.skills. Both entry points now require CREWAI_EXPERIMENTAL=1: - resolve_registry_ref() calls require_experimental_skills() before resolving - The `crewai experimental` CLI group raises UsageError when the flag is unset SkillDownloadStarted/CompletedEvent move out of crewai.events.types.skill_events into crewai.experimental.skills.events.
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (4)
💤 Files with no reviewable changes (1)
📝 WalkthroughWalkthroughThis PR moves registry-backed skill resolution and related cache/registry helpers and events into a new crewai.experimental.skills namespace gated by CREWAI_EXPERIMENTAL, adds a feature gate and CLI experimental group, updates consumers/tests to the new modules, and migrates skill frontmatter version handling into metadata. Skills Registry Experimental Namespace Migration
Sequence DiagramsequenceDiagram
participant CLI as crewi_cli
participant Flag as crewi.experimental.skills._flag
participant Registry as crewi.experimental.skills.registry
participant CacheMgr as SkillCacheManager
CLI->>Flag: require_experimental_skills()
Flag-->>CLI: OK / raise ExperimentalFeatureDisabledError
CLI->>Registry: resolve_registry_ref(registry_ref)
Registry->>CacheMgr: download_skill / resolve from cache
CacheMgr-->>Registry: cache_path or raise SkillNotCachedError
Registry-->>CLI: resolved path
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
lib/crewai/src/crewai/experimental/skills/registry.py (1)
23-27:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winUpdate remediation command in
SkillNotCachedErrorto the experimental CLI path.Line 26 still suggests
crewai skill install {ref}, but this PR moves the command undercrewai experimental skill install. The current message will direct users to a non-existent/incorrect command.Suggested fix
- f"Run `crewai skill install {ref}` to install it first." + f"Run `crewai experimental skill install {ref}` to install it first."🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@lib/crewai/src/crewai/experimental/skills/registry.py` around lines 23 - 27, The error message in the SkillNotCachedError constructor (__init__) points users to the old CLI command; update the string to instruct running "crewai experimental skill install {ref}" instead of "crewai skill install {ref}" so the exception message correctly guides users to the experimental CLI path (update the f-string in the __init__ of SkillNotCachedError to use the new command).
🧹 Nitpick comments (1)
lib/cli/src/crewai_cli/cli.py (1)
549-549: 💤 Low valueRemove redundant
import osstatement.The
osmodule is already imported at the top of the file (line 4), so this local import is unnecessary.♻️ Proposed fix
def experimental() -> None: """Experimental, unstable commands. Subject to change without notice.""" - import os - if os.environ.get("CREWAI_EXPERIMENTAL") != "1":🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@lib/cli/src/crewai_cli/cli.py` at line 549, Remove the redundant local "import os" statement found in the function/block (the duplicated "import os" line) since "os" is already imported at the top of the file; simply delete the duplicate import and run tests/lint to verify no references were affected.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@lib/crewai/src/crewai/experimental/skills/registry.py`:
- Around line 23-27: The error message in the SkillNotCachedError constructor
(__init__) points users to the old CLI command; update the string to instruct
running "crewai experimental skill install {ref}" instead of "crewai skill
install {ref}" so the exception message correctly guides users to the
experimental CLI path (update the f-string in the __init__ of
SkillNotCachedError to use the new command).
---
Nitpick comments:
In `@lib/cli/src/crewai_cli/cli.py`:
- Line 549: Remove the redundant local "import os" statement found in the
function/block (the duplicated "import os" line) since "os" is already imported
at the top of the file; simply delete the duplicate import and run tests/lint to
verify no references were affected.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: c0c4d21c-f84b-4549-8b74-23f32b4b6346
📒 Files selected for processing (21)
lib/cli/src/crewai_cli/cli.pylib/cli/src/crewai_cli/experimental/__init__.pylib/cli/src/crewai_cli/experimental/skills/__init__.pylib/cli/src/crewai_cli/experimental/skills/main.pylib/cli/tests/experimental/__init__.pylib/cli/tests/experimental/skills/__init__.pylib/cli/tests/experimental/skills/test_main.pylib/crewai/src/crewai/agent/core.pylib/crewai/src/crewai/events/types/skill_events.pylib/crewai/src/crewai/experimental/skills/__init__.pylib/crewai/src/crewai/experimental/skills/_flag.pylib/crewai/src/crewai/experimental/skills/cache.pylib/crewai/src/crewai/experimental/skills/events.pylib/crewai/src/crewai/experimental/skills/registry.pylib/crewai/src/crewai/skills/__init__.pylib/crewai/tests/experimental/skills/__init__.pylib/crewai/tests/experimental/skills/conftest.pylib/crewai/tests/experimental/skills/test_cache.pylib/crewai/tests/experimental/skills/test_flag.pylib/crewai/tests/experimental/skills/test_models_version.pylib/crewai/tests/experimental/skills/test_registry.py
💤 Files with no reviewable changes (2)
- lib/crewai/src/crewai/skills/init.py
- lib/crewai/src/crewai/events/types/skill_events.py
The skill version is now stored as `metadata.version` rather than a top-level field on `SkillFrontmatter`. A `before` validator lifts any top-level YAML `version:` into `metadata['version']` so existing SKILL.md files keep parsing. - crewai.skills.models: drop `version` field; add lift validator - crewai_cli experimental skill template: `metadata.version: 0.1.0` - publish/_read_version: read from metadata first, fall back to top-level - test_models_version: cover metadata access, lift, and precedence
Per the agentskills.io spec, `version` only ever lives under `metadata` — top-level was never a valid frontmatter field. Remove the back-compat lift validator on SkillFrontmatter and the matching CLI fallback in publish/_read_version.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@lib/crewai/src/crewai/skills/models.py`:
- Around line 97-105: The lift_top_level_version method is currently using
values.get("metadata") or {} which will coerce falsy but invalid metadata (e.g.
"" or []) into an empty dict and hide malformed input; change the logic in
lift_top_level_version to only default metadata to {} when metadata is exactly
None, e.g. metadata = values.get("metadata") and if metadata is None: metadata =
{}; then ensure you only assign metadata["version"] when isinstance(metadata,
dict) and finally return values from lift_top_level_version so the updated dict
is returned.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 13e704b7-aae6-41ca-b943-49c7018cdba9
📒 Files selected for processing (3)
lib/cli/src/crewai_cli/experimental/skills/main.pylib/crewai/src/crewai/skills/models.pylib/crewai/tests/experimental/skills/test_models_version.py
lorenzejay
approved these changes
May 28, 2026
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 9d3ef6c. Configure here.
|
Actionable comments posted: 0 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
crewai.experimental.skillsand the CLI commands undercrewai experimental skill. The stable local-file skills feature (loader, parser, validation, models) stays increwai.skills.CREWAI_EXPERIMENTAL=1:resolve_registry_ref()callsrequire_experimental_skills(), and thecrewai experimentalCLI group raisesUsageErrorwhen the flag is unset.SkillDownloadStartedEvent/SkillDownloadCompletedEventmove out ofcrewai.events.types.skill_eventsintocrewai.experimental.skills.events(these events are not re-exported fromcrewai.events, so no public surface change).What moved
SDK (
lib/crewai/src/crewai/)skills/cache.py→experimental/skills/cache.pyskills/registry.py→experimental/skills/registry.pyexperimental/skills/_flag.py,experimental/skills/events.pyagent/core.pyrewired to import fromcrewai.experimental.skills.registrycrewai.skills.__init__no longer re-exportsSkillCacheManager/is_registry_ref/resolve_registry_refCLI (
lib/cli/src/crewai_cli/)skills/→experimental/skills/crewai experimental skill {create,install,publish,list}Tests — moved to
lib/{crewai,cli}/tests/experimental/skills/; added aconftest.pyautouse fixture to set the flag andtest_flag.pycovering the gate.Test plan
pytest lib/crewai/tests/experimental/skills/ lib/cli/tests/experimental/skills/ lib/crewai/tests/skills/— 109 passedruff checkon touched paths cleancrewai.experimental.skills.*,crewai_cli.experimental.skills.main,Agent,Crewcrewai experimental skill listwithout flag → UsageError; withCREWAI_EXPERIMENTAL=1→ worksAgent(skills=['@org/x']).set_skills()without flag →ExperimentalFeatureDisabledErrorNote
Medium Risk
Breaking for callers of removed crewai.skills registry exports and old crewai skill CLI; SKILL.md must use metadata.version for publish. Gating limits blast radius for users who do not opt in.
Overview
Registry-backed skills (cache,
@org/nameresolution, downloads) move undercrewai.experimental.skillsandcrewai experimental skill, both gated byCREWAI_EXPERIMENTAL=1. Stable filesystem skills stay increwai.skills; its public exports drop cache/registry helpers.resolve_registry_ref()and the experimental CLI group fail fast without the flag. Download lifecycle events move tocrewai.experimental.skills.events.SkillFrontmatterno longer has a top-levelversion; publishing and templates usemetadata.version(agentskills.io). Tests relocate undertests/experimental/skills/with autouse flag fixtures.Reviewed by Cursor Bugbot for commit 9d3ef6c. Bugbot is set up for automated code reviews on this repo. Configure here.
Summary by CodeRabbit
New Features
Refactor
Tests