Implement agent skills standard support (#564)

* Update Agent Skills to match agentskills.io standard

- Update XML format to use standard <skill>/<name>/<description>/<location>
  elements instead of custom <agent-skill> attributes
- Use absolute paths for skill locations per specification requirement
- Add read_skill tool for non-ACP contexts (ACP uses read_text_file)
- Parse optional spec fields: license, compatibility, metadata, allowed-tools
- Update format_skills_for_prompt with read_tool_name parameter
- Remove relative_path from SkillManifest (now always uses absolute path)
- Update tests to verify standard compliance

* path handling tests

* multi-directory support

* update tests

* quality

---------

Co-authored-by: Claude <[email protected]>

Author: evalstate

src/fast_agent/acp/server/agent_acp_server.py

@@ -9,7 +9,8 @@
 import uuid
 from dataclasses import dataclass, field
 from importlib.metadata import version as get_version
-from typing import Any, Awaitable, Callable
+from pathlib import Path
+from typing import Any, Awaitable, Callable, Sequence
 
 from acp import Agent as ACPAgent
 from acp import (
@@ -187,7 +188,7 @@ def __init__(
         instance_scope: str,
         server_name: str = "fast-agent-acp",
         server_version: str | None = None,
-        skills_directory_override: str | None = None,
+        skills_directory_override: Sequence[str | Path] | str | Path | None = None,
         permissions_enabled: bool = True,
     ) -> None:
         """

src/fast_agent/acp/slash_commands.py

@@ -15,7 +15,7 @@
 import time
 from importlib.metadata import version as get_version
 from pathlib import Path
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
 
 from acp.schema import (
     AvailableCommand,
@@ -37,6 +37,16 @@
     from mcp.types import ListToolsResult, Tool
 
     from fast_agent.core.fastagent import AgentInstance
+    from fast_agent.skills.registry import SkillRegistry
+
+
+@runtime_checkable
+class WarningAwareAgent(Protocol):
+    @property
+    def warnings(self) -> list[str]: ...
+
+    @property
+    def skill_registry(self) -> "SkillRegistry | None": ...
 
 
 class SlashCommandHandler:
@@ -482,6 +492,10 @@ async def _handle_status(self, arguments: str | None = None) -> str:
         status_lines.extend(["", f"ACP Agent Uptime: {format_duration(uptime_seconds)}"])
         status_lines.extend(["", "## Error Handling"])
         status_lines.extend(self._get_error_handling_report(agent))
+        warning_report = self._get_warning_report(agent)
+        if warning_report:
+            status_lines.append("")
+            status_lines.extend(warning_report)
 
         return "\n".join(status_lines)
 
@@ -1001,6 +1015,31 @@ def _get_error_handling_report(self, agent, max_entries: int = 3) -> list[str]:
 
         return ["_No errors recorded_"]
 
+    def _get_warning_report(self, agent, max_entries: int = 5) -> list[str]:
+        warnings: list[str] = []
+        if isinstance(agent, WarningAwareAgent):
+            warnings.extend(agent.warnings)
+            if agent.skill_registry:
+                warnings.extend(agent.skill_registry.warnings)
+
+        cleaned: list[str] = []
+        seen: set[str] = set()
+        for warning in warnings:
+            message = str(warning).strip()
+            if message and message not in seen:
+                cleaned.append(message)
+                seen.add(message)
+
+        if not cleaned:
+            return []
+
+        lines = ["Warnings:"]
+        for message in cleaned[:max_entries]:
+            lines.append(f"- {message}")
+        if len(cleaned) > max_entries:
+            lines.append(f"- ... ({len(cleaned) - max_entries} more)")
+        return lines
+
     def _context_usage_line(self, summary: ConversationSummary, agent) -> str:
         """Generate a context usage line with token estimation and fallbacks."""
         # Prefer usage accumulator when available (matches enhanced/interactive prompt display)

src/fast_agent/agents/agent_types.py

@@ -40,7 +40,14 @@ class AgentConfig:
     tools: dict[str, list[str]] = field(default_factory=dict)  # filters for tools
     resources: dict[str, list[str]] = field(default_factory=dict)  # filters for resources
     prompts: dict[str, list[str]] = field(default_factory=dict)  # filters for prompts
-    skills: SkillManifest | SkillRegistry | Path | str | None = None
+    skills: (
+        SkillManifest
+        | SkillRegistry
+        | Path
+        | str
+        | list[SkillManifest | SkillRegistry | Path | str | None]
+        | None
+    ) = None
     skill_manifests: list[SkillManifest] = field(default_factory=list, repr=False)
     model: str | None = None
     use_history: bool = True

src/fast_agent/agents/mcp_agent.py

@@ -48,13 +48,15 @@
     is_namespaced_name,
 )
 from fast_agent.mcp.mcp_aggregator import MCPAggregator, NamespacedTool, ServerStatus
-from fast_agent.skills.registry import format_skills_for_prompt
+from fast_agent.skills import SkillManifest
+from fast_agent.skills.registry import SkillRegistry, format_skills_for_prompt
 from fast_agent.tools.elicitation import (
     get_elicitation_tool,
     run_elicitation_form,
     set_elicitation_input_callback,
 )
 from fast_agent.tools.shell_runtime import ShellRuntime
+from fast_agent.tools.skill_reader import SkillReader
 from fast_agent.types import PromptMessageExtended, RequestParams
 from fast_agent.ui import console
 
@@ -69,7 +71,6 @@
 
     from fast_agent.context import Context
     from fast_agent.llm.usage_tracking import UsageAccumulator
-    from fast_agent.skills import SkillManifest
 
 
 class McpAgent(ABC, ToolAgent):
@@ -109,17 +110,23 @@ def __init__(
         self.executor = context.executor if context else None
         self.logger = get_logger(f"{__name__}.{self._name}")
         manifests: list[SkillManifest] = list(getattr(self.config, "skill_manifests", []) or [])
-        if not manifests and context and getattr(context, "skill_registry", None):
+        if not manifests and context and context.skill_registry:
             try:
                 manifests = list(context.skill_registry.load_manifests())  # type: ignore[assignment]
             except Exception:
                 manifests = []
 
-        self._skill_manifests = list(manifests)
-        self._skill_map: dict[str, SkillManifest] = {
-            manifest.name: manifest for manifest in manifests
-        }
-        self._agent_skills_warning_shown = False
+        self._skill_manifests: list[SkillManifest] = []
+        self._skill_map: dict[str, SkillManifest] = {}
+        self._skill_reader: SkillReader | None = None
+        self.set_skill_manifests(manifests)
+        self.skill_registry: SkillRegistry | None = None
+        if isinstance(self.config.skills, SkillRegistry):
+            self.skill_registry = self.config.skills
+        elif self.config.skills is None and context and context.skill_registry:
+            self.skill_registry = context.skill_registry
+        self._warnings: list[str] = []
+        self._warning_messages_seen: set[str] = set()
         shell_flag_requested = bool(context and getattr(context, "shell_runtime", False))
         skills_configured = bool(self._skill_manifests)
         self._shell_runtime_activation_reason: str | None = None
@@ -285,21 +292,12 @@ async def _apply_instruction_templates(self) -> None:
         self.instruction = await self._instruction_builder.build()
 
         # Warn if skills configured but placeholder missing
-        if (
-            self._skill_manifests
-            and not self._agent_skills_warning_shown
-            and "{{agentSkills}}" not in self._instruction_builder.template
-        ):
+        if self._skill_manifests and "{{agentSkills}}" not in self._instruction_builder.template:
             warning_message = (
                 "Agent skills are configured but the system prompt does not include {{agentSkills}}. "
                 "Skill descriptions will not be added to the system prompt."
             )
-            self.logger.warning(warning_message)
-            try:
-                console.console.print(f"[yellow]{warning_message}[/yellow]")
-            except Exception:  # pragma: no cover - console fallback
-                pass
-            self._agent_skills_warning_shown = True
+            self._record_warning(warning_message)
 
         # Update default request params to match
         if self._default_request_params:
@@ -322,8 +320,36 @@ async def _resolve_server_instructions(self) -> str:
 
     async def _resolve_agent_skills(self) -> str:
         """Resolver for {{agentSkills}} placeholder."""
-        self._agent_skills_warning_shown = True
-        return format_skills_for_prompt(self._skill_manifests)
+        # Determine which tool to reference in the preamble
+        # ACP context provides read_text_file; otherwise use read_skill
+        if self._filesystem_runtime and hasattr(self._filesystem_runtime, "tools"):
+            read_tool_name = "read_text_file"
+        else:
+            read_tool_name = "read_skill"
+        return format_skills_for_prompt(self._skill_manifests, read_tool_name=read_tool_name)
+
+    def set_skill_manifests(self, manifests: Sequence[SkillManifest]) -> None:
+        self._skill_manifests = list(manifests)
+        self._skill_map = {manifest.name: manifest for manifest in self._skill_manifests}
+        if self._skill_manifests:
+            self._skill_reader = SkillReader(self._skill_manifests, self.logger)
+        else:
+            self._skill_reader = None
+
+    def _record_warning(self, message: str) -> None:
+        if message in self._warning_messages_seen:
+            return
+        self._warning_messages_seen.add(message)
+        self._warnings.append(message)
+        self.logger.warning(message)
+        try:
+            console.console.print(f"[yellow]{message}[/yellow]")
+        except Exception:  # pragma: no cover - console fallback
+            pass
+
+    @property
+    def warnings(self) -> list[str]:
+        return list(self._warnings)
 
     def set_instruction_context(self, context: dict[str, str]) -> None:
         """
@@ -585,6 +611,10 @@ async def call_tool(
                             arguments, tool_use_id
                         )
 
+        # Check skill reader (non-ACP context with skills)
+        if self._skill_reader and name == "read_skill":
+            return await self._skill_reader.execute(arguments)
+
         # Fall back to shell runtime
         if self._shell_runtime.tool and name == self._shell_runtime.tool.name:
             return await self._shell_runtime.execute(arguments)
@@ -909,12 +939,16 @@ async def run_tools(self, request: PromptMessageExtended) -> PromptMessageExtend
                 and hasattr(self._filesystem_runtime, "tools")
                 and any(tool.name == tool_name for tool in self._filesystem_runtime.tools)
             )
+            is_skill_reader_tool = (
+                self._skill_reader and self._skill_reader.enabled and tool_name == "read_skill"
+            )
 
             tool_available = (
                 tool_name == HUMAN_INPUT_TOOL_NAME
                 or (self._shell_runtime.tool and tool_name == self._shell_runtime.tool.name)
                 or is_external_runtime_tool
                 or is_filesystem_runtime_tool
+                or is_skill_reader_tool
                 or namespaced_tool is not None
                 or local_tool is not None
                 or candidate_namespaced_tool is not None
@@ -1208,6 +1242,12 @@ async def list_tools(self) -> ListToolsResult:
                 if fs_tool and fs_tool.name not in existing_names:
                     merged_tools.append(fs_tool)
                     existing_names.add(fs_tool.name)
+        elif self._skill_reader and self._skill_reader.enabled:
+            # Non-ACP context with skills: provide read_skill tool
+            skill_tool = self._skill_reader.tool
+            if skill_tool.name not in existing_names:
+                merged_tools.append(skill_tool)
+                existing_names.add(skill_tool.name)
 
         if self.config.human_input:
             human_tool = getattr(self, "_human_input_tool", None)

src/fast_agent/cli/commands/check_config.py

@@ -169,7 +169,7 @@ def get_config_summary(config_path: Path | None) -> dict:
             "step_seconds": default_settings.mcp_timeline.step_seconds,
         },
         "mcp_servers": [],
-        "skills_directory": None,
+        "skills_directories": None,
     }
 
     if not config_path:
@@ -282,9 +282,11 @@ def get_config_summary(config_path: Path | None) -> dict:
         # Skills directory override
         skills_cfg = config.get("skills") if isinstance(config, dict) else None
         if isinstance(skills_cfg, dict):
-            directory_value = skills_cfg.get("directory")
-            if isinstance(directory_value, str) and directory_value.strip():
-                result["skills_directory"] = directory_value.strip()
+            directory_value = skills_cfg.get("directories")
+            if isinstance(directory_value, list):
+                cleaned = [str(value).strip() for value in directory_value if str(value).strip()]
+                if cleaned:
+                    result["skills_directories"] = cleaned
 
     except Exception as e:
         # File exists but has parse errors
@@ -402,10 +404,14 @@ def _relative_path(path: Path) -> str:
         except ValueError:
             return str(path)
 
-    skills_override = config_summary.get("skills_directory")
-    override_directory = Path(skills_override).expanduser() if skills_override else None
-    skills_registry = SkillRegistry(base_dir=cwd, override_directory=override_directory)
-    skills_dir = skills_registry.directory
+    skills_override = config_summary.get("skills_directories")
+    override_directories = (
+        [Path(entry).expanduser() for entry in skills_override]
+        if isinstance(skills_override, list)
+        else None
+    )
+    skills_registry = SkillRegistry(base_dir=cwd, directories=override_directories)
+    skills_dirs = skills_registry.directories
     skills_manifests, skill_errors = skills_registry.load_manifests_with_errors()
 
     # Logger Settings panel with two-column layout
@@ -634,8 +640,13 @@ def format_provider_row(provider, status):
             console.print(servers_table)
 
     _print_section_header("Agent Skills", color="blue")
-    if skills_dir:
-        console.print(f"Directory: [green]{_relative_path(skills_dir)}[/green]")
+    if skills_dirs:
+        if len(skills_dirs) == 1:
+            console.print(f"Directory: [green]{_relative_path(skills_dirs[0])}[/green]")
+        else:
+            console.print("Directories:")
+            for directory in skills_dirs:
+                console.print(f"- [green]{_relative_path(directory)}[/green]")
 
         if skills_manifests or skill_errors:
             skills_table = Table(show_header=True, box=None)
@@ -650,11 +661,7 @@ def _truncate(text: str, length: int = 70) -> str:
                 return text[: length - 3] + "..."
 
             for manifest in skills_manifests:
-                try:
-                    relative_source = manifest.path.parent.relative_to(skills_dir)
-                    source_display = str(relative_source) if relative_source != Path(".") else "."
-                except ValueError:
-                    source_display = _relative_path(manifest.path.parent)
+                source_display = _relative_path(manifest.path.parent)
 
                 skills_table.add_row(
                     manifest.name,
@@ -668,11 +675,7 @@ def _truncate(text: str, length: int = 70) -> str:
                 source_display = "[dim]n/a[/dim]"
                 if error_path_str:
                     error_path = Path(error_path_str)
-                    try:
-                        relative_error = error_path.parent.relative_to(skills_dir)
-                        source_display = str(relative_error) if relative_error != Path(".") else "."
-                    except ValueError:
-                        source_display = _relative_path(error_path.parent)
+                    source_display = _relative_path(error_path.parent)
                 message = error.get("error", "Failed to parse skill manifest")
                 skills_table.add_row(
                     "[red]—[/red]",
@@ -683,19 +686,11 @@ def _truncate(text: str, length: int = 70) -> str:
 
             console.print(skills_table)
         else:
-            console.print("[yellow]No skills found in the directory[/yellow]")
+            console.print("[yellow]No skills found in the configured directories[/yellow]")
     else:
-        if skills_registry.override_failed and override_directory:
-            console.print(
-                f"[red]Override directory not found:[/red] {_relative_path(override_directory)}"
-            )
-            console.print(
-                "[yellow]Default folders were not loaded because the override failed[/yellow]"
-            )
-        else:
-            console.print(
-                "[dim]Agent Skills not configured. Go to https://fast-agent.ai/agents/skills/[/dim]"
-            )
+        console.print(
+            "[dim]Agent Skills not configured. Go to https://fast-agent.ai/agents/skills/[/dim]"
+        )
 
     # Show help tips
     if config_status == "not_found" or secrets_status == "not_found":

src/fast_agent/config.py

@@ -105,7 +105,7 @@ def _coerce_steps(cls, value: Any) -> int:
 class SkillsSettings(BaseModel):
     """Configuration for the skills directory override."""
 
-    directory: str | None = None
+    directories: list[str] | None = None
 
     model_config = ConfigDict(extra="ignore")
 

src/fast_agent/constants.py

@@ -38,4 +38,9 @@
 
 The current date is {{currentDate}}."""
 
+DEFAULT_SKILLS_PATHS = [
+    ".fast-agent/skills",
+    ".claude/skills",
+]
+
 CONTROL_MESSAGE_SAVE_HISTORY = "***SAVE_HISTORY"