models

src/personal_mcp/registry/models/skill.py

@@ -4,6 +4,7 @@ from pathlib import PurePosixPath
 import yaml
 from pydantic import Field
 from pydantic import field_validator
+from pydantic import model_validator
 
 from .common import SEMVER_RE
 from .common import SKILL_ID_RE
@@ -107,6 +108,18 @@ class SkillFrontmatter(StrictFrozenModel):
             raise ValueError("name must not contain reserved words anthropic or claude")
         return value
 
+    @classmethod
+    def from_raw_yaml(cls, raw: str | None) -> "SkillFrontmatter":
+        if raw is None:
+            raise ValueError("missing YAML frontmatter")
+        try:
+            data = yaml.safe_load(raw)
+        except yaml.YAMLError as e:
+            raise ValueError(f"invalid YAML in frontmatter: {e}") from e
+        if not isinstance(data, dict):
+            raise TypeError("frontmatter must parse to an object")
+        return cls.model_validate(data)
+
 
 class StoredSkillReference(StrictFrozenModel):
     """Structured representation of a skill reference markdown document."""
@@ -124,15 +137,40 @@ class StoredSkill(StrictFrozenModel):
     relpath: PurePosixPath
     content: str
     frontmatter: SkillFrontmatter
-    references: dict[str, StoredSkillReference] = Field(default_factory=dict)
+    references: Mapping[str, StoredSkillReference] = Field(default_factory=frozen_mapping)
 
     @field_validator("frontmatter", mode="before")
     @classmethod
-    def parse_frontmatter_yaml(cls, value: str | None):
-        if value is None:
-            return None
-        try:
-            data = yaml.safe_load(value)
-        except yaml.YAMLError as e:
-            raise ValueError(f"invalid YAML in frontmatter: {e}") from e
-        return SkillFrontmatter.model_validate(data)
+    def parse_frontmatter_yaml(cls, value: SkillFrontmatter | str | None) -> SkillFrontmatter:
+        if isinstance(value, SkillFrontmatter):
+            return value
+        return SkillFrontmatter.from_raw_yaml(value)
+
+    @field_validator("references", mode="before")
+    @classmethod
+    def freeze_references(cls, value: Mapping[str, StoredSkillReference] | None) -> Mapping[str, StoredSkillReference]:
+        return frozen_mapping(value)
+
+    @model_validator(mode="after")
+    def validate_contract(self) -> "StoredSkill":
+        parts = self.relpath.parts
+        if len(parts) < 3 or parts[0] != "skills":
+            raise ValueError("skill relpath must be under skills/<slug>/")
+
+        skill_dir_name = parts[1]
+        if self.frontmatter.name != skill_dir_name:
+            raise ValueError("frontmatter name must exactly match skill directory name")
+        if self.frontmatter.x_personal_mcp.id != self.frontmatter.name:
+            raise ValueError("x-personal-mcp.id must exactly match name")
+
+        expected_capability = f"resource://skills/{self.frontmatter.name}/document"
+        if expected_capability not in self.frontmatter.x_personal_mcp.capabilities:
+            raise ValueError(f"capabilities must include {expected_capability}")
+
+        if self.skill_id != self.frontmatter.x_personal_mcp.id:
+            raise ValueError("skill_id must exactly match x-personal-mcp.id")
+
+        for ref_id, ref in self.references.items():
+            if ref.ref_id != ref_id:
+                raise ValueError(f"reference key must match ref_id: {ref_id}")
+        return self