Merge pull request #57 from ggozad/feature/skill-extras

Add "extras" to skills

Author: ggozad

CHANGELOG.md

@@ -6,6 +6,7 @@
 
 - **`SkillsCapability`**: New pydantic-ai capability wrapping `SkillToolset` + system prompt. Provides a single-line integration path via `Agent(capabilities=[SkillsCapability(...)])`. `SkillToolset` remains available for advanced use cases.
 - **Skill thinking configuration**: Skills can specify `thinking` effort level (`True`, `'low'`, `'medium'`, `'high'`, etc.) to configure reasoning on their sub-agents. Supported across providers via pydantic-ai's unified thinking setting.
+- **Skill extras**: Skills can carry arbitrary non-tool data via `extras: dict[str, Any]`. Useful for exposing utility functions or other resources that the consuming app needs but that aren't agent tools.
 
 ### Fixed
 

docs/skills.md

@@ -142,6 +142,32 @@ Skills automatically discover resource files — any non-script, non-Python file
 - Resolved paths must stay within the skill directory (traversal defense).
 - Files must be text — binary files raise an error.
 
+## Extras
+
+Skills can carry arbitrary non-tool data via `extras`. This is useful for exposing utility functions or other resources that the consuming app needs but that aren't agent tools:
+
+```python
+def calculate_calories(ingredient: str, grams: float) -> float:
+    ...
+
+skill = Skill(
+    metadata=SkillMetadata(name="recipes", description="Recipe search."),
+    instructions="...",
+    tools=[...],
+    extras={"calculate_calories": calculate_calories},
+)
+```
+
+The app discovers skills via [entrypoints](tutorial.md#entrypoint-skills) and accesses extras by name:
+
+```python
+from haiku.skills.discovery import discover_from_entrypoints
+
+skills = {s.metadata.name: s for s in discover_from_entrypoints()}
+skill = skills["recipes"]
+calories = skill.extras["calculate_calories"]("flour", 200)
+```
+
 ## Per-skill state
 
 Entrypoint skills can declare a Pydantic state model. State is passed to tool functions via `RunContext[SkillRunDeps]` and tracked per namespace on the toolset:

haiku/skills/models.py

@@ -85,6 +85,7 @@ class Skill(BaseModel):
     _toolsets: list[AbstractToolset[Any]] = PrivateAttr(default_factory=list)
     _state_type: type[BaseModel] | None = PrivateAttr(default=None)
     _state_namespace: str | None = PrivateAttr(default=None)
+    _extras: dict[str, Any] = PrivateAttr(default_factory=dict)
     _thinking: ThinkingLevel | None = PrivateAttr(default=None)
     _factory: Callable[..., "Skill"] | None = PrivateAttr(default=None)
 
@@ -95,6 +96,7 @@ def __init__(
         toolsets: Sequence[AbstractToolset[Any]] | None = None,
         state_type: type[BaseModel] | None = None,
         state_namespace: str | None = None,
+        extras: dict[str, Any] | None = None,
         thinking: ThinkingLevel | None = None,
         **data: Any,
     ) -> None:
@@ -103,6 +105,7 @@ def __init__(
         self._toolsets = list(toolsets) if toolsets else []
         self._state_type = state_type
         self._state_namespace = state_namespace
+        self._extras = dict(extras) if extras else {}
         self._thinking = thinking
 
     @property
@@ -137,6 +140,14 @@ def state_namespace(self) -> str | None:
     def state_namespace(self, value: str | None) -> None:
         self._state_namespace = value
 
+    @property
+    def extras(self) -> dict[str, Any]:
+        return self._extras
+
+    @extras.setter
+    def extras(self, value: dict[str, Any]) -> None:
+        self._extras = value
+
     @property
     def thinking(self) -> ThinkingLevel | None:
         return self._thinking
@@ -148,8 +159,8 @@ def thinking(self, value: ThinkingLevel | None) -> None:
     def reconfigure(self, **kwargs: Any) -> None:
         """Re-create this skill with new factory arguments.
 
-        Calls the stored factory with the given kwargs and copies
-        tools, toolsets, state_type, state_namespace, and model from the result.
+        Calls the stored factory with the given kwargs and copies all
+        private attributes and model from the result.
         """
         if self._factory is None:
             raise RuntimeError("Skill has no factory — cannot reconfigure")
@@ -158,6 +169,7 @@ def reconfigure(self, **kwargs: Any) -> None:
         self._toolsets = new_skill._toolsets
         self._state_type = new_skill._state_type
         self._state_namespace = new_skill._state_namespace
+        self._extras = new_skill._extras
         self._thinking = new_skill._thinking
         self.model = new_skill.model
 

tests/test_models.py

@@ -326,6 +326,40 @@ def test_state_metadata_partial_namespace_without_type(self):
         )
         assert skill.state_metadata() is None
 
+    def test_extras(self):
+        async def visualize(chunk_id: str) -> list:
+            return []
+
+        meta = SkillMetadata(name="test", description="Test skill.")
+        skill = Skill(
+            metadata=meta,
+            source=SkillSource.FILESYSTEM,
+            extras={"visualize_chunk": visualize},
+        )
+        assert skill.extras["visualize_chunk"] is visualize
+
+    def test_extras_default_empty(self):
+        meta = SkillMetadata(name="test", description="Test skill.")
+        skill = Skill(metadata=meta, source=SkillSource.FILESYSTEM)
+        assert skill.extras == {}
+
+    def test_extras_setter(self):
+        meta = SkillMetadata(name="test", description="Test skill.")
+        skill = Skill(metadata=meta, source=SkillSource.FILESYSTEM)
+        new_extras = {"key": 42}
+        skill.extras = new_extras
+        assert skill.extras == {"key": 42}
+
+    def test_extras_excluded_from_serialization(self):
+        meta = SkillMetadata(name="test", description="Test skill.")
+        skill = Skill(
+            metadata=meta,
+            source=SkillSource.FILESYSTEM,
+            extras={"fn": lambda: None},
+        )
+        data = skill.model_dump()
+        assert "extras" not in data
+
 
 class TestSkillFactory:
     def test_factory_default_none(self):
@@ -415,6 +449,28 @@ def factory(use_b: bool = False) -> Skill:
         assert skill.state_type is StateB
         assert skill.state_namespace == "b"
 
+    def test_reconfigure_replaces_extras(self):
+        extras_a = {"helper": "a"}
+        extras_b = {"helper": "b", "extra": True}
+
+        def factory(use_b: bool = False) -> Skill:
+            return Skill(
+                metadata=SkillMetadata(name="test", description="Test."),
+                source=SkillSource.ENTRYPOINT,
+                extras=extras_b if use_b else extras_a,
+            )
+
+        skill = Skill(
+            metadata=SkillMetadata(name="test", description="Test."),
+            source=SkillSource.ENTRYPOINT,
+            extras=extras_a,
+        )
+        skill._factory = factory
+        assert skill.extras == {"helper": "a"}
+
+        skill.reconfigure(use_b=True)
+        assert skill.extras == {"helper": "b", "extra": True}
+
     def test_reconfigure_replaces_model(self):
         def factory(use_custom: bool = False) -> Skill:
             m = "custom-model" if use_custom else "default-model"