Skip to content

πŸš€ 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.py
index 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 MappingNode
from fastmcp.skills.models import MCPSkill, SkillFrontmatter
from 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 frontmatter
def scan_files(root: Path) -> list[Path]:
diff --git a/fastmcp_slim/fastmcp/skills/models.py b/fastmcp_slim/fastmcp/skills/models.py
index 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.py
index 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.py
index 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.py
index 177d29a44..3da916177 100644
--- a/tests/skills/test_skill.py
+++ b/tests/skills/test_skill.py
@@ -1,6 +1,7 @@
from __future__ import annotations
import hashlib
+import logging
import os
import sys
from 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)