unique-skill-tool 2026.22.0.dev5__tar.gz → 2026.22.0.dev6__tar.gz

{unique_skill_tool-2026.22.0.dev5 → unique_skill_tool-2026.22.0.dev6}/PKG-INFO

@@ -1,13 +1,14 @@
 Metadata-Version: 2.3
 Name: unique-skill-tool
-Version: 2026.22.0.dev5
+Version: 2026.22.0.dev6
 Summary: 
 Author: Fabian Schläpfer
 Author-email: Fabian Schläpfer <fabian@unique.ch>
 License: Proprietary
 Requires-Dist: jinja2>=3.1.0,<4
 Requires-Dist: pydantic>=2.8.2,<3
-Requires-Dist: unique-toolkit>=2026.22.0.dev9,<2026.22.0rc0
+Requires-Dist: python-frontmatter>=1.1.0,<2
+Requires-Dist: unique-toolkit>=2026.22.0.dev11,<2026.22.0rc0
 Requires-Python: >=3.12, <4
 Description-Content-Type: text/markdown
 

{unique_skill_tool-2026.22.0.dev5 → unique_skill_tool-2026.22.0.dev6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_skill_tool"
-version = "2026.22.0.dev5"
+version = "2026.22.0.dev6"
 description = ""
 readme = "README.md"
 license = { text = "Proprietary" }
@@ -11,7 +11,8 @@ requires-python = ">=3.12,<4"
 dependencies = [
     "jinja2>=3.1.0,<4",
     "pydantic>=2.8.2,<3",
-    "unique-toolkit>=2026.22.0.dev9,<2026.22.0rc0",
+    "python-frontmatter>=1.1.0,<2",
+    "unique-toolkit>=2026.22.0.dev11,<2026.22.0rc0",
 ]
 
 [build-system]

{unique_skill_tool-2026.22.0.dev5 → unique_skill_tool-2026.22.0.dev6}/unique_skill_tool/__init__.py

@@ -1,4 +1,5 @@
 from unique_skill_tool.config import SkillToolConfig
+from unique_skill_tool.loader import parse_skill_file
 from unique_skill_tool.schemas import SkillDefinition
 from unique_skill_tool.service import SkillTool
 
@@ -6,4 +7,5 @@ __all__ = [
     "SkillTool",
     "SkillToolConfig",
     "SkillDefinition",
+    "parse_skill_file",
 ]

unique_skill_tool-2026.22.0.dev6/unique_skill_tool/loader.py

@@ -0,0 +1,137 @@
+"""Parse SKILL.md files into ``SkillDefinition`` objects.
+
+Every skill is a folder with a ``SKILL.md`` entrypoint that carries YAML
+frontmatter::
+
+    ---
+    name: summarize-report
+    description: >-
+      Summarize a document into key findings.
+    metadata:           # optional
+      thinking_level: high
+    ---
+
+    # Summarize Report
+    ...instructions...
+
+:func:`parse_skill_file` is the single public entry point: it accepts the raw
+text of one ``SKILL.md`` file and returns a ``SkillDefinition``, or ``None``
+when the file is empty or malformed.
+"""
+
+from __future__ import annotations
+
+from logging import Logger
+
+import frontmatter
+from pydantic import ValidationError
+from unique_toolkit.language_model.schemas import to_reasoning_effort
+
+from unique_skill_tool.schemas import SkillDefinition, SkillMetadata
+
+
+def _parse_frontmatter(*, text: str) -> tuple[dict[str, object], str]:
+    """Split YAML frontmatter from the markdown body.
+
+    Thin wrapper around ``python-frontmatter``. On a YAML parse error, or when
+    the frontmatter parses to a non-mapping (e.g. a top-level YAML list), falls
+    back to ``({}, <original text>)`` so a broken skill file never leaks raw
+    ``---\\nname: ...\\n---`` delimiters into the LLM prompt and never raises.
+    """
+    try:
+        post = frontmatter.loads(text)
+        body = post.content
+        return dict(post.metadata), body
+    except Exception:
+        return {}, text
+
+
+def parse_skill_file(
+    *,
+    file_text: str,
+    content_id: str,
+    source_label: str = "",
+    logger: Logger | None = None,
+) -> SkillDefinition | None:
+    """Build a ``SkillDefinition`` from the raw text of a SKILL.md file.
+
+    Parses YAML frontmatter for ``name`` and ``description``. A malformed
+    ``name`` (non-kebab-case, contains whitespace/punctuation, too long) is
+    rejected by ``SkillDefinition`` validation rather than silently flowing into
+    the OpenAI tool enum where the model could never emit it verbatim.
+
+    Args:
+        file_text: Raw UTF-8 text of the SKILL.md file.
+        content_id: Knowledge-base content ID this skill was loaded from.
+        source_label: Human-readable identifier used only in warning messages
+            so callers can locate the offending file (e.g. a knowledge-base
+            content key or file path).
+        logger: Optional logger for diagnostic warnings. Pass ``None`` to
+            suppress all log output (useful in tests).
+
+    Returns:
+        A validated ``SkillDefinition``, or ``None`` when the file is empty,
+        missing required frontmatter fields, or fails schema validation.
+    """
+    if not file_text.strip():
+        return None
+
+    metadata, body = _parse_frontmatter(text=file_text)
+
+    name = metadata.get("name")
+    description = metadata.get("description")
+
+    if (
+        not isinstance(name, str)
+        or not isinstance(description, str)
+        or not name
+        or not description
+    ):
+        if logger is not None:
+            logger.warning(
+                "Skipping '%s': wrong skill format.",
+                source_label,
+            )
+        return None
+
+    skill_meta: SkillMetadata | None = None
+    raw_meta = metadata.get("metadata")
+    if raw_meta is not None and not isinstance(raw_meta, dict):
+        if logger is not None:
+            logger.warning(
+                "Skill '%s': 'metadata' must be a key-value mapping, got %r — ignoring.",
+                source_label,
+                type(raw_meta).__name__,
+            )
+        raw_meta = None
+    if isinstance(raw_meta, dict):
+        raw_thinking = raw_meta.get("thinking_level")
+        thinking_level = None
+        if raw_thinking is not None:
+            try:
+                thinking_level = to_reasoning_effort(str(raw_thinking))
+            except ValueError:
+                if logger is not None:
+                    logger.warning(
+                        "Skill '%s': unknown thinking_level %r — ignoring.",
+                        source_label,
+                        raw_thinking,
+                    )
+        skill_meta = SkillMetadata(thinking_level=thinking_level)
+
+    try:
+        return SkillDefinition(
+            name=name,
+            description=description,
+            content=body,
+            content_id=content_id,
+            metadata=skill_meta,
+        )
+    except ValidationError as exc:
+        if logger is not None:
+            logger.warning(
+                "Skipping '%s': invalid skill definition: %s",
+                source_label,
+                exc.errors(include_url=False),
+            )
+        return None

{unique_skill_tool-2026.22.0.dev5 → unique_skill_tool-2026.22.0.dev6}/unique_skill_tool/schemas.py

@@ -2,11 +2,27 @@ from __future__ import annotations
 
 from pydantic import BaseModel, Field
 from unique_toolkit._common.pydantic_helpers import get_configuration_dict
+from unique_toolkit.language_model.schemas import ReasoningEffort
 
 SKILL_NAME_PATTERN = r"^[a-z0-9]+(?:-[a-z0-9]+)*$"
 SKILL_NAME_MAX_LENGTH = 64
 
 
+class SkillMetadata(BaseModel):
+    """Typed representation of a skill's SKILL.md ``metadata`` frontmatter block."""
+
+    model_config = get_configuration_dict()
+
+    thinking_level: ReasoningEffort | None = Field(
+        default=None,
+        description=(
+            "Optional reasoning effort hint. The orchestrator uses the highest "
+            "level across all activated skills in a run to set "
+            "``reasoning_effort`` on the LLM call."
+        ),
+    )
+
+
 class SkillDefinition(BaseModel):
     """A skill that the agent can activate via the SkillTool.
 
@@ -36,3 +52,7 @@ class SkillDefinition(BaseModel):
     content_id: str = Field(
         description="Knowledge-base content ID this skill was loaded from.",
     )
+    metadata: SkillMetadata | None = Field(
+        default=None,
+        description="Parsed ``metadata`` block from the skill's SKILL.md frontmatter.",
+    )

{unique_skill_tool-2026.22.0.dev5 → unique_skill_tool-2026.22.0.dev6}/unique_skill_tool/service.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import override
+from typing import cast, override
 
 from jinja2.sandbox import SandboxedEnvironment
 from unique_toolkit.agentic.evaluation.schemas import EvaluationMetricName
@@ -11,14 +11,14 @@ from unique_toolkit.agentic.tools.tool_progress_reporter import ToolProgressRepo
 from unique_toolkit.app.schemas import ChatEvent
 from unique_toolkit.chat.schemas import MessageLog, MessageLogStatus
 from unique_toolkit.language_model.schemas import (
+    REASONING_EFFORT_ORDER,
     LanguageModelFunction,
     LanguageModelToolDescription,
+    ReasoningEffort,
 )
 
 from unique_skill_tool.config import SkillToolConfig
-from unique_skill_tool.schemas import (
-    SkillDefinition,
-)
+from unique_skill_tool.schemas import SkillDefinition
 from unique_skill_tool.utils import (
     format_skill_listing,
     normalize_skill_name,
@@ -46,6 +46,7 @@ class SkillTool(Tool[SkillToolConfig]):
     ) -> None:
         super().__init__(config, event, tool_progress_reporter)
         self._skill_registry: dict[str, SkillDefinition] = {}
+        self._activated_skills: list[SkillDefinition] = []
 
     @property
     def skill_registry(self) -> dict[str, SkillDefinition]:
@@ -55,6 +56,27 @@ class SkillTool(Tool[SkillToolConfig]):
     def skill_registry(self, value: dict[str, SkillDefinition]) -> None:
         self._skill_registry = value
 
+    @property
+    def activated_skills(self) -> list[SkillDefinition]:
+        """All skills successfully activated in this run, in activation order."""
+        return self._activated_skills
+
+    @property
+    def max_thinking_level(self) -> ReasoningEffort | None:
+        """Highest ``thinking_level`` across all skills activated in this run.
+
+        Returns ``None`` when no activated skill declares a ``thinking_level``.
+        The ordering is ``none < minimal < low < medium < high < xhigh``.
+        """
+        levels = [
+            s.metadata.thinking_level
+            for s in self._activated_skills
+            if s.metadata is not None and s.metadata.thinking_level is not None
+        ]
+        if not levels:
+            return None
+        return cast(ReasoningEffort, max(levels, key=REASONING_EFFORT_ORDER.index))
+
     @override
     def display_name(self) -> str:
         return "Skill"
@@ -153,6 +175,7 @@ class SkillTool(Tool[SkillToolConfig]):
                 ),
             )
 
+        self._activated_skills.append(skill)
         self._active_message_log = await self._log_skill_loaded(skill_name=skill_name)
 
         content_parts = [