Function run_skill

openkb/agent/skill_runner.py:64–216

Load ``skill_name`` and run it as an agent with ``intent``. When the skill's frontmatter declares ``od.mode == "deck"`` and ``od.output_path_template`` is set, ``run_skill``: 1. Templates the path with the provided ``slug``. 2. Adds a "Write to: " line to the agent's inte

(
    *,
    skill_name: str,
    intent: str,
    kb_dir: Path,
    model: str,
    language: str = "en",
    max_turns: int = MAX_TURNS,
    seed: Optional[str] = None,
    slug: Optional[str] = None,
    extra_skill_roots: tuple[str | Path, ...] = (),
)

async def run_skill(
    *,
    skill_name: str,
    intent: str,
    kb_dir: Path,
    model: str,
    language: str = "en",
    max_turns: int = MAX_TURNS,
    seed: Optional[str] = None,
    slug: Optional[str] = None,
    extra_skill_roots: tuple[str | Path, ...] = (),
) -> SkillRunResult:
    """Load ``skill_name`` and run it as an agent with ``intent``.

    When the skill's frontmatter declares ``od.mode == "deck"`` and
    ``od.output_path_template`` is set, ``run_skill``:

      1. Templates the path with the provided ``slug``.
      2. Adds a "Write to: <path>" line to the agent&#x27;s intent so the
         skill knows the expected destination.
      3. After the agent run, checks the file exists and (if the skill
         declared ``od.deck_grammar``) runs ``validate_deck`` against it.

    Args:
        skill_name: Name (frontmatter ``name:``) of the skill to invoke.
        intent: Natural-language brief for what to produce.
        kb_dir: KB root. Used both for skill discovery and for the
            agent&#x27;s wiki read-tools / write-file scoping.
        model: LiteLLM-formatted model string from KB config.
        language: Passed through to the underlying query agent for
            answer-language consistency.
        max_turns: Hard cap on agent loop iterations.
        seed: Optional kick-off user message. Defaults to a short nudge
            that points the agent at its own instructions.
        slug: Required when the skill declares
            ``od.output_path_template`` (it substitutes ``{slug}``).
            Otherwise ignored.
        extra_skill_roots: Additional directories to scan beyond the
            built-in ``<kb>/skills``, ``~/.openkb/skills``,
            ``~/.claude/skills``.

    Returns:
        A :class:`SkillRunResult` carrying the resolved output path (if
        any) and the validation result (for deck-mode skills).

    Raises:
        SkillNotFoundError: if no skill with ``skill_name`` is found.
        RuntimeError: on turn-cap, model error, or missing
            output file after a templated-path run.
    """
    skills = scan_local_skills(kb_dir, extra_roots=extra_skill_roots)
    match = next((s for s in skills if s["name"] == skill_name), None)
    if match is None:
        available = ", ".join(sorted(s["name"] for s in skills)) or "(none)"
        raise SkillNotFoundError(
            f"Skill {skill_name!r} not found. Available: {available}. "
            f"Drop a SKILL.md into ~/.openkb/skills/<name>/ or "
            f"<kb>/skills/<name>/ and re-run."