fast-agent-mcp 0.3.15__py3-none-any.whl → 0.3.16__py3-none-any.whl

fast_agent/cli/commands/go.py

@@ -1,9 +1,10 @@
 """Run an interactive agent directly from the command line."""
 
 import asyncio
+import logging
 import shlex
 import sys
-from typing import Dict, List, Optional
+from pathlib import Path
 
 import typer
 
@@ -11,6 +12,7 @@ from fast_agent import FastAgent
 from fast_agent.agents.llm_agent import LlmAgent
 from fast_agent.cli.commands.server_helpers import add_servers_to_config, generate_server_name
 from fast_agent.cli.commands.url_parser import generate_server_configs, parse_server_urls
+from fast_agent.constants import DEFAULT_AGENT_INSTRUCTION
 from fast_agent.ui.console_display import ConsoleDisplay
 
 app = typer.Typer(
@@ -18,28 +20,60 @@ app = typer.Typer(
     context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
 )
 
-default_instruction = """You are a helpful AI Agent.
+default_instruction = DEFAULT_AGENT_INSTRUCTION
 
-{{serverInstructions}}
 
-The current date is {{currentDate}}."""
+def _set_asyncio_exception_handler(loop: asyncio.AbstractEventLoop) -> None:
+    """Attach a detailed exception handler to the provided event loop."""
+
+    logger = logging.getLogger("fast_agent.asyncio")
+
+    def _handler(_loop: asyncio.AbstractEventLoop, context: dict) -> None:
+        message = context.get("message", "(no message)")
+        task = context.get("task")
+        future = context.get("future")
+        handle = context.get("handle")
+        source_traceback = context.get("source_traceback")
+        exception = context.get("exception")
+
+        details = {
+            "message": message,
+            "task": repr(task) if task else None,
+            "future": repr(future) if future else None,
+            "handle": repr(handle) if handle else None,
+            "source_traceback": [str(frame) for frame in source_traceback]
+            if source_traceback
+            else None,
+        }
+
+        logger.error("Unhandled asyncio error: %s", message)
+        logger.error("Asyncio context: %s", details)
+
+        if exception:
+            logger.exception("Asyncio exception", exc_info=exception)
+
+    try:
+        loop.set_exception_handler(_handler)
+    except Exception:
+        logger = logging.getLogger("fast_agent.asyncio")
+        logger.exception("Failed to set asyncio exception handler")
 
 
 async def _run_agent(
     name: str = "fast-agent cli",
     instruction: str = default_instruction,
-    config_path: Optional[str] = None,
-    server_list: Optional[List[str]] = None,
-    model: Optional[str] = None,
-    message: Optional[str] = None,
-    prompt_file: Optional[str] = None,
-    url_servers: Optional[Dict[str, Dict[str, str]]] = None,
-    stdio_servers: Optional[Dict[str, Dict[str, str]]] = None,
-    agent_name: Optional[str] = "agent",
+    config_path: str | None = None,
+    server_list: list[str] | None = None,
+    model: str | None = None,
+    message: str | None = None,
+    prompt_file: str | None = None,
+    url_servers: dict[str, dict[str, str]] | None = None,
+    stdio_servers: dict[str, dict[str, str]] | None = None,
+    agent_name: str | None = "agent",
+    skills_directory: Path | None = None,
+    shell_runtime: bool = False,
 ) -> None:
     """Async implementation to run an interactive agent."""
-    from pathlib import Path
-
     from fast_agent.mcp.prompts.prompt_load import load_prompt
 
     # Create the FastAgent instance
@@ -50,9 +84,15 @@ async def _run_agent(
         "ignore_unknown_args": True,
         "parse_cli_args": False,  # Don't parse CLI args, we're handling it ourselves
     }
+    if skills_directory is not None:
+        fast_kwargs["skills_directory"] = skills_directory
 
     fast = FastAgent(**fast_kwargs)
 
+    if shell_runtime:
+        await fast.app.initialize()
+        setattr(fast.app.context, "shell_runtime", True)
+
     # Add all dynamic servers to the configuration
     await add_servers_to_config(fast, url_servers)
     await add_servers_to_config(fast, stdio_servers)
@@ -149,15 +189,17 @@ async def _run_agent(
 def run_async_agent(
     name: str,
     instruction: str,
-    config_path: Optional[str] = None,
-    servers: Optional[str] = None,
-    urls: Optional[str] = None,
-    auth: Optional[str] = None,
-    model: Optional[str] = None,
-    message: Optional[str] = None,
-    prompt_file: Optional[str] = None,
-    stdio_commands: Optional[List[str]] = None,
-    agent_name: Optional[str] = None,
+    config_path: str | None = None,
+    servers: str | None = None,
+    urls: str | None = None,
+    auth: str | None = None,
+    model: str | None = None,
+    message: str | None = None,
+    prompt_file: str | None = None,
+    stdio_commands: list[str] | None = None,
+    agent_name: str | None = None,
+    skills_directory: Path | None = None,
+    shell_enabled: bool = False,
 ):
     """Run the async agent function with proper loop handling."""
     server_list = servers.split(",") if servers else None
@@ -240,10 +282,12 @@ def run_async_agent(
             # Instead, create a new loop
             loop = asyncio.new_event_loop()
             asyncio.set_event_loop(loop)
+        _set_asyncio_exception_handler(loop)
     except RuntimeError:
         # No event loop exists, so we'll create one
         loop = asyncio.new_event_loop()
         asyncio.set_event_loop(loop)
+        _set_asyncio_exception_handler(loop)
 
     try:
         loop.run_until_complete(
@@ -258,6 +302,8 @@ def run_async_agent(
                 url_servers=url_servers,
                 stdio_servers=stdio_servers,
                 agent_name=agent_name,
+                skills_directory=skills_directory,
+                shell_runtime=shell_enabled,
             )
         )
     finally:
@@ -280,39 +326,49 @@ def run_async_agent(
 def go(
     ctx: typer.Context,
     name: str = typer.Option("fast-agent", "--name", help="Name for the agent"),
-    instruction: Optional[str] = typer.Option(
+    instruction: str | None = typer.Option(
         None, "--instruction", "-i", help="Path to file or URL containing instruction for the agent"
     ),
-    config_path: Optional[str] = typer.Option(
-        None, "--config-path", "-c", help="Path to config file"
-    ),
-    servers: Optional[str] = typer.Option(
+    config_path: str | None = typer.Option(None, "--config-path", "-c", help="Path to config file"),
+    servers: str | None = typer.Option(
         None, "--servers", help="Comma-separated list of server names to enable from config"
     ),
-    urls: Optional[str] = typer.Option(
+    urls: str | None = typer.Option(
         None, "--url", help="Comma-separated list of HTTP/SSE URLs to connect to"
     ),
-    auth: Optional[str] = typer.Option(
+    auth: str | None = typer.Option(
         None, "--auth", help="Bearer token for authorization with URL-based servers"
     ),
-    model: Optional[str] = typer.Option(
+    model: str | None = typer.Option(
         None, "--model", "--models", help="Override the default model (e.g., haiku, sonnet, gpt-4)"
     ),
-    message: Optional[str] = typer.Option(
+    message: str | None = typer.Option(
         None, "--message", "-m", help="Message to send to the agent (skips interactive mode)"
     ),
-    prompt_file: Optional[str] = typer.Option(
+    prompt_file: str | None = typer.Option(
         None, "--prompt-file", "-p", help="Path to a prompt file to use (either text or JSON)"
     ),
-    npx: Optional[str] = typer.Option(
+    skills_dir: Path | None = typer.Option(
+        None,
+        "--skills-dir",
+        "--skills",
+        help="Override the default skills directory",
+    ),
+    npx: str | None = typer.Option(
         None, "--npx", help="NPX package and args to run as MCP server (quoted)"
     ),
-    uvx: Optional[str] = typer.Option(
+    uvx: str | None = typer.Option(
         None, "--uvx", help="UVX package and args to run as MCP server (quoted)"
     ),
-    stdio: Optional[str] = typer.Option(
+    stdio: str | None = typer.Option(
         None, "--stdio", help="Command to run as STDIO MCP server (quoted)"
     ),
+    shell: bool = typer.Option(
+        False,
+        "--shell",
+        "-x",
+        help="Enable a local shell runtime and expose the execute tool (bash or pwsh).",
+    ),
 ) -> None:
     """
     Run an interactive agent directly from the command line.
@@ -328,6 +384,7 @@ def go(
         fast-agent go --uvx "mcp-server-fetch --verbose"
         fast-agent go --stdio "python my_server.py --debug"
         fast-agent go --stdio "uv run server.py --config=settings.json"
+        fast-agent go --skills /path/to/myskills -x
 
     This will start an interactive session with the agent, using the specified model
     and instruction. It will use the default configuration from fastagent.config.yaml
@@ -341,12 +398,15 @@ def go(
         --auth                Bearer token for authorization with URL-based servers
         --message, -m         Send a single message and exit
         --prompt-file, -p     Use a prompt file instead of interactive mode
+        --skills              Override the default skills folder
+        --shell, -x           Enable local shell runtime
         --npx                 NPX package and args to run as MCP server (quoted)
         --uvx                 UVX package and args to run as MCP server (quoted)
         --stdio               Command to run as STDIO MCP server (quoted)
     """
     # Collect all stdio commands from convenience options
     stdio_commands = []
+    shell_enabled = shell
 
     if npx:
         stdio_commands.append(f"npx {npx}")
@@ -357,6 +417,8 @@ def go(
     if stdio:
         stdio_commands.append(stdio)
 
+    # When shell is enabled we don't add an MCP stdio server; handled inside the agent
+
     # Resolve instruction from file/URL or use default
     resolved_instruction = default_instruction  # Default
     agent_name = "agent"
@@ -396,4 +458,6 @@ def go(
         prompt_file=prompt_file,
         stdio_commands=stdio_commands,
         agent_name=agent_name,
+        skills_directory=skills_dir,
+        shell_enabled=shell_enabled,
     )

fast_agent/cli/constants.py

@@ -19,7 +19,19 @@ GO_SPECIFIC_OPTIONS = {
     "--name",
     "--config-path",
     "-c",
+    "--shell",
+    "-x",
 }
 
 # Known subcommands that should not trigger auto-routing
-KNOWN_SUBCOMMANDS = {"go", "setup", "check", "auth", "bootstrap", "quickstart", "--help", "-h", "--version"}
+KNOWN_SUBCOMMANDS = {
+    "go",
+    "setup",
+    "check",
+    "auth",
+    "bootstrap",
+    "quickstart",
+    "--help",
+    "-h",
+    "--version",
+}

fast_agent/cli/main.py

@@ -62,6 +62,7 @@ def show_welcome() -> None:
     table.add_column("Description", header_style="bold bright_white")
 
     table.add_row("[bold]go[/bold]", "Start an interactive session")
+    table.add_row("go --shell", "Start an interactive session with a local shell tool")
     table.add_row("check", "Show current configuration")
     table.add_row("auth", "Manage OAuth tokens and keyring")
     table.add_row("setup", "Create agent template and configuration")

fast_agent/config.py

@@ -95,18 +95,41 @@ class MCPTimelineSettings(BaseModel):
             raise ValueError("Timeline steps must be greater than zero.")
         return value
 
-    @field_validator("step_seconds", mode="before")
+
+class SkillsSettings(BaseModel):
+    """Configuration for the skills directory override."""
+
+    directory: str | None = None
+
+    model_config = ConfigDict(extra="ignore")
+
+
+class ShellSettings(BaseModel):
+    """Configuration for shell execution behavior."""
+
+    timeout_seconds: int = 90
+    """Maximum seconds to wait for command output before terminating (default: 90s)"""
+
+    warning_interval_seconds: int = 30
+    """Show timeout warnings every N seconds (default: 30s)"""
+
+    model_config = ConfigDict(extra="ignore")
+
+    @field_validator("timeout_seconds", mode="before")
     @classmethod
-    def _coerce_step_seconds(cls, value: Any) -> int:
+    def _coerce_timeout(cls, value: Any) -> int:
+        """Support duration strings like '90s', '2m', '1h'"""
         if isinstance(value, str):
-            value = cls._parse_duration(value)
-        elif isinstance(value, (int, float)):
-            value = int(value)
-        else:
-            raise TypeError("Timeline step duration must be a number of seconds.")
-        if value <= 0:
-            raise ValueError("Timeline step duration must be greater than zero.")
-        return value
+            return MCPTimelineSettings._parse_duration(value)
+        return int(value)
+
+    @field_validator("warning_interval_seconds", mode="before")
+    @classmethod
+    def _coerce_warning_interval(cls, value: Any) -> int:
+        """Support duration strings like '30s', '1m'"""
+        if isinstance(value, str):
+            return MCPTimelineSettings._parse_duration(value)
+        return int(value)
 
 
 class MCPRootSettings(BaseModel):
@@ -591,6 +614,12 @@ class Settings(BaseSettings):
     mcp_timeline: MCPTimelineSettings = MCPTimelineSettings()
     """Display settings for MCP activity timelines."""
 
+    skills: SkillsSettings = SkillsSettings()
+    """Local skills discovery and selection settings."""
+
+    shell_execution: ShellSettings = ShellSettings()
+    """Shell execution timeout and warning settings."""
+
     @classmethod
     def find_config(cls) -> Path | None:
         """Find the config file in the current directory or parent directories."""

fast_agent/constants.py

@@ -11,3 +11,11 @@ FAST_AGENT_REMOVED_METADATA_CHANNEL = "fast-agent-removed-meta"
 # should we have MAX_TOOL_CALLS instead to constrain by number of tools rather than turns...?
 DEFAULT_MAX_ITERATIONS = 20
 """Maximum number of User/Assistant turns to take"""
+
+DEFAULT_AGENT_INSTRUCTION = """You are a helpful AI Agent.
+
+{{serverInstructions}}
+
+{{agentSkills}}
+
+The current date is {{currentDate}}."""

fast_agent/context.py

@@ -26,6 +26,7 @@ from fast_agent.core.logging.events import EventFilter, StreamingExclusionFilter
 from fast_agent.core.logging.logger import LoggingConfig, get_logger
 from fast_agent.core.logging.transport import create_transport
 from fast_agent.mcp_server_registry import ServerRegistry
+from fast_agent.skills import SkillRegistry
 
 if TYPE_CHECKING:
     from fast_agent.core.executor.workflow_signal import SignalWaitCallback
@@ -56,6 +57,7 @@ class Context(BaseModel):
     # Registries
     server_registry: Optional[ServerRegistry] = None
     task_registry: Optional[ActivityRegistry] = None
+    skill_registry: Optional[SkillRegistry] = None
 
     tracer: trace.Tracer | None = None
     _connection_manager: "MCPConnectionManager | None" = None
@@ -145,28 +147,26 @@ async def configure_logger(config: "Settings") -> None:
     python_logger.setLevel(settings.level.upper())
     python_logger.propagate = False
 
-    handler: logging.Handler
+    transport = None
     if settings.type == "console":
+        # Console mode: use the Python logger to emit to stdout and skip additional transport output
         handler = logging.StreamHandler()
-    elif settings.type == "file":
-        log_path = Path(settings.path)
-        if log_path.parent:
-            log_path.parent.mkdir(parents=True, exist_ok=True)
-        handler = logging.FileHandler(log_path)
-    elif settings.type == "none":
-        handler = logging.NullHandler()
+        handler.setLevel(settings.level.upper())
+        handler.setFormatter(logging.Formatter("%(message)s"))
+        python_logger.addHandler(handler)
     else:
-        # For transports that handle output elsewhere (e.g., HTTP), suppress console output.
-        handler = logging.NullHandler()
-
-    handler.setLevel(settings.level.upper())
-    handler.setFormatter(logging.Formatter("%(message)s"))
-    python_logger.addHandler(handler)
+        # For all other modes, rely on transports (file/http/none) and keep the Python logger quiet
+        python_logger.addHandler(logging.NullHandler())
 
     # Use StreamingExclusionFilter to prevent streaming events from flooding logs
     event_filter: EventFilter = StreamingExclusionFilter(min_level=settings.level)
     logger.info(f"Configuring logger with level: {settings.level}")
-    transport = create_transport(settings=settings, event_filter=event_filter)
+    if settings.type == "console":
+        from fast_agent.core.logging.transport import NoOpTransport
+
+        transport = NoOpTransport(event_filter=event_filter)
+    else:
+        transport = create_transport(settings=settings, event_filter=event_filter)
     await LoggingConfig.configure(
         event_filter=event_filter,
         transport=transport,
@@ -206,6 +206,15 @@ async def initialize_context(
     context.config = config
     context.server_registry = ServerRegistry(config=config)
 
+    skills_settings = getattr(config, "skills", None)
+    override_directory = None
+    if skills_settings and getattr(skills_settings, "directory", None):
+        override_directory = Path(skills_settings.directory).expanduser()
+    context.skill_registry = SkillRegistry(
+        base_dir=Path.cwd(),
+        override_directory=override_directory,
+    )
+
     # Configure logging and telemetry
     await configure_otel(config)
     await configure_logger(config)

fast_agent/core/direct_decorators.py

@@ -27,6 +27,7 @@ from fast_agent.agents.workflow.iterative_planner import ITERATIVE_PLAN_SYSTEM_P
 from fast_agent.agents.workflow.router_agent import (
     ROUTING_SYSTEM_INSTRUCTION,
 )
+from fast_agent.skills import SkillManifest, SkillRegistry
 from fast_agent.types import RequestParams
 
 # Type variables for the decorated function
@@ -182,6 +183,9 @@ def _decorator_impl(
     tools: Optional[Dict[str, List[str]]] = None,
     resources: Optional[Dict[str, List[str]]] = None,
     prompts: Optional[Dict[str, List[str]]] = None,
+    skills: SkillManifest | SkillRegistry | Path | str | List[
+        SkillManifest | SkillRegistry | Path | str | None
+    ] | None = None,
     **extra_kwargs,
 ) -> Callable[[Callable[P, Coroutine[Any, Any, R]]], Callable[P, Coroutine[Any, Any, R]]]:
     """
@@ -209,6 +213,7 @@ def _decorator_impl(
             tools=tools,
             resources=resources,
             prompts=prompts,
+            skills=skills,
             model=model,
             use_history=use_history,
             human_input=human_input,
@@ -256,6 +261,7 @@ def agent(
     tools: Optional[Dict[str, List[str]]] = None,
     resources: Optional[Dict[str, List[str]]] = None,
     prompts: Optional[Dict[str, List[str]]] = None,
+    skills: SkillManifest | SkillRegistry | Path | str | None = None,
     model: Optional[str] = None,
     use_history: bool = True,
     request_params: RequestParams | None = None,
@@ -306,6 +312,7 @@ def agent(
         tools=tools,
         resources=resources,
         prompts=prompts,
+        skills=skills,
         api_key=api_key,
     )
 
@@ -321,6 +328,7 @@ def custom(
     tools: Optional[Dict[str, List[str]]] = None,
     resources: Optional[Dict[str, List[str]]] = None,
     prompts: Optional[Dict[str, List[str]]] = None,
+    skills: SkillManifest | SkillRegistry | Path | str | None = None,
     model: Optional[str] = None,
     use_history: bool = True,
     request_params: RequestParams | None = None,
@@ -368,6 +376,7 @@ def custom(
         tools=tools,
         resources=resources,
         prompts=prompts,
+        skills=skills,
     )
 
 

fast_agent/core/fastagent.py

@@ -6,6 +6,7 @@ directly creates Agent instances without proxies.
 
 import argparse
 import asyncio
+import pathlib
 import sys
 from contextlib import asynccontextmanager
 from importlib.metadata import version as get_version
@@ -76,12 +77,14 @@ from fast_agent.core.validation import (
     validate_workflow_references,
 )
 from fast_agent.mcp.prompts.prompt_load import load_prompt
+from fast_agent.skills import SkillManifest, SkillRegistry
 from fast_agent.ui.usage_display import display_usage_report
 
 if TYPE_CHECKING:
     from mcp.client.session import ElicitationFnT
     from pydantic import AnyUrl
 
+    from fast_agent.constants import DEFAULT_AGENT_INSTRUCTION
     from fast_agent.interfaces import AgentProtocol
     from fast_agent.types import PromptMessageExtended
 
@@ -102,6 +105,7 @@ class FastAgent:
         ignore_unknown_args: bool = False,
         parse_cli_args: bool = True,
         quiet: bool = False,  # Add quiet parameter
+        skills_directory: str | pathlib.Path | None = None,
         **kwargs,
     ) -> None:
         """
@@ -119,6 +123,10 @@ class FastAgent:
         """
         self.args = argparse.Namespace()  # Initialize args always
         self._programmatic_quiet = quiet  # Store the programmatic quiet setting
+        self._skills_directory_override = (
+            Path(skills_directory).expanduser() if skills_directory else None
+        )
+        self._default_skill_manifests: List[SkillManifest] = []
 
         # --- Wrap argument parsing logic ---
         if parse_cli_args:
@@ -173,6 +181,10 @@ class FastAgent:
                 default="0.0.0.0",
                 help="Host address to bind to when running as a server with SSE transport",
             )
+            parser.add_argument(
+                "--skills",
+                help="Path to skills directory to use instead of default .claude/skills",
+            )
 
             if ignore_unknown_args:
                 known_args, _ = parser.parse_known_args()
@@ -200,6 +212,14 @@ class FastAgent:
         if self._programmatic_quiet:
             self.args.quiet = True
 
+        # Apply CLI skills directory if not already set programmatically
+        if (
+            self._skills_directory_override is None
+            and hasattr(self.args, "skills")
+            and self.args.skills
+        ):
+            self._skills_directory_override = Path(self.args.skills).expanduser()
+
         self.name = name
         self.config_path = config_path
 
@@ -271,6 +291,7 @@ class FastAgent:
         from collections.abc import Coroutine
         from pathlib import Path
 
+        from fast_agent.skills import SkillManifest, SkillRegistry
         from fast_agent.types import RequestParams
 
         P = ParamSpec("P")
@@ -281,11 +302,12 @@ class FastAgent:
             name: str = "default",
             instruction_or_kwarg: Optional[str | Path | AnyUrl] = None,
             *,
-            instruction: str | Path | AnyUrl = "You are a helpful agent.",
+            instruction: str | Path | AnyUrl = DEFAULT_AGENT_INSTRUCTION,
             servers: List[str] = [],
             tools: Optional[Dict[str, List[str]]] = None,
             resources: Optional[Dict[str, List[str]]] = None,
             prompts: Optional[Dict[str, List[str]]] = None,
+            skills: Optional[List[SkillManifest | SkillRegistry | Path | str | None]] = None,
             model: Optional[str] = None,
             use_history: bool = True,
             request_params: RequestParams | None = None,
@@ -430,6 +452,21 @@ class FastAgent:
         with tracer.start_as_current_span(self.name):
             try:
                 async with self.app.run():
+                    registry = getattr(self.context, "skill_registry", None)
+                    if self._skills_directory_override is not None:
+                        override_registry = SkillRegistry(
+                            base_dir=Path.cwd(),
+                            override_directory=self._skills_directory_override,
+                        )
+                        self.context.skill_registry = override_registry
+                        registry = override_registry
+
+                    default_skills: List[SkillManifest] = []
+                    if registry:
+                        default_skills = registry.load_manifests()
+
+                    self._apply_skills_to_agent_configs(default_skills)
+
                     # Apply quiet mode if requested
                     if quiet_mode:
                         cfg = self.app.context.config
@@ -621,6 +658,69 @@ class FastAgent:
                         except Exception:
                             pass
 
+    def _apply_skills_to_agent_configs(self, default_skills: List[SkillManifest]) -> None:
+        self._default_skill_manifests = list(default_skills)
+
+        for agent_data in self.agents.values():
+            config_obj = agent_data.get("config")
+            if not config_obj:
+                continue
+
+            resolved = self._resolve_skills(config_obj.skills)
+            if not resolved:
+                resolved = list(default_skills)
+            else:
+                resolved = self._deduplicate_skills(resolved)
+
+            config_obj.skill_manifests = resolved
+
+    def _resolve_skills(
+        self,
+        entry: SkillManifest
+        | SkillRegistry
+        | Path
+        | str
+        | List[SkillManifest | SkillRegistry | Path | str | None]
+        | None,
+    ) -> List[SkillManifest]:
+        if entry is None:
+            return []
+        if isinstance(entry, list):
+            manifests: List[SkillManifest] = []
+            for item in entry:
+                manifests.extend(self._resolve_skills(item))
+            return manifests
+        if isinstance(entry, SkillManifest):
+            return [entry]
+        if isinstance(entry, SkillRegistry):
+            try:
+                return entry.load_manifests()
+            except Exception:
+                logger.debug(
+                    "Failed to load skills from registry",
+                    data={"registry": type(entry).__name__},
+                )
+                return []
+        if isinstance(entry, Path):
+            return SkillRegistry.load_directory(entry.expanduser().resolve())
+        if isinstance(entry, str):
+            return SkillRegistry.load_directory(Path(entry).expanduser().resolve())
+
+        logger.debug(
+            "Unsupported skill entry type",
+            data={"type": type(entry).__name__},
+        )
+        return []
+
+    @staticmethod
+    def _deduplicate_skills(manifests: List[SkillManifest]) -> List[SkillManifest]:
+        unique: Dict[str, SkillManifest] = {}
+        for manifest in manifests:
+            key = manifest.name.lower()
+            if key not in unique:
+                unique[key] = manifest
+        return list(unique.values())
+
     def _handle_error(self, e: Exception, error_type: Optional[str] = None) -> None:
         """
         Handle errors with consistent formatting and messaging.