fix: resolve mypy no-redef error for reasoning_content

Co-Authored-By: João <joao@crewai.com>

.github/workflows/build-uv-cache.yml

@@ -26,7 +26,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
         with:
           version: "0.11.3"
           python-version: ${{ matrix.python-version }}

.github/workflows/generate-tool-specs.yml

@@ -22,10 +22,10 @@ jobs:
     steps:
       - name: Generate GitHub App token
         id: app-token
-        uses: tibdex/github-app-token@v2
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
         with:
-          app_id: ${{ secrets.CREWAI_TOOL_SPECS_APP_ID }}
-          private_key: ${{ secrets.CREWAI_TOOL_SPECS_PRIVATE_KEY }}
+          app-id: ${{ secrets.CREWAI_TOOL_SPECS_APP_ID }}
+          private-key: ${{ secrets.CREWAI_TOOL_SPECS_PRIVATE_KEY }}
 
       - name: Checkout code
         uses: actions/checkout@v4
@@ -34,7 +34,7 @@ jobs:
           token: ${{ steps.app-token.outputs.token }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
         with:
           version: "0.11.3"
           python-version: "3.12"

.github/workflows/linter.yml

@@ -13,7 +13,7 @@ jobs:
       code: ${{ steps.filter.outputs.code }}
     steps:
       - uses: actions/checkout@v4
-      - uses: dorny/paths-filter@v3
+      - uses: dorny/paths-filter@d1c1ffe0248fe513906c8e24db8ea791d46f8590 # v3
         id: filter
         with:
           filters: |
@@ -41,7 +41,7 @@ jobs:
             uv-main-py3.11-
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
         with:
           version: "0.11.3"
           python-version: "3.11"

.github/workflows/nightly.yml

@@ -44,7 +44,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
         with:
           version: "0.11.3"
           python-version: "3.12"
@@ -103,7 +103,7 @@ jobs:
       contents: read
     steps:
       - name: Install uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
         with:
           version: "0.11.3"
           python-version: "3.12"

.github/workflows/pr-size.yml

@@ -10,7 +10,7 @@ jobs:
     permissions:
       pull-requests: write
     steps:
-      - uses: codelytv/pr-size-labeler@v1
+      - uses: codelytv/pr-size-labeler@095a41fca88b8764fd9e008ad269bcdb82bb38b9 # v1
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           xs_label: "size/XS"

.github/workflows/pr-title.yml

@@ -12,7 +12,7 @@ jobs:
   pr-title:
     runs-on: ubuntu-latest
     steps:
-      - uses: amannn/action-semantic-pull-request@v5
+      - uses: amannn/action-semantic-pull-request@e32d7e603df1aa1ba07e981f2a23455dee596825 # v5
         continue-on-error: true
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/publish.yml

@@ -34,7 +34,7 @@ jobs:
           python-version: "3.12"
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v4
 
       - name: Build packages
         run: |
@@ -63,7 +63,7 @@ jobs:
           ref: ${{ inputs.release_tag || github.ref }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
         with:
           version: "0.11.3"
           python-version: "3.12"
@@ -159,7 +159,7 @@ jobs:
 
       - name: Notify Slack
         if: success()
-        uses: slackapi/slack-github-action@v2.1.0
+        uses: slackapi/slack-github-action@b0fa283ad8fea605de13dc3f449259339835fc52 # v2.1.0
         with:
           webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
           webhook-type: incoming-webhook

.github/workflows/tests.yml

@@ -13,7 +13,7 @@ jobs:
       code: ${{ steps.filter.outputs.code }}
     steps:
       - uses: actions/checkout@v4
-      - uses: dorny/paths-filter@v3
+      - uses: dorny/paths-filter@d1c1ffe0248fe513906c8e24db8ea791d46f8590 # v3
         id: filter
         with:
           filters: |
@@ -51,7 +51,7 @@ jobs:
             uv-main-py${{ matrix.python-version }}-
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
         with:
           version: "0.11.3"
           python-version: ${{ matrix.python-version }}

.github/workflows/type-checker.yml

@@ -13,7 +13,7 @@ jobs:
       code: ${{ steps.filter.outputs.code }}
     steps:
       - uses: actions/checkout@v4
-      - uses: dorny/paths-filter@v3
+      - uses: dorny/paths-filter@d1c1ffe0248fe513906c8e24db8ea791d46f8590 # v3
         id: filter
         with:
           filters: |
@@ -48,7 +48,7 @@ jobs:
             uv-main-py${{ matrix.python-version }}-
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
         with:
           version: "0.11.3"
           python-version: ${{ matrix.python-version }}

.github/workflows/update-test-durations.yml

@@ -38,7 +38,7 @@ jobs:
             uv-main-py${{ matrix.python-version }}-
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
         with:
           version: "0.11.3"
           python-version: ${{ matrix.python-version }}

.github/workflows/vulnerability-scan.yml

@@ -31,7 +31,7 @@ jobs:
             uv-main-py3.11-
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
         with:
           version: "0.11.3"
           python-version: "3.11"
@@ -46,11 +46,39 @@ jobs:
       - name: Run pip-audit
         run: |
           uv run pip-audit --desc --aliases --skip-editable --format json --output pip-audit-report.json \
-            --ignore-vuln CVE-2026-3219 \
-            --ignore-vuln GHSA-r374-rxx8-8654
+            --ignore-vuln PYSEC-2024-277 \
+            --ignore-vuln PYSEC-2026-89 \
+            --ignore-vuln PYSEC-2026-97 \
+            --ignore-vuln PYSEC-2025-148 \
+            --ignore-vuln PYSEC-2025-183 \
+            --ignore-vuln PYSEC-2025-189 \
+            --ignore-vuln PYSEC-2025-190 \
+            --ignore-vuln PYSEC-2025-191 \
+            --ignore-vuln PYSEC-2025-192 \
+            --ignore-vuln PYSEC-2025-193 \
+            --ignore-vuln PYSEC-2025-194 \
+            --ignore-vuln PYSEC-2025-195 \
+            --ignore-vuln PYSEC-2025-196 \
+            --ignore-vuln PYSEC-2025-197 \
+            --ignore-vuln PYSEC-2025-210 \
+            --ignore-vuln PYSEC-2026-139 \
+            --ignore-vuln PYSEC-2025-211 \
+            --ignore-vuln PYSEC-2025-212 \
+            --ignore-vuln PYSEC-2025-213 \
+            --ignore-vuln PYSEC-2025-214 \
+            --ignore-vuln PYSEC-2025-215 \
+            --ignore-vuln PYSEC-2025-216 \
+            --ignore-vuln PYSEC-2025-217 \
+            --ignore-vuln PYSEC-2025-218
         # Ignored CVEs:
-        #   CVE-2026-3219      - pip 26.0.1 (GHSA-58qw-9mgm-455v): no fix available, archive handling issue
-        #   GHSA-r374-rxx8-8654 - paramiko 4.0.0 (SHA-1 in rsakey.py): no fix available; transitive via composio-core
+        #   PYSEC-2024-277      - joblib 1.5.3: disputed; NumpyArrayWrapper only used with trusted caches
+        #   PYSEC-2026-89       - markdown 3.10.2: DoS via malformed HTML; fix 3.8.1 — already past, advisory range is stale
+        #   PYSEC-2026-97       - nltk 3.9.4: arbitrary file read in filestring(); no fix available
+        #   PYSEC-2025-148      - onnx 1.21.0: path traversal in save_external_data; no fix available
+        #   PYSEC-2025-183      - pyjwt 2.12.1: disputed weak-encryption claim; key length is application-chosen
+        #   PYSEC-2025-189..197 - torch 2.11.0: memory-corruption/DoS in functions only reachable via untrusted models; no fix available
+        #   PYSEC-2025-210, PYSEC-2026-139 - torch 2.11.0: profiler/deserialization issues; no fix available
+        #   PYSEC-2025-211..218 - transformers 5.5.4: deserialization/code injection via malicious model checkpoints; no fix available
         continue-on-error: true
 
       - name: Display results

docs/ar/enterprise/guides/enable-crew-studio.mdx

@@ -146,7 +146,6 @@ Crew Studio هو طريقة مبتكرة لإنشاء طواقم وكلاء ال
 
   </Step>
 
-{" "}
 <Step title="الإجابة على الأسئلة">
   أجب على أسئلة التوضيح من مساعد الطاقم لتنقيح
   متطلباتك.
@@ -161,12 +160,10 @@ Crew Studio هو طريقة مبتكرة لإنشاء طواقم وكلاء ال
 
   </Step>
 
-{" "}
 <Step title="الموافقة أو التعديل">
   وافق على الخطة أو اطلب تغييرات إذا لزم الأمر.
 </Step>
 
-{" "}
 <Step title="التنزيل أو النشر">
   نزّل الكود للتخصيص أو انشر مباشرة على المنصة.
 </Step>

docs/ar/learn/llm-selection-guide.mdx

@@ -802,7 +802,6 @@ The tables below show a representative sample of current top-performing models a
     Begin with well-established models like **GPT-4.1**, **Claude 3.7 Sonnet**, or **Gemini 2.0 Flash** that offer good performance across multiple dimensions and have extensive real-world validation.
   </Step>
 
-{" "}
 <Step title="Identify Specialized Needs">
   Determine if your crew has specific requirements (coding, reasoning, speed)
   that would benefit from specialized models like **Claude 4 Sonnet** for
@@ -810,7 +809,6 @@ The tables below show a representative sample of current top-performing models a
   consider fast inference providers like **Groq** alongside model selection.
 </Step>
 
-{" "}
 <Step title="Implement Multi-Model Strategy">
   Use different models for different agents based on their roles.
   High-capability models for managers and complex tasks, efficient models for

docs/en/enterprise/guides/enable-crew-studio.mdx

@@ -146,7 +146,6 @@ Here's a typical workflow for creating a crew with Crew Studio:
 
   </Step>
 
-{" "}
 <Step title="Answer Questions">
   Respond to clarifying questions from the Crew Assistant to refine your
   requirements.
@@ -161,12 +160,10 @@ Here's a typical workflow for creating a crew with Crew Studio:
 
   </Step>
 
-{" "}
 <Step title="Approve or Modify">
   Approve the plan or request changes if necessary.
 </Step>
 
-{" "}
 <Step title="Download or Deploy">
   Download the code for customization or deploy directly to the platform.
 </Step>

docs/en/learn/llm-selection-guide.mdx

@@ -805,7 +805,6 @@ The tables below show a representative sample of current top-performing models a
     Begin with well-established models like **GPT-4.1**, **Claude 3.7 Sonnet**, or **Gemini 2.0 Flash** that offer good performance across multiple dimensions and have extensive real-world validation.
   </Step>
 
-{" "}
 <Step title="Identify Specialized Needs">
   Determine if your crew has specific requirements (coding, reasoning, speed)
   that would benefit from specialized models like **Claude 4 Sonnet** for
@@ -813,7 +812,6 @@ The tables below show a representative sample of current top-performing models a
   consider fast inference providers like **Groq** alongside model selection.
 </Step>
 
-{" "}
 <Step title="Implement Multi-Model Strategy">
   Use different models for different agents based on their roles.
   High-capability models for managers and complex tasks, efficient models for

docs/ko/enterprise/guides/enable-crew-studio.mdx

@@ -145,7 +145,6 @@ LLM 연결과 기본 설정을 구성했다면 이제 Crew Studio 사용을 시
 
   </Step>
 
-{" "}
 <Step title="질문에 답하기">
   crew assistant가 요구 사항을 구체화할 수 있도록 하는 추가 질문에 답변하세요.
 </Step>
@@ -159,12 +158,10 @@ LLM 연결과 기본 설정을 구성했다면 이제 Crew Studio 사용을 시
 
   </Step>
 
-{" "}
 <Step title="승인 또는 수정">
   계획을 승인하거나 필요하다면 변경을 요청하세요.
 </Step>
 
-{" "}
 <Step title="다운로드 또는 배포">
   사용자화를 위해 코드를 다운로드하거나 플랫폼에 직접 배포하세요.
 </Step>

docs/ko/learn/llm-selection-guide.mdx

@@ -797,7 +797,6 @@ LLM 선택을 최적화하고자 하는 팀을 위해 **CrewAI AMP 플랫폼**
     여러 차원에서 우수한 성능을 제공하며 실제 환경에서 광범위하게 검증된 **GPT-4.1**, **Claude 3.7 Sonnet**, **Gemini 2.0 Flash**와 같은 잘 알려진 모델부터 시작하십시오.
   </Step>
 
-{" "}
 <Step title="특화된 요구 사항 식별">
   crew에 코드 작성, reasoning, 속도 등 특정 요구가 있는지 확인하고, 이러한
   요구에 부합하는 **Claude 4 Sonnet**(개발용) 또는 **o3**(복잡한 분석용)과 같은
@@ -805,7 +804,6 @@ LLM 선택을 최적화하고자 하는 팀을 위해 **CrewAI AMP 플랫폼**
   더불어 **Groq**와 같은 빠른 추론 제공자를 고려할 수 있습니다.
 </Step>
 
-{" "}
 <Step title="다중 모델 전략 구현">
   각 에이전트의 역할에 따라 다양한 모델을 사용하세요. 관리자와 복잡한 작업에는
   고성능 모델을, 일상적 운영에는 효율적인 모델을 적용합니다.

docs/pt-BR/enterprise/guides/enable-crew-studio.mdx

@@ -146,7 +146,6 @@ Veja um fluxo de trabalho típico para criação de um crew com o Crew Studio:
 
   </Step>
 
-{" "}
 <Step title="Responder Perguntas">
   Responda às perguntas de esclarecimento do Crew Assistant para refinar seus
   requisitos.
@@ -161,12 +160,10 @@ Veja um fluxo de trabalho típico para criação de um crew com o Crew Studio:
 
   </Step>
 
-{" "}
 <Step title="Aprovar ou Modificar">
   Aprove o plano ou solicite alterações, se necessário.
 </Step>
 
-{" "}
 <Step title="Baixar ou Fazer Deploy">
   Baixe o código para personalização ou faça o deploy diretamente na plataforma.
 </Step>

docs/pt-BR/learn/llm-selection-guide.mdx

@@ -797,7 +797,6 @@ As tabelas abaixo mostram uma amostra dos modelos de maior destaque em cada cate
     Inicie com opções consagradas como **GPT-4.1**, **Claude 3.7 Sonnet** ou **Gemini 2.0 Flash**, que oferecem bom desempenho e ampla validação.
   </Step>
 
-{" "}
 <Step title="Identifique Demandas Especializadas">
   Descubra se sua crew possui requisitos específicos (código, raciocínio,
   velocidade) que justifiquem modelos como **Claude 4 Sonnet** para
@@ -805,7 +804,6 @@ As tabelas abaixo mostram uma amostra dos modelos de maior destaque em cada cate
   velocidade, considere Groq aliado à seleção do modelo.
 </Step>
 
-{" "}
 <Step title="Implemente Estratégia Multi-Modelo">
   Use modelos diferentes para agentes distintos conforme o papel. Modelos de
   alta capacidade para managers e tarefas complexas, eficientes para rotinas.

lib/cli/src/crewai_cli/cli.py

@@ -26,6 +26,7 @@ from crewai_cli.replay_from_task import replay_task_command
 from crewai_cli.reset_memories_command import reset_memories_command
 from crewai_cli.run_crew import run_crew
 from crewai_cli.settings.main import SettingsCommand
+from crewai_cli.skills.main import SkillCommand
 from crewai_cli.task_outputs import load_task_outputs
 from crewai_cli.tools.main import ToolCommand
 from crewai_cli.train_crew import train_crew
@@ -546,6 +547,56 @@ def tool_publish(is_public: bool, force: bool) -> None:
     tool_cmd.publish(is_public, force)
 
 
+@crewai.group()
+def skill() -> None:
+    """Skill Repository related commands."""
+
+
+@skill.command(name="create")
+@click.argument("name")
+@click.option(
+    "--no-project",
+    "in_project",
+    is_flag=True,
+    default=True,
+    flag_value=False,
+    help="Create skill in current dir instead of ./skills/",
+)
+def skill_create(name: str, in_project: bool) -> None:
+    skill_cmd = SkillCommand()
+    skill_cmd.create(name, in_project=in_project)
+
+
+@skill.command(name="install")
+@click.argument("ref")
+def skill_install(ref: str) -> None:
+    skill_cmd = SkillCommand()
+    skill_cmd.install(ref)
+
+
+@skill.command(name="publish")
+@click.option(
+    "--force",
+    is_flag=True,
+    default=False,
+    show_default=True,
+    help="Skip git-state validation.",
+)
+@click.option("--public", "is_public", flag_value=True, default=False)
+@click.option("--private", "is_public", flag_value=False)
+@click.option("--org", default=None, help="Organisation slug (overrides settings).")
+def skill_publish(is_public: bool, org: str | None, force: bool) -> None:
+    skill_cmd = SkillCommand()
+    skill_cmd.publish(is_public, org=org, force=force)
+
+
+@skill.command(name="list")
+def skill_list() -> None:
+    """List locally installed skills."""
+    skill_cmd = SkillCommand()
+    skill_cmd.list_cached()
+
+
 @crewai.group()
 def template() -> None:
     """Browse and install project templates."""

lib/cli/src/crewai_cli/deploy/main.py

@@ -1,5 +1,6 @@
 from typing import Any
 
+from crewai_core.plus_api import CreateCrewPayload
 from rich.console import Console
 
 from crewai_cli import git
@@ -161,7 +162,7 @@ class DeployCommand(BaseCommand, PlusAPIMixin):
         self,
         env_vars: dict[str, str],
         remote_repo_url: str,
-    ) -> dict[str, Any]:
+    ) -> CreateCrewPayload:
         """
         Create the payload for crew creation.
 
@@ -172,6 +173,8 @@ class DeployCommand(BaseCommand, PlusAPIMixin):
         Returns:
             Dict[str, Any]: The payload for crew creation.
         """
+        if not self.project_name:
+            raise ValueError("project_name is required to create a deployment payload")
         return {
             "deploy": {
                 "name": self.project_name,

lib/cli/src/crewai_cli/git.py

@@ -40,7 +40,7 @@ class Repository:
             encoding="utf-8",
         ).strip()
 
-    @cached_property  # noqa: B019
+    @cached_property
     def is_git_repo(self) -> bool:
         """Check if the current directory is a git repository."""
         try:

lib/cli/src/crewai_cli/skills/main.py

@@ -0,0 +1,415 @@
+"""Skill Repository CLI commands for CrewAI."""
+
+from __future__ import annotations
+
+import base64
+import io
+import json
+import os
+from pathlib import Path
+import tarfile
+import zipfile
+
+from rich.console import Console
+from rich.table import Table
+
+from crewai_cli.command import BaseCommand, PlusAPIMixin
+from crewai_cli.config import Settings
+from crewai_cli.constants import DEFAULT_CREWAI_ENTERPRISE_URL
+
+
+console = Console()
+
+_SKILL_MD_TEMPLATE = """\
+---
+name: {name}
+version: 0.1.0
+description: |
+  A short description of what this skill does.
+---
+
+## Instructions
+
+Describe the skill behaviour here. This section is shown to the agent at activation time.
+"""
+
+
+class SkillCommand(BaseCommand, PlusAPIMixin):
+    """Skill Repository related operations for CrewAI projects."""
+
+    def __init__(self) -> None:
+        BaseCommand.__init__(self)
+        PlusAPIMixin.__init__(self, telemetry=self._telemetry)
+
+    # ------------------------------------------------------------------
+    # create
+    # ------------------------------------------------------------------
+
+    def create(self, name: str, in_project: bool = True) -> None:
+        """Scaffold a new skill directory.
+
+        If pyproject.toml is present (crew project), creates ./skills/{name}/.
+        Otherwise creates ./{name}/.
+        """
+        if in_project and os.path.isfile("pyproject.toml"):
+            skill_dir = Path("skills") / name
+        else:
+            skill_dir = Path(name)
+
+        if skill_dir.exists():
+            console.print(f"[red]Directory {skill_dir} already exists.[/red]")
+            raise SystemExit(1)
+
+        skill_dir.mkdir(parents=True)
+        (skill_dir / "scripts").mkdir()
+        (skill_dir / "references").mkdir()
+        (skill_dir / "assets").mkdir()
+
+        skill_md = skill_dir / "SKILL.md"
+        skill_md.write_text(_SKILL_MD_TEMPLATE.format(name=name))
+
+        console.print(
+            f"[green]Created skill [bold]{name}[/bold] at [bold]{skill_dir}[/bold].[/green]"
+        )
+        console.print(f"Edit [bold]{skill_md}[/bold] to define the skill instructions.")
+
+    # ------------------------------------------------------------------
+    # install
+    # ------------------------------------------------------------------
+
+    def install(self, ref: str) -> None:
+        """Download and install a registry skill.
+
+        Format: @org/name
+
+        Inside a crew project (pyproject.toml present): installs to ./skills/{name}/
+        Outside a project: installs to ~/.crewai/skills/{org}/{name}/
+        """
+        if not ref.startswith("@"):
+            console.print(
+                "[red]Invalid skill reference. Use the format @org/name.[/red]"
+            )
+            raise SystemExit(1)
+
+        without_at = ref[1:]
+        if without_at.count("/") != 1:
+            console.print(
+                "[red]Invalid skill reference. Use the format @org/name.[/red]"
+            )
+            raise SystemExit(1)
+
+        org, name = without_at.split("/", 1)
+        if (
+            not org
+            or not name
+            or org.startswith(".")
+            or name.startswith(".")
+            or len(Path(org).parts) != 1
+            or len(Path(name).parts) != 1
+        ):
+            console.print(
+                "[red]Invalid skill reference: org and name must be single, "
+                "non-empty path segments (no slashes, no '..').[/red]"
+            )
+            raise SystemExit(1)
+
+        self._print_current_organization()
+        console.print(f"[bold blue]Downloading skill {ref}...[/bold blue]")
+
+        get_response = self.plus_api_client.get_skill(org, name)
+
+        if get_response.status_code == 404:
+            console.print(
+                f"[red]Skill {ref} not found. Ensure it has been published and you have access.[/red]"
+            )
+            raise SystemExit(1)
+        if get_response.status_code != 200:
+            console.print(
+                f"[red]Failed to download skill {ref}: {get_response.status_code}[/red]"
+            )
+            raise SystemExit(1)
+
+        data = get_response.json()
+        version = data.get("latest_version") or data.get("version")
+
+        download_url = data.get("download_url")
+        if download_url:
+            import httpx
+
+            dl_response = httpx.get(download_url, follow_redirects=True)
+            dl_response.raise_for_status()
+            archive_bytes = dl_response.content
+        else:
+            encoded = data.get("file", "")
+            if "," in encoded:
+                encoded = encoded.split(",", 1)[1]
+            archive_bytes = base64.b64decode(encoded)
+
+        in_project = os.path.isfile("pyproject.toml")
+        if in_project:
+            dest = Path("skills") / name
+            dest.mkdir(parents=True, exist_ok=True)
+            self._unpack_archive(archive_bytes, dest)
+            console.print(
+                f"[green]Installed [bold]{ref}[/bold]{' (' + version + ')' if version else ''} to [bold]{dest}[/bold].[/green]"
+            )
+        else:
+            try:
+                from crewai.skills.cache import SkillCacheManager
+
+                cache = SkillCacheManager()
+                cache.store(org, name, version, archive_bytes)
+            except ImportError:
+                # Fallback if SDK not installed — write directly
+                cache_dir = Path.home() / ".crewai" / "skills" / org / name
+                if cache_dir.exists():
+                    import shutil
+
+                    shutil.rmtree(cache_dir)
+                cache_dir.mkdir(parents=True, exist_ok=True)
+                self._unpack_archive(archive_bytes, cache_dir)
+                # Write metadata so `crewai skill list` can discover it
+                from datetime import datetime, timezone
+
+                meta = {
+                    "org": org,
+                    "name": name,
+                    "version": version,
+                    "installed_at": datetime.now(tz=timezone.utc).isoformat(),
+                }
+                (cache_dir / ".crewai_meta.json").write_text(json.dumps(meta, indent=2))
+            console.print(
+                f"[green]Installed [bold]{ref}[/bold]{' (' + version + ')' if version else ''} to global cache.[/green]"
+            )
+
+    # ------------------------------------------------------------------
+    # publish
+    # ------------------------------------------------------------------
+
+    def publish(self, is_public: bool, org: str | None, force: bool = False) -> None:
+        """Publish the skill in the current directory to the registry."""
+        skill_md = Path("SKILL.md")
+        if not skill_md.exists():
+            console.print(
+                "[red]No SKILL.md found in current directory. "
+                "Run this command from inside a skill directory.[/red]"
+            )
+            raise SystemExit(1)
+
+        # Parse frontmatter to extract name + version
+        try:
+            frontmatter = self._parse_frontmatter(skill_md.read_text())
+        except ValueError as exc:
+            console.print(f"[red]Failed to parse SKILL.md frontmatter: {exc}[/red]")
+            raise SystemExit(1) from exc
+
+        name = frontmatter.get("name")
+        version = frontmatter.get("version")
+        description = frontmatter.get("description")
+
+        if not name:
+            console.print(
+                "[red]SKILL.md frontmatter must include a 'name' field.[/red]"
+            )
+            raise SystemExit(1)
+
+        if not version:
+            console.print(
+                "[red]SKILL.md frontmatter must include a 'version' field before publishing.[/red]"
+            )
+            raise SystemExit(1)
+
+        settings = Settings()
+        effective_org = org or settings.org_name
+        if not effective_org:
+            console.print(
+                "[red]No organisation set. Run `crewai org switch <org_id>` first, "
+                "or pass --org.[/red]"
+            )
+            raise SystemExit(1)
+
+        self._print_current_organization()
+        console.print(
+            f"[bold blue]Publishing skill [bold]{name}[/bold] v{version} to {effective_org}...[/bold blue]"
+        )
+
+        archive_bytes = self._build_skill_tarball()
+        encoded_file = "data:application/x-gzip;base64," + base64.b64encode(
+            archive_bytes
+        ).decode("utf-8")
+
+        response = self.plus_api_client.publish_skill(
+            org=effective_org,
+            name=name,
+            version=version,
+            is_public=is_public,
+            description=description,
+            encoded_file=encoded_file,
+        )
+
+        self._validate_response(response)
+
+        base_url = settings.enterprise_base_url or DEFAULT_CREWAI_ENTERPRISE_URL
+        console.print(
+            f"[green]Published [bold]{effective_org}/{name}[/bold] v{version}.\n\n"
+            "Security checks are running in the background. "
+            "Your skill will be available once checks complete.\n"
+            f"Monitor status at: {base_url}/crewai_plus/skills/{effective_org}/{name}[/green]"
+        )
+
+    # ------------------------------------------------------------------
+    # list_cached
+    # ------------------------------------------------------------------
+
+    def list_cached(self) -> None:
+        """Show locally installed skills."""
+        table = Table(title="Installed Skills", show_lines=True)
+        table.add_column("Source", style="dim")
+        table.add_column("Ref")
+        table.add_column("Version")
+        table.add_column("Path")
+
+        # Project-local ./skills/
+        local_skills_dir = Path("skills")
+        if local_skills_dir.is_dir():
+            for skill_dir in sorted(local_skills_dir.iterdir()):
+                if skill_dir.is_dir() and (skill_dir / "SKILL.md").exists():
+                    version = self._read_version(skill_dir / "SKILL.md")
+                    table.add_row(
+                        "project",
+                        skill_dir.name,
+                        version or "-",
+                        str(skill_dir),
+                    )
+
+        # Global cache
+        cache_root = Path.home() / ".crewai" / "skills"
+        if cache_root.exists():
+            for org_dir in sorted(cache_root.iterdir()):
+                if not org_dir.is_dir():
+                    continue
+                for skill_dir in sorted(org_dir.iterdir()):
+                    meta_file = skill_dir / ".crewai_meta.json"
+                    if meta_file.exists():
+                        try:
+                            meta = json.loads(meta_file.read_text())
+                            table.add_row(
+                                "cache",
+                                f"@{meta['org']}/{meta['name']}",
+                                meta.get("version") or "-",
+                                str(skill_dir),
+                            )
+                        except (json.JSONDecodeError, KeyError):
+                            console.print(
+                                f"[yellow]Warning: skipping malformed cache entry at {meta_file}[/yellow]"
+                            )
+
+        console.print(table)
+
+    # ------------------------------------------------------------------
+    # internal helpers
+    # ------------------------------------------------------------------
+
+    def _print_current_organization(self) -> None:
+        settings = Settings()
+        if settings.org_uuid:
+            console.print(
+                f"Current organization: {settings.org_name} ({settings.org_uuid})",
+                style="bold blue",
+            )
+        else:
+            console.print(
+                "No organization currently set. We recommend setting one before using: "
+                "`crewai org switch <org_id>` command.",
+                style="yellow",
+            )
+
+    def _unpack_archive(self, archive_bytes: bytes, dest: Path) -> None:
+        """Unpack a .tar.gz or .zip archive into dest."""
+        # Try tar first, then zip
+        try:
+            with tarfile.open(fileobj=io.BytesIO(archive_bytes), mode="r:gz") as tf:
+                try:
+                    tf.extractall(dest, filter="data")
+                except TypeError:
+                    _safe_extractall(tf, dest)
+            return
+        except tarfile.TarError:
+            pass
+
+        # Fallback: zip
+        with zipfile.ZipFile(io.BytesIO(archive_bytes)) as zf:
+            _safe_extract_zip(zf, dest)
+
+    def _build_skill_tarball(self) -> bytes:
+        """Build an in-memory .tar.gz of SKILL.md + scripts/ + references/ + assets/."""
+        buf = io.BytesIO()
+        with tarfile.open(fileobj=buf, mode="w:gz") as tf:
+            tf.add("SKILL.md")
+            for folder in ("scripts", "references", "assets"):
+                folder_path = Path(folder)
+                if folder_path.is_dir():
+                    for fpath in sorted(folder_path.rglob("*")):
+                        if fpath.is_file():
+                            tf.add(str(fpath))
+        return buf.getvalue()
+
+    def _parse_frontmatter(self, content: str) -> dict[str, str]:
+        """Extract YAML frontmatter fields from a SKILL.md string.
+
+        Reuses crewai.skills.parser when available, with a minimal
+        fallback for environments where the full SDK isn't installed.
+        """
+        try:
+            from crewai.skills.parser import parse_frontmatter
+
+            fm_dict, _ = parse_frontmatter(content)
+            return fm_dict
+        except ImportError:
+            pass
+
+        # Fallback: minimal YAML parsing without SDK dependency
+        import re
+
+        match = re.match(r"^---\n(.*?)\n---", content, re.DOTALL)
+        if not match:
+            raise ValueError("No YAML frontmatter block found")
+        try:
+            import yaml
+
+            return yaml.safe_load(match.group(1)) or {}
+        except ImportError:
+            result: dict[str, str] = {}
+            for line in match.group(1).splitlines():
+                if ":" in line:
+                    key, _, value = line.partition(":")
+                    result[key.strip()] = value.strip()
+            return result
+
+    def _read_version(self, skill_md: Path) -> str | None:
+        """Read the version field from a SKILL.md file, or None."""
+        try:
+            fm = self._parse_frontmatter(skill_md.read_text())
+            return fm.get("version")
+        except Exception:
+            return None
+
+
+def _safe_extractall(tf: tarfile.TarFile, dest: Path) -> None:
+    """Path-traversal-safe extraction for Python < 3.12."""
+    dest_resolved = dest.resolve()
+    for member in tf.getmembers():
+        member_path = (dest / member.name).resolve()
+        if not member_path.is_relative_to(dest_resolved):
+            raise ValueError(f"Blocked path traversal attempt: {member.name!r}")
+    tf.extractall(dest)  # noqa: S202
+
+
+def _safe_extract_zip(zf: zipfile.ZipFile, dest: Path) -> None:
+    """Path-traversal-safe ZIP extraction."""
+    dest_resolved = dest.resolve()
+    for member in zf.namelist():
+        member_path = (dest / member).resolve()
+        if not member_path.is_relative_to(dest_resolved):
+            raise ValueError(f"Blocked path traversal attempt: {member!r}")
+    zf.extractall(dest)  # noqa: S202

lib/cli/tests/skills/test_main.py

@@ -0,0 +1,205 @@
+"""Tests for SkillCommand CLI."""
+
+from __future__ import annotations
+
+import io
+import os
+import tempfile
+import zipfile
+from contextlib import contextmanager
+from datetime import datetime, timedelta
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from crewai_cli.shared.token_manager import TokenManager
+
+
+@contextmanager
+def in_temp_dir():
+    original = os.getcwd()
+    with tempfile.TemporaryDirectory() as td:
+        os.chdir(td)
+        try:
+            yield td
+        finally:
+            os.chdir(original)
+
+
+@pytest.fixture
+def skill_command():
+    with tempfile.TemporaryDirectory() as temp_dir:
+        with patch.object(
+            TokenManager, "_get_secure_storage_path", return_value=Path(temp_dir)
+        ):
+            TokenManager().save_tokens(
+                "test-token", (datetime.now() + timedelta(seconds=36000)).timestamp()
+            )
+            from crewai_cli.skills.main import SkillCommand
+            cmd = SkillCommand()
+            yield cmd
+
+
+# ---------------------------------------------------------------------------
+# create
+# ---------------------------------------------------------------------------
+
+class TestSkillCreate:
+    def test_create_in_project(self, skill_command, tmp_path):
+        with in_temp_dir():
+            # Simulate being inside a project
+            Path("pyproject.toml").write_text("[tool.poetry]\nname = 'test'\n")
+            skill_command.create("my-skill")
+            assert Path("skills/my-skill/SKILL.md").exists()
+            assert Path("skills/my-skill/scripts").is_dir()
+            assert Path("skills/my-skill/references").is_dir()
+            assert Path("skills/my-skill/assets").is_dir()
+
+    def test_create_outside_project(self, skill_command, tmp_path):
+        with in_temp_dir():
+            skill_command.create("standalone-skill", in_project=False)
+            assert Path("standalone-skill/SKILL.md").exists()
+
+    def test_create_adds_name_to_skill_md(self, skill_command):
+        with in_temp_dir():
+            skill_command.create("hello-world", in_project=False)
+            content = Path("hello-world/SKILL.md").read_text()
+            assert "name: hello-world" in content
+            assert "version: 0.1.0" in content
+
+    def test_create_fails_if_dir_exists(self, skill_command):
+        with in_temp_dir():
+            Path("existing-skill").mkdir()
+            with pytest.raises(SystemExit):
+                skill_command.create("existing-skill", in_project=False)
+
+
+# ---------------------------------------------------------------------------
+# install
+# ---------------------------------------------------------------------------
+
+class TestSkillInstall:
+    def _zip_skill(self, name: str) -> bytes:
+        buf = io.BytesIO()
+        with zipfile.ZipFile(buf, "w") as zf:
+            zf.writestr("SKILL.md", f"---\nname: {name}\ndescription: Test.\n---\nInstructions.")
+        return buf.getvalue()
+
+    def test_install_invalid_ref_no_at(self, skill_command):
+        with pytest.raises(SystemExit):
+            skill_command.install("acme/my-skill")
+
+    def test_install_invalid_ref_no_slash(self, skill_command):
+        with pytest.raises(SystemExit):
+            skill_command.install("@acmeskill")
+
+    def test_install_404(self, skill_command):
+        mock_resp = MagicMock()
+        mock_resp.status_code = 404
+        skill_command.plus_api_client.get_skill = MagicMock(return_value=mock_resp)
+
+        with pytest.raises(SystemExit):
+            skill_command.install("@acme/ghost")
+
+    def test_install_in_project(self, skill_command):
+        import base64
+        archive = self._zip_skill("my-skill")
+        encoded = "data:application/zip;base64," + base64.b64encode(archive).decode()
+
+        mock_resp = MagicMock()
+        mock_resp.status_code = 200
+        mock_resp.json.return_value = {"file": encoded, "version": "1.0.0"}
+        skill_command.plus_api_client.get_skill = MagicMock(return_value=mock_resp)
+
+        with in_temp_dir():
+            Path("pyproject.toml").write_text("[tool]\n")
+            skill_command.install("@acme/my-skill")
+            assert Path("skills/my-skill/SKILL.md").exists()
+
+
+# ---------------------------------------------------------------------------
+# publish
+# ---------------------------------------------------------------------------
+
+class TestSkillPublish:
+    def test_publish_no_skill_md(self, skill_command):
+        with in_temp_dir():
+            with pytest.raises(SystemExit):
+                skill_command.publish(is_public=True, org="acme")
+
+    def test_publish_missing_version(self, skill_command):
+        with in_temp_dir():
+            Path("SKILL.md").write_text(
+                "---\nname: my-skill\ndescription: Test.\n---\nInstructions."
+            )
+            with pytest.raises(SystemExit):
+                skill_command.publish(is_public=True, org="acme")
+
+    def test_publish_missing_name(self, skill_command):
+        with in_temp_dir():
+            Path("SKILL.md").write_text(
+                "---\ndescription: Test.\nversion: 1.0.0\n---\nInstructions."
+            )
+            with pytest.raises(SystemExit):
+                skill_command.publish(is_public=True, org="acme")
+
+    def test_publish_no_org(self, skill_command):
+        with in_temp_dir():
+            Path("SKILL.md").write_text(
+                "---\nname: my-skill\nversion: 1.0.0\ndescription: Test.\n---\nInstructions."
+            )
+            with patch.object(skill_command, "plus_api_client") as mock_client:
+                mock_resp = MagicMock()
+                mock_resp.is_success = True
+                mock_resp.status_code = 200
+                mock_resp.json.return_value = {}
+                mock_client.publish_skill.return_value = mock_resp
+                # No org set → should SystemExit (no org_name in settings)
+                with patch("crewai_cli.skills.main.Settings") as mock_settings_cls:
+                    mock_settings_cls.return_value.org_name = None
+                    mock_settings_cls.return_value.enterprise_base_url = None
+                    with pytest.raises(SystemExit):
+                        skill_command.publish(is_public=True, org=None)
+
+    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."
+            )
+            mock_resp = MagicMock()
+            mock_resp.is_success = True
+            mock_resp.status_code = 200
+            mock_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:
+                mock_settings_cls.return_value.org_name = "acme"
+                mock_settings_cls.return_value.enterprise_base_url = None
+
+                skill_command.publish(is_public=False, org="acme")
+
+            skill_command.plus_api_client.publish_skill.assert_called_once()
+            call_kwargs = skill_command.plus_api_client.publish_skill.call_args
+            assert call_kwargs.kwargs["name"] == "my-skill"
+            assert call_kwargs.kwargs["version"] == "1.0.0"
+
+
+# ---------------------------------------------------------------------------
+# list_cached
+# ---------------------------------------------------------------------------
+
+class TestSkillListCached:
+    def test_list_cached_empty(self, skill_command, capsys):
+        with in_temp_dir():
+            skill_command.list_cached()
+            # Should not raise
+
+    def test_list_cached_shows_project_skills(self, skill_command, capsys):
+        with in_temp_dir():
+            skill_dir = Path("skills/my-skill")
+            skill_dir.mkdir(parents=True)
+            (skill_dir / "SKILL.md").write_text(
+                "---\nname: my-skill\nversion: 0.5.0\ndescription: A skill.\n---\nBody."
+            )
+            skill_command.list_cached()
+            # Should complete without error

lib/crewai-core/src/crewai_core/plus_api.py

@@ -3,36 +3,162 @@
 from __future__ import annotations
 
 import os
-from typing import Any
+from typing import Any, Final, Literal, TypedDict, cast
 from urllib.parse import urljoin
 
 import httpx
+from typing_extensions import NotRequired
 
 from crewai_core.constants import DEFAULT_CREWAI_ENTERPRISE_URL
 from crewai_core.settings import Settings
 from crewai_core.version import get_crewai_version
 
 
+HttpMethod = Literal["GET", "POST", "PATCH", "DELETE"]
+
+
+class AvailableExport(TypedDict):
+    name: str
+
+
+class EnvVarEntry(TypedDict):
+    name: str
+    description: str
+    required: bool
+    default: str | None
+
+
+class ToolMetadata(TypedDict):
+    name: str
+    module: str
+    humanized_name: str
+    description: str
+    run_params_schema: dict[str, Any]
+    init_params_schema: dict[str, Any]
+    env_vars: list[EnvVarEntry]
+
+
+class ToolsMetadataPayload(TypedDict):
+    package: str
+    tools: list[ToolMetadata] | None
+
+
+class PublishToolPayload(TypedDict):
+    handle: str
+    public: bool
+    version: str
+    file: str
+    description: str | None
+    available_exports: list[AvailableExport] | None
+    tools_metadata: ToolsMetadataPayload | None
+
+
+class CrewDeploymentSpec(TypedDict):
+    name: str
+    repo_clone_url: str
+    env: dict[str, str]
+
+
+class CreateCrewPayload(TypedDict):
+    deploy: CrewDeploymentSpec
+
+
+class _WithUserIdentifier(TypedDict):
+    user_identifier: NotRequired[str]
+
+
+class LoginPayload(_WithUserIdentifier):
+    pass
+
+
+class TraceExecutionContext(TypedDict):
+    crew_fingerprint: str | None
+    crew_name: str | None
+    flow_name: str | None
+    crewai_version: str
+    privacy_level: str
+
+
+class TraceExecutionMetadata(TypedDict):
+    expected_duration_estimate: int
+    agent_count: int
+    task_count: int
+    flow_method_count: int
+    execution_started_at: str
+
+
+class TraceBatchInitPayload(_WithUserIdentifier):
+    trace_id: str
+    execution_type: str
+    execution_context: TraceExecutionContext
+    execution_metadata: TraceExecutionMetadata
+    ephemeral_trace_id: NotRequired[str]
+
+
+class TraceBatchMetadata(TypedDict):
+    events_count: int
+    batch_sequence: int
+    is_final_batch: bool
+
+
+class TraceEventsPayload(TypedDict):
+    events: list[dict[str, Any]]
+    batch_metadata: TraceBatchMetadata
+
+
+class TraceFinalizePayload(TypedDict):
+    status: Literal["completed"]
+    duration_ms: float | None
+    final_event_count: int
+
+
+class TraceFailedPayload(TypedDict):
+    status: Literal["failed"]
+    failure_reason: str
+
+
+Headers = TypedDict(
+    "Headers",
+    {
+        "Content-Type": str,
+        "User-Agent": str,
+        "X-Crewai-Version": str,
+        "Authorization": NotRequired[str],
+        "X-Crewai-Organization-Id": NotRequired[str],
+    },
+)
+
+
+class RequestKwargs(TypedDict):
+    headers: dict[str, str]
+    json: NotRequired[Any]
+    params: NotRequired[dict[str, str]]
+    timeout: NotRequired[float]
+
+
 class PlusAPI:
     """Client for working with the CrewAI+ API."""
 
-    TOOLS_RESOURCE = "/crewai_plus/api/v1/tools"
-    ORGANIZATIONS_RESOURCE = "/crewai_plus/api/v1/me/organizations"
-    CREWS_RESOURCE = "/crewai_plus/api/v1/crews"
-    AGENTS_RESOURCE = "/crewai_plus/api/v1/agents"
-    TRACING_RESOURCE = "/crewai_plus/api/v1/tracing"
-    EPHEMERAL_TRACING_RESOURCE = "/crewai_plus/api/v1/tracing/ephemeral"
-    INTEGRATIONS_RESOURCE = "/crewai_plus/api/v1/integrations"
+    TOOLS_RESOURCE: Final = "/crewai_plus/api/v1/tools"
+    SKILLS_RESOURCE: Final = "/crewai_plus/api/v1/skills"
+    ORGANIZATIONS_RESOURCE: Final = "/crewai_plus/api/v1/me/organizations"
+    CREWS_RESOURCE: Final = "/crewai_plus/api/v1/crews"
+    AGENTS_RESOURCE: Final = "/crewai_plus/api/v1/agents"
+    TRACING_RESOURCE: Final = "/crewai_plus/api/v1/tracing"
+    EPHEMERAL_TRACING_RESOURCE: Final = "/crewai_plus/api/v1/tracing/ephemeral"
+    INTEGRATIONS_RESOURCE: Final = "/crewai_plus/api/v1/integrations"
 
     def __init__(self, api_key: str | None = None) -> None:
+        version = get_crewai_version()
         self.api_key = api_key
-        self.headers = {
+        self.headers: Headers = {
             "Content-Type": "application/json",
-            "User-Agent": f"CrewAI-CLI/{get_crewai_version()}",
-            "X-Crewai-Version": get_crewai_version(),
+            "User-Agent": f"CrewAI-CLI/{version}",
+            "X-Crewai-Version": version,
         }
         if api_key:
             self.headers["Authorization"] = f"Bearer {api_key}"
+
         settings = Settings()
         if settings.org_uuid:
             self.headers["X-Crewai-Organization-Id"] = settings.org_uuid
@@ -44,17 +170,30 @@ class PlusAPI:
         )
 
     def _make_request(
-        self, method: str, endpoint: str, **kwargs: Any
+        self,
+        method: HttpMethod,
+        endpoint: str,
+        *,
+        json: Any = None,
+        params: dict[str, str] | None = None,
+        timeout: float | None = None,
+        verify: bool = True,
     ) -> httpx.Response:
         url = urljoin(self.base_url, endpoint)
-        verify = kwargs.pop("verify", True)
+        request_kwargs: RequestKwargs = {"headers": cast(dict[str, str], self.headers)}
+        if json is not None:
+            request_kwargs["json"] = json
+        if params is not None:
+            request_kwargs["params"] = params
+        if timeout is not None:
+            request_kwargs["timeout"] = timeout
         with httpx.Client(trust_env=False, verify=verify) as client:
-            return client.request(method, url, headers=self.headers, **kwargs)
+            return client.request(method, url, **request_kwargs)
 
     def login_to_tool_repository(
         self, user_identifier: str | None = None
     ) -> httpx.Response:
-        payload = {}
+        payload: LoginPayload = {}
         if user_identifier:
             payload["user_identifier"] = user_identifier
         return self._make_request("POST", f"{self.TOOLS_RESOURCE}/login", json=payload)
@@ -65,7 +204,7 @@ class PlusAPI:
     async def get_agent(self, handle: str) -> httpx.Response:
         url = urljoin(self.base_url, f"{self.AGENTS_RESOURCE}/{handle}")
         async with httpx.AsyncClient() as client:
-            return await client.get(url, headers=self.headers)
+            return await client.get(url, headers=cast(dict[str, str], self.headers))
 
     def publish_tool(
         self,
@@ -74,10 +213,10 @@ class PlusAPI:
         version: str,
         description: str | None,
         encoded_file: str,
-        available_exports: list[dict[str, Any]] | None = None,
-        tools_metadata: list[dict[str, Any]] | None = None,
+        available_exports: list[AvailableExport] | None = None,
+        tools_metadata: list[ToolMetadata] | None = None,
     ) -> httpx.Response:
-        params = {
+        params: PublishToolPayload = {
             "handle": handle,
             "public": is_public,
             "version": version,
@@ -90,6 +229,47 @@ class PlusAPI:
         }
         return self._make_request("POST", f"{self.TOOLS_RESOURCE}", json=params)
 
+    def get_skill(
+        self, org: str, name: str, version: str | None = None
+    ) -> httpx.Response:
+        params: dict[str, str] = {}
+        if version is not None:
+            params["version"] = version
+        return self._make_request(
+            "GET",
+            f"{self.SKILLS_RESOURCE}/{org}/{name}",
+            params=params or None,
+        )
+
+    def publish_skill(
+        self,
+        org: str,
+        name: str,
+        version: str,
+        is_public: bool,
+        description: str | None,
+        encoded_file: str,
+    ) -> httpx.Response:
+        payload = {
+            "org": org,
+            "name": name,
+            "version": version,
+            "public": is_public,
+            "description": description,
+            "file": encoded_file,
+        }
+        return self._make_request("POST", self.SKILLS_RESOURCE, json=payload)
+
+    def list_skills(self, org: str | None = None) -> httpx.Response:
+        params: dict[str, str] = {}
+        if org is not None:
+            params["org"] = org
+        return self._make_request(
+            "GET",
+            self.SKILLS_RESOURCE,
+            params=params or None,
+        )
+
     def deploy_by_name(self, project_name: str) -> httpx.Response:
         return self._make_request(
             "POST", f"{self.CREWS_RESOURCE}/by-name/{project_name}/deploy"
@@ -129,13 +309,13 @@ class PlusAPI:
     def list_crews(self) -> httpx.Response:
         return self._make_request("GET", self.CREWS_RESOURCE)
 
-    def create_crew(self, payload: dict[str, Any]) -> httpx.Response:
+    def create_crew(self, payload: CreateCrewPayload) -> httpx.Response:
         return self._make_request("POST", self.CREWS_RESOURCE, json=payload)
 
     def get_organizations(self) -> httpx.Response:
         return self._make_request("GET", self.ORGANIZATIONS_RESOURCE)
 
-    def initialize_trace_batch(self, payload: dict[str, Any]) -> httpx.Response:
+    def initialize_trace_batch(self, payload: TraceBatchInitPayload) -> httpx.Response:
         return self._make_request(
             "POST",
             f"{self.TRACING_RESOURCE}/batches",
@@ -144,7 +324,7 @@ class PlusAPI:
         )
 
     def initialize_ephemeral_trace_batch(
-        self, payload: dict[str, Any]
+        self, payload: TraceBatchInitPayload
     ) -> httpx.Response:
         return self._make_request(
             "POST",
@@ -153,7 +333,7 @@ class PlusAPI:
         )
 
     def send_trace_events(
-        self, trace_batch_id: str, payload: dict[str, Any]
+        self, trace_batch_id: str, payload: TraceEventsPayload
     ) -> httpx.Response:
         return self._make_request(
             "POST",
@@ -163,7 +343,7 @@ class PlusAPI:
         )
 
     def send_ephemeral_trace_events(
-        self, trace_batch_id: str, payload: dict[str, Any]
+        self, trace_batch_id: str, payload: TraceEventsPayload
     ) -> httpx.Response:
         return self._make_request(
             "POST",
@@ -173,7 +353,7 @@ class PlusAPI:
         )
 
     def finalize_trace_batch(
-        self, trace_batch_id: str, payload: dict[str, Any]
+        self, trace_batch_id: str, payload: TraceFinalizePayload
     ) -> httpx.Response:
         return self._make_request(
             "PATCH",
@@ -183,7 +363,7 @@ class PlusAPI:
         )
 
     def finalize_ephemeral_trace_batch(
-        self, trace_batch_id: str, payload: dict[str, Any]
+        self, trace_batch_id: str, payload: TraceFinalizePayload
     ) -> httpx.Response:
         return self._make_request(
             "PATCH",
@@ -195,20 +375,28 @@ class PlusAPI:
     def mark_trace_batch_as_failed(
         self, trace_batch_id: str, error_message: str
     ) -> httpx.Response:
+        payload: TraceFailedPayload = {
+            "status": "failed",
+            "failure_reason": error_message,
+        }
         return self._make_request(
             "PATCH",
             f"{self.TRACING_RESOURCE}/batches/{trace_batch_id}",
-            json={"status": "failed", "failure_reason": error_message},
+            json=payload,
             timeout=30,
         )
 
     def mark_ephemeral_trace_batch_as_failed(
         self, trace_batch_id: str, error_message: str
     ) -> httpx.Response:
+        payload: TraceFailedPayload = {
+            "status": "failed",
+            "failure_reason": error_message,
+        }
         return self._make_request(
             "PATCH",
             f"{self.EPHEMERAL_TRACING_RESOURCE}/batches/{trace_batch_id}",
-            json={"status": "failed", "failure_reason": error_message},
+            json=payload,
             timeout=30,
         )
 

lib/crewai/src/crewai/agent/core.py

@@ -434,7 +434,7 @@ class Agent(BaseAgent):
         from crewai.crew import Crew
 
         if resolved_crew_skills is None:
-            crew_skills: list[Path | SkillModel] | None = (
+            crew_skills: list[Path | SkillModel | str] | None = (
                 self.crew.skills
                 if isinstance(self.crew, Crew) and isinstance(self.crew.skills, list)
                 else None
@@ -446,7 +446,7 @@ class Agent(BaseAgent):
             return
 
         needs_work = self.skills and any(
-            isinstance(s, Path)
+            isinstance(s, (Path, str))
             or (isinstance(s, SkillModel) and s.disclosure_level < INSTRUCTIONS)
             for s in self.skills
         )
@@ -454,14 +454,28 @@ class Agent(BaseAgent):
             return
 
         seen: set[str] = set()
-        resolved: list[Path | SkillModel] = []
-        items: list[Path | SkillModel] = list(self.skills) if self.skills else []
+        resolved: list[Path | SkillModel | str] = []
+        items: list[Path | SkillModel | str] = list(self.skills) if self.skills else []
 
         if crew_skills:
             items.extend(crew_skills)
 
         for item in items:
-            if isinstance(item, Path):
+            if isinstance(item, str):
+                from crewai.skills.registry import (
+                    is_registry_ref,
+                    parse_registry_ref,
+                    resolve_registry_ref,
+                )
+
+                if is_registry_ref(item):
+                    skill = resolve_registry_ref(item, source=self)
+                    org, _ = parse_registry_ref(item)
+                    dedup_key = f"{org}/{skill.name}"
+                    if dedup_key not in seen:
+                        seen.add(dedup_key)
+                        resolved.append(skill)
+            elif isinstance(item, Path):
                 discovered = discover_skills(item, source=self)
                 for skill in discovered:
                     if skill.name not in seen:

lib/crewai/src/crewai/agents/agent_builder/base_agent.py

@@ -334,9 +334,9 @@ class BaseAgent(BaseModel, ABC, metaclass=AgentMeta):
             "If not set, falls back to crew memory."
         ),
     )
-    skills: list[Path | Skill] | None = Field(
+    skills: list[Path | Skill | str] | None = Field(
         default=None,
-        description="Agent Skills. Accepts paths for discovery or pre-loaded Skill objects.",
+        description="Agent Skills. Accepts paths for discovery, pre-loaded Skill objects, or '@org/name' registry refs.",
         min_length=1,
     )
     execution_context: ExecutionContext | None = Field(default=None)
@@ -429,6 +429,20 @@ class BaseAgent(BaseModel, ABC, metaclass=AgentMeta):
     def process_model_config(cls, values: Any) -> dict[str, Any]:
         return process_config(values, cls)
 
+    @field_validator("skills", mode="before")
+    @classmethod
+    def coerce_skill_strings(cls, skills: Any) -> Any:
+        """Coerce plain path strings to Path objects; keep @-prefixed refs as str."""
+        if not isinstance(skills, list):
+            return skills
+        result = []
+        for item in skills:
+            if isinstance(item, str) and not item.startswith("@"):
+                result.append(Path(item))
+            else:
+                result.append(item)
+        return result
+
     @field_validator("tools")
     @classmethod
     def validate_tools(cls, tools: list[Any]) -> list[BaseTool]:

lib/crewai/src/crewai/agents/crew_agent_executor.py

@@ -422,7 +422,10 @@ class CrewAgentExecutor(BaseAgentExecutor):
                     )
 
                 self._invoke_step_callback(formatted_answer)
-                self._append_message(formatted_answer.text)
+                self._append_message(
+                    formatted_answer.text,
+                    reasoning_content=self._get_llm_reasoning_content(),
+                )
 
             except OutputParserError as e:
                 formatted_answer = handle_output_parser_exception(  # type: ignore[assignment]
@@ -525,8 +528,9 @@ class CrewAgentExecutor(BaseAgentExecutor):
                         output=answer,
                         text=answer,
                     )
+                    reasoning = self._get_llm_reasoning_content()
                     self._invoke_step_callback(formatted_answer)
-                    self._append_message(answer)
+                    self._append_message(answer, reasoning_content=reasoning)
                     self._show_logs(formatted_answer)
                     return formatted_answer
 
@@ -537,8 +541,9 @@ class CrewAgentExecutor(BaseAgentExecutor):
                         output=answer,
                         text=output_json,
                     )
+                    reasoning = self._get_llm_reasoning_content()
                     self._invoke_step_callback(formatted_answer)
-                    self._append_message(output_json)
+                    self._append_message(output_json, reasoning_content=reasoning)
                     self._show_logs(formatted_answer)
                     return formatted_answer
 
@@ -547,8 +552,9 @@ class CrewAgentExecutor(BaseAgentExecutor):
                     output=str(answer),
                     text=str(answer),
                 )
+                reasoning = self._get_llm_reasoning_content()
                 self._invoke_step_callback(formatted_answer)
-                self._append_message(str(answer))
+                self._append_message(str(answer), reasoning_content=reasoning)
                 self._show_logs(formatted_answer)
                 return formatted_answer
 
@@ -1234,7 +1240,10 @@ class CrewAgentExecutor(BaseAgentExecutor):
                     )
 
                 await self._ainvoke_step_callback(formatted_answer)
-                self._append_message(formatted_answer.text)
+                self._append_message(
+                    formatted_answer.text,
+                    reasoning_content=self._get_llm_reasoning_content(),
+                )
 
             except OutputParserError as e:
                 formatted_answer = handle_output_parser_exception(  # type: ignore[assignment]
@@ -1336,8 +1345,9 @@ class CrewAgentExecutor(BaseAgentExecutor):
                         output=answer,
                         text=answer,
                     )
+                    reasoning = self._get_llm_reasoning_content()
                     await self._ainvoke_step_callback(formatted_answer)
-                    self._append_message(answer)
+                    self._append_message(answer, reasoning_content=reasoning)
                     self._show_logs(formatted_answer)
                     return formatted_answer
 
@@ -1348,8 +1358,9 @@ class CrewAgentExecutor(BaseAgentExecutor):
                         output=answer,
                         text=output_json,
                     )
+                    reasoning = self._get_llm_reasoning_content()
                     await self._ainvoke_step_callback(formatted_answer)
-                    self._append_message(output_json)
+                    self._append_message(output_json, reasoning_content=reasoning)
                     self._show_logs(formatted_answer)
                     return formatted_answer
 
@@ -1358,8 +1369,9 @@ class CrewAgentExecutor(BaseAgentExecutor):
                     output=str(answer),
                     text=str(answer),
                 )
+                reasoning = self._get_llm_reasoning_content()
                 await self._ainvoke_step_callback(formatted_answer)
-                self._append_message(str(answer))
+                self._append_message(str(answer), reasoning_content=reasoning)
                 self._show_logs(formatted_answer)
                 return formatted_answer
 
@@ -1473,16 +1485,26 @@ class CrewAgentExecutor(BaseAgentExecutor):
             if inspect.iscoroutine(cb_result):
                 await cb_result
 
+    def _get_llm_reasoning_content(self) -> str | None:
+        """Return reasoning_content from the last LLM response, if any."""
+        return getattr(self.llm, "reasoning_content", None)
+
     def _append_message(
-        self, text: str, role: Literal["user", "assistant", "system"] = "assistant"
+        self,
+        text: str,
+        role: Literal["user", "assistant", "system"] = "assistant",
+        reasoning_content: str | None = None,
     ) -> None:
         """Add message to conversation history.
 
         Args:
             text: Message content.
             role: Message role (default: assistant).
+            reasoning_content: Optional reasoning content from the LLM response.
         """
-        self.messages.append(format_message_for_llm(text, role=role))
+        self.messages.append(
+            format_message_for_llm(text, role=role, reasoning_content=reasoning_content)
+        )
 
     def _show_start_logs(self) -> None:
         """Emit agent start event."""

lib/crewai/src/crewai/crew.py

@@ -341,9 +341,9 @@ class Crew(FlowTrackable, BaseModel):
         default=None,
         description="Knowledge for the crew.",
     )
-    skills: list[Path | Skill] | None = Field(
+    skills: list[Path | Skill | str] | None = Field(
         default=None,
-        description="Skill search paths or pre-loaded Skill objects applied to all agents in the crew.",
+        description="Skill search paths, pre-loaded Skill objects, or '@org/name' registry refs applied to all agents in the crew.",
     )
 
     security_config: SecurityConfig = Field(
@@ -526,6 +526,20 @@ class Crew(FlowTrackable, BaseModel):
         if max_seq > 0:
             set_emission_counter(max_seq)
 
+    @field_validator("skills", mode="before")
+    @classmethod
+    def coerce_skill_strings(cls, skills: Any) -> Any:
+        """Coerce plain path strings to Path objects; keep @-prefixed refs as str."""
+        if not isinstance(skills, list):
+            return skills
+        result = []
+        for item in skills:
+            if isinstance(item, str) and not item.startswith("@"):
+                result.append(Path(item))
+            else:
+                result.append(item)
+        return result
+
     @field_validator("id", mode="before")
     @classmethod
     def _deny_user_set_id(cls, v: UUID4 | None, info: Any) -> UUID4 | None:

lib/crewai/src/crewai/events/listeners/tracing/trace_batch_manager.py

@@ -6,6 +6,14 @@ import time
 from typing import Any
 import uuid
 
+from crewai_core.plus_api import (
+    TraceBatchInitPayload,
+    TraceBatchMetadata,
+    TraceEventsPayload,
+    TraceExecutionContext,
+    TraceExecutionMetadata,
+    TraceFinalizePayload,
+)
 from crewai_core.settings import Settings
 from rich.console import Console
 from rich.panel import Panel
@@ -123,25 +131,27 @@ class TraceBatchManager:
             return None
 
         try:
-            payload = {
+            execution_context: TraceExecutionContext = {
+                "crew_fingerprint": execution_metadata.get("crew_fingerprint"),
+                "crew_name": execution_metadata.get("crew_name", None),
+                "flow_name": execution_metadata.get("flow_name", None),
+                "crewai_version": self.current_batch.version,
+                "privacy_level": user_context.get("privacy_level", "standard"),
+            }
+            execution_metadata_payload: TraceExecutionMetadata = {
+                "expected_duration_estimate": execution_metadata.get(
+                    "expected_duration_estimate", 300
+                ),
+                "agent_count": execution_metadata.get("agent_count", 0),
+                "task_count": execution_metadata.get("task_count", 0),
+                "flow_method_count": execution_metadata.get("flow_method_count", 0),
+                "execution_started_at": datetime.now(timezone.utc).isoformat(),
+            }
+            payload: TraceBatchInitPayload = {
                 "trace_id": self.current_batch.batch_id,
                 "execution_type": execution_metadata.get("execution_type", "crew"),
-                "execution_context": {
-                    "crew_fingerprint": execution_metadata.get("crew_fingerprint"),
-                    "crew_name": execution_metadata.get("crew_name", None),
-                    "flow_name": execution_metadata.get("flow_name", None),
-                    "crewai_version": self.current_batch.version,
-                    "privacy_level": user_context.get("privacy_level", "standard"),
-                },
-                "execution_metadata": {
-                    "expected_duration_estimate": execution_metadata.get(
-                        "expected_duration_estimate", 300
-                    ),
-                    "agent_count": execution_metadata.get("agent_count", 0),
-                    "task_count": execution_metadata.get("task_count", 0),
-                    "flow_method_count": execution_metadata.get("flow_method_count", 0),
-                    "execution_started_at": datetime.now(timezone.utc).isoformat(),
-                },
+                "execution_context": execution_context,
+                "execution_metadata": execution_metadata_payload,
             }
             if use_ephemeral:
                 payload["ephemeral_trace_id"] = self.current_batch.batch_id
@@ -264,13 +274,14 @@ class TraceBatchManager:
         if not self.plus_api or not self.trace_batch_id or not self.event_buffer:
             return 500
         try:
-            payload = {
+            batch_metadata: TraceBatchMetadata = {
+                "events_count": len(self.event_buffer),
+                "batch_sequence": 1,
+                "is_final_batch": False,
+            }
+            payload: TraceEventsPayload = {
                 "events": [event.to_dict() for event in self.event_buffer],
-                "batch_metadata": {
-                    "events_count": len(self.event_buffer),
-                    "batch_sequence": 1,
-                    "is_final_batch": False,
-                },
+                "batch_metadata": batch_metadata,
             }
 
             response = (
@@ -364,7 +375,7 @@ class TraceBatchManager:
             return
 
         try:
-            payload = {
+            payload: TraceFinalizePayload = {
                 "status": "completed",
                 "duration_ms": self.calculate_duration("execution"),
                 "final_event_count": events_count,

lib/crewai/src/crewai/events/types/skill_events.py

@@ -60,3 +60,20 @@ 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 = None

lib/crewai/src/crewai/experimental/agent_executor.py

@@ -1330,6 +1330,8 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):
                 self.state.pending_tool_calls = list(answer)
                 return "native_tool_calls"
 
+            reasoning = self._get_llm_reasoning_content()
+
             if isinstance(answer, BaseModel):
                 self.state.current_answer = AgentFinish(
                     thought="",
@@ -1337,7 +1339,9 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):
                     text=answer.model_dump_json(),
                 )
                 self._invoke_step_callback(self.state.current_answer)
-                self._append_message_to_state(answer.model_dump_json())
+                self._append_message_to_state(
+                    answer.model_dump_json(), reasoning_content=reasoning
+                )
                 return self._route_finish_with_todos("native_finished")
 
             # Text response - this is the final answer
@@ -1348,7 +1352,7 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):
                     text=answer,
                 )
                 self._invoke_step_callback(self.state.current_answer)
-                self._append_message_to_state(answer)
+                self._append_message_to_state(answer, reasoning_content=reasoning)
 
                 return self._route_finish_with_todos("native_finished")
 
@@ -1359,7 +1363,7 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):
                 text=str(answer),
             )
             self._invoke_step_callback(self.state.current_answer)
-            self._append_message_to_state(str(answer))
+            self._append_message_to_state(str(answer), reasoning_content=reasoning)
 
             return self._route_finish_with_todos("native_finished")
 
@@ -2813,16 +2817,26 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):
                     color="red",
                 )
 
+    def _get_llm_reasoning_content(self) -> str | None:
+        """Return reasoning_content from the last LLM response, if any."""
+        return getattr(self.llm, "reasoning_content", None)
+
     def _append_message_to_state(
-        self, text: str, role: Literal["user", "assistant", "system"] = "assistant"
+        self,
+        text: str,
+        role: Literal["user", "assistant", "system"] = "assistant",
+        reasoning_content: str | None = None,
     ) -> None:
         """Add message to state conversation history.
 
         Args:
             text: Message content.
             role: Message role (default: assistant).
+            reasoning_content: Optional reasoning content from the LLM response.
         """
-        self.state.messages.append(format_message_for_llm(text, role=role))
+        self.state.messages.append(
+            format_message_for_llm(text, role=role, reasoning_content=reasoning_content)
+        )
 
     def _show_start_logs(self) -> None:
         """Emit agent start event."""

lib/crewai/src/crewai/llm.py

@@ -1232,6 +1232,15 @@ class LLM(BaseLLM):
             0
         ].message
         text_response = response_message.content or ""
+
+        # Store reasoning_content for models that return it (e.g. DeepSeek thinking mode)
+        self.reasoning_content: str | None = getattr(
+            response_message, "reasoning_content", None
+        ) or (
+            response_message.get("reasoning_content")
+            if hasattr(response_message, "get")
+            else None
+        )
         # --- 3) Handle callbacks with usage info
         if callbacks and len(callbacks) > 0:
             for callback in callbacks:
@@ -1742,6 +1751,7 @@ class LLM(BaseLLM):
             ValueError: If response format is not supported
             LLMContextLengthExceededError: If input exceeds model's context limit
         """
+        self.reasoning_content = None
         with llm_call_context() as call_id:
             crewai_event_bus.emit(
                 self,

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

@@ -3,15 +3,20 @@
 Provides filesystem-based skill packaging with progressive disclosure.
 """
 
+from crewai.skills.cache import SkillCacheManager
 from crewai.skills.loader import activate_skill, discover_skills
 from crewai.skills.models import Skill, SkillFrontmatter
 from 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",
 ]

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

@@ -0,0 +1,148 @@
+"""Cache manager for registry-downloaded skills.
+
+Manages ~/.crewai/skills/{org}/{name}/ as the global skill cache.
+One version is stored per skill (last install wins).
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import json
+import logging
+from pathlib import Path
+import tarfile
+from typing import TypedDict
+import zipfile
+
+
+_logger = logging.getLogger(__name__)
+
+
+_CACHE_ROOT = Path.home() / ".crewai" / "skills"
+_META_FILENAME = ".crewai_meta.json"
+
+
+class SkillMetadata(TypedDict):
+    org: str
+    name: str
+    version: str | None
+    installed_at: str
+
+
+class SkillCacheManager:
+    """Manages the global skill cache at ~/.crewai/skills/."""
+
+    def __init__(self, cache_root: Path | None = None) -> None:
+        self._root = cache_root or _CACHE_ROOT
+
+    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."""
+        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
+
+    def store(
+        self, org: str, name: str, version: str | None, archive_bytes: bytes
+    ) -> Path:
+        """Unpack an archive into the cache and write metadata.
+
+        Uses tarfile with filter='data' for path-traversal protection.
+
+        Args:
+            org: Organisation slug.
+            name: Skill name.
+            version: Semantic version string, or None if unknown.
+            archive_bytes: Raw bytes of a .tar.gz archive.
+
+        Returns:
+            Path to the stored skill directory.
+        """
+        skill_dir = self._skill_dir(org, name)
+        # Wipe any previous version
+        if skill_dir.exists():
+            import shutil
+
+            shutil.rmtree(skill_dir)
+        skill_dir.mkdir(parents=True, exist_ok=True)
+
+        import io
+
+        # Try tar.gz first, fall back to zip
+        try:
+            with tarfile.open(fileobj=io.BytesIO(archive_bytes), mode="r:gz") as tf:
+                try:
+                    tf.extractall(skill_dir, filter="data")
+                except TypeError:
+                    _safe_extractall(tf, skill_dir)
+        except tarfile.TarError:
+            with zipfile.ZipFile(io.BytesIO(archive_bytes)) as zf:
+                _safe_extract_zip(zf, skill_dir)
+
+        meta: SkillMetadata = {
+            "org": org,
+            "name": name,
+            "version": version,
+            "installed_at": datetime.now(tz=timezone.utc).isoformat(),
+        }
+        (skill_dir / _META_FILENAME).write_text(json.dumps(meta, indent=2))
+        return skill_dir
+
+    def list_cached(self) -> list[SkillMetadata]:
+        """Return metadata for every cached skill."""
+        results: list[SkillMetadata] = []
+        if not self._root.exists():
+            return results
+        for org_dir in sorted(self._root.iterdir()):
+            if not org_dir.is_dir():
+                continue
+            for skill_dir in sorted(org_dir.iterdir()):
+                meta_file = skill_dir / _META_FILENAME
+                if meta_file.exists():
+                    try:
+                        results.append(json.loads(meta_file.read_text()))
+                    except (json.JSONDecodeError, KeyError):
+                        _logger.debug(
+                            "Skipping malformed cache entry: %s",
+                            meta_file,
+                            exc_info=True,
+                        )
+        return results
+
+    def invalidate(self, org: str, name: str) -> bool:
+        """Remove a cached skill.
+
+        Returns:
+            True if the cache entry existed and was removed, False otherwise.
+        """
+        skill_dir = self._skill_dir(org, name)
+        if skill_dir.exists():
+            import shutil
+
+            shutil.rmtree(skill_dir)
+            return True
+        return False
+
+
+def _safe_extractall(tf: tarfile.TarFile, dest: Path) -> None:
+    """Path-traversal-safe extraction for Python < 3.12."""
+    dest_resolved = dest.resolve()
+    for member in tf.getmembers():
+        member_path = (dest / member.name).resolve()
+        if not member_path.is_relative_to(dest_resolved):
+            raise ValueError(f"Blocked path traversal attempt: {member.name!r}")
+    tf.extractall(dest)  # noqa: S202
+
+
+def _safe_extract_zip(zf: zipfile.ZipFile, dest: Path) -> None:
+    """Path-traversal-safe ZIP extraction."""
+    dest_resolved = dest.resolve()
+    for member in zf.namelist():
+        member_path = (dest / member).resolve()
+        if not member_path.is_relative_to(dest_resolved):
+            raise ValueError(f"Blocked path traversal attempt: {member!r}")
+    zf.extractall(dest)  # noqa: S202

lib/crewai/src/crewai/skills/models.py

@@ -78,6 +78,10 @@ class SkillFrontmatter(BaseModel):
         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")
     @classmethod

lib/crewai/src/crewai/skills/registry.py

@@ -0,0 +1,223 @@
+"""Registry reference resolution for the Agent Skills standard.
+
+Handles @org/skill-name references, local-first resolution, and downloads
+via the CrewAI+ API with a global cache at ~/.crewai/skills/.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+import sys
+from typing import Any
+
+from crewai.skills.cache import SkillCacheManager
+
+
+_logger = logging.getLogger(__name__)
+
+
+class SkillNotCachedError(Exception):
+    """Raised when a registry skill is not cached and the environment is non-interactive."""
+
+    def __init__(self, ref: str) -> None:
+        super().__init__(
+            f"Skill {ref!r} is not cached locally. "
+            f"Run `crewai skill install {ref}` to install it first."
+        )
+        self.ref = ref
+
+
+def is_registry_ref(value: Any) -> bool:
+    """Return True if *value* looks like a registry reference (@org/name)."""
+    return isinstance(value, str) and value.startswith("@")
+
+
+def parse_registry_ref(ref: str) -> tuple[str, str]:
+    """Parse '@org/skill-name' into (org, name).
+
+    Args:
+        ref: A registry reference, e.g. '@acme/my-skill'.
+
+    Returns:
+        A (org, name) tuple.
+
+    Raises:
+        ValueError: If the reference format is invalid.
+    """
+    if not ref.startswith("@"):
+        raise ValueError(f"Registry reference must start with '@', got: {ref!r}")
+    without_at = ref[1:]
+    if without_at.count("/") != 1:
+        raise ValueError(
+            f"Registry reference must be in '@org/name' format, got: {ref!r}"
+        )
+    org, name = without_at.split("/", 1)
+    if (
+        not org
+        or not name
+        or org.startswith(".")
+        or name.startswith(".")
+        or "/" in org
+        or "/" in name
+    ):
+        raise ValueError(
+            f"Registry reference org and name must be single, non-empty path "
+            f"segments (no '..' or leading dots), got: {ref!r}"
+        )
+    return org, name
+
+
+def _is_noninteractive() -> bool:
+    """Return True in CI or explicitly non-interactive environments."""
+    import os
+
+    return (
+        os.environ.get("CI") == "1"
+        or os.environ.get("CREWAI_NONINTERACTIVE") == "1"
+        or not sys.stdin.isatty()
+    )
+
+
+def resolve_registry_ref(
+    ref: str,
+    source: Any = None,
+) -> Skill:  # type: ignore[name-defined]  # noqa: F821
+    """Resolve a registry reference to a Skill object.
+
+    Resolution order:
+    1. ./skills/{name}/ in the current working directory (project-local)
+    2. ~/.crewai/skills/{org}/{name}/ (global cache)
+    3. Download from registry (interactive only; raises SkillNotCachedError in CI)
+
+    Args:
+        ref: A registry reference, e.g. '@acme/my-skill'.
+        source: Optional source object passed through to skill loaders (for events).
+
+    Returns:
+        A Skill loaded at INSTRUCTIONS disclosure level.
+
+    Raises:
+        SkillNotCachedError: When not cached and running in non-interactive mode.
+    """
+    from crewai.skills.loader import activate_skill
+    from crewai.skills.parser import load_skill_metadata
+
+    org, name = parse_registry_ref(ref)
+
+    # 1. Project-local: ./skills/{name}/
+    local_path = Path.cwd() / "skills" / name
+    if local_path.is_dir() and (local_path / "SKILL.md").exists():
+        try:
+            skill = load_skill_metadata(local_path)
+            return activate_skill(skill, source=source)
+        except Exception:
+            _logger.debug("Failed to load local skill at %s", local_path, exc_info=True)
+
+    # 2. Global cache
+    cache = SkillCacheManager()
+    cached_path = cache.get_cached_path(org, name)
+    if cached_path is not None and (cached_path / "SKILL.md").exists():
+        try:
+            skill = load_skill_metadata(cached_path)
+            return activate_skill(skill, source=source)
+        except Exception:
+            _logger.debug(
+                "Failed to load cached skill at %s", cached_path, exc_info=True
+            )
+
+    # 3. Download
+    if _is_noninteractive():
+        raise SkillNotCachedError(ref)
+
+    return download_skill(org, name, source=source)
+
+
+def download_skill(
+    org: str,
+    name: str,
+    source: Any = None,
+) -> Skill:  # type: ignore[name-defined]  # noqa: F821
+    """Download a skill from the registry and store it in the cache.
+
+    Args:
+        org: Organisation slug.
+        name: Skill name.
+        source: Optional source for event emission.
+
+    Returns:
+        The downloaded Skill at INSTRUCTIONS level.
+    """
+    from crewai.skills.loader import activate_skill
+    from crewai.skills.parser import load_skill_metadata
+
+    ref = f"@{org}/{name}"
+
+    try:
+        from crewai.events.event_bus import crewai_event_bus
+        from crewai.events.types.skill_events import (
+            SkillDownloadCompletedEvent,
+            SkillDownloadStartedEvent,
+        )
+
+        _has_events = True
+    except ImportError:
+        _has_events = False
+
+    if _has_events:
+        crewai_event_bus.emit(
+            source,
+            event=SkillDownloadStartedEvent(
+                registry_ref=ref,
+            ),
+        )
+
+    try:
+        from crewai_core.plus_api import PlusAPI
+
+        api = PlusAPI()
+        response = api.get_skill(org, name)
+        response.raise_for_status()
+        data = response.json()
+    except Exception as exc:
+        raise RuntimeError(
+            f"Failed to download skill {ref!r} from registry: {exc}"
+        ) from exc
+
+    import base64
+
+    import httpx
+
+    version = data.get("latest_version") or data.get("version")
+
+    download_url = data.get("download_url")
+    if download_url:
+        dl_response = httpx.get(download_url, follow_redirects=True)
+        dl_response.raise_for_status()
+        archive_bytes = dl_response.content
+    else:
+        encoded = data.get("file", "")
+        # Strip data URI prefix if present
+        if "," in encoded:
+            encoded = encoded.split(",", 1)[1]
+        archive_bytes = base64.b64decode(encoded)
+
+    cache = SkillCacheManager()
+    skill_dir = cache.store(org, name, version, archive_bytes)
+
+    if _has_events:
+        crewai_event_bus.emit(
+            source,
+            event=SkillDownloadCompletedEvent(
+                registry_ref=ref,
+                version=version,
+                cache_path=skill_dir,
+            ),
+        )
+
+    if not (skill_dir / "SKILL.md").exists():
+        raise RuntimeError(
+            f"Skill archive for {ref!r} downloaded but no SKILL.md found in {skill_dir}"
+        )
+    skill = load_skill_metadata(skill_dir)
+    return activate_skill(skill, source=source)

lib/crewai/src/crewai/utilities/agent_utils.py

@@ -347,20 +347,28 @@ def handle_max_iterations_exceeded(
 
 
 def format_message_for_llm(
-    prompt: str, role: Literal["user", "assistant", "system"] = "user"
+    prompt: str,
+    role: Literal["user", "assistant", "system"] = "user",
+    reasoning_content: str | None = None,
 ) -> LLMMessage:
     """Format a message for the LLM.
 
     Args:
         prompt:  The message content.
         role:  The role of the message sender, either 'user' or 'assistant'.
+        reasoning_content:  Optional reasoning content for assistant messages
+            (e.g. from DeepSeek thinking mode). Only included when role is
+            'assistant' and the value is non-empty.
 
     Returns:
         A dictionary with 'role' and 'content' keys.
 
     """
     prompt = prompt.rstrip()
-    return {"role": role, "content": prompt}
+    msg: LLMMessage = {"role": role, "content": prompt}
+    if reasoning_content and role == "assistant":
+        msg["reasoning_content"] = reasoning_content
+    return msg
 
 
 def format_answer(answer: str) -> AgentAction | AgentFinish:

lib/crewai/src/crewai/utilities/project_utils.py

@@ -13,6 +13,7 @@ import sys
 import types
 from typing import Any, cast, get_type_hints
 
+from crewai_core.plus_api import AvailableExport, EnvVarEntry, ToolMetadata
 from crewai_core.project import (
     get_project_description as get_project_description,
     get_project_name as get_project_name,
@@ -279,7 +280,7 @@ def is_valid_tool(obj: Any) -> bool:
     return isinstance(obj, Tool)
 
 
-def extract_available_exports(dir_path: str = "src") -> list[dict[str, Any]]:
+def extract_available_exports(dir_path: str = "src") -> list[AvailableExport]:
     """Extract available tool classes from the project's __init__.py files.
 
     Only includes classes that inherit from BaseTool or functions decorated with @tool.
@@ -338,7 +339,7 @@ def _load_module_from_file(
         sys.modules.pop(module_name, None)
 
 
-def _load_tools_from_init(init_file: Path) -> list[dict[str, Any]]:
+def _load_tools_from_init(init_file: Path) -> list[AvailableExport]:
     """Load and validate tools from a given __init__.py file."""
     try:
         with _load_module_from_file(init_file) as module:
@@ -392,7 +393,7 @@ def _print_no_tools_warning() -> None:
     )
 
 
-def extract_tools_metadata(dir_path: str = "src") -> list[dict[str, Any]]:
+def extract_tools_metadata(dir_path: str = "src") -> list[ToolMetadata]:
     """
     Extract rich metadata from tool classes in the project.
 
@@ -404,7 +405,7 @@ def extract_tools_metadata(dir_path: str = "src") -> list[dict[str, Any]]:
     - init_params_schema: JSON Schema for __init__ params (filtered)
     - env_vars: List of environment variable dicts
     """
-    tools_metadata: list[dict[str, Any]] = []
+    tools_metadata: list[ToolMetadata] = []
 
     for init_file in Path(dir_path).glob("**/__init__.py"):
         tools = _extract_tool_metadata_from_init(init_file)
@@ -413,7 +414,7 @@ def extract_tools_metadata(dir_path: str = "src") -> list[dict[str, Any]]:
     return tools_metadata
 
 
-def _extract_tool_metadata_from_init(init_file: Path) -> list[dict[str, Any]]:
+def _extract_tool_metadata_from_init(init_file: Path) -> list[ToolMetadata]:
     """
     Load module from init file and extract metadata from valid tool classes.
     """
@@ -428,7 +429,7 @@ def _extract_tool_metadata_from_init(init_file: Path) -> list[dict[str, Any]]:
             if not exported_names:
                 return []
 
-            tools_metadata = []
+            tools_metadata: list[ToolMetadata] = []
             for name in exported_names:
                 obj = getattr(module, name, None)
                 if obj is None or not (
@@ -446,7 +447,7 @@ def _extract_tool_metadata_from_init(init_file: Path) -> list[dict[str, Any]]:
         return []
 
 
-def _extract_single_tool_metadata(tool_class: type) -> dict[str, Any] | None:
+def _extract_single_tool_metadata(tool_class: type) -> ToolMetadata | None:
     """
     Extract metadata from a single tool class.
     """
@@ -470,19 +471,17 @@ def _extract_single_tool_metadata(tool_class: type) -> dict[str, Any] | None:
         except (TypeError, ValueError):
             module = tool_class.__module__
 
-        return {
-            "name": tool_class.__name__,
-            "module": module,
-            "humanized_name": _extract_field_default(
-                fields.get("name"), fallback=tool_class.__name__
+        return ToolMetadata(
+            name=tool_class.__name__,
+            module=module,
+            humanized_name=str(
+                _extract_field_default(fields.get("name"), fallback=tool_class.__name__)
             ),
-            "description": str(
-                _extract_field_default(fields.get("description"))
-            ).strip(),
-            "run_params_schema": _extract_run_params_schema(fields.get("args_schema")),
-            "init_params_schema": _extract_init_params_schema(tool_class),
-            "env_vars": _extract_env_vars(fields.get("env_vars")),
-        }
+            description=str(_extract_field_default(fields.get("description"))).strip(),
+            run_params_schema=_extract_run_params_schema(fields.get("args_schema")),
+            init_params_schema=_extract_init_params_schema(tool_class),
+            env_vars=_extract_env_vars(fields.get("env_vars")),
+        )
 
     except Exception:
         return None
@@ -597,7 +596,7 @@ def _extract_init_params_schema(tool_class: type) -> dict[str, Any]:
         return {}
 
 
-def _extract_env_vars(env_vars_field: dict[str, Any] | None) -> list[dict[str, Any]]:
+def _extract_env_vars(env_vars_field: dict[str, Any] | None) -> list[EnvVarEntry]:
     """
     Extract environment variable definitions from env_vars field.
     """

lib/crewai/src/crewai/utilities/types.py

@@ -27,4 +27,5 @@ class LLMMessage(TypedDict):
     name: NotRequired[str]
     tool_calls: NotRequired[list[dict[str, Any]]]
     raw_tool_call_parts: NotRequired[list[Any]]
+    reasoning_content: NotRequired[str | None]
     files: NotRequired[dict[str, FileInput]]

lib/crewai/tests/llms/litellm/test_reasoning_content.py

@@ -0,0 +1,267 @@
+"""Tests for reasoning_content support (DeepSeek thinking mode).
+
+Verifies that reasoning_content from LLM responses is:
+1. Extracted and stored by LLM.call()
+2. Propagated into assistant messages by the executor
+3. Omitted when the model does not return it
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any
+from unittest.mock import MagicMock, patch
+
+import pytest
+from litellm.types.utils import Choices, Message, ModelResponse
+
+from crewai.llm import LLM
+from crewai.utilities.agent_utils import format_message_for_llm
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _make_response(content: str, reasoning_content: str | None = None) -> ModelResponse:
+    """Build a litellm ModelResponse, optionally with reasoning_content."""
+    msg_kwargs: dict[str, Any] = {"content": content, "role": "assistant"}
+    if reasoning_content is not None:
+        msg_kwargs["reasoning_content"] = reasoning_content
+    message = Message(**msg_kwargs)
+    choice = Choices(message=message, index=0, finish_reason="stop")
+    return ModelResponse(choices=[choice])
+
+
+# ---------------------------------------------------------------------------
+# LLM.call tests
+# ---------------------------------------------------------------------------
+
+class TestLLMReasoningContent:
+    """LLM.call should extract and store reasoning_content."""
+
+    @patch("crewai.llm.litellm.completion")
+    def test_stores_reasoning_content(self, mock_completion: MagicMock) -> None:
+        mock_completion.return_value = _make_response(
+            content="Paris",
+            reasoning_content="The user asked about the capital of France.",
+        )
+        llm = LLM(model="deepseek/deepseek-reasoner", is_litellm=True)
+        result = llm.call(
+            [{"role": "user", "content": "What is the capital of France?"}]
+        )
+
+        assert result == "Paris"
+        assert llm.reasoning_content == "The user asked about the capital of France."
+
+    @patch("crewai.llm.litellm.completion")
+    def test_none_when_absent(self, mock_completion: MagicMock) -> None:
+        mock_completion.return_value = _make_response(content="Hello!")
+        llm = LLM(model="gpt-4o", is_litellm=True)
+        result = llm.call([{"role": "user", "content": "Hi"}])
+
+        assert result == "Hello!"
+        assert llm.reasoning_content is None
+
+    @patch("crewai.llm.litellm.completion")
+    def test_resets_between_calls(self, mock_completion: MagicMock) -> None:
+        mock_completion.return_value = _make_response(
+            content="first", reasoning_content="thinking1"
+        )
+        llm = LLM(model="deepseek/deepseek-reasoner", is_litellm=True)
+        llm.call([{"role": "user", "content": "q1"}])
+        assert llm.reasoning_content == "thinking1"
+
+        mock_completion.return_value = _make_response(content="second")
+        llm.call([{"role": "user", "content": "q2"}])
+        assert llm.reasoning_content is None
+
+
+# ---------------------------------------------------------------------------
+# format_message_for_llm tests
+# ---------------------------------------------------------------------------
+
+class TestFormatMessageReasoningContent:
+    """format_message_for_llm should handle reasoning_content correctly."""
+
+    def test_includes_reasoning_content_for_assistant(self) -> None:
+        msg = format_message_for_llm(
+            "Hello", role="assistant", reasoning_content="thinking..."
+        )
+        assert msg == {
+            "role": "assistant",
+            "content": "Hello",
+            "reasoning_content": "thinking...",
+        }
+
+    def test_omits_reasoning_content_for_user(self) -> None:
+        msg = format_message_for_llm(
+            "Hello", role="user", reasoning_content="thinking..."
+        )
+        assert msg == {"role": "user", "content": "Hello"}
+
+    def test_omits_reasoning_content_when_none(self) -> None:
+        msg = format_message_for_llm(
+            "Hello", role="assistant", reasoning_content=None
+        )
+        assert msg == {"role": "assistant", "content": "Hello"}
+        assert "reasoning_content" not in msg
+
+    def test_omits_reasoning_content_when_empty_string(self) -> None:
+        msg = format_message_for_llm(
+            "Hello", role="assistant", reasoning_content=""
+        )
+        assert msg == {"role": "assistant", "content": "Hello"}
+        assert "reasoning_content" not in msg
+
+
+# ---------------------------------------------------------------------------
+# CrewAgentExecutor unit tests
+# ---------------------------------------------------------------------------
+
+def _build_crew_executor(llm: Any) -> Any:
+    """Build a minimal CrewAgentExecutor using model_construct to skip validation."""
+    from crewai.agents.crew_agent_executor import CrewAgentExecutor
+    from crewai.utilities.agent_utils import format_message_for_llm
+
+    agent = MagicMock()
+    agent.role = "test"
+    agent.verbose = False
+    agent.id = "agent-1"
+    agent.key = "agent-key"
+    agent.security_config = MagicMock()
+
+    task = MagicMock()
+    task.name = "test task"
+    task.description = "test task"
+    task.id = "task-1"
+
+    crew = MagicMock()
+    crew.verbose = False
+    crew._train = False
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", DeprecationWarning)
+        executor = CrewAgentExecutor.model_construct(
+            llm=llm,
+            task=task,
+            crew=crew,
+            agent=agent,
+            messages=[
+                format_message_for_llm("You are helpful.", role="system"),
+            ],
+            iterations=0,
+            max_iter=3,
+            tools=[],
+            original_tools=[],
+            tools_names="",
+            stop=[],
+            tools_description="",
+            tools_handler=None,
+            step_callback=None,
+            function_calling_llm=None,
+            respect_context_window=False,
+            request_within_rpm_limit=None,
+            callbacks=[],
+            response_model=None,
+            ask_for_human_input=False,
+            log_error_after=3,
+            before_llm_call_hooks=[],
+            after_llm_call_hooks=[],
+        )
+    return executor
+
+
+class TestCrewExecutorReasoningContent:
+    """CrewAgentExecutor should propagate reasoning_content to message history."""
+
+    def test_get_llm_reasoning_content(self) -> None:
+        llm = MagicMock()
+        llm.reasoning_content = "some reasoning"
+        executor = _build_crew_executor(llm)
+        assert executor._get_llm_reasoning_content() == "some reasoning"
+
+    def test_get_llm_reasoning_content_missing(self) -> None:
+        llm = MagicMock(
+            spec=["call", "supports_stop_words", "supports_function_calling", "stop"]
+        )
+        executor = _build_crew_executor(llm)
+        assert executor._get_llm_reasoning_content() is None
+
+    def test_append_message_includes_reasoning_content(self) -> None:
+        llm = MagicMock()
+        executor = _build_crew_executor(llm)
+        initial_count = len(executor.messages)
+
+        executor._append_message(
+            "hello", role="assistant", reasoning_content="thinking..."
+        )
+
+        new_msg = executor.messages[initial_count]
+        assert new_msg["role"] == "assistant"
+        assert new_msg["content"] == "hello"
+        assert new_msg["reasoning_content"] == "thinking..."
+
+    def test_append_message_omits_reasoning_content_when_none(self) -> None:
+        llm = MagicMock()
+        executor = _build_crew_executor(llm)
+        initial_count = len(executor.messages)
+
+        executor._append_message("hello", role="assistant", reasoning_content=None)
+
+        new_msg = executor.messages[initial_count]
+        assert new_msg["role"] == "assistant"
+        assert new_msg["content"] == "hello"
+        assert "reasoning_content" not in new_msg
+
+    @patch("crewai.llm.litellm.completion")
+    def test_invoke_loop_preserves_reasoning_content(
+        self, mock_completion: MagicMock
+    ) -> None:
+        """The ReAct invoke loop should include reasoning_content in assistant messages."""
+        llm = LLM(model="deepseek/deepseek-reasoner", is_litellm=True)
+
+        mock_completion.return_value = _make_response(
+            content="Thought: I need to think about this.\nFinal Answer: 42",
+            reasoning_content="Let me reason step by step...",
+        )
+
+        executor = _build_crew_executor(llm)
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            executor.invoke(
+                {"input": "What is the answer?", "tool_names": "", "tools": ""}
+            )
+
+        assistant_msgs = [
+            m for m in executor.messages if m["role"] == "assistant"
+        ]
+        assert len(assistant_msgs) >= 1
+        assert (
+            assistant_msgs[0].get("reasoning_content")
+            == "Let me reason step by step..."
+        )
+
+    @patch("crewai.llm.litellm.completion")
+    def test_invoke_loop_no_reasoning_content_for_normal_models(
+        self, mock_completion: MagicMock
+    ) -> None:
+        """Assistant messages should NOT have reasoning_content for normal models."""
+        llm = LLM(model="gpt-4o", is_litellm=True)
+
+        mock_completion.return_value = _make_response(
+            content="Thought: Simple question.\nFinal Answer: Hello!",
+        )
+
+        executor = _build_crew_executor(llm)
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            executor.invoke(
+                {"input": "Say hi", "tool_names": "", "tools": ""}
+            )
+
+        assistant_msgs = [
+            m for m in executor.messages if m["role"] == "assistant"
+        ]
+        assert len(assistant_msgs) >= 1
+        assert "reasoning_content" not in assistant_msgs[0]

lib/crewai/tests/skills/test_cache.py

@@ -0,0 +1,116 @@
+"""Tests for SkillCacheManager."""
+
+from __future__ import annotations
+
+import gzip
+import io
+import json
+import tarfile
+from pathlib import Path
+
+from crewai.skills.cache import SkillCacheManager
+
+
+def _make_tar_gz(files: dict[str, str]) -> bytes:
+    """Build an in-memory .tar.gz containing the given filename → content mapping."""
+    buf = io.BytesIO()
+    with gzip.GzipFile(fileobj=buf, mode="wb") as gz:
+        gz_buf = io.BytesIO()
+        with tarfile.open(fileobj=gz_buf, mode="w") as tf:
+            for name, content in files.items():
+                data = content.encode()
+                info = tarfile.TarInfo(name=name)
+                info.size = len(data)
+                tf.addfile(info, io.BytesIO(data))
+        gz.write(gz_buf.getvalue())
+    buf.seek(0)
+    # Re-create properly: gzip wrapping a tar stream
+    out = io.BytesIO()
+    with tarfile.open(fileobj=out, mode="w:gz") as tf:
+        for name, content in files.items():
+            data = content.encode()
+            info = tarfile.TarInfo(name=name)
+            info.size = len(data)
+            tf.addfile(info, io.BytesIO(data))
+    return out.getvalue()
+
+
+class TestSkillCacheManager:
+    def test_get_cached_path_missing(self, tmp_path: Path) -> None:
+        cache = SkillCacheManager(cache_root=tmp_path)
+        assert cache.get_cached_path("acme", "my-skill") is None
+
+    def test_store_and_retrieve(self, tmp_path: Path) -> None:
+        cache = SkillCacheManager(cache_root=tmp_path)
+        archive = _make_tar_gz({"SKILL.md": "---\nname: my-skill\n---\nHello"})
+        dest = cache.store("acme", "my-skill", "1.0.0", archive)
+
+        assert dest.is_dir()
+        assert (dest / "SKILL.md").exists()
+
+        retrieved = cache.get_cached_path("acme", "my-skill")
+        assert retrieved == dest
+
+    def test_store_writes_metadata(self, tmp_path: Path) -> None:
+        cache = SkillCacheManager(cache_root=tmp_path)
+        archive = _make_tar_gz({"SKILL.md": "content"})
+        dest = cache.store("acme", "my-skill", "2.3.4", archive)
+
+        meta_file = dest / ".crewai_meta.json"
+        assert meta_file.exists()
+        meta = json.loads(meta_file.read_text())
+        assert meta["org"] == "acme"
+        assert meta["name"] == "my-skill"
+        assert meta["version"] == "2.3.4"
+        assert "installed_at" in meta
+
+    def test_store_overwrites_previous_version(self, tmp_path: Path) -> None:
+        cache = SkillCacheManager(cache_root=tmp_path)
+        archive_v1 = _make_tar_gz({"SKILL.md": "v1", "extra.txt": "old"})
+        cache.store("acme", "my-skill", "1.0.0", archive_v1)
+
+        archive_v2 = _make_tar_gz({"SKILL.md": "v2"})
+        dest = cache.store("acme", "my-skill", "2.0.0", archive_v2)
+
+        # Old file should be gone
+        assert not (dest / "extra.txt").exists()
+        assert (dest / "SKILL.md").read_text() == "v2"
+
+        meta = json.loads((dest / ".crewai_meta.json").read_text())
+        assert meta["version"] == "2.0.0"
+
+    def test_list_cached_empty(self, tmp_path: Path) -> None:
+        cache = SkillCacheManager(cache_root=tmp_path)
+        assert cache.list_cached() == []
+
+    def test_list_cached(self, tmp_path: Path) -> None:
+        cache = SkillCacheManager(cache_root=tmp_path)
+        archive = _make_tar_gz({"SKILL.md": "x"})
+        cache.store("acme", "skill-a", "1.0.0", archive)
+        cache.store("acme", "skill-b", "0.1.0", archive)
+        cache.store("other-org", "skill-c", None, archive)
+
+        entries = cache.list_cached()
+        names = {e["name"] for e in entries}
+        assert names == {"skill-a", "skill-b", "skill-c"}
+
+    def test_invalidate_existing(self, tmp_path: Path) -> None:
+        cache = SkillCacheManager(cache_root=tmp_path)
+        archive = _make_tar_gz({"SKILL.md": "x"})
+        cache.store("acme", "my-skill", "1.0.0", archive)
+
+        removed = cache.invalidate("acme", "my-skill")
+        assert removed is True
+        assert cache.get_cached_path("acme", "my-skill") is None
+
+    def test_invalidate_missing(self, tmp_path: Path) -> None:
+        cache = SkillCacheManager(cache_root=tmp_path)
+        removed = cache.invalidate("acme", "ghost-skill")
+        assert removed is False
+
+    def test_store_version_none(self, tmp_path: Path) -> None:
+        cache = SkillCacheManager(cache_root=tmp_path)
+        archive = _make_tar_gz({"SKILL.md": "x"})
+        dest = cache.store("acme", "my-skill", None, archive)
+        meta = json.loads((dest / ".crewai_meta.json").read_text())
+        assert meta["version"] is None

lib/crewai/tests/skills/test_models_version.py

@@ -0,0 +1,32 @@
+"""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]

lib/crewai/tests/skills/test_registry.py

@@ -0,0 +1,129 @@
+"""Tests for SkillRegistry."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from crewai.skills.registry import (
+    SkillNotCachedError,
+    is_registry_ref,
+    parse_registry_ref,
+)
+
+
+class TestIsRegistryRef:
+    def test_at_prefixed(self) -> None:
+        assert is_registry_ref("@acme/my-skill") is True
+
+    def test_plain_string(self) -> None:
+        assert is_registry_ref("my-skill") is False
+
+    def test_path_like_string(self) -> None:
+        assert is_registry_ref("./skills/my-skill") is False
+
+    def test_non_string(self) -> None:
+        assert is_registry_ref(None) is False
+        assert is_registry_ref(42) is False
+        assert is_registry_ref(Path("something")) is False
+
+
+class TestParseRegistryRef:
+    def test_valid(self) -> None:
+        assert parse_registry_ref("@acme/my-skill") == ("acme", "my-skill")
+
+    def test_valid_with_dashes(self) -> None:
+        assert parse_registry_ref("@my-org/cool-skill") == ("my-org", "cool-skill")
+
+    def test_missing_at(self) -> None:
+        with pytest.raises(ValueError, match="must start with '@'"):
+            parse_registry_ref("acme/my-skill")
+
+    def test_missing_slash(self) -> None:
+        with pytest.raises(ValueError, match="'@org/name' format"):
+            parse_registry_ref("@acme-skill")
+
+    def test_empty_org(self) -> None:
+        with pytest.raises(ValueError, match="non-empty"):
+            parse_registry_ref("@/my-skill")
+
+    def test_empty_name(self) -> None:
+        with pytest.raises(ValueError, match="non-empty"):
+            parse_registry_ref("@acme/")
+
+
+class TestResolveRegistryRef:
+    """Test resolution order and CI mode behaviour."""
+
+    def _make_skill_dir(self, base: Path, name: str) -> Path:
+        """Write a minimal SKILL.md into base/name/."""
+        skill_dir = base / name
+        skill_dir.mkdir(parents=True)
+        (skill_dir / "SKILL.md").write_text(
+            f"---\nname: {name}\ndescription: Test skill.\n---\n\nInstructions."
+        )
+        return skill_dir
+
+    def test_resolves_project_local(self, tmp_path: Path) -> None:
+        """Local ./skills/{name}/ takes priority over cache."""
+        skills_dir = tmp_path / "skills"
+        skills_dir.mkdir()
+        self._make_skill_dir(skills_dir, "my-skill")
+
+        # Mock SkillCacheManager to return None (not cached) so only local is hit
+        mock_cache = MagicMock()
+        mock_cache.get_cached_path.return_value = None
+
+        with (
+            patch("crewai.skills.registry._is_noninteractive", return_value=False),
+            patch.object(Path, "cwd", return_value=tmp_path),
+            patch("crewai.skills.registry.SkillCacheManager", return_value=mock_cache),
+        ):
+            from crewai.skills.registry import resolve_registry_ref
+            skill = resolve_registry_ref("@acme/my-skill")
+
+        assert skill.name == "my-skill"
+
+    def test_raises_in_ci_when_not_cached(self, tmp_path: Path) -> None:
+        """In CI mode, raise SkillNotCachedError if no local or cached copy."""
+        mock_cache = MagicMock()
+        mock_cache.get_cached_path.return_value = None
+
+        with (
+            patch("crewai.skills.registry._is_noninteractive", return_value=True),
+            patch.object(Path, "cwd", return_value=tmp_path),
+            patch("crewai.skills.registry.SkillCacheManager", return_value=mock_cache),
+        ):
+            from crewai.skills.registry import resolve_registry_ref
+            with pytest.raises(SkillNotCachedError) as exc_info:
+                resolve_registry_ref("@acme/ghost-skill")
+            assert "@acme/ghost-skill" in str(exc_info.value)
+
+    def test_resolves_from_cache(self, tmp_path: Path) -> None:
+        """Falls back to global cache when no project-local skill exists."""
+        cache_dir = tmp_path / "acme" / "cached-skill"
+        cache_dir.mkdir(parents=True)
+        (cache_dir / "SKILL.md").write_text(
+            "---\nname: cached-skill\ndescription: Cached.\n---\n\nCached instructions."
+        )
+
+        mock_cache = MagicMock()
+        mock_cache.get_cached_path.return_value = cache_dir
+
+        # tmp_path has no ./skills/ directory
+        with (
+            patch("crewai.skills.registry._is_noninteractive", return_value=False),
+            patch.object(Path, "cwd", return_value=tmp_path),
+            patch("crewai.skills.registry.SkillCacheManager", return_value=mock_cache),
+        ):
+            from crewai.skills.registry import resolve_registry_ref
+            skill = resolve_registry_ref("@acme/cached-skill")
+
+        assert skill.name == "cached-skill"
+
+    def test_skill_not_cached_error_contains_ref(self) -> None:
+        err = SkillNotCachedError("@foo/bar")
+        assert "@foo/bar" in str(err)
+        assert err.ref == "@foo/bar"

lib/devtools/src/crewai_devtools/cli.py

@@ -744,18 +744,23 @@ def _is_prerelease(version: str) -> bool:
     return any(indicator in v for indicator in _PRERELEASE_INDICATORS)
 
 
-def get_commits_from_last_tag(tag_name: str, version: str) -> tuple[str, str]:
+def get_commits_from_last_tag(
+    tag_name: str, version: str, cwd: Path | None = None
+) -> tuple[str, str]:
     """Get commits from the last tag, excluding current version.
 
     Args:
         tag_name: Current tag name (e.g., "v1.0.0").
         version: Current version (e.g., "1.0.0").
+        cwd: Directory to run git commands in (defaults to current).
 
     Returns:
         Tuple of (commit_range, commits) where commits is newline-separated.
     """
     try:
-        all_tags = run_command(["git", "tag", "--sort=-version:refname"]).split("\n")
+        all_tags = run_command(
+            ["git", "tag", "--sort=-version:refname"], cwd=cwd
+        ).split("\n")
         prev_tags = [t for t in all_tags if t and t != tag_name and t != f"v{version}"]
 
         if not _is_prerelease(version):
@@ -764,22 +769,30 @@ def get_commits_from_last_tag(tag_name: str, version: str) -> tuple[str, str]:
         if prev_tags:
             last_tag = prev_tags[0]
             commit_range = f"{last_tag}..HEAD"
-            commits = run_command(["git", "log", commit_range, "--pretty=format:%s"])
+            commits = run_command(
+                ["git", "log", commit_range, "--pretty=format:%s"], cwd=cwd
+            )
         else:
             commit_range = "HEAD"
-            commits = run_command(["git", "log", "--pretty=format:%s"])
+            commits = run_command(["git", "log", "--pretty=format:%s"], cwd=cwd)
     except subprocess.CalledProcessError:
         commit_range = "HEAD"
-        commits = run_command(["git", "log", "--pretty=format:%s"])
+        commits = run_command(["git", "log", "--pretty=format:%s"], cwd=cwd)
 
     return commit_range, commits
 
 
-def get_github_contributors(commit_range: str) -> list[str]:
+def get_github_contributors(
+    commit_range: str,
+    repo: str = "crewAIInc/crewAI",
+    cwd: Path | None = None,
+) -> list[str]:
     """Get GitHub usernames from commit range using GitHub API.
 
     Args:
         commit_range: Git commit range (e.g., "abc123..HEAD").
+        repo: GitHub repo in ``owner/name`` form to resolve commits against.
+        cwd: Directory to run git commands in (defaults to current).
 
     Returns:
         List of GitHub usernames sorted alphabetically.
@@ -791,10 +804,10 @@ def get_github_contributors(commit_range: str) -> list[str]:
             gh_token = None
 
         g = Github(login_or_token=gh_token) if gh_token else Github()
-        github_repo = g.get_repo("crewAIInc/crewAI")
+        github_repo = g.get_repo(repo)
 
         commit_shas = run_command(
-            ["git", "log", commit_range, "--pretty=format:%H"]
+            ["git", "log", commit_range, "--pretty=format:%H"], cwd=cwd
         ).split("\n")
 
         contributors = set()
@@ -934,9 +947,26 @@ def _generate_release_notes(
     version: str,
     tag_name: str,
     no_edit: bool,
+    cwd: Path | None = None,
+    gh_repo: str = "crewAIInc/crewAI",
+    openai_client: OpenAI | None = None,
+    bump_already_done: bool = True,
 ) -> tuple[str, OpenAI, bool]:
     """Generate, display, and optionally edit release notes.
 
+    Args:
+        version: Version being released.
+        tag_name: Tag name for the release.
+        no_edit: Skip the interactive edit prompt.
+        cwd: Directory to run git commands in (defaults to current).
+        gh_repo: GitHub repo (``owner/name``) for resolving contributors.
+        openai_client: Reuse an existing OpenAI client if provided.
+        bump_already_done: True when the ``feat: bump versions to <version>``
+            commit for the current release is already in history (the real
+            release path). False in previews where no bump exists yet — the
+            most recent bump commit is the *previous* version and must be
+            used as the range start.
+
     Returns:
         Tuple of (release_notes, openai_client, is_prerelease).
     """
@@ -951,7 +981,8 @@ def _generate_release_notes(
                     "log",
                     "--grep=^feat: bump versions to",
                     "--format=%H %s",
-                ]
+                ],
+                cwd=cwd,
             )
             bump_entries = [
                 line for line in prev_bump_output.strip().split("\n") if line.strip()
@@ -959,7 +990,8 @@ def _generate_release_notes(
 
             is_stable = not _is_prerelease(version)
             prev_commit = None
-            for entry in bump_entries[1:]:
+            scan_entries = bump_entries[1:] if bump_already_done else bump_entries
+            for entry in scan_entries:
                 bump_ver = entry.split("feat: bump versions to", 1)[-1].strip()
                 if is_stable and _is_prerelease(bump_ver):
                     continue
@@ -969,7 +1001,7 @@ def _generate_release_notes(
             if prev_commit:
                 commit_range = f"{prev_commit}..HEAD"
                 commits = run_command(
-                    ["git", "log", commit_range, "--pretty=format:%s"]
+                    ["git", "log", commit_range, "--pretty=format:%s"], cwd=cwd
                 )
 
                 commit_lines = [
@@ -979,14 +1011,21 @@ def _generate_release_notes(
                 ]
                 commits = "\n".join(commit_lines)
             else:
-                commit_range, commits = get_commits_from_last_tag(tag_name, version)
+                commit_range, commits = get_commits_from_last_tag(
+                    tag_name, version, cwd=cwd
+                )
 
         except subprocess.CalledProcessError:
-            commit_range, commits = get_commits_from_last_tag(tag_name, version)
+            commit_range, commits = get_commits_from_last_tag(
+                tag_name, version, cwd=cwd
+            )
 
-        github_contributors = get_github_contributors(commit_range)
+        github_contributors = get_github_contributors(
+            commit_range, repo=gh_repo, cwd=cwd
+        )
 
-        openai_client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
+        if openai_client is None:
+            openai_client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
 
         if commits.strip():
             contributors_section = ""
@@ -1544,7 +1583,13 @@ def _wait_for_pr_merged(branch: str, cwd: Path) -> None:
         time.sleep(_PR_MERGE_POLL_INTERVAL)
 
 
-def _release_enterprise(version: str, is_prerelease: bool, dry_run: bool) -> None:
+def _release_enterprise(
+    version: str,
+    is_prerelease: bool,
+    dry_run: bool,
+    no_edit: bool = False,
+    openai_client: OpenAI | None = None,
+) -> None:
     """Clone the enterprise repo, bump versions, and create a release PR.
 
     Expects ENTERPRISE_REPO, ENTERPRISE_VERSION_DIRS, and
@@ -1554,6 +1599,8 @@ def _release_enterprise(version: str, is_prerelease: bool, dry_run: bool) -> Non
         version: New version string.
         is_prerelease: Whether this is a pre-release version.
         dry_run: Show what would be done without making changes.
+        no_edit: Skip the interactive release-notes edit prompt.
+        openai_client: Reuse OpenAI client from earlier phases if available.
     """
     if (
         not _ENTERPRISE_REPO
@@ -1571,7 +1618,6 @@ def _release_enterprise(version: str, is_prerelease: bool, dry_run: bool) -> Non
     )
 
     if dry_run:
-        console.print(f"[dim][DRY RUN][/dim] Would clone {enterprise_repo}")
         for d in _ENTERPRISE_VERSION_DIRS:
             console.print(f"[dim][DRY RUN][/dim] Would update versions in {d}")
         console.print(
@@ -1582,6 +1628,26 @@ def _release_enterprise(version: str, is_prerelease: bool, dry_run: bool) -> Non
             "[dim][DRY RUN][/dim] Would create bump PR, wait for merge, "
             "then tag and release"
         )
+
+        with tempfile.TemporaryDirectory() as tmp:
+            repo_dir = Path(tmp) / enterprise_repo.split("/")[-1]
+            console.print(f"\nCloning {enterprise_repo} (read-only preview)...")
+            run_command(["gh", "repo", "clone", enterprise_repo, str(repo_dir)])
+            console.print(f"[green]✓[/green] Cloned {enterprise_repo}")
+
+            _generate_release_notes(
+                version,
+                version,
+                no_edit,
+                cwd=repo_dir,
+                gh_repo=enterprise_repo,
+                openai_client=openai_client,
+                bump_already_done=False,
+            )
+            console.print(
+                "[dim][DRY RUN][/dim] Would tag and create GitHub release "
+                "with the notes above"
+            )
         return
 
     with tempfile.TemporaryDirectory() as tmp:
@@ -1694,8 +1760,18 @@ def _release_enterprise(version: str, is_prerelease: bool, dry_run: bool) -> Non
         run_command(["git", "pull"], cwd=repo_dir)
 
         tag_name = version
+
+        release_notes, _, _ = _generate_release_notes(
+            version,
+            tag_name,
+            no_edit,
+            cwd=repo_dir,
+            gh_repo=enterprise_repo,
+            openai_client=openai_client,
+        )
+
         run_command(
-            ["git", "tag", "-a", tag_name, "-m", f"Release {version}"],
+            ["git", "tag", "-a", tag_name, "-m", release_notes],
             cwd=repo_dir,
         )
         run_command(["git", "push", "origin", tag_name], cwd=repo_dir)
@@ -1711,7 +1787,7 @@ def _release_enterprise(version: str, is_prerelease: bool, dry_run: bool) -> Non
             "--title",
             tag_name,
             "--notes",
-            f"Release {version}",
+            release_notes,
         ]
         if is_prerelease:
             gh_cmd.append("--prerelease")
@@ -2010,7 +2086,7 @@ def tag(dry_run: bool, no_edit: bool) -> None:
             console.print("[green]✓[/green] main branch up to date")
 
         release_notes, openai_client, is_prerelease = _generate_release_notes(
-            version, tag_name, no_edit
+            version, tag_name, no_edit, bump_already_done=True
         )
 
         docs_branch = _update_docs_and_create_pr(
@@ -2121,7 +2197,7 @@ def release(
 
     if skip_to_enterprise:
         try:
-            _release_enterprise(version, is_prerelease, dry_run)
+            _release_enterprise(version, is_prerelease, dry_run, no_edit=no_edit)
         except BaseException as e:
             _print_release_error(e)
             _resume_hint(
@@ -2217,7 +2293,7 @@ def release(
             console.print("[green]✓[/green] main branch up to date")
 
         release_notes, openai_client, is_prerelease = _generate_release_notes(
-            version, tag_name, no_edit
+            version, tag_name, no_edit, bump_already_done=not dry_run
         )
 
         docs_branch = _update_docs_and_create_pr(
@@ -2271,7 +2347,13 @@ def release(
 
     if not skip_enterprise:
         try:
-            _release_enterprise(version, is_prerelease, dry_run)
+            _release_enterprise(
+                version,
+                is_prerelease,
+                dry_run,
+                no_edit=no_edit,
+                openai_client=openai_client,
+            )
         except BaseException as e:
             _print_release_error(e)
             _resume_hint(

pyproject.toml

@@ -187,6 +187,8 @@ exclude-newer = "3 days"
 # urllib3 <2.7.0 has GHSA-qccp-gfcp-xxvc (ProxyManager cross-origin redirect leaks Authorization/Cookie) and GHSA-mf9v-mfxr-j63j (streaming decompression-bomb bypass); force 2.7.0+.
 # langsmith <0.8.0 has GHSA-3644-q5cj-c5c7 (public prompt manifest deserialization, SSRF/secret disclosure); force 0.8.0+.
 # authlib <1.6.11 has GHSA-jj8c-mmj3-mmgv (CSRF bypass in cache-based state storage).
+# pip <26.1.1 has GHSA-58qw-9mgm-455v (archive handling); OSV considers 26.1.1 unaffected.
+# paramiko <5.0.0 has GHSA-r374-rxx8-8654 (SHA-1 in rsakey.py); OSV considers 5.0.0 unaffected. Transitive via composio-core.
 # litellm 1.83.8+ hard-pins openai==2.24.0, missing openai.types.responses used by crewai;
 # override to >=2.30.0 (the version litellm 1.83.7 used) until upstream relaxes the pin.
 override-dependencies = [
@@ -205,6 +207,8 @@ override-dependencies = [
     "gitpython>=3.1.50,<4",
     "langsmith>=0.8.0,<1",
     "authlib>=1.6.11",
+    "pip>=26.1.1",
+    "paramiko>=5.0.0",
 ]
 
 [tool.uv.workspace]

uv.lock

@@ -13,7 +13,7 @@ resolution-markers = [
 ]
 
 [options]
-exclude-newer = "2026-05-12T13:27:48.906744Z"
+exclude-newer = "2026-05-17T14:20:01.778505Z"
 exclude-newer-span = "P3D"
 
 [manifest]
@@ -34,7 +34,9 @@ overrides = [
     { name = "langsmith", specifier = ">=0.8.0,<1" },
     { name = "onnxruntime", marker = "python_full_version < '3.11'", specifier = "<1.24" },
     { name = "openai", specifier = ">=2.30.0,<3" },
+    { name = "paramiko", specifier = ">=5.0.0" },
     { name = "pillow", specifier = ">=12.1.1" },
+    { name = "pip", specifier = ">=26.1.1" },
     { name = "pypdf", specifier = ">=6.10.2,<7" },
     { name = "python-multipart", specifier = ">=0.0.27,<1" },
     { name = "rich", specifier = ">=13.7.1" },
@@ -3268,11 +3270,11 @@ wheels = [
 
 [[package]]
 name = "idna"
-version = "3.11"
+version = "3.15"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/6f/6d/0703ccc57f3a7233505399edb88de3cbd678da106337b9fcde432b65ed60/idna-3.11.tar.gz", hash = "sha256:795dafcc9c04ed0c1fb032c2aa73654d8e8c5023a7df64a53f39190ada629902", size = 194582, upload-time = "2025-10-12T14:55:20.501Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/82/77/7b3966d0b9d1d31a36ddf1746926a11dface89a83409bf1483f0237aa758/idna-3.15.tar.gz", hash = "sha256:ca962446ea538f7092a95e057da437618e886f4d349216d2b1e294abfdb65fdc", size = 199245, upload-time = "2026-05-12T22:45:57.011Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/0e/61/66938bbb5fc52dbdf84594873d5b51fb1f7c7794e9c0f5bd885f30bc507b/idna-3.11-py3-none-any.whl", hash = "sha256:771a87f49d9defaf64091e6e6fe9c18d4833f140bd19464795bc32d966ca37ea", size = 71008, upload-time = "2025-10-12T14:55:18.883Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/23/408243171aa9aaba178d3e2559159c24c1171a641aa83b67bdd3394ead8e/idna-3.15-py3-none-any.whl", hash = "sha256:048adeaf8c2d788c40fee287673ccaa74c24ffd8dcf09ffa555a2fbb59f10ac8", size = 72340, upload-time = "2026-05-12T22:45:55.733Z" },
 ]
 
 [[package]]
@@ -5788,7 +5790,7 @@ wheels = [
 
 [[package]]
 name = "paramiko"
-version = "4.0.0"
+version = "5.0.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "bcrypt" },
@@ -5796,9 +5798,9 @@ dependencies = [
     { name = "invoke" },
     { name = "pynacl" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/1f/e7/81fdcbc7f190cdb058cffc9431587eb289833bdd633e2002455ca9bb13d4/paramiko-4.0.0.tar.gz", hash = "sha256:6a25f07b380cc9c9a88d2b920ad37167ac4667f8d9886ccebd8f90f654b5d69f", size = 1630743, upload-time = "2025-08-04T01:02:03.711Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/62/93/dcc25d52f49022ae6175d15e6bd751f1acc99b98bc61fc55e5155a7be2e7/paramiko-5.0.0.tar.gz", hash = "sha256:36763b5b95c2a0dcfdf1abc48e48156ee425b21efe2f0e787c2dd5a95c0e5e79", size = 1548586, upload-time = "2026-05-09T18:28:52.256Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/a9/90/a744336f5af32c433bd09af7854599682a383b37cfd78f7de263de6ad6cb/paramiko-4.0.0-py3-none-any.whl", hash = "sha256:0e20e00ac666503bf0b4eda3b6d833465a2b7aff2e2b3d79a8bba5ef144ee3b9", size = 223932, upload-time = "2025-08-04T01:02:02.029Z" },
+    { url = "https://files.pythonhosted.org/packages/82/5b/eadf6d45de38d30ab603f49393b6cd2cbe7e233af8cf90197e32782b68a9/paramiko-5.0.0-py3-none-any.whl", hash = "sha256:b7044611c30140d9a75261653210e2002977b71a0497ff3ba0d98d7edbf62f7c", size = 208919, upload-time = "2026-05-09T18:28:50.295Z" },
 ]
 
 [[package]]
@@ -6060,11 +6062,11 @@ wheels = [
 
 [[package]]
 name = "pip"
-version = "26.1"
+version = "26.1.1"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/73/7e/d2b04004e1068ad4fdfa2f227b839b5d03e602e47cdbbf49de71137c9546/pip-26.1.tar.gz", hash = "sha256:81e13ebcca3ffa8cc85e4deff5c27e1ee26dea0aa7fc2f294a073ac208806ff3", size = 1840316, upload-time = "2026-04-26T21:00:05.406Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/b6/48/cb9b7a682f6fe01a4221e1728941dd4ac3cd9090a17db3779d6ff490b602/pip-26.1.1.tar.gz", hash = "sha256:d36762751d156a4ee895de8af39aa0abeeeb577f93a2eca6ab62467bbf0f8a78", size = 1840400, upload-time = "2026-05-04T19:02:21.248Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/70/7a/be4bd8bcbb24ea475856dd68159d78b03b2bb53dae369f69c9606b8888f5/pip-26.1-py3-none-any.whl", hash = "sha256:4e8486d821d814b77319acb7b9e8bf5a4ee7590a643e7cb21029f209be8573c1", size = 1812804, upload-time = "2026-04-26T21:00:03.194Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/eb/fea4d1d51c49832120f7f285d07306db3960f423a2612c6057caf3e8196f/pip-26.1.1-py3-none-any.whl", hash = "sha256:99cb1c2899893b075ff56e4ed0af55669a955b49ad7fb8d8603ecdaf4ed653fb", size = 1812777, upload-time = "2026-05-04T19:02:18.9Z" },
 ]
 
 [[package]]