fix(skills): resolve registry skills through the runtime's CrewAI+ client

Skill downloads built their own `PlusAPI` and authenticated it from
`CREWAI_USER_PAT`, the platform integration token, or the saved CLI login. An
Enterprise deployment has none of those, so loading a repository agent that
carries skills failed on the download — while the agent fetch beside it
succeeded, because that path goes through the client the runtime installs.

Skills now resolve their client the same way:

- Add `crewai.utilities.plus_client_factory` with `set_plus_client_factory()` /
  `resolve_plus_client()`, and route both the Agent Repository and the Skills
  Repository through it, so a new registry lookup can't accidentally reach for a
  credential a deployment doesn't have. It also reads the legacy
  `agent_utils._create_plus_client_hook` slot, so already-released runtimes that
  patch that attribute pick up skills without a matched upgrade
- A client that can't fetch skills falls back to environment credentials and
  warns, keeping behavior unchanged on older runtimes
- Move the sync/async response bridging out of `load_agent_from_repository` into
  `resolve_response()`, shared by both call sites

Version pinning, which the same bug was hiding:

- Registry refs accept `@org/name@version` (`@org/name@v1.2.0` too), parsed by
  the new `parse_skill_ref()` returning a `SkillRef`. `parse_registry_ref()`
  keeps its `(org, name)` shape for compatibility
- Repository agents record a version per skill in `skill_versions`, which was
  parsed off the response and dropped. Those pins are now folded into the skill
  refs, so publishing a new version of a skill no longer silently changes every
  agent using it
- A pinned ref only accepts a local or cached copy declaring that version, and
  the cache reports a miss when its recorded version differs, so a pin
  re-resolves instead of loading the wrong version

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: joaomdmoura

docs/edge/en/concepts/skills.mdx

@@ -221,6 +221,32 @@ agent = Agent(
 )
 ```
 
+### Pin a Version
+
+An unpinned reference resolves to the newest published version, so publishing a
+new version changes every agent that references it. Append `@<version>` to pin
+one instead:
+
+```python
+agent = Agent(
+    role="Senior Code Reviewer",
+    goal="Review pull requests for quality and security issues",
+    backstory="Staff engineer with expertise in secure coding practices.",
+    skills=["@acme/code-review@1.2.0"],  # pinned; a leading "v" also works
+)
+```
+
+A pinned reference only accepts a cached or project-local copy that reports the
+same version in its `metadata.version` frontmatter, and re-downloads otherwise —
+a pin asks for a specific version rather than hinting at one. Pinning an
+unpublished version fails rather than falling back to the latest.
+
+<Note>
+Agents from the **Agent Repository** are pinned automatically: the repository
+records a version alongside each skill it assigns, and the runtime applies those
+pins when it loads the agent.
+</Note>
+
 ### List
 
 ```shell Terminal

lib/crewai/src/crewai/experimental/skills/__init__.py

@@ -12,8 +12,10 @@
 from crewai.skills import cache, events, registry
 from crewai.skills.cache import SkillCacheManager
 from crewai.skills.registry import (
+    SkillRef,
     is_registry_ref,
     parse_registry_ref,
+    parse_skill_ref,
     resolve_registry_ref,
 )
 
@@ -26,10 +28,12 @@
 
 __all__ = [
     "SkillCacheManager",
+    "SkillRef",
     "cache",
     "events",
     "is_registry_ref",
     "parse_registry_ref",
+    "parse_skill_ref",
     "registry",
     "resolve_registry_ref",
 ]

lib/crewai/src/crewai/skills/__init__.py

@@ -15,8 +15,10 @@
 from crewai.skills.models import Skill, SkillFrontmatter
 from crewai.skills.parser import SkillParseError
 from crewai.skills.registry import (
+    SkillRef,
     is_registry_ref,
     parse_registry_ref,
+    parse_skill_ref,
     resolve_registry_ref,
 )
 
@@ -26,11 +28,13 @@
     "SkillCacheManager",
     "SkillFrontmatter",
     "SkillParseError",
+    "SkillRef",
     "activate_skill",
     "discover_skills",
     "is_registry_ref",
     "load_skill",
     "load_skills",
     "parse_registry_ref",
+    "parse_skill_ref",
     "resolve_registry_ref",
 ]

lib/crewai/src/crewai/skills/cache.py

@@ -15,6 +15,8 @@
 from typing import TypedDict
 import zipfile
 
+from crewai.skills.validation import versions_match
+
 
 _logger = logging.getLogger(__name__)
 
@@ -39,13 +41,38 @@ def __init__(self, cache_root: Path | None = None) -> None:
     def _skill_dir(self, org: str, name: str) -> Path:
         return self._root / org / name
 
-    def get_cached_path(self, org: str, name: str) -> Path | None:
-        """Return the cached skill directory path if it exists, else None."""
+    def get_cached_path(
+        self, org: str, name: str, version: str | None = None
+    ) -> Path | None:
+        """Return the cached skill directory path if usable, else None.
+
+        Args:
+            org: Organisation slug.
+            name: Skill name.
+            version: When given, the cached entry must record this version.
+                The cache holds one version per skill, so a pinned lookup for a
+                different version reports a miss and the caller re-downloads
+                rather than loading the wrong version.
+
+        Returns:
+            The cached skill directory, or None on a miss.
+        """
         skill_dir = self._skill_dir(org, name)
         meta_file = skill_dir / _META_FILENAME
-        if skill_dir.is_dir() and meta_file.exists():
-            return skill_dir
-        return None
+        if not (skill_dir.is_dir() and meta_file.exists()):
+            return None
+        if version is not None and not self._records_version(meta_file, version):
+            return None
+        return skill_dir
+
+    def _records_version(self, meta_file: Path, version: str) -> bool:
+        """Return True when the cache metadata records *version*."""
+        try:
+            meta = json.loads(meta_file.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            _logger.debug("Unreadable cache entry: %s", meta_file, exc_info=True)
+            return False
+        return versions_match(version, meta.get("version"))
 
     def store(
         self, org: str, name: str, version: str | None, archive_bytes: bytes