DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"""
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",
]