Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

39.7 KB
Raw Blame
"""
SkillService
============

Capability-skill storage and runtime loading, nanobot-style.

A skill is a self-contained capability package the model consults *on
demand*: a ``SKILL.md`` playbook plus optional ``references/`` (and, once the
execution sandbox ships, ``scripts/``). Skills are never injected wholesale
into the system prompt — the prompt carries a one-line-per-skill manifest
(see :func:`render_skills_manifest`) and the model fetches full content
through the ``read_skill`` tool when a task matches. The exceptions are
skills marked ``always: true`` in frontmatter, whose bodies are eagerly
injected (used for house rules that must apply to every turn).

Two layers, user shadows builtin:

* builtin — shipped with the product under ``deeptutor/skills/builtin/``,
  read-only at runtime;
* user — authored via the API under ``data/user/workspace/skills/``.

Each skill lives in its own directory::

    <root>/<name>/SKILL.md
    <root>/<name>/references/...   (optional, readable via read_skill)

Frontmatter schema::

    ---
    name: my-skill
    description: One-line summary shown in the manifest.
    tags: [style]            # optional, user-facing organisation only
    always: false            # optional, eager-inject when true
    requires:                 # optional availability gates
      bins: [git]            # CLI binaries that must exist on PATH
      env: [GITHUB_TOKEN]    # environment variables that must be set
      sandbox: shell         # needs the shell execution sandbox
    ---

A small ``.tags.json`` file next to the user skill directories holds the
canonical user-managed tag vocabulary so tags can be created, renamed, or
deleted independently of the skills that use them.

Behaviour/voice presets ("teacher", "peer", …) are NOT skills — they live in
:mod:`deeptutor.services.persona` and are eagerly injected because a persona
must shape the voice from the first token.
"""

from __future__ import annotations

from dataclasses import dataclass, field
import json
import os
from pathlib import Path
import re
import shutil
from typing import Any
from uuid import uuid4

import yaml

from deeptutor.services.path_service import get_path_service

_FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n?", re.DOTALL)
_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,63}$")
_TAG_RE = re.compile(r"^[a-z0-9][a-z0-9\- _]{0,31}$")
_DEFAULT_TAGS: tuple[str, ...] = ("style", "tool")
_TAGS_FILE = ".tags.json"

# Builtin skills shipped inside the package. Partners run on the chat agent
# loop, so this is the single builtin set for both product chat and partner
# workspaces (the old TutorBot-only skill set died with its engine).
BUILTIN_SKILLS_ROOT = Path(__file__).resolve().parents[2] / "skills" / "builtin"

# Hard cap for read_skill payloads so a huge reference file cannot flood the
# context window. Mirrors the truncation posture of the other read tools.
_MAX_READ_CHARS = 100_000

# Provenance ledger for skills imported from an external hub (ClawHub, …).
# Sits beside ``.tags.json`` so the UI/CLI can show "from [email protected]" and
# an update path knows where each imported skill came from.
_HUB_LOCK_FILE = ".hub-lock.json"

# Bounds for importing a skill package from an untrusted source. A skill is a
# text playbook plus small supporting files — anything bigger is suspect, so
# the import fails closed instead of filling the workspace.
_IMPORT_MAX_FILE_BYTES = 1_000_000
_IMPORT_MAX_TOTAL_BYTES = 20_000_000
_IMPORT_MAX_FILES = 500

# Supporting-file suffixes an imported skill may carry (whitelist, lowercase).
# Text playbooks, references, and scripts only — never binaries or archives.
# Suffix-less files (LICENSE, Makefile) are allowed; copies drop the exec bit.
_IMPORT_ALLOWED_SUFFIXES = frozenset(
    {
        "",
        ".md", ".markdown", ".txt", ".rst",
        ".py", ".js", ".mjs", ".ts", ".sh", ".rb", ".lua", ".r",
        ".json", ".jsonl", ".yaml", ".yml", ".toml", ".ini", ".cfg",
        ".csv", ".tsv", ".html", ".htm", ".css", ".xml", ".sql",
        ".jinja", ".j2", ".tmpl", ".template",
    }
)  # fmt: skip


@dataclass(slots=True)
class SkillInfo:
    name: str
    description: str
    tags: list[str] = field(default_factory=list)
    source: str = "user"  # "user" | "builtin" | "admin"

    def to_dict(self) -> dict[str, Any]:
        return {
            "name": self.name,
            "description": self.description,
            "tags": list(self.tags),
            "source": self.source,
            "read_only": self.source != "user",
        }


@dataclass(slots=True)
class SkillDetail:
    name: str
    description: str
    content: str
    tags: list[str] = field(default_factory=list)
    source: str = "user"

    def to_dict(self) -> dict[str, Any]:
        return {
            "name": self.name,
            "description": self.description,
            "content": self.content,
            "tags": list(self.tags),
            "source": self.source,
            "read_only": self.source != "user",
        }


@dataclass(slots=True)
class SkillSummaryEntry:
    """One manifest row: what the model sees about a skill before reading it."""

    name: str
    description: str
    available: bool = True
    missing: list[str] = field(default_factory=list)
    always: bool = False


@dataclass(slots=True)
class SkillInstallResult:
    """Outcome of :meth:`SkillService.install_tree`.

    ``skipped`` lists support files the import gate dropped, as
    ``(relative-path, reason)`` pairs, so callers can surface what did not
    make it into the workspace instead of failing the whole install.
    """

    info: SkillInfo
    skipped: list[tuple[str, str]] = field(default_factory=list)


class SkillNotFoundError(Exception):
    pass


class SkillFileNotFoundError(Exception):
    """The skill exists but the requested file inside it does not."""


class SkillExistsError(Exception):
    pass


class SkillReadOnlyError(Exception):
    """Raised when a write targets a builtin (read-only) skill."""


class InvalidSkillNameError(Exception):
    pass


class InvalidSkillPathError(Exception):
    """Raised when ``read_skill_file`` is asked for a path outside the skill dir."""


class SkillImportError(Exception):
    """Raised when an imported skill package fails a structural/safety gate."""


class InvalidTagError(Exception):
    pass


class TagNotFoundError(Exception):
    pass


class TagExistsError(Exception):
    pass


def _sandbox_available(kind: str) -> bool:
    """Whether the execution sandbox satisfies a ``requires.sandbox`` gate.

    Late import so the skill layer stays decoupled from the sandbox layer;
    fails closed when the sandbox service is absent or disabled.
    """
    try:
        from deeptutor.services.sandbox import exec_capability_available

        return exec_capability_available(kind)
    except Exception:
        return False


class SkillService:
    """CRUD + runtime loading for SKILL.md packages (builtin + user layers)."""

    def __init__(
        self,
        root: Path | None = None,
        builtin_root: Path | None = BUILTIN_SKILLS_ROOT,
    ) -> None:
        self._root = root or (get_path_service().get_workspace_dir() / "skills")
        self._builtin_root = builtin_root

    @property
    def root(self) -> Path:
        return self._root

    # ── path helpers ────────────────────────────────────────────────────

    def _validate_name(self, name: str) -> str:
        candidate = (name or "").strip().lower()
        if not _NAME_RE.match(candidate):
            raise InvalidSkillNameError("Skill name must match ^[a-z0-9][a-z0-9-]{0,63}$")
        return candidate

    def _skill_dir(self, name: str) -> Path:
        return self._root / self._validate_name(name)

    def _skill_file(self, name: str) -> Path:
        return self._skill_dir(name) / "SKILL.md"

    def _resolve_skill_dir(self, name: str) -> tuple[Path, str] | None:
        """Locate a skill across layers: user first, then builtin."""
        slug = self._validate_name(name)
        user_dir = self._root / slug
        if (user_dir / "SKILL.md").exists():
            return user_dir, "user"
        if self._builtin_root is not None:
            builtin_dir = self._builtin_root / slug
            if (builtin_dir / "SKILL.md").exists():
                return builtin_dir, "builtin"
        return None

    # ── tag helpers ─────────────────────────────────────────────────────

    @staticmethod
    def _normalize_tag(raw: Any) -> str:
        candidate = str(raw or "").strip().lower()
        if not candidate:
            raise InvalidTagError("Tag name must not be empty.")
        if not _TAG_RE.match(candidate):
            raise InvalidTagError(
                "Tag must match ^[a-z0-9][a-z0-9- _]{0,31}$ (letters/digits/dash/space/underscore)."
            )
        return candidate

    @staticmethod
    def _dedupe_tags(values: list[str]) -> list[str]:
        seen: set[str] = set()
        out: list[str] = []
        for v in values:
            if v in seen:
                continue
            seen.add(v)
            out.append(v)
        return out

    def _tags_path(self) -> Path:
        return self._root / _TAGS_FILE

    def _read_tag_vocab(self) -> list[str]:
        path = self._tags_path()
        if not path.exists():
            return []
        try:
            data = json.loads(path.read_text(encoding="utf-8"))
        except (OSError, json.JSONDecodeError):
            return []
        raw = data.get("tags") if isinstance(data, dict) else None
        if not isinstance(raw, list):
            return []
        out: list[str] = []
        for item in raw:
            try:
                out.append(self._normalize_tag(item))
            except InvalidTagError:
                continue
        return self._dedupe_tags(out)

    def _write_tag_vocab(self, tags: list[str]) -> None:
        self._root.mkdir(parents=True, exist_ok=True)
        payload = {"tags": self._dedupe_tags(tags)}
        self._tags_path().write_text(
            json.dumps(payload, ensure_ascii=False, indent=2),
            encoding="utf-8",
        )

    def _tags_from_meta(self, meta: dict[str, Any]) -> list[str]:
        raw = meta.get("tags")
        if not isinstance(raw, list):
            return []
        out: list[str] = []
        for item in raw:
            try:
                out.append(self._normalize_tag(item))
            except InvalidTagError:
                continue
        return self._dedupe_tags(out)

    def _collect_skill_tags(self) -> list[str]:
        """Scan user skills and collect tags present in their frontmatter."""
        found: list[str] = []
        for info in self.list_skills():
            if info.source != "user":
                continue
            for tag in info.tags:
                if tag not in found:
                    found.append(tag)
        return found

    def _ensure_initialized_vocab(self) -> list[str]:
        """Seed default tags on first access and backfill any tags found on skills."""
        vocab = self._read_tag_vocab()
        existed = self._tags_path().exists()
        if not existed:
            vocab = list(_DEFAULT_TAGS)
        union = self._dedupe_tags(vocab + self._collect_skill_tags())
        if not existed or union != vocab:
            self._write_tag_vocab(union)
        return union

    # ── parsing ─────────────────────────────────────────────────────────

    @staticmethod
    def _parse_frontmatter(content: str) -> tuple[dict[str, Any], str]:
        match = _FRONTMATTER_RE.match(content)
        if not match:
            return {}, content
        raw = match.group(1)
        body = content[match.end() :]
        try:
            data = yaml.safe_load(raw) or {}
        except yaml.YAMLError:
            data = {}
        if not isinstance(data, dict):
            data = {}
        return data, body

    @staticmethod
    def _requires_from_meta(meta: dict[str, Any]) -> dict[str, Any]:
        raw = meta.get("requires")
        return raw if isinstance(raw, dict) else {}

    @classmethod
    def _availability(cls, meta: dict[str, Any]) -> tuple[bool, list[str]]:
        """Check ``requires`` gates; return ``(available, missing-labels)``.

        ``bins`` are checked against the host PATH. Once the runner-sidecar
        sandbox ships, exec-flavoured skills should prefer the
        ``sandbox`` gate over host ``bins`` (the runner image carries its
        own binaries).
        """
        requires = cls._requires_from_meta(meta)
        missing: list[str] = []
        for b in requires.get("bins") or []:
            label = str(b).strip()
            if label and not shutil.which(label):
                missing.append(f"CLI: {label}")
        for env_var in requires.get("env") or []:
            label = str(env_var).strip()
            if label and not os.environ.get(label):
                missing.append(f"ENV: {label}")
        sandbox = requires.get("sandbox")
        if sandbox:
            kind = "shell" if sandbox is True else str(sandbox).strip()
            if kind and not _sandbox_available(kind):
                missing.append(f"SANDBOX: {kind}")
        return (not missing), missing

    def _load_info(self, skill_dir: Path, source: str) -> SkillInfo | None:
        file = skill_dir / "SKILL.md"
        try:
            text = file.read_text(encoding="utf-8")
        except OSError:
            return None
        meta, _ = self._parse_frontmatter(text)
        return SkillInfo(
            name=skill_dir.name,
            description=str(meta.get("description") or "").strip(),
            tags=self._tags_from_meta(meta),
            source=source,
        )

    # ── public read API ─────────────────────────────────────────────────

    def list_skills(self) -> list[SkillInfo]:
        """All skills visible from this service: user layer + unshadowed builtin."""
        out: list[SkillInfo] = []
        seen: set[str] = set()
        if self._root.exists():
            for entry in sorted(self._root.iterdir()):
                if not entry.is_dir() or not (entry / "SKILL.md").exists():
                    continue
                if not _NAME_RE.match(entry.name):
                    continue
                info = self._load_info(entry, "user")
                if info is not None:
                    out.append(info)
                    seen.add(info.name)
        if self._builtin_root is not None and self._builtin_root.exists():
            for entry in sorted(self._builtin_root.iterdir()):
                if not entry.is_dir() or not (entry / "SKILL.md").exists():
                    continue
                if entry.name in seen or not _NAME_RE.match(entry.name):
                    continue
                info = self._load_info(entry, "builtin")
                if info is not None:
                    out.append(info)
        return out

    def get_detail(self, name: str) -> SkillDetail:
        resolved = self._resolve_skill_dir(name)
        if resolved is None:
            raise SkillNotFoundError(name)
        skill_dir, source = resolved
        text = (skill_dir / "SKILL.md").read_text(encoding="utf-8")
        meta, _ = self._parse_frontmatter(text)
        return SkillDetail(
            name=skill_dir.name,
            description=str(meta.get("description") or "").strip(),
            content=text,
            tags=self._tags_from_meta(meta),
            source=source,
        )

    def read_skill_file(self, name: str, rel_path: str = "SKILL.md") -> str:
        """Read a file from inside a skill package (for the ``read_skill`` tool).

        ``rel_path`` is resolved strictly within the skill directory —
        absolute paths and traversal segments are rejected. Content longer
        than the read cap is truncated with an explicit marker.
        """
        resolved = self._resolve_skill_dir(name)
        if resolved is None:
            raise SkillNotFoundError(name)
        skill_dir, _source = resolved

        candidate = (rel_path or "SKILL.md").strip() or "SKILL.md"
        rel = Path(candidate)
        if rel.is_absolute() or ".." in rel.parts:
            raise InvalidSkillPathError(f"Illegal skill file path: {rel_path}")
        target = (skill_dir / rel).resolve()
        if not target.is_relative_to(skill_dir.resolve()):
            raise InvalidSkillPathError(f"Illegal skill file path: {rel_path}")
        if not target.is_file():
            raise SkillFileNotFoundError(f"File not found in skill: {name}/{candidate}")
        text = target.read_text(encoding="utf-8", errors="replace")
        if len(text) > _MAX_READ_CHARS:
            text = text[:_MAX_READ_CHARS] + "\n\n[... truncated ...]"
        return text

    def list_skill_files(self, name: str) -> list[str]:
        """Relative paths of readable files inside a skill package."""
        resolved = self._resolve_skill_dir(name)
        if resolved is None:
            raise SkillNotFoundError(name)
        skill_dir, _source = resolved
        files: list[str] = []
        for path in sorted(skill_dir.rglob("*")):
            if path.is_file() and not path.name.startswith("."):
                files.append(str(path.relative_to(skill_dir)))
        return files

    # ── runtime loading (manifest + always) ─────────────────────────────

    def summary_entries(self) -> list[SkillSummaryEntry]:
        """Manifest rows for every skill visible from this service."""
        entries: list[SkillSummaryEntry] = []
        for info in self.list_skills():
            resolved = self._resolve_skill_dir(info.name)
            if resolved is None:
                continue
            skill_dir, _source = resolved
            meta, _ = self._parse_frontmatter((skill_dir / "SKILL.md").read_text(encoding="utf-8"))
            available, missing = self._availability(meta)
            entries.append(
                SkillSummaryEntry(
                    name=info.name,
                    description=info.description,
                    available=available,
                    missing=missing,
                    always=bool(meta.get("always")),
                )
            )
        return entries

    def load_for_context(self, names: list[str]) -> str:
        """Render the given skills' full bodies into a system-prompt block.

        Used for ``always: true`` skills only — everything else reaches the
        model through the manifest + ``read_skill``.
        """
        if not names:
            return ""
        parts: list[str] = []
        for name in names:
            try:
                detail = self.get_detail(name)
            except (SkillNotFoundError, InvalidSkillNameError):
                continue
            _, body = self._parse_frontmatter(detail.content)
            body = body.strip()
            if not body:
                continue
            parts.append(f"### Skill: {detail.name}\n\n{body}")
        if not parts:
            return ""
        return (
            "## Active Skills\n"
            "Follow the playbooks below. They override generic defaults.\n\n"
            + "\n\n---\n\n".join(parts)
        )

    def load_always_for_context(self) -> str:
        """Eagerly render skills marked ``always: true`` (and available)."""
        names = [e.name for e in self.summary_entries() if e.always and e.available]
        return self.load_for_context(names)

    # ── public write API (user layer only) ──────────────────────────────

    def _assert_writable(self, slug: str) -> None:
        """Writes must target the user layer; builtin skills are read-only."""
        if (self._root / slug / "SKILL.md").exists():
            return
        if self._builtin_root is not None and (self._builtin_root / slug / "SKILL.md").exists():
            raise SkillReadOnlyError(f"Skill is builtin (read-only): {slug}")
        raise SkillNotFoundError(slug)

    def create(
        self,
        name: str,
        description: str,
        content: str,
        tags: list[str] | None = None,
    ) -> SkillInfo:
        slug = self._validate_name(name)
        target_dir = self._skill_dir(slug)
        if target_dir.exists():
            raise SkillExistsError(slug)
        clean_tags = self._validate_tag_list(tags)
        body = self._normalize_content(
            slug,
            description,
            content,
            tags=clean_tags,
        )
        target_dir.mkdir(parents=True, exist_ok=False)
        self._skill_file(slug).write_text(body, encoding="utf-8")
        self._merge_tags_into_vocab(clean_tags)
        return SkillInfo(name=slug, description=description.strip(), tags=clean_tags)

    def update(
        self,
        name: str,
        *,
        description: str | None = None,
        content: str | None = None,
        rename_to: str | None = None,
        tags: list[str] | None = None,
    ) -> SkillInfo:
        slug = self._validate_name(name)
        self._assert_writable(slug)
        target_dir = self._skill_dir(slug)

        if content is not None:
            text = content
        else:
            text = self._skill_file(slug).read_text(encoding="utf-8")

        if description is not None:
            text = self._rewrite_frontmatter(text, description=description.strip())

        clean_tags: list[str] | None = None
        if tags is not None:
            clean_tags = self._validate_tag_list(tags)
            text = self._rewrite_frontmatter(text, tags=clean_tags)

        meta, _ = self._parse_frontmatter(text)
        final_description = str(meta.get("description") or "").strip()
        final_tags = self._tags_from_meta(meta)

        if rename_to and rename_to != slug:
            new_slug = self._validate_name(rename_to)
            new_dir = self._skill_dir(new_slug)
            if new_dir.exists():
                raise SkillExistsError(new_slug)
            text = self._rewrite_frontmatter(text, name=new_slug)
            target_dir.rename(new_dir)
            slug = new_slug
            target_dir = new_dir

        self._skill_file(slug).write_text(text, encoding="utf-8")
        if clean_tags is not None:
            self._merge_tags_into_vocab(clean_tags)
        return SkillInfo(name=slug, description=final_description, tags=final_tags)

    def delete(self, name: str) -> None:
        slug = self._validate_name(name)
        self._assert_writable(slug)
        shutil.rmtree(self._skill_dir(slug))
        self._drop_hub_origin(slug)

    # ── imported skill packages (hub) ────────────────────────────────────

    def install_tree(
        self,
        source_dir: str | Path,
        *,
        rename_to: str | None = None,
        fallback_description: str | None = None,
        origin: dict[str, Any] | None = None,
        force: bool = False,
        extra_tags: list[str] | None = None,
    ) -> SkillInstallResult:
        """Import an extracted skill package directory into the user layer.

        Unlike :meth:`create` (single authored ``SKILL.md``), this takes a
        whole package tree — ``SKILL.md`` plus support files — as produced by
        an external hub download, and applies the import policy:

        * frontmatter is adapted: ``name`` is forced to the slug, flat
          ``bins:``/``env:`` keys (Agent-Skills style) fold into
          ``requires.*``, and ``always:`` is **stripped** — an imported skill
          must never eager-inject itself into the system prompt;
        * support files pass a suffix whitelist plus size/count caps;
          symlinks abort the import (see :meth:`_copy_support_tree`);
        * the tree is staged and swapped in atomically, so a failed import
          never leaves a half-written skill;
        * ``extra_tags`` are merged into the package's own tags (the hub
          installer stamps the source hub, e.g. ``eduhub``, this way);
        * ``origin`` (hub provenance) is recorded in ``.hub-lock.json``.
        """
        source = Path(source_dir).resolve()
        skill_md = source / "SKILL.md"
        if not skill_md.is_file():
            raise SkillImportError("Package has no SKILL.md at its root.")
        if skill_md.stat().st_size > _IMPORT_MAX_FILE_BYTES:
            raise SkillImportError("SKILL.md exceeds the import size limit.")
        text = skill_md.read_text(encoding="utf-8", errors="replace")
        meta, body = self._parse_frontmatter(text)

        slug = self._validate_name(self._slugify(str(rename_to or meta.get("name") or source.name)))
        description = (
            str(meta.get("description") or "").strip() or (fallback_description or "").strip()
        )
        if not description:
            raise SkillImportError("SKILL.md has no description and no fallback was provided.")
        tags = self._validate_tag_list(
            (meta.get("tags") if isinstance(meta.get("tags"), list) else [])
            + list(extra_tags or [])
        )

        target_dir = self._skill_dir(slug)
        if target_dir.exists() and not force:
            raise SkillExistsError(slug)

        header = yaml.safe_dump(
            self._compose_imported_frontmatter(meta, slug=slug, description=description, tags=tags),
            sort_keys=False,
            allow_unicode=True,
        ).strip()
        adapted = f"---\n{header}\n---\n\n{body.lstrip()}".rstrip() + "\n"

        staging = self._root / f".install-{slug}.tmp"
        if staging.exists():
            shutil.rmtree(staging)
        try:
            staging.mkdir(parents=True)
            skipped = self._copy_support_tree(source, staging)
            (staging / "SKILL.md").write_text(adapted, encoding="utf-8")
            previous = self._root / f".{slug}.previous-{uuid4().hex}"
            had_previous = target_dir.exists()
            if had_previous:
                target_dir.rename(previous)
            try:
                staging.rename(target_dir)
            except BaseException:
                if had_previous:
                    previous.rename(target_dir)
                raise
            if had_previous:
                shutil.rmtree(previous)
        finally:
            if staging.exists():
                shutil.rmtree(staging, ignore_errors=True)

        self._merge_tags_into_vocab(tags)
        if origin is not None:
            self.record_hub_origin(slug, origin)
        else:
            self._drop_hub_origin(slug)
        return SkillInstallResult(
            info=SkillInfo(name=slug, description=description, tags=tags),
            skipped=skipped,
        )

    @staticmethod
    def _slugify(raw: str) -> str:
        candidate = re.sub(r"[^a-z0-9-]+", "-", (raw or "").strip().lower())
        return re.sub(r"-{2,}", "-", candidate).strip("-")[:64]

    @staticmethod
    def _as_str_list(value: Any) -> list[str]:
        if isinstance(value, list):
            return [str(item).strip() for item in value if str(item).strip()]
        if isinstance(value, str) and value.strip():
            return [value.strip()]
        return []

    def _compose_imported_frontmatter(
        self,
        meta: dict[str, Any],
        *,
        slug: str,
        description: str,
        tags: list[str],
    ) -> dict[str, Any]:
        """Frontmatter for an imported skill: our schema, their extras.

        Flat ``bins``/``env`` (the Agent-Skills/ClawHub spelling) merge into
        ``requires.*``; ``always`` is dropped — letting a downloaded package
        force itself into every system prompt would be an injection vector.
        Unknown keys (version, license, metadata, …) ride along untouched.
        """
        requires_raw = meta.get("requires")
        requires = dict(requires_raw) if isinstance(requires_raw, dict) else {}
        bins = self._dedupe_tags(
            self._as_str_list(requires.get("bins")) + self._as_str_list(meta.get("bins"))
        )
        env = self._dedupe_tags(
            self._as_str_list(requires.get("env")) + self._as_str_list(meta.get("env"))
        )
        if bins:
            requires["bins"] = bins
        if env:
            requires["env"] = env

        out: dict[str, Any] = {"name": slug, "description": description}
        if tags:
            out["tags"] = list(tags)
        if requires:
            out["requires"] = requires
        for key, value in meta.items():
            if key in {"name", "description", "tags", "requires", "bins", "env", "always"}:
                continue
            out[key] = value
        return out

    def _copy_support_tree(self, source: Path, staging: Path) -> list[tuple[str, str]]:
        """Copy a package's support files into the staging dir, gated.

        Dotfiles/dot-dirs are silently ignored; disallowed suffixes and
        oversized files are skipped and reported; symlinks abort the whole
        import (a link can alias content outside the package). Copies go
        through ``shutil.copyfile`` so no permission bits (notably exec)
        survive the import.
        """
        skipped: list[tuple[str, str]] = []
        count = 0
        total = 0
        for path in sorted(source.rglob("*")):
            rel = path.relative_to(source)
            if any(part.startswith(".") for part in rel.parts):
                continue
            if path.is_symlink():
                raise SkillImportError(f"Symbolic links are not allowed: {rel}")
            if path.is_dir():
                continue
            if rel.as_posix() == "SKILL.md":
                continue  # rewritten separately after frontmatter adaptation
            if path.suffix.lower() not in _IMPORT_ALLOWED_SUFFIXES:
                skipped.append((rel.as_posix(), "file type not allowed"))
                continue
            size = path.stat().st_size
            if size > _IMPORT_MAX_FILE_BYTES:
                skipped.append((rel.as_posix(), "file exceeds size limit"))
                continue
            count += 1
            total += size
            if count > _IMPORT_MAX_FILES:
                raise SkillImportError("Package has too many files.")
            if total > _IMPORT_MAX_TOTAL_BYTES:
                raise SkillImportError("Package exceeds the total size limit.")
            dest = staging / rel
            dest.parent.mkdir(parents=True, exist_ok=True)
            shutil.copyfile(path, dest)
        return skipped

    # ── hub provenance (.hub-lock.json) ──────────────────────────────────

    def _hub_lock_path(self) -> Path:
        return self._root / _HUB_LOCK_FILE

    def _read_hub_lock(self) -> dict[str, dict[str, Any]]:
        path = self._hub_lock_path()
        if not path.exists():
            return {}
        try:
            data = json.loads(path.read_text(encoding="utf-8"))
        except (OSError, json.JSONDecodeError):
            return {}
        if not isinstance(data, dict):
            return {}
        return {
            key: value
            for key, value in data.items()
            if isinstance(key, str) and isinstance(value, dict)
        }

    def _write_hub_lock(self, data: dict[str, dict[str, Any]]) -> None:
        self._root.mkdir(parents=True, exist_ok=True)
        self._hub_lock_path().write_text(
            json.dumps(data, ensure_ascii=False, indent=2),
            encoding="utf-8",
        )

    def record_hub_origin(self, name: str, origin: dict[str, Any]) -> None:
        slug = self._validate_name(name)
        lock = self._read_hub_lock()
        lock[slug] = dict(origin)
        self._write_hub_lock(lock)

    def hub_origin(self, name: str) -> dict[str, Any] | None:
        try:
            slug = self._validate_name(name)
        except InvalidSkillNameError:
            return None
        return self._read_hub_lock().get(slug)

    def _drop_hub_origin(self, slug: str) -> None:
        lock = self._read_hub_lock()
        if slug in lock:
            del lock[slug]
            self._write_hub_lock(lock)

    # ── tag management API ─────────────────────────────────────────────

    def list_tags(self) -> list[str]:
        return self._ensure_initialized_vocab()

    def create_tag(self, name: str) -> str:
        tag = self._normalize_tag(name)
        vocab = self._ensure_initialized_vocab()
        if tag in vocab:
            raise TagExistsError(tag)
        self._write_tag_vocab(vocab + [tag])
        return tag

    def rename_tag(self, old: str, new: str) -> str:
        old_tag = self._normalize_tag(old)
        new_tag = self._normalize_tag(new)
        vocab = self._ensure_initialized_vocab()
        if old_tag not in vocab:
            raise TagNotFoundError(old_tag)
        if new_tag != old_tag and new_tag in vocab:
            raise TagExistsError(new_tag)
        if new_tag == old_tag:
            return old_tag
        new_vocab = [new_tag if t == old_tag else t for t in vocab]
        self._write_tag_vocab(new_vocab)
        # Cascade: rewrite frontmatter on every user skill that used the old tag.
        self._replace_tag_in_skills(old_tag, new_tag)
        return new_tag

    def delete_tag(self, name: str) -> None:
        tag = self._normalize_tag(name)
        vocab = self._ensure_initialized_vocab()
        if tag not in vocab:
            raise TagNotFoundError(tag)
        new_vocab = [t for t in vocab if t != tag]
        self._write_tag_vocab(new_vocab)
        self._replace_tag_in_skills(tag, None)

    # ── internal tag helpers ───────────────────────────────────────────

    def _validate_tag_list(self, tags: list[str] | None) -> list[str]:
        if not tags:
            return []
        cleaned: list[str] = []
        for raw in tags:
            try:
                cleaned.append(self._normalize_tag(raw))
            except InvalidTagError:
                continue
        return self._dedupe_tags(cleaned)

    def _merge_tags_into_vocab(self, new_tags: list[str]) -> None:
        if not new_tags:
            # Still trigger init so the vocab file exists after first write.
            self._ensure_initialized_vocab()
            return
        vocab = self._ensure_initialized_vocab()
        merged = self._dedupe_tags(vocab + new_tags)
        if merged != vocab:
            self._write_tag_vocab(merged)

    def _replace_tag_in_skills(self, old_tag: str, new_tag: str | None) -> None:
        if not self._root.exists():
            return
        for entry in sorted(self._root.iterdir()):
            if not entry.is_dir() or not (entry / "SKILL.md").exists():
                continue
            info = self._load_info(entry, "user")
            if info is None or old_tag not in info.tags:
                continue
            updated: list[str] = []
            for t in info.tags:
                if t == old_tag:
                    if new_tag and new_tag not in updated:
                        updated.append(new_tag)
                elif t not in updated:
                    updated.append(t)
            text = (entry / "SKILL.md").read_text(encoding="utf-8")
            new_text = self._rewrite_frontmatter(text, tags=updated)
            (entry / "SKILL.md").write_text(new_text, encoding="utf-8")

    # ── content helpers ────────────────────────────────────────────────

    def _normalize_content(
        self,
        name: str,
        description: str,
        content: str,
        *,
        tags: list[str] | None = None,
    ) -> str:
        """Ensure the saved file has a valid frontmatter block with ``name``/``description``.

        If the user-provided ``content`` already has frontmatter we patch the
        ``name``, ``description`` and ``tags`` fields; otherwise we synthesise
        a header.
        """
        text = content if content is not None else ""
        if _FRONTMATTER_RE.match(text):
            text = self._rewrite_frontmatter(
                text,
                name=name,
                description=description.strip(),
                tags=tags,
            )
            return text
        payload: dict[str, Any] = {
            "name": name,
            "description": description.strip(),
        }
        if tags:
            payload["tags"] = list(tags)
        header = yaml.safe_dump(
            payload,
            sort_keys=False,
            allow_unicode=True,
        ).strip()
        body = text.lstrip()
        return f"---\n{header}\n---\n\n{body}".rstrip() + "\n"

    def _rewrite_frontmatter(
        self,
        text: str,
        *,
        name: str | None = None,
        description: str | None = None,
        tags: list[str] | None = None,
    ) -> str:
        meta, body = self._parse_frontmatter(text)
        if name is not None:
            meta["name"] = name
        if description is not None:
            meta["description"] = description
        if tags is not None:
            if tags:
                meta["tags"] = list(tags)
            elif "tags" in meta:
                meta.pop("tags", None)
        if not meta:
            return text
        header = yaml.safe_dump(meta, sort_keys=False, allow_unicode=True).strip()
        return f"---\n{header}\n---\n\n{body.lstrip()}".rstrip() + "\n"


def render_skills_manifest(entries: list[SkillSummaryEntry]) -> str:
    """Render manifest rows into the system-prompt Skills block.

    ``always`` entries are excluded — their full bodies are already injected
    eagerly, so listing them again would only waste tokens. Duplicate names
    keep their first occurrence (caller orders user > admin > builtin).
    """
    seen: set[str] = set()
    lines: list[str] = []
    for entry in entries:
        if entry.always or entry.name in seen:
            continue
        seen.add(entry.name)
        suffix = ""
        if not entry.available:
            suffix = f" (unavailable: {', '.join(entry.missing)})"
        description = entry.description or entry.name
        lines.append(f"- **{entry.name}** — {description}{suffix}")
    if not lines:
        return ""
    return (
        "## Skills\n"
        "Specialised playbooks available on demand. When a task matches a "
        "skill's description, call `read_skill` with its name BEFORE "
        "attempting the task, then follow the returned instructions. Skills "
        "marked unavailable cannot be used until their requirements are met.\n\n" + "\n".join(lines)
    )


_instances: dict[str, SkillService] = {}


def get_admin_skill_service() -> SkillService:
    """Resolve the shared admin skill catalog, including storage migrations."""
    from deeptutor.multi_user.paths import local_admin_user, user_context

    with user_context(local_admin_user()):
        return get_skill_service()


def get_skill_service() -> SkillService:
    from deeptutor.core.identities import is_partner_user_id
    from deeptutor.multi_user.context import get_current_user
    from deeptutor.services.workspace import get_content_workspace_service

    root = (
        get_path_service().get_workspace_dir() / "skills"
        if is_partner_user_id(get_current_user().id)
        else get_content_workspace_service().system_binding().root / "skills"
    ).resolve()
    key = str(root)
    if key not in _instances:
        _instances[key] = SkillService(root=root)
    return _instances[key]


__all__ = [
    "BUILTIN_SKILLS_ROOT",
    "InvalidSkillNameError",
    "InvalidSkillPathError",
    "InvalidTagError",
    "SkillDetail",
    "SkillExistsError",
    "SkillImportError",
    "SkillInfo",
    "SkillInstallResult",
    "SkillNotFoundError",
    "SkillReadOnlyError",
    "SkillService",
    "SkillSummaryEntry",
    "TagExistsError",
    "TagNotFoundError",
    "get_skill_service",
    "get_admin_skill_service",
    "render_skills_manifest",
]