agent-framework-lib 0.6.3.post3__tar.gz → 0.6.3.post4__tar.gz

{agent_framework_lib-0.6.3.post3/agent_framework_lib.egg-info → agent_framework_lib-0.6.3.post4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-framework-lib
-Version: 0.6.3.post3
+Version: 0.6.3.post4
 Summary: A comprehensive Python framework for building and serving conversational AI agents with FastAPI
 Author-email: Sebastian Pavel <sebastian@cinco.ai>, Elliott Girard <elliott.girard@icloud.com>
 Maintainer-email: Sebastian Pavel <sebastian@cinco.ai>
@@ -373,13 +373,13 @@ ANTHROPIC_API_KEY=sk-ant-your-anthropic-key
 GEMINI_API_KEY=your-gemini-key
 
 # Model Configuration
-DEFAULT_MODEL=gpt-5-mini
+DEFAULT_MODEL=gpt-5.4-mini
 
 # Multi-Model Routing (Auto Mode)
 DEFAULT_MODEL_MODE=auto                    # "auto" or specific model name
-AUTO_CLASSIFIER_MODEL=gpt-5-nano           # Model for complexity classification
-PREFERRED_LIGHT_MODELS=gpt-5-nano,claude-haiku-4-5-20251001
-PREFERRED_STANDARD_MODELS=gpt-5-mini
+AUTO_CLASSIFIER_MODEL=gpt-5.4-nano           # Model for complexity classification
+PREFERRED_LIGHT_MODELS=gpt-5.4-nano,claude-haiku-4-5-20251001
+PREFERRED_STANDARD_MODELS=gpt-5.4-mini
 PREFERRED_ADVANCED_MODELS=gpt-5.2,claude-opus-4-6
 
 # Session Storage (optional)
@@ -446,8 +446,8 @@ When `DEFAULT_MODEL_MODE=auto`, the system analyzes each query and routes it to
 
 | Tier | Icon | Use Case | Example Models |
 |------|------|----------|----------------|
-| **Light** | 💨 | Simple queries, greetings, basic info | gpt-5-nano, claude-haiku-4-5 |
-| **Standard** | ⚖️ | Typical questions, explanations | gpt-5-mini, claude-sonnet-4-6 |
+| **Light** | 💨 | Simple queries, greetings, basic info | gpt-5.4-nano, claude-haiku-4-5 |
+| **Standard** | ⚖️ | Typical questions, explanations | gpt-5.4-mini, claude-sonnet-4-6 |
 | **Advanced** | 🧠 | Complex analysis, creative tasks | gpt-5.2, claude-opus-4-6 |
 
 **Benefits:**
@@ -469,11 +469,11 @@ Users can also select a specific model from the UI dropdown:
 DEFAULT_MODEL_MODE=auto
 
 # Model used for complexity classification (should be fast and cheap)
-AUTO_CLASSIFIER_MODEL=gpt-5-nano
+AUTO_CLASSIFIER_MODEL=gpt-5.4-nano
 
 # Preferred models per tier (comma-separated, in order of preference)
-PREFERRED_LIGHT_MODELS=gpt-5-nano,claude-haiku-4-5-20251001,gemini-2.5-flash-lite
-PREFERRED_STANDARD_MODELS=gpt-5-mini,gemini-2.5-flash
+PREFERRED_LIGHT_MODELS=gpt-5.4-nano,claude-haiku-4-5-20251001,gemini-2.5-flash-lite
+PREFERRED_STANDARD_MODELS=gpt-5.4-mini,gemini-2.5-flash
 PREFERRED_ADVANCED_MODELS=gpt-5.2,claude-opus-4-6,gemini-2.5-pro
 ```
 
@@ -486,12 +486,12 @@ curl http://localhost:8000/api/models
 # Response
 {
   "models_by_tier": {
-    "light": [{"id": "gpt-5-nano", "provider": "openai", "available": true}, ...],
+    "light": [{"id": "gpt-5.4-nano", "provider": "openai", "available": true}, ...],
     "standard": [...],
     "advanced": [...]
   },
   "default_mode": "auto",
-  "classifier_model": "gpt-5-nano"
+  "classifier_model": "gpt-5.4-nano"
 }
 ```
 
@@ -520,7 +520,7 @@ class MyAgent(LlamaIndexAgent):
         )
         # Default model config (can be overridden per session)
         self.default_temperature = 0.7
-        self.default_model = "gpt-5-mini"
+        self.default_model = "gpt-5.4-mini"
 ```
 
 **Runtime Configuration:**

{agent_framework_lib-0.6.3.post3 → agent_framework_lib-0.6.3.post4}/README.md

@@ -227,13 +227,13 @@ ANTHROPIC_API_KEY=sk-ant-your-anthropic-key
 GEMINI_API_KEY=your-gemini-key
 
 # Model Configuration
-DEFAULT_MODEL=gpt-5-mini
+DEFAULT_MODEL=gpt-5.4-mini
 
 # Multi-Model Routing (Auto Mode)
 DEFAULT_MODEL_MODE=auto                    # "auto" or specific model name
-AUTO_CLASSIFIER_MODEL=gpt-5-nano           # Model for complexity classification
-PREFERRED_LIGHT_MODELS=gpt-5-nano,claude-haiku-4-5-20251001
-PREFERRED_STANDARD_MODELS=gpt-5-mini
+AUTO_CLASSIFIER_MODEL=gpt-5.4-nano           # Model for complexity classification
+PREFERRED_LIGHT_MODELS=gpt-5.4-nano,claude-haiku-4-5-20251001
+PREFERRED_STANDARD_MODELS=gpt-5.4-mini
 PREFERRED_ADVANCED_MODELS=gpt-5.2,claude-opus-4-6
 
 # Session Storage (optional)
@@ -300,8 +300,8 @@ When `DEFAULT_MODEL_MODE=auto`, the system analyzes each query and routes it to
 
 | Tier | Icon | Use Case | Example Models |
 |------|------|----------|----------------|
-| **Light** | 💨 | Simple queries, greetings, basic info | gpt-5-nano, claude-haiku-4-5 |
-| **Standard** | ⚖️ | Typical questions, explanations | gpt-5-mini, claude-sonnet-4-6 |
+| **Light** | 💨 | Simple queries, greetings, basic info | gpt-5.4-nano, claude-haiku-4-5 |
+| **Standard** | ⚖️ | Typical questions, explanations | gpt-5.4-mini, claude-sonnet-4-6 |
 | **Advanced** | 🧠 | Complex analysis, creative tasks | gpt-5.2, claude-opus-4-6 |
 
 **Benefits:**
@@ -323,11 +323,11 @@ Users can also select a specific model from the UI dropdown:
 DEFAULT_MODEL_MODE=auto
 
 # Model used for complexity classification (should be fast and cheap)
-AUTO_CLASSIFIER_MODEL=gpt-5-nano
+AUTO_CLASSIFIER_MODEL=gpt-5.4-nano
 
 # Preferred models per tier (comma-separated, in order of preference)
-PREFERRED_LIGHT_MODELS=gpt-5-nano,claude-haiku-4-5-20251001,gemini-2.5-flash-lite
-PREFERRED_STANDARD_MODELS=gpt-5-mini,gemini-2.5-flash
+PREFERRED_LIGHT_MODELS=gpt-5.4-nano,claude-haiku-4-5-20251001,gemini-2.5-flash-lite
+PREFERRED_STANDARD_MODELS=gpt-5.4-mini,gemini-2.5-flash
 PREFERRED_ADVANCED_MODELS=gpt-5.2,claude-opus-4-6,gemini-2.5-pro
 ```
 
@@ -340,12 +340,12 @@ curl http://localhost:8000/api/models
 # Response
 {
   "models_by_tier": {
-    "light": [{"id": "gpt-5-nano", "provider": "openai", "available": true}, ...],
+    "light": [{"id": "gpt-5.4-nano", "provider": "openai", "available": true}, ...],
     "standard": [...],
     "advanced": [...]
   },
   "default_mode": "auto",
-  "classifier_model": "gpt-5-nano"
+  "classifier_model": "gpt-5.4-nano"
 }
 ```
 
@@ -374,7 +374,7 @@ class MyAgent(LlamaIndexAgent):
         )
         # Default model config (can be overridden per session)
         self.default_temperature = 0.7
-        self.default_model = "gpt-5-mini"
+        self.default_model = "gpt-5.4-mini"
 ```
 
 **Runtime Configuration:**

{agent_framework_lib-0.6.3.post3 → agent_framework_lib-0.6.3.post4}/agent_framework/__init__.py

@@ -345,6 +345,11 @@ def create_basic_agent_server(
     
     logger.info(f"[create_basic_agent_server] Starting server for {agent_class.__name__} on {host}:{port}")
     logger.info(f"[create_basic_agent_server] Reload: {reload}")
+
+    # Ensure AGENT_HOST and AGENT_PORT are in the environment so that
+    # subprocesses (e.g. skill scripts via ShellTool) can reach this server.
+    os.environ["AGENT_HOST"] = host
+    os.environ["AGENT_PORT"] = str(port)
     
     # When reload=True, uvicorn requires an import string, not the app object directly
     if reload:

{agent_framework_lib-0.6.3.post3 → agent_framework_lib-0.6.3.post4}/agent_framework/core/model_config.py

@@ -14,7 +14,7 @@ This module provides:
 Environment Variables:
 - OPENAI_API_KEY: OpenAI API key
 - GEMINI_API_KEY: Google Gemini API key
-- DEFAULT_MODEL: Default model to use (default: "gpt-5-mini")
+- DEFAULT_MODEL: Default model to use (default: "gpt-5.4-mini")
 - OPENAI_MODELS: Comma-separated list of OpenAI model names
 - GEMINI_MODELS: Comma-separated list of Gemini model names
 - FALLBACK_PROVIDER: Provider to use when model provider is unknown
@@ -27,7 +27,7 @@ Example:
     from agent_framework.model_config import model_config
     
     # Get provider for a model
-    provider = model_config.get_provider("gpt-5-mini")
+    provider = model_config.get_provider("gpt-5.4-mini")
     
     # Get API key for a provider
     api_key = model_config.get_api_key(provider)
@@ -383,7 +383,7 @@ class ModelConfigManager:
         Get a flat list of all models with provider info and availability status.
         
         Returns a list of dictionaries, each containing:
-        - id: The model identifier (e.g., "gpt-5-minio-mini")
+        - id: The model identifier (e.g., "gpt-5.4-minio-mini")
         - provider: The provider name (e.g., "openai")
         - available: Boolean indicating if the model's API key is configured
         
@@ -394,7 +394,7 @@ class ModelConfigManager:
             ```python
             models = model_config.get_all_available_models()
             # [
-            #     {"id": "gpt-5-minio", "provider": "openai", "available": True},
+            #     {"id": "gpt-5.4-minio", "provider": "openai", "available": True},
             #     {"id": "claude-3-opus", "provider": "anthropic", "available": False},
             #     ...
             # ]
@@ -500,7 +500,7 @@ class ModelConfigManager:
             ```python
             model_config.register_agent_config("my-agent", {
                 "system_prompt": "You are a helpful assistant.",
-                "model_name": "gpt-5-minio",
+                "model_name": "gpt-5.4-minio",
                 "model_config": {"temperature": 0.7, "max_tokens": 50000}
             })
             ```

{agent_framework_lib-0.6.3.post3 → agent_framework_lib-0.6.3.post4}/agent_framework/core/step_display_config.py

@@ -279,6 +279,16 @@ DEFAULT_TOOL_DISPLAY: dict[str, StepDisplayInfo] = {
         category="file",
     ),
     # ==========================================================================
+    # Shell & Script Execution Tools
+    # ==========================================================================
+    "shell_exec": StepDisplayInfo(
+        id="shell_exec",
+        friendly_name="🐚 Exécution du script",
+        description="Exécution d'un script ou d'une commande shell",
+        icon="🐚",
+        category="shell",
+    ),
+    # ==========================================================================
     # Code Execution Tools
     # ==========================================================================
     "execute_code": StepDisplayInfo(

{agent_framework_lib-0.6.3.post3 → agent_framework_lib-0.6.3.post4}/agent_framework/monitoring/llm_metrics.py

@@ -47,7 +47,7 @@ class LLMMetrics(BaseModel):
             thinking_tokens=50,
             output_tokens=200,
             start_time=datetime.now(timezone.utc),
-            model_name="gpt-5-mini",
+            model_name="gpt-5.4-mini",
             session_id="session-123"
         )
         print(f"Total tokens: {metrics.total_tokens}")

{agent_framework_lib-0.6.3.post3 → agent_framework_lib-0.6.3.post4}/agent_framework/monitoring/llm_metrics_collector.py

@@ -66,7 +66,7 @@ class LLMMetricsCollector:
         ```python
         # Fallback usage when auto-instrumentation is unavailable
         collector = LLMMetricsCollector(
-            model_name="gpt-5-mini",
+            model_name="gpt-5.4-mini",
             session_id="session-123",
             enabled=True
         )

{agent_framework_lib-0.6.3.post3 → agent_framework_lib-0.6.3.post4}/agent_framework/monitoring/otel_instrumentor.py

@@ -77,7 +77,7 @@ def get_tracer() -> Any:
         tracer = get_tracer()
         if tracer:
             with tracer.start_as_current_span("llm.chat") as span:
-                span.set_attribute("model", "gpt-5")
+                span.set_attribute("model", "gpt-5.4")
         ```
     """
     global _tracer
@@ -106,7 +106,7 @@ def get_meter() -> Any:
         meter = get_meter()
         if meter:
             counter = meter.create_counter("llm.tokens.total")
-            counter.add(100, {"model": "gpt-5"})
+            counter.add(100, {"model": "gpt-5.4"})
         ```
     """
     global _meter
@@ -147,7 +147,7 @@ class OTELInstrumentor:
 
         with instrumentor.trace_llm_call(
             operation_name="llm.chat",
-            model_name="gpt-5-mini",
+            model_name="gpt-5.4-mini",
             session_id="session-123"
         ) as span:
             # Perform LLM call

{agent_framework_lib-0.6.3.post3 → agent_framework_lib-0.6.3.post4}/agent_framework/monitoring/token_counter.py

@@ -56,7 +56,7 @@ class TokenCounter:
 
     Example:
         ```python
-        counter = TokenCounter(model_name="gpt-5-mini")
+        counter = TokenCounter(model_name="gpt-5.4-mini")
         result = counter.count_tokens("Hello, world!")
         print(f"Tokens: {result.count}, Encoding: {result.encoding_name}")
         ```
@@ -215,7 +215,7 @@ class TokenCounter:
 
         Example:
             ```python
-            counter = TokenCounter(model_name="gpt-5-mini")
+            counter = TokenCounter(model_name="gpt-5.4-mini")
             result = counter.count_tokens("Hello, world!")
             print(f"Token count: {result.count}")
             ```
@@ -245,7 +245,7 @@ class TokenCounter:
 
         Example:
             ```python
-            counter = TokenCounter(model_name="gpt-5-mini")
+            counter = TokenCounter(model_name="gpt-5.4-mini")
             messages = [
                 {"role": "system", "content": "You are a helpful assistant."},
                 {"role": "user", "content": "Hello!"}

{agent_framework_lib-0.6.3.post3 → agent_framework_lib-0.6.3.post4}/agent_framework/skills/agent_mixin.py

@@ -127,13 +127,16 @@ class SkillsMixin:
         self._skill_registry.unload(name)
         logger.info(f"Unloaded skill '{name}' for agent '{getattr(self, 'agent_id', 'unknown')}'")
 
-    def register_builtin_skills(self, source: str = "python") -> None:
+    def register_builtin_skills(self, source: str = "markdown") -> None:
         """Register all built-in skills with this agent.
 
+        After registering builtins, also loads any custom skills found in
+        the ``CUSTOM_SKILLS_DIR`` environment variable (default ``./custom_skills``).
+
         Args:
             source: Loading strategy passed to ``get_all_builtin_skills``.
-                Use ``"python"`` (default) for Python factory functions or
-                ``"markdown"`` to load from SKILL.md files.
+                Use ``"markdown"`` (default) to load from SKILL.md files or
+                ``"python"`` for legacy Python factory functions.
                 Skills already registered are skipped.
         """
         from .builtin import get_all_builtin_skills
@@ -158,6 +161,62 @@ class SkillsMixin:
                 f"for agent '{getattr(self, 'agent_id', 'unknown')}'"
             )
 
+        self._register_custom_skills()
+
+    def _register_custom_skills(self) -> None:
+        """Load custom skills from CUSTOM_SKILLS_DIR into this agent's registry.
+
+        Each subdirectory containing a SKILL.md is loaded, has native tools
+        attached, and is registered with ``source="custom"``.  Failures are
+        logged as warnings without blocking the remaining skills.
+        """
+        import os
+        import shutil
+
+        from .markdown_loader import MarkdownSkillLoader
+        from ..tools.shell_tool import ShellTool
+        from ..tools.web_fetch_tool import WebFetchTool
+
+        custom_dir = Path(os.getenv("CUSTOM_SKILLS_DIR", "./custom_skills"))
+        if not custom_dir.is_dir():
+            return
+
+        loader = MarkdownSkillLoader()
+        count = 0
+
+        for child in sorted(custom_dir.iterdir()):
+            if not child.is_dir():
+                continue
+            skill_md = child / "SKILL.md"
+            if not skill_md.exists():
+                continue
+            try:
+                skill = loader.load_from_file(skill_md)
+                if self._skill_registry.get(skill.metadata.name) is not None:
+                    continue
+                existing_types = {type(t) for t in skill.tools}
+                if ShellTool not in existing_types:
+                    skill.tools.append(ShellTool(default_timeout=60))
+                if WebFetchTool not in existing_types:
+                    skill.tools.append(WebFetchTool())
+                for binary in skill.metadata.requires_bins:
+                    if shutil.which(binary) is None:
+                        logger.warning(
+                            "Custom skill '%s' requires binary '%s' not found in PATH",
+                            skill.metadata.name,
+                            binary,
+                        )
+                self._skill_registry.register(skill, source="custom")
+                count += 1
+            except Exception as exc:
+                logger.warning("Failed to load custom skill from %s: %s", child, exc)
+
+        if count > 0:
+            logger.info(
+                f"Registered {count} custom skill(s) "
+                f"for agent '{getattr(self, 'agent_id', 'unknown')}'"
+            )
+
     def get_skill_tools(self) -> list[Callable[..., str]]:
         """
         Get skill management tools for the agent.

{agent_framework_lib-0.6.3.post3 → agent_framework_lib-0.6.3.post4}/agent_framework/skills/base.py

@@ -220,13 +220,15 @@ class SkillRegistry:
         self._skills: dict[str, Skill] = {}
         self._loaded: set[str] = set()
         self._loaded_contexts: dict[str, LoadedSkillContext] = {}
+        self._sources: dict[str, str] = {}
 
-    def register(self, skill: Skill) -> None:
+    def register(self, skill: Skill, source: str = "builtin") -> None:
         """
         Register a skill in the registry.
 
         Args:
             skill: The skill to register
+            source: Origin of the skill (e.g. "builtin" or "custom").
 
         Raises:
             ValueError: If the skill is invalid
@@ -234,6 +236,7 @@ class SkillRegistry:
         if not skill.validate_skill():
             raise ValueError(f"Invalid skill: {skill.metadata.name}")
         self._skills[skill.metadata.name] = skill
+        self._sources[skill.metadata.name] = source
 
     def unregister(self, name: str) -> None:
         """
@@ -248,6 +251,18 @@ class SkillRegistry:
             self.unload(name)
         if name in self._skills:
             del self._skills[name]
+        self._sources.pop(name, None)
+
+    def get_source(self, name: str) -> str | None:
+        """Return the source for a registered skill.
+
+        Args:
+            name: Name of the skill
+
+        Returns:
+            The source string (e.g. "builtin", "custom") or None if not found.
+        """
+        return self._sources.get(name)
 
     def get(self, name: str) -> Skill | None:
         """

{agent_framework_lib-0.6.3.post3 → agent_framework_lib-0.6.3.post4}/agent_framework/skills/builtin/__init__.py

@@ -98,28 +98,44 @@ def _get_builtin_skills_from_python() -> list[Skill]:
 
 
 def _get_builtin_skills_from_markdown() -> list[Skill]:
-    """Load built-in skills from SKILL.md files."""
+    """Load built-in skills from SKILL.md files with ShellTool and WebFetchTool attached."""
     from ..markdown_loader import MarkdownSkillLoader
-    return MarkdownSkillLoader().load_from_dir(_SKILLS_MD_DIR)
+    from ...tools.shell_tool import ShellTool
+    from ...tools.web_fetch_tool import WebFetchTool
+
+    skills = MarkdownSkillLoader().load_from_dir(_SKILLS_MD_DIR)
+    for skill in skills:
+        existing_types = {type(t) for t in skill.tools}
+        if ShellTool not in existing_types:
+            skill.tools.append(ShellTool(default_timeout=60))
+        if WebFetchTool not in existing_types:
+            skill.tools.append(WebFetchTool())
+    return skills
 
 
 def get_all_builtin_skills(
-    source: Literal["python", "markdown"] = "python",
+    source: Literal["python", "markdown"] = "markdown",
 ) -> list[Skill]:
     """Get all built-in skills.
 
     Args:
         source: Loading strategy.
-            - ``"python"`` (default): use Python factory functions.
-            - ``"markdown"``: use SKILL.md files from the ``skills/`` directory.
-              This will become the default once the migration is complete.
+            - ``"markdown"`` (default): use SKILL.md files from the ``skills/`` directory.
+            - ``"python"``: deprecated, use Python factory functions.
 
     Returns:
         List of Skill instances for all built-in skills.
     """
-    if source == "markdown":
-        return _get_builtin_skills_from_markdown()
-    return _get_builtin_skills_from_python()
+    if source == "python":
+        import warnings
+
+        warnings.warn(
+            "source='python' is deprecated. Use source='markdown' (now default).",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return _get_builtin_skills_from_python()
+    return _get_builtin_skills_from_markdown()
 
 
 __all__ = [

agent_framework_lib-0.6.3.post4/agent_framework/skills/builtin/scripts/__init__.py

@@ -0,0 +1 @@
+"""Shared scripts for builtin skills."""

agent_framework_lib-0.6.3.post4/agent_framework/skills/builtin/scripts/create_and_register.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+"""Wrapper that creates a file via a skill script and registers it to storage.
+
+Combines file creation and storage registration into a single CLI invocation.
+Runs the underlying skill script as a subprocess, verifies the output file,
+uploads it to the Storage API, cleans up the local copy, and emits a single
+JSON result with the download URL.
+
+Usage:
+    uv run python -m agent_framework.skills.builtin.scripts.create_and_register \
+        --skill <skill_name> --filename <name> [--output-dir <dir>] [extra args...]
+"""
+import json
+import os
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+
+from agent_framework.skills.builtin.scripts.register_to_storage import (
+    _guess_mime,
+    _multipart_body,
+)
+
+SKILL_MODULE_MAP = {
+    "chart": "agent_framework.skills.builtin.skills.chart.chart_to_image",
+    "unified_pdf": "agent_framework.skills.builtin.skills.unified_pdf.create_pdf",
+    "excel": "agent_framework.skills.builtin.skills.excel.create_excel",
+    "file": "agent_framework.skills.builtin.skills.file.create_file",
+    "mermaid": "agent_framework.skills.builtin.skills.mermaid.mermaid_to_image",
+    "drawio": "agent_framework.skills.builtin.skills.drawio.create_drawio",
+    "table": "agent_framework.skills.builtin.skills.table.table_to_image",
+}
+
+
+def _emit_error(message: str, code: int = 1) -> None:
+    """Print a JSON error to stderr and exit."""
+    print(json.dumps({"status": "error", "message": message}), file=sys.stderr)
+    sys.exit(code)
+
+
+def _parse_args(argv: list[str]) -> tuple[str, str, str | None, list[str]]:
+    """Extract --skill, --filename, --output-dir from argv.
+
+    Returns:
+        Tuple of (skill, filename, output_dir, remaining_args).
+    """
+    skill = None
+    filename = None
+    output_dir = None
+    remaining = []
+    i = 0
+    while i < len(argv):
+        if argv[i] == "--skill" and i + 1 < len(argv):
+            skill = argv[i + 1]
+            i += 2
+        elif argv[i] == "--filename" and i + 1 < len(argv):
+            filename = argv[i + 1]
+            i += 2
+        elif argv[i] == "--output-dir" and i + 1 < len(argv):
+            output_dir = argv[i + 1]
+            i += 2
+        else:
+            remaining.append(argv[i])
+            i += 1
+
+    if not skill:
+        _emit_error("Missing required argument: --skill", code=2)
+    if not filename:
+        _emit_error("Missing required argument: --filename", code=2)
+
+    return skill, filename, output_dir, remaining  # type: ignore[return-value]
+
+
+def _run_skill(
+    module: str,
+    filename: str,
+    output_dir: str | None,
+    extra_args: list[str],
+    stdin_data: bytes,
+) -> str:
+    """Invoke the skill script as a subprocess and return the created file path."""
+    cmd = [sys.executable, "-m", module, "--filename", filename]
+    if output_dir:
+        cmd.extend(["--output-dir", output_dir])
+    cmd.extend(extra_args)
+
+    result = subprocess.run(cmd, input=stdin_data, capture_output=True)
+
+    if result.returncode != 0:
+        sys.stderr.buffer.write(result.stderr)
+        sys.exit(result.returncode)
+
+    try:
+        output = json.loads(result.stdout.decode("utf-8"))
+    except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+        _emit_error(f"Failed to parse skill output: {exc}")
+
+    if "file" not in output:
+        _emit_error("Skill output missing 'file' field")
+
+    return output["file"]
+
+
+def _verify_file(filepath: str) -> None:
+    """Check that the created file exists and is non-empty."""
+    if not os.path.isfile(filepath):
+        _emit_error(f"Created file not found: {filepath}")
+    if os.path.getsize(filepath) == 0:
+        _emit_error(f"Created file is empty: {filepath}")
+
+
+def _upload_file(filepath: str) -> dict:
+    """Upload the file to the Storage API and return the response dict."""
+    user_id = os.environ.get("AGENT_USER_ID", "default_user")
+    session_id = os.environ.get("AGENT_SESSION_ID", "")
+    host = os.environ.get("AGENT_HOST", "localhost")
+    port = os.environ.get("AGENT_PORT", "8203")
+
+    filename = os.path.basename(filepath)
+    mime = _guess_mime(filepath)
+
+    params = f"user_id={user_id}&is_generated=true&tags=agent-created"
+    if session_id:
+        params += f"&session_id={session_id}"
+
+    url = f"http://{host}:{port}/files/upload?{params}"
+    body, content_type = _multipart_body(filepath, filename, mime)
+
+    req = urllib.request.Request(url, data=body, method="POST")
+    req.add_header("Content-Type", content_type)
+
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        err = e.read().decode("utf-8", errors="replace")
+        _emit_error(f"Server {e.code}: {err}")
+    except urllib.error.URLError as e:
+        _emit_error(
+            f"Cannot connect to server at http://{host}:{port}: {e.reason}"
+        )
+    return {}  # unreachable, but satisfies type checker
+
+
+def _cleanup(filepath: str) -> bool:
+    """Delete the local file. Returns True on success, False on failure."""
+    try:
+        os.remove(filepath)
+        return True
+    except OSError:
+        return False
+
+
+def main() -> None:
+    """Entry point for the create-and-register wrapper."""
+    stdin_data = sys.stdin.buffer.read()
+
+    skill, filename, output_dir, extra_args = _parse_args(sys.argv[1:])
+
+    module = SKILL_MODULE_MAP.get(skill)
+    if module is None:
+        _emit_error(f"Unknown skill: {skill}")
+
+    filepath = _run_skill(module, filename, output_dir, extra_args, stdin_data)  # type: ignore[arg-type]
+
+    _verify_file(filepath)
+
+    upload_result = _upload_file(filepath)
+
+    local_cleaned = _cleanup(filepath)
+
+    mime = _guess_mime(filepath)
+    size_bytes = upload_result.get("size_bytes", 0)
+
+    output = {
+        "status": "success",
+        "file_id": upload_result.get("file_id", ""),
+        "download_url": upload_result.get("download_url", ""),
+        "filename": os.path.basename(filepath),
+        "size_bytes": size_bytes,
+        "mime_type": mime,
+        "local_cleaned": local_cleaned,
+    }
+    print(json.dumps(output))
+
+
+if __name__ == "__main__":
+    main()