unique-skill-tool 2026.16.0__tar.gz

unique_skill_tool-2026.16.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.3
+Name: unique-skill-tool
+Version: 2026.16.0
+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>=1.47.7,<2
+Requires-Python: >=3.12, <4
+Description-Content-Type: text/markdown
+
+# unique_skill_tool

unique_skill_tool-2026.16.0/README.md

@@ -0,0 +1 @@
+# unique_skill_tool

unique_skill_tool-2026.16.0/pyproject.toml

@@ -0,0 +1,92 @@
+[project]
+name = "unique_skill_tool"
+version = "2026.16.0"
+description = ""
+readme = "README.md"
+license = { text = "Proprietary" }
+authors = [
+    { name = "Fabian Schläpfer", email = "fabian@unique.ch" },
+]
+requires-python = ">=3.12,<4"
+dependencies = [
+    "jinja2>=3.1.0,<4",
+    "pydantic>=2.8.2,<3",
+    "unique-toolkit>=1.47.7,<2",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.14,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = ""
+
+[tool.uv]
+exclude-newer = "2 weeks"
+
+[tool.uv.exclude-newer-package]
+"unique-toolkit" = false
+
+[dependency-groups]
+dev = []
+
+[tool.uv.sources]
+unique-toolkit = { workspace = true }
+
+[tool.poe.tasks]
+lint = "ruff check ."
+lint-fix = "ruff check . --fix"
+format = "ruff format ."
+test = "pytest"
+typecheck = "basedpyright"
+depcheck = "deptry ."
+coverage = "pytest --cov=unique_skill_tool --cov-report=term-missing"
+ci-typecheck = { shell = "bash $(git rev-parse --show-toplevel)/.github/scripts/dev.sh typecheck" }
+ci-coverage = { shell = "bash $(git rev-parse --show-toplevel)/.github/scripts/dev.sh coverage" }
+
+[tool.deptry]
+known_first_party = ["unique_skill_tool"]
+extend_exclude = ["tests"]
+
+[tool.deptry.per_rule_ignores]
+DEP002 = ["unique-toolkit"]
+DEP003 = ["unique_toolkit"]
+
+[tool.basedpyright]
+typeCheckingMode = "recommended"
+include = ["unique_skill_tool"]
+exclude = ["**/tests/**", "**/test_*.py"]
+
+# Any-cascade: originates from jinja2 and LanguageModelFunction.arguments in
+# unique_toolkit; not fixable from this package.
+reportAny = "none"
+reportUnknownVariableType = "none"
+reportUnknownMemberType = "none"
+reportUnknownArgumentType = "none"
+
+# unique_toolkit submodules ship no inline stubs; suppressed identically to toolkit.
+reportMissingTypeStubs = "none"
+
+# base-class/mixin patterns make per-attribute annotations impractical.
+reportUnannotatedClassAttribute = "none"
+
+[tool.pytest.ini_options]
+addopts = "--strict-markers --import-mode=importlib"
+asyncio_mode = "auto"
+markers = [
+    "ai: AI-authored or AI-generated tests",
+    "asyncio: asyncio tests",
+    "integration: integration tests that require API access or credentials",
+    "serial: tests that must run serially",
+    "unit: unit tests",
+    "verified: AI-generated tests with human verification",
+]
+filterwarnings = [
+    "ignore::DeprecationWarning",
+]
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+extend-select = ["I"]

unique_skill_tool-2026.16.0/unique_skill_tool/__init__.py

@@ -0,0 +1,9 @@
+from unique_skill_tool.config import SkillToolConfig
+from unique_skill_tool.schemas import SkillDefinition
+from unique_skill_tool.service import SkillTool
+
+__all__ = [
+    "SkillTool",
+    "SkillToolConfig",
+    "SkillDefinition",
+]

unique_skill_tool-2026.16.0/unique_skill_tool/config.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import Field
+from unique_toolkit._common.pydantic.rjsf_tags import RJSFMetaTag
+from unique_toolkit.agentic.tools.schemas import BaseToolConfig
+
+from unique_skill_tool.prompts import (
+    DEFAULT_TOOL_DESCRIPTION,
+    DEFAULT_TOOL_DESCRIPTION_FOR_SYSTEM_PROMPT,
+    DEFAULT_TOOL_DESCRIPTION_FOR_USER_PROMPT,
+    DEFAULT_TOOL_PARAMETER_ARGUMENTS_DESCRIPTION,
+    DEFAULT_TOOL_PARAMETER_SKILL_NAME_DESCRIPTION,
+    DEFAULT_TOOL_SYSTEM_REMINDER_FOR_USER_MESSAGE,
+)
+
+CHARS_PER_TOKEN = 4
+DEFAULT_CHAR_BUDGET = 8_000
+SKILL_BUDGET_CONTEXT_PERCENT = 0.03
+MAX_LISTING_DESC_CHARS = 250
+
+
+class SkillToolConfig(BaseToolConfig):
+    """Configuration for the Skill tool."""
+
+    enabled: Annotated[
+        bool,
+        RJSFMetaTag.BooleanWidget.checkbox(
+            help=(
+                "Master switch for the Skill tool. When disabled, the tool "
+                "is not registered and skills are not available to the agent."
+            ),
+        ),
+    ] = Field(
+        default=False,
+        description="Enable the Skill tool.",
+    )
+
+    tool_description: Annotated[
+        str,
+        RJSFMetaTag.StringWidget.textarea(rows=3),
+    ] = Field(
+        default=DEFAULT_TOOL_DESCRIPTION,
+        description="The LLM-facing description of the Skill tool.",
+    )
+
+    tool_description_for_system_prompt: Annotated[
+        str,
+        RJSFMetaTag.StringWidget.textarea(rows=7),
+    ] = Field(
+        default=DEFAULT_TOOL_DESCRIPTION_FOR_SYSTEM_PROMPT,
+        description="Instructions for the system prompt explaining how to use skills.",
+    )
+
+    tool_description_for_user_prompt: Annotated[
+        str,
+        RJSFMetaTag.StringWidget.textarea(rows=5),
+    ] = Field(
+        default=DEFAULT_TOOL_DESCRIPTION_FOR_USER_PROMPT,
+        description=(
+            "Optional extra text appended to the per-turn user-message injection.."
+        ),
+    )
+
+    tool_system_reminder_for_user_message: Annotated[
+        str,
+        RJSFMetaTag.StringWidget.textarea(rows=5),
+    ] = Field(
+        default=DEFAULT_TOOL_SYSTEM_REMINDER_FOR_USER_MESSAGE,
+        description=(
+            "Per-turn ``<system-reminder>`` template injected into the "
+            "user message. Jinja variable ``skill_list`` is rendered "
+            "with the budget-aware skill listing. Refreshed every loop "
+            "iteration."
+        ),
+    )
+
+    tool_parameter_description_skill_name: Annotated[
+        str,
+        RJSFMetaTag.StringWidget.textarea(rows=2),
+    ] = Field(
+        default=DEFAULT_TOOL_PARAMETER_SKILL_NAME_DESCRIPTION,
+        description="The description of the 'skill_name' parameter.",
+    )
+
+    tool_parameter_description_arguments: Annotated[
+        str,
+        RJSFMetaTag.StringWidget.textarea(rows=2),
+    ] = Field(
+        default=DEFAULT_TOOL_PARAMETER_ARGUMENTS_DESCRIPTION,
+        description="The description of the 'arguments' parameter.",
+    )
+
+    scope_ids: list[str] = Field(
+        default_factory=list,
+        title="Scope IDs",
+        description=(
+            "Knowledge base scope IDs to load skills from. Only the "
+            "scopes listed here are queried — sub-folders are not "
+            "traversed automatically, so add each scope you want "
+            "searched explicitly."
+        ),
+    )
+
+    max_listing_desc_chars: int = Field(
+        default=MAX_LISTING_DESC_CHARS,
+        ge=20,
+        le=1000,
+        description=(
+            "Per-entry hard cap on skill descriptions in the listing. "
+            "The listing is for discovery only — the tool loads full "
+            "content on invoke."
+        ),
+    )
+
+    skill_budget_context_percent: float = Field(
+        default=SKILL_BUDGET_CONTEXT_PERCENT,
+        ge=0.01,
+        le=0.15,
+        description="Percentage of context window allocated for the skill listing.",
+    )

unique_skill_tool-2026.16.0/unique_skill_tool/examples/README.md

@@ -0,0 +1,51 @@
+# Example Skill Files
+
+These `.md` files are example skills for the SkillTool. To use them:
+
+1. Create one or more **scopes** in the knowledge base (or use existing ones).
+2. Upload these `.md` files directly into those scopes. Sub-folders are
+   not traversed automatically — add each sub-folder's scope ID to
+   `scope_ids` if you want its skills loaded.
+3. Add every scope ID to `skill_tool_config.scope_ids` in the space
+   configuration (the field accepts a list — click "Add Item" for each).
+4. Set `skill_tool_config.enabled` to `true`.
+
+The SkillTool fetches all `.md` files from the configured scopes. Only the
+scopes listed in `scope_ids` are queried — sub-folders are not traversed
+automatically, so add each scope you want searched explicitly. Per-user
+folder permissions are enforced by the backend ACL, so users only see
+skills in folders they can access.
+
+## File format
+
+Each skill file uses **YAML frontmatter** to declare its metadata:
+
+```markdown
+---
+name: summarize-document
+description: >-
+  Structured document summarization with executive summary.
+  Use when the user asks to summarize or get an overview of a document.
+---
+
+# Summarize Document
+
+You are an expert document summarizer...
+```
+
+| Frontmatter key | Required | Purpose                                                     |
+|-----------------|----------|-------------------------------------------------------------|
+| `name`          | Yes      | Skill identifier (defaults to file name without `.md`)      |
+| `description`   | Yes      | Short description shown to the LLM in the skill listing — include guidance on when to activate this skill |
+
+Everything below the frontmatter is the **skill body** — the full prompt
+instructions injected when the agent invokes the skill.
+
+## Included examples
+
+| File                      | Purpose                                    |
+|---------------------------|--------------------------------------------|
+| `analyze-data.md`         | Tabular / numerical data analysis          |
+| `analyze-factsheet.md`    | Factsheet data analysis                    |
+| `draft-email.md`          | Professional email drafting                |
+| `review-contract.md`      | Contract risk analysis and review          |

unique_skill_tool-2026.16.0/unique_skill_tool/examples/analyze-data.md

@@ -0,0 +1,46 @@
+---
+name: analyze-data
+description: >-
+  Tabular and numerical data analysis with descriptive statistics and insights.
+  Use when the user provides data, tables, CSVs, or numbers and wants analysis.
+---
+
+# Analyze Data
+
+You are a data analysis expert. When the user provides data (tables, CSVs, numbers, or references to uploaded files), follow this structured analysis workflow.
+
+## Steps
+
+1. **Understand the data**: Identify columns, data types, time ranges, and units.
+2. **Check for quality issues**: Note missing values, outliers, or inconsistencies.
+3. **Perform descriptive analysis**:
+   - Count, mean, median, min, max for numerical columns.
+   - Frequency counts for categorical columns.
+   - Time-based trends if dates are present.
+4. **Identify patterns**: Correlations, groupings, anomalies, or trends.
+5. **Answer the user's question** using the analysis as evidence.
+
+## Output Format
+
+### Data Overview
+| Property | Value |
+|----------|-------|
+| Rows     | ...   |
+| Columns  | ...   |
+| Time range | ... |
+
+### Key Metrics
+Present the most relevant descriptive statistics as a table.
+
+### Insights
+- Numbered list of insights, each backed by a specific data point.
+
+### Recommendations
+Actionable suggestions based on the analysis.
+
+## Rules
+
+- Always show your work — include the numbers that support each insight.
+- If the data is ambiguous, state your assumptions explicitly.
+- Use tables for structured output wherever possible.
+- When referencing uploaded files, use `[sourceN]` citations.

unique_skill_tool-2026.16.0/unique_skill_tool/examples/analyze-factsheet.md

@@ -0,0 +1,58 @@
+---
+name: analyze-factsheet
+description: Financial factsheet analysis with key metrics extraction and investment rationale
+---
+
+# Analyze Financial Factsheet
+
+You are a financial analysis specialist. Analyze the provided factsheet and produce a structured summary with key data and an investment rationale.
+
+## Steps
+
+1. Read the full factsheet thoroughly.
+2. Identify the **fund name**, **asset class**, **currency**, **benchmark**, and **reporting date**.
+3. Extract key financial metrics (performance, fees, risk indicators, holdings).
+4. Assess the fund's positioning, strategy, and market context.
+5. Formulate an investment rationale based on the extracted data.
+
+## Output Format
+
+### Overall Summary
+A concise 3-5 sentence overview covering the fund's objective, strategy, current positioning, and recent performance context.
+
+### Key Data
+| Metric | Value |
+|--------|-------|
+| Fund Name | ... |
+| Asset Class | ... |
+| Currency | ... |
+| Benchmark | ... |
+| Inception Date | ... |
+| Fund Size (AUM) | ... |
+| Ongoing Charges (TER) | ... |
+| YTD Performance | ... |
+| 1Y Performance | ... |
+| 3Y Performance (ann.) | ... |
+| 5Y Performance (ann.) | ... |
+| Volatility | ... |
+| Sharpe Ratio | ... |
+| Max Drawdown | ... |
+| Top Holdings | ... |
+| Sector Allocation | ... |
+
+Omit rows where data is not available in the factsheet.
+
+### Investment Rationale
+A structured assessment covering:
+- **Strengths** — what makes this fund attractive (e.g., consistent outperformance, low fees, diversification).
+- **Risks** — potential concerns (e.g., concentration, volatility, sector/geographic exposure).
+- **Suitability** — what type of investor or portfolio this fund fits (e.g., growth-oriented, income-seeking, conservative).
+
+## Rules
+
+- This is NOT investment advice — clearly state this disclaimer at the top of your output.
+- Only report data explicitly stated in the factsheet — do not invent or estimate figures.
+- Use `[sourceN]` citations when referencing factsheet content.
+- If performance figures are provided for multiple share classes, note which class is being reported.
+- If the factsheet is not in English, provide the analysis in the factsheet's language.
+- Flag any missing critical data points (e.g., no risk metrics, no benchmark comparison).

unique_skill_tool-2026.16.0/unique_skill_tool/examples/draft-email.md

@@ -0,0 +1,46 @@
+---
+name: draft-email
+description: >-
+  Professional email drafting with appropriate tone and structure.
+  Use when the user wants to write, compose, or draft an email.
+---
+
+# Draft Email
+
+You are a professional communication specialist. Help the user draft a clear, well-structured email.
+
+## Steps
+
+1. Ask for or identify from context:
+   - **Recipient(s)** and their role/relationship
+   - **Purpose** of the email (request, update, follow-up, introduction, etc.)
+   - **Key points** to communicate
+   - **Tone** (formal, semi-formal, casual)
+2. Draft the email following the structure below.
+3. Review for clarity, brevity, and appropriate tone.
+
+## Output Format
+
+```
+Subject: [Clear, specific subject line]
+
+[Greeting],
+
+[Opening — context or reason for writing, 1-2 sentences]
+
+[Body — key information, requests, or updates. Use bullet points for multiple items.]
+
+[Closing — next steps, call to action, or sign-off]
+
+[Sign-off],
+[Name]
+```
+
+## Rules
+
+- Keep emails concise — aim for under 200 words for routine communication.
+- One email = one topic. Suggest splitting if multiple unrelated topics are detected.
+- Use active voice and direct language.
+- Avoid jargon unless the recipient is a domain expert.
+- If the user provides arguments or context, incorporate it — do not invent details.
+- Suggest a subject line that is specific and actionable (not "Update" or "Quick question").

unique_skill_tool-2026.16.0/unique_skill_tool/examples/review-contract.md

@@ -0,0 +1,54 @@
+---
+name: review-contract
+description: >-
+  Contract risk analysis, obligation mapping, and clause review.
+  Use when the user asks to review, analyze, or check a contract or legal document.
+---
+
+# Review Contract
+
+You are a contract review specialist. Analyze the provided contract or legal document and produce a structured review.
+
+## Steps
+
+1. Read the full document thoroughly.
+2. Identify the **parties**, **effective date**, **term**, and **governing law**.
+3. Analyze each section for:
+   - **Obligations** — what each party must do.
+   - **Rights** — what each party is entitled to.
+   - **Risks** — clauses that could be unfavorable or ambiguous.
+4. Flag any missing standard clauses.
+5. Summarize and provide recommendations.
+
+## Output Format
+
+### Contract Overview
+| Property | Value |
+|----------|-------|
+| Parties  | ...   |
+| Type     | ...   |
+| Effective Date | ... |
+| Term     | ...   |
+| Governing Law | ... |
+
+### Key Obligations
+For each party, list their main obligations as bullet points.
+
+### Risk Assessment
+| Risk | Clause Reference | Severity | Recommendation |
+|------|-----------------|----------|----------------|
+| ...  | Section X.Y     | High/Med/Low | ... |
+
+### Missing Clauses
+List any standard clauses that are absent (e.g., force majeure, limitation of liability, data protection).
+
+### Recommendations
+Prioritized list of suggested changes or points to negotiate.
+
+## Rules
+
+- This is NOT legal advice — clearly state this disclaimer at the top of your output.
+- Reference specific sections and clause numbers from the document.
+- Use `[sourceN]` citations when referencing document content.
+- Flag ambiguous language explicitly.
+- If the document is not in English, provide the review in the document's language.

unique_skill_tool-2026.16.0/unique_skill_tool/prompts.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+DEFAULT_TOOL_DESCRIPTION = (
+    "PRIORITY TOOL — call FIRST before any other tool when a skill matches. "
+    "Execute a skill to activate specialized capabilities and domain knowledge. "
+    "When a skill matches the user's request, this is a BLOCKING REQUIREMENT: "
+    "invoke the Skill tool BEFORE calling any other tool or generating any "
+    "response. NEVER mention a skill without actually calling this tool."
+)
+
+DEFAULT_TOOL_DESCRIPTION_FOR_SYSTEM_PROMPT = (
+    "Execute a skill within the main conversation.\n\n"
+    "CRITICAL — Skill tool has HIGHEST PRIORITY among all tools:\n"
+    "1. Before you call ANY other tool (InternalSearch, OpenFile, etc.) or "
+    "generate ANY response, check if a skill matches the user's request.\n"
+    "2. If a skill matches, you MUST invoke the Skill tool FIRST as your "
+    "very first action. This is a BLOCKING REQUIREMENT — do not call other "
+    "tools or produce text until the skill is loaded.\n"
+    "3. NEVER mention a skill without actually calling the tool.\n"
+    "4. Do not invoke a skill that is already active in the current turn "
+    "(check for <skill_loaded> tags in the conversation).\n"
+    "5. After the skill is loaded, follow its instructions directly. The "
+    "skill may tell you to call other tools (e.g. InternalSearch) as part "
+    "of its workflow — that is expected.\n\n"
+    "Important:\n"
+    "- Available skills are listed in system-reminder messages in the "
+    "conversation. The listing is refreshed every turn — do not rely on a "
+    "name unless it appears in the most recent reminder.\n"
+    "- The skill description in the listing is a summary. The full "
+    "instructions are injected into the conversation only after you invoke "
+    "the tool.\n\n"
+    "How to invoke:\n"
+    '- name: "analyze-data" — invoke a skill by name\n'
+    '- name: "summarize", arguments: "focus on key metrics" — invoke with arguments'
+)
+
+DEFAULT_TOOL_DESCRIPTION_FOR_USER_PROMPT = ""
+
+DEFAULT_TOOL_SYSTEM_REMINDER_FOR_USER_MESSAGE = (
+    "<system-reminder>\n"
+    "The following skills are available. Use the Skill tool to invoke them.\n"
+    "\n"
+    "{{ skill_list }}\n"
+    "</system-reminder>"
+)
+
+DEFAULT_TOOL_PARAMETER_SKILL_NAME_DESCRIPTION = (
+    "The name of the skill to invoke. Must be one of the available skills."
+)
+
+DEFAULT_TOOL_PARAMETER_ARGUMENTS_DESCRIPTION = (
+    "Optional arguments or context to pass to the skill."
+)

unique_skill_tool-2026.16.0/unique_skill_tool/schemas.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+SKILL_NAME_PATTERN = r"^[a-z0-9]+(?:-[a-z0-9]+)*$"
+SKILL_NAME_MAX_LENGTH = 64
+
+
+class SkillDefinition(BaseModel):
+    """A skill that the agent can activate via the SkillTool.
+
+    Skills are prompt instruction sets loaded from the knowledge base.
+    The listing (name + description) is shown to the LLM for discovery;
+    the full ``content`` is only returned when the skill is actually
+    invoked.
+    """
+
+    name: str = Field(
+        description=(
+            "Unique identifier for the skill (used as the tool parameter value). "
+            "Must be lowercase kebab-case (a-z, 0-9, hyphens), 1-64 chars."
+        ),
+        min_length=1,
+        max_length=SKILL_NAME_MAX_LENGTH,
+        pattern=SKILL_NAME_PATTERN,
+    )
+    description: str = Field(
+        description="Short description shown in the skill listing for the LLM.",
+    )
+    content: str = Field(
+        description="Full prompt / instructions injected when the skill is invoked.",
+    )

unique_skill_tool-2026.16.0/unique_skill_tool/service.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+from typing import override
+
+from jinja2.sandbox import SandboxedEnvironment
+from unique_toolkit.agentic.evaluation.schemas import EvaluationMetricName
+from unique_toolkit.agentic.tools.factory import ToolFactory
+from unique_toolkit.agentic.tools.schemas import ToolCallResponse
+from unique_toolkit.agentic.tools.tool import Tool
+from unique_toolkit.app.schemas import ChatEvent
+from unique_toolkit.chat.schemas import MessageLog, MessageLogStatus
+from unique_toolkit.language_model.schemas import (
+    LanguageModelFunction,
+    LanguageModelToolDescription,
+)
+
+from unique_skill_tool.config import SkillToolConfig
+from unique_skill_tool.schemas import (
+    SkillDefinition,
+)
+from unique_skill_tool.utils import (
+    format_skill_listing,
+    normalize_skill_name,
+)
+
+
+class SkillTool(Tool[SkillToolConfig]):
+    """Tool that lets the agent activate a named skill.
+
+    The agent calls this with a ``skill_name`` it sees in the skill listing
+    (system prompt).  The tool looks up the skill in the skill registry
+    and returns its full content as the tool response so the agent can
+    follow those instructions.
+    """
+
+    name = "Skill"
+
+    def __init__(
+        self,
+        event: ChatEvent,
+        skill_registry: dict[str, SkillDefinition],
+        config: SkillToolConfig,
+    ) -> None:
+        super().__init__(config, event)
+        self._skill_registry = skill_registry
+
+    @property
+    def skill_registry(self) -> dict[str, SkillDefinition]:
+        return self._skill_registry
+
+    @override
+    def display_name(self) -> str:
+        return "Skill"
+
+    @override
+    def tool_description(self) -> LanguageModelToolDescription:
+        skill_names = list(self._skill_registry.keys())
+
+        skill_name_schema: dict[str, str | list[str]] = {
+            "type": "string",
+            "description": self.config.tool_parameter_description_skill_name,
+        }
+        if skill_names:
+            skill_name_schema["enum"] = skill_names
+
+        return LanguageModelToolDescription(
+            name=self.name,
+            description=self.config.tool_description,
+            parameters={
+                "type": "object",
+                "properties": {
+                    "skill_name": skill_name_schema,
+                    "arguments": {
+                        "type": "string",
+                        "description": self.config.tool_parameter_description_arguments,
+                    },
+                },
+                "required": ["skill_name"],
+            },
+        )
+
+    @override
+    def tool_description_for_system_prompt(self) -> str:
+        """Static instructions for the system prompt.
+
+        The skill listing is intentionally NOT rendered here. It is
+        injected per-turn as a ``<system-reminder>`` block via
+        ``SkillTool`` prompt / system-reminder split).
+        """
+        return self.config.tool_description_for_system_prompt
+
+    @override
+    def tool_description_for_user_prompt(self) -> str:
+        return self.config.tool_description_for_user_prompt
+
+    @override
+    def tool_system_reminder_for_user_prompt(self) -> str:
+        """Per-turn ``<system-reminder>`` block listing available skills.
+
+        Renders :attr:`SkillToolConfig.tool_system_reminder_for_user_message` as a
+        Jinja template with the budget-aware ``skill_list``. Returned
+        verbatim by the orchestrator as a ``{"type": "text"}`` part
+        on the latest user message every loop iteration (see
+        ``unique_orchestrator._builders.inject_tool_reminders``), so
+        the listing cannot go stale. Returns an empty string when the
+        skill registry is empty or the reminder template is unset.
+        """
+        skills = list(self._skill_registry.values())
+        if not skills or not self.config.tool_system_reminder_for_user_message:
+            return ""
+
+        listing = format_skill_listing(skills=skills, config=self.config)
+        return (
+            SandboxedEnvironment()
+            .from_string(self.config.tool_system_reminder_for_user_message)
+            .render(skill_list=listing)
+        )
+
+    @override
+    async def run(self, tool_call: LanguageModelFunction) -> ToolCallResponse:
+        args = tool_call.arguments or {}
+        raw_skill_name: str = args.get("skill_name", "")
+        arguments: str = args.get("arguments", "")
+
+        if not raw_skill_name or not raw_skill_name.strip():
+            return ToolCallResponse(
+                id=tool_call.id,
+                name=self.name,
+                error_message="skill_name must be a non-empty string.",
+            )
+
+        skill_name = normalize_skill_name(raw_skill_name)
+        skill = self._skill_registry.get(skill_name)
+
+        if skill is None:
+            available = ", ".join(sorted(self._skill_registry.keys()))
+            return ToolCallResponse(
+                id=tool_call.id,
+                name=self.name,
+                error_message=(
+                    f"Unknown skill: '{skill_name}'. Available skills: {available}"
+                ),
+            )
+
+        self._active_message_log = await self._log_skill_loaded(skill_name=skill_name)
+
+        content_parts = [
+            f"<skill_loaded>{skill_name}</skill_loaded>",
+            f"Skill '{skill_name}' is now active. Follow the instructions below.",
+            "",
+            skill.content,
+        ]
+        if arguments:
+            content_parts.append(f"\nUser-provided arguments: {arguments}")
+
+        return ToolCallResponse(
+            id=tool_call.id,
+            name=self.name,
+            content="\n".join(content_parts),
+            system_reminder=(
+                f"The skill '{skill_name}' has been loaded. "
+                "Follow its instructions now. Do NOT call the Skill tool "
+                "again for the same skill in this turn."
+            ),
+        )
+
+    async def _log_skill_loaded(self, *, skill_name: str) -> MessageLog | None:
+        """Emit a completed message log entry for the loaded skill."""
+        progress_message = f"Loaded skill `{skill_name}`"
+
+        try:
+            return await self._message_step_logger.create_or_update_message_log_async(
+                active_message_log=None,
+                header=progress_message,
+                status=MessageLogStatus.COMPLETED,
+            )
+        except Exception:
+            self.logger.debug(
+                "SkillTool: failed to write skill-loaded message log",
+                exc_info=True,
+            )
+            return None
+
+    @override
+    def evaluation_check_list(self) -> list[EvaluationMetricName]:
+        return []
+
+    @override
+    def get_evaluation_checks_based_on_tool_response(
+        self, tool_response: ToolCallResponse
+    ) -> list[EvaluationMetricName]:
+        return []
+
+
+ToolFactory.register_tool(SkillTool, SkillToolConfig)

unique_skill_tool-2026.16.0/unique_skill_tool/utils.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import re
+
+from unique_skill_tool.config import (
+    CHARS_PER_TOKEN,
+    DEFAULT_CHAR_BUDGET,
+    SkillToolConfig,
+)
+from unique_skill_tool.schemas import (
+    SkillDefinition,
+)
+
+MIN_DESC_LENGTH = 20
+
+_SKILL_PREFIX_TOKEN_RE = re.compile(r"\A\s*/([A-Za-z0-9][A-Za-z0-9_-]*)(?=\s|\Z)")
+
+
+def get_char_budget(
+    context_window_tokens: int | None,
+    config: SkillToolConfig,
+) -> int:
+    """Return the character budget for the skill listing.
+
+    Uses *config.skill_budget_context_percent* of the context window
+    (converted to characters via ``CHARS_PER_TOKEN``).  Falls back to
+    ``DEFAULT_CHAR_BUDGET`` when the context window size is unknown.
+    """
+    if context_window_tokens is not None:
+        return int(
+            context_window_tokens
+            * CHARS_PER_TOKEN
+            * config.skill_budget_context_percent
+        )
+    return DEFAULT_CHAR_BUDGET
+
+
+def _get_skill_description(skill: SkillDefinition, max_chars: int) -> str:
+    desc = skill.description
+    if len(desc) > max_chars:
+        return desc[: max_chars - 3] + "..."
+    return desc
+
+
+def _format_entry(skill: SkillDefinition, max_desc_chars: int) -> str:
+    return f"- {skill.name}: {_get_skill_description(skill, max_desc_chars)}"
+
+
+def format_skill_listing(
+    skills: list[SkillDefinition],
+    context_window_tokens: int | None = None,
+    config: SkillToolConfig | None = None,
+) -> str:
+    """Format the skill listing for the system prompt within a character budget.
+
+    Ported from Claude Code's ``formatCommandsWithinBudget`` (prompt.ts).
+
+    Strategy:
+    1. Try full descriptions (capped at ``max_listing_desc_chars``).
+    2. If over budget, uniformly truncate descriptions to fit.
+    3. If truncation leaves less than ``MIN_DESC_LENGTH`` per entry, fall
+       back to names only.
+    """
+    if not skills:
+        return ""
+
+    if config is None:
+        config = SkillToolConfig()
+
+    budget = get_char_budget(context_window_tokens, config)
+    max_desc = config.max_listing_desc_chars
+
+    full_entries = [_format_entry(skill, max_desc) for skill in skills]
+    full_total = sum(len(e) for e in full_entries) + len(full_entries) - 1
+
+    if full_total <= budget:
+        return "\n".join(full_entries)
+
+    name_overhead = sum(len(s.name) + 4 for s in skills) + len(skills) - 1
+    available_for_descs = budget - name_overhead
+    max_desc_len = available_for_descs // len(skills)
+
+    if max_desc_len < MIN_DESC_LENGTH:
+        return "\n".join(f"- {s.name}" for s in skills)
+
+    return "\n".join(
+        f"- {s.name}: {_get_skill_description(s, max_desc_len)}" for s in skills
+    )
+
+
+def normalize_skill_name(skill: str) -> str:
+    """Strip whitespace and a leading ``/`` from a skill name."""
+    skill = skill.strip()
+    if skill.startswith("/"):
+        return skill[1:]
+    return skill
+
+
+def extract_prefix_skills(
+    user_text: str,
+    skill_registry: dict[str, SkillDefinition],
+) -> tuple[list[SkillDefinition], str]:
+    """Pull consecutive ``/skill-name`` tokens from the very start of *user_text*.
+
+    Matches only tokens at the beginning of the message (after optional
+    leading whitespace). Matching stops at the first non-token or unknown
+    skill name, so ``/``-prefixed words appearing mid-message (URLs, code,
+    prose) are ignored.
+
+    Duplicates are dropped while preserving first-occurrence order.
+
+    Returns ``(ordered_skills, remaining_text)`` where *remaining_text* is
+    the original message with the matched prefix tokens stripped and
+    leading whitespace removed.
+    """
+    remaining = user_text
+    ordered: list[SkillDefinition] = []
+    seen: set[str] = set()
+
+    while True:
+        match = _SKILL_PREFIX_TOKEN_RE.match(remaining)
+        if match is None:
+            break
+        name = match.group(1)
+        skill = skill_registry.get(name)
+        if skill is None:
+            break
+        if name not in seen:
+            seen.add(name)
+            ordered.append(skill)
+        remaining = remaining[match.end() :]
+
+    return ordered, remaining.lstrip()