π The fast, Pythonic way to build MCP servers and clients.
Accept structured skill metadata and allowed-tools lists (#6292)
Jake Kaplan53965ef05d3e
diff --git a/fastmcp_slim/fastmcp/skills/_snapshot.py b/fastmcp_slim/fastmcp/skills/_snapshot.pyindex 04ba83aff..b36ac6588 100644--- a/fastmcp_slim/fastmcp/skills/_snapshot.py+++ b/fastmcp_slim/fastmcp/skills/_snapshot.py@@ -15,6 +15,9 @@ from yaml.nodes import MappingNodefrom fastmcp.skills.models import MCPSkill, SkillFrontmatterfrom fastmcp.skills.skill import Skill, _validate_limits+from fastmcp.utilities.logging import get_logger++logger = get_logger(__name__)class _FrontmatterLoader(yaml.SafeLoader):@@ -65,7 +68,20 @@ def parse_frontmatter(content: bytes) -> SkillFrontmatter:if not isinstance(value, dict):raise ValueError("frontmatter must be a mapping")_validate_json(value, set())- return SkillFrontmatter.model_validate(value)+ frontmatter = SkillFrontmatter.model_validate(value)+ if any(not isinstance(item, str) for item in (frontmatter.metadata or {}).values()):+ logger.info(+ "Skill %r has non-string metadata values; the Agent Skills spec "+ "expects strings, so they are served as written",+ frontmatter.name,+ )+ if isinstance(frontmatter.allowed_tools, list):+ logger.info(+ "Skill %r lists allowed-tools as a list; the Agent Skills spec "+ "expects a space-separated string, so it is served as written",+ frontmatter.name,+ )+ return frontmatterdef scan_files(root: Path) -> list[Path]:diff --git a/fastmcp_slim/fastmcp/skills/models.py b/fastmcp_slim/fastmcp/skills/models.pyindex f8d100d81..dab7debd3 100644--- a/fastmcp_slim/fastmcp/skills/models.py+++ b/fastmcp_slim/fastmcp/skills/models.py@@ -62,10 +62,18 @@ class SkillFrontmatter(RootModel[dict[str, JsonValue]]):):raise ValueError("description must contain 1-1024 characters")- for field_name in ("license", "allowed-tools"):- value = self.root.get(field_name)- if field_name in self.root and not isinstance(value, str):- raise ValueError(f"{field_name} must be a string")+ if "license" in self.root and not isinstance(self.root["license"], str):+ raise ValueError("license must be a string")++ allowed_tools = self.root.get("allowed-tools")+ if "allowed-tools" in self.root and not (+ isinstance(allowed_tools, str)+ or (+ isinstance(allowed_tools, list)+ and all(isinstance(tool, str) for tool in allowed_tools)+ )+ ):+ raise ValueError("allowed-tools must be a string or a list of strings")compatibility = self.root.get("compatibility")if "compatibility" in self.root and not isinstance(compatibility, str):@@ -73,12 +81,8 @@ class SkillFrontmatter(RootModel[dict[str, JsonValue]]):if isinstance(compatibility, str) and not 1 <= len(compatibility) <= 500:raise ValueError("compatibility must contain 1-500 characters")- metadata = self.root.get("metadata")- if "metadata" in self.root and (- not isinstance(metadata, dict)- or any(not isinstance(value, str) for value in metadata.values())- ):- raise ValueError("metadata must map string keys to string values")+ if "metadata" in self.root and not isinstance(self.root["metadata"], dict):+ raise ValueError("metadata must be a mapping")_reject_non_finite(self.root)return self@@ -100,12 +104,12 @@ class SkillFrontmatter(RootModel[dict[str, JsonValue]]):return cast("str | None", self.root.get("compatibility"))@property- def metadata(self) -> dict[str, str] | None:- return cast("dict[str, str] | None", self.root.get("metadata"))+ def metadata(self) -> dict[str, JsonValue] | None:+ return cast("dict[str, JsonValue] | None", self.root.get("metadata"))@property- def allowed_tools(self) -> str | None:- return cast("str | None", self.root.get("allowed-tools"))+ def allowed_tools(self) -> str | list[str] | None:+ return cast("str | list[str] | None", self.root.get("allowed-tools"))def _reject_non_finite(value: JsonValue) -> None:diff --git a/tests/experimental/skills/test_snapshot.py b/tests/experimental/skills/test_snapshot.pyindex a239a74bb..994ff6b6a 100644--- a/tests/experimental/skills/test_snapshot.py+++ b/tests/experimental/skills/test_snapshot.py@@ -68,7 +68,7 @@ def test_snapshot_retains_backing_paths_for_encoded_nested_files(tmp_path: Path)"custom: !!set {a: null}","custom: &cycle [*cycle]","custom: {a: &x 1, b: *x}",- "metadata: {count: 2}",+ "metadata: [author, version]",],)def test_rejects_lossy_or_invalid_frontmatter(extra: str):diff --git a/tests/skills/test_models.py b/tests/skills/test_models.pyindex a0ac1be5d..df82c9d1f 100644--- a/tests/skills/test_models.py+++ b/tests/skills/test_models.py@@ -90,9 +90,10 @@ def test_frontmatter_rejects_non_finite_extra_values() -> None:[("license", None, "license must be a string"),("compatibility", None, "compatibility must be a string"),- ("metadata", None, "metadata must map"),- ("metadata", {"version": 1}, "metadata must map"),- ("allowed-tools", None, "allowed-tools must be a string"),+ ("metadata", None, "metadata must be a mapping"),+ ("metadata", ["author"], "metadata must be a mapping"),+ ("allowed-tools", None, "allowed-tools must be a string or a list"),+ ("allowed-tools", ["Read", 1], "allowed-tools must be a string or a list"),],)def test_frontmatter_rejects_invalid_known_optional_fields(diff --git a/tests/skills/test_skill.py b/tests/skills/test_skill.pyindex 177d29a44..3da916177 100644--- a/tests/skills/test_skill.py+++ b/tests/skills/test_skill.py@@ -1,6 +1,7 @@from __future__ import annotationsimport hashlib+import loggingimport osimport sysfrom pathlib import Path@@ -71,6 +72,35 @@ def test_from_files_requires_valid_frontmatter():Skill.from_files({"SKILL.md": "# no frontmatter\n"})+def test_from_files_accepts_structured_metadata_and_tool_lists(+ caplog: pytest.LogCaptureFixture,+):+ with caplog.at_level(logging.INFO):+ skill = Skill.from_files(+ {+ "SKILL.md": (+ "---\n"+ "name: nextjs\n"+ "description: Next.js guidance\n"+ "allowed-tools:\n"+ " - Read\n"+ " - Bash(next build)\n"+ "metadata:\n"+ " priority: 5\n"+ " pathPatterns:\n"+ " - 'app/**'\n"+ "---\n"+ "# Next.js\n"+ )+ }+ )++ assert skill.frontmatter.metadata == {"priority": 5, "pathPatterns": ["app/**"]}+ assert skill.frontmatter.allowed_tools == ["Read", "Bash(next build)"]+ assert "'nextjs' has non-string metadata values" in caplog.text+ assert "'nextjs' lists allowed-tools as a list" in caplog.text++def test_from_directory_snapshots_exact_bytes(tmp_path: Path):folder = write_skill(tmp_path)skill = Skill.from_directory(folder)