fix(skills): resolve registry skills through the installed AMP client

Skill downloads built their own `PlusAPI` and authenticated it from
`CREWAI_USER_PAT`, the platform integration token, or the saved CLI login.
Managed runtimes have no user credential to offer: they install a client of
their own, which `load_agent_from_repository` already resolves through, so
Agent Repository lookups worked while the skill downloads beside them failed
with 401.

Skills now resolve their client the same way, via `resolve_plus_client()` next
to the hook it reads. A client that can't fetch skills falls back to
environment credentials and warns, so older runtimes behave as they do today.
`resolve_plus_response()` shares the sync/async bridging both lookups need,
since `PlusAPI` is synchronous while managed clients are not.

Version pinning, which the same bug was hiding:

- Registry refs accept `@org/name@version`, and `@org/name@v1.2.0` since people
  write it both ways. `parse_skill_ref()` returns a `SkillRef(org, name,
  version)`; `parse_registry_ref()` keeps its `(org, name)` shape and drops the
  pin, so existing callers are unaffected
- Agent Repository agents record a version per skill, which was parsed off the
  response and dropped. Those pins now travel with the refs, so publishing a
  new version of a skill no longer changes every agent that uses it
- A pinned ref only accepts a project-local copy declaring that version in its
  `metadata.version` frontmatter, and the cache reports a miss when the version
  it recorded differs — so a pin re-resolves rather than loading another
  version. Unpinned refs keep hitting the cache as before
- An unknown pin fails instead of quietly falling back to the newest 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,43 @@ 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
+        if not isinstance(meta, dict):
+            _logger.debug("Malformed cache entry: %s", meta_file)
+            return False
+        # versions_match() treats a non-string version as no match, so a
+        # corrupted entry reads as a miss rather than raising.
+        return versions_match(version, meta.get("version"))
 
     def store(
         self, org: str, name: str, version: str | None, archive_bytes: bytes