agent-skilltree 0.2.0__py3-none-any.whl

skilltree/federation.py

@@ -0,0 +1,109 @@
+"""P5.4 — walk the federation: a tree of marketplaces under a root.
+
+A child marketplace joins by contributing a `registry`-kind entry to its parent's
+registry.json (pointing at the child's own registry.json). Federation is then a
+walk: from the root registry, resolve each `registry` entry to the child's
+registry and recurse — a tree of marketplaces mirroring the tree of repos.
+
+`resolve` is pluggable so this works offline: it maps a `registry` entry to a
+registry dict (a local map for tests; a fetch-by-repo-ref for the real network).
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import json
+from pathlib import Path
+from typing import Callable
+
+from .registry import load_registry, validate_registry
+
+Resolver = Callable[[dict], "dict | None"]
+
+
+def local_resolver(name_to_registry: dict[str, dict]) -> Resolver:
+    """Resolve a `registry` entry to a child registry from an in-memory/local map."""
+    def _resolve(entry: dict) -> dict | None:
+        target = name_to_registry.get(entry["name"]) or name_to_registry.get(entry.get("repo", ""))
+        if isinstance(target, (str, Path)):
+            return load_registry(target)
+        return target
+    return _resolve
+
+
+def _children(registry: dict) -> list[dict]:
+    return [e for e in registry.get("entries", []) if e.get("kind") == "registry"]
+
+
+def walk_federation(registry: dict, resolve: Resolver, *, _seen: frozenset[str] | None = None) -> dict:
+    """Return the nested federation tree rooted at `registry`."""
+    _seen = _seen or frozenset()
+    name = registry.get("name")
+    node = {
+        "name": name,
+        "entries": [e for e in registry.get("entries", []) if e.get("kind") != "registry"],
+        "children": [],
+    }
+    if name in _seen:                       # cycle guard
+        node["cycle"] = True
+        return node
+    seen = _seen | {name}
+    for entry in _children(registry):
+        child = resolve(entry)
+        if child is None:
+            node["children"].append({"name": entry["name"], "unresolved": True})
+        else:
+            node["children"].append(walk_federation(child, resolve, _seen=seen))
+    return node
+
+
+def flatten_federation(registry: dict, resolve: Resolver) -> list[dict]:
+    """Every leaf entry across the federation, tagged with the registry path it came through."""
+    out: list[dict] = []
+
+    def rec(node: dict, path: tuple[str, ...]) -> None:
+        here = path + (node["name"],)
+        for e in node.get("entries", []):
+            out.append({**e, "_path": list(here)})
+        for c in node.get("children", []):
+            if not c.get("unresolved") and not c.get("cycle"):
+                rec(c, here)
+    rec(walk_federation(registry, resolve), ())
+    return out
+
+
+def validate_federation(registry: dict, resolve: Resolver) -> list[str]:
+    """Check the federation: child schemas valid, parent backrefs consistent, no cycles."""
+    errs: list[str] = []
+
+    def rec(reg: dict, seen: frozenset[str]) -> None:
+        errs.extend(f"{reg.get('name')}: {e}" for e in validate_registry(reg))
+        if reg.get("name") in seen:
+            errs.append(f"federation cycle at {reg.get('name')!r}")
+            return
+        s = seen | {reg.get("name")}
+        for entry in _children(reg):
+            child = resolve(entry)
+            if child is None:
+                errs.append(f"{reg.get('name')}: unresolved child registry {entry['name']!r}")
+                continue
+            if child.get("parent") not in (None, reg.get("name")) and "github" not in str(child.get("parent", "")):
+                errs.append(f"{child.get('name')!r}: parent backref {child.get('parent')!r} "
+                            f"does not match {reg.get('name')!r}")
+            rec(child, s)
+    rec(registry, frozenset())
+    return errs
+
+
+def register_child(parent_path: str | Path, name: str, repo: str, *,
+                   manifest: str = "registry.json", by: str = "maintainer",
+                   now: str | None = None) -> dict:
+    """Add a `registry`-kind child to a parent registry (federation link, unverified)."""
+    p = Path(parent_path)
+    data = load_registry(p)
+    data.setdefault("entries", []).append({
+        "name": name, "kind": "registry", "repo": repo, "manifest": manifest,
+        "version": "0.1.0", "trust": "unverified",
+        "provenance": {"by": by, "at": now or _dt.datetime.now().isoformat(timespec="seconds")},
+    })
+    p.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    return data

skilltree/forest.py

@@ -0,0 +1,101 @@
+"""Make a SkillTree (or a forest of them) visible from the TOP — `~/.claude/skills`.
+
+The top-level user `.claude/skills` is scanned in every session, but the scan is
+non-recursive WITHIN a `.claude/skills` (a skill can't contain auto-loadable
+sub-skills). So to surface a tree from the top you SYMLINK its entry skill dirs
+into `~/.claude/skills`, and the `cat`-breadcrumbs carry you down from there.
+
+  - single tree  → `link_tree`: symlink the root (and its first-layer branches) up
+  - many trees   → `build_forest`: one forest-root skill that breadcrumbs to each
+                   tree's root, symlinked up — a forest view over the top.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from .model import SkillTree, skill_name
+
+_CRUMB = "- {name} ({kind}): Read `{path}`"     # the Read TOOL injects the layer, not `cat`
+
+
+def _skill_dir(node_dir: Path, name: str) -> Path:
+    return Path(node_dir) / ".claude" / "skills" / name
+
+
+def _symlink(link: Path, target: Path) -> Path:
+    link.parent.mkdir(parents=True, exist_ok=True)
+    if link.is_symlink() or link.exists():
+        link.unlink()
+    link.symlink_to(Path(target).resolve(), target_is_directory=True)
+    return link
+
+
+def link_tree(tree_dir: str | Path, *, user_skills_dir: str | Path,
+              manifest: str | Path | None = None,
+              include_root: bool = True, branches: bool = True) -> list[Path]:
+    """Symlink a single tree's entry points into the top-level user skills dir.
+
+    The root gives the overview + breadcrumbs; the branches (root's direct
+    children) are surfaced too so the first layer is reachable from the top.
+    Deeper levels stay behind `cat` (progressive disclosure).
+    """
+    tree_dir = Path(tree_dir)
+    tree = SkillTree.load(manifest or tree_dir / "skilltree.json")
+    user = Path(user_skills_dir)
+    links: list[Path] = []
+    if include_root:
+        rn = skill_name(tree.root)
+        links.append(_symlink(user / rn, _skill_dir(tree_dir, rn)))
+    if branches:
+        for child in tree.root.children:
+            cn = skill_name(child)
+            links.append(_symlink(user / cn, _skill_dir(tree_dir / child.name, cn)))
+    return links
+
+
+def build_forest(name: str, members: list[str | Path], *, user_skills_dir: str | Path,
+                 forest_dir: str | Path, description: str | None = None) -> Path:
+    """Build a forest-root skill over several trees and symlink it to the top.
+
+    `members` = tree dirs (each with a skilltree.json). The forest root's body
+    breadcrumbs to each tree's root; one top-level entry, progressive descent.
+    """
+    fdir = _skill_dir(Path(forest_dir), name)
+    fdir.mkdir(parents=True, exist_ok=True)
+    crumbs, roots = [], []
+    for tdir in members:
+        tdir = Path(tdir)
+        tree = SkillTree.load(tdir / "skilltree.json")
+        rn = skill_name(tree.root)
+        md = _skill_dir(tdir, rn) / "SKILL.md"
+        crumbs.append(_CRUMB.format(name=rn, kind=tree.root.kind, path=md.resolve()))
+        roots.append(rn)
+    desc = description or f"Forest of {len(members)} skill tree(s): {', '.join(roots)}."
+    body = (f"Forest **{name}** — {len(members)} skill tree(s). "
+            "Pick one and **Read** (the Read tool) into its root to load it, then follow its "
+            "breadcrumbs down (`cat` won't load it — only the Read tool does):\n\n" + "\n".join(crumbs))
+    (fdir / "SKILL.md").write_text(f"---\nname: {name}\ndescription: {desc}\n---\n\n{body}\n", encoding="utf-8")
+    return _symlink(Path(user_skills_dir) / name, fdir)
+
+
+def list_links(user_skills_dir: str | Path) -> list[dict]:
+    """List symlinks in the user skills dir and whether they still resolve."""
+    user = Path(user_skills_dir)
+    out: list[dict] = []
+    if user.exists():
+        for p in sorted(user.iterdir()):
+            if p.is_symlink():
+                out.append({"name": p.name, "target": str(p.readlink()), "resolves": p.exists()})
+    return out
+
+
+def unlink(user_skills_dir: str | Path, *names: str) -> list[str]:
+    """Remove named symlinks (only if they are symlinks — never deletes real dirs)."""
+    user = Path(user_skills_dir)
+    removed: list[str] = []
+    for n in names:
+        p = user / n
+        if p.is_symlink():
+            p.unlink()
+            removed.append(n)
+    return removed

skilltree/mapper.py

@@ -0,0 +1,117 @@
+"""skilltree map — render a flat folder into ONE coordinate-addressed CLAUDE.md.
+
+Folds the former `skillmap` seedling into skilltree as a module. It mirrors a folder's
+directory nesting as a tree, gives every node a hierarchical coordinate, and writes a single
+CLAUDE.md — a Folder Map + an addressable Index + branch summaries — so an agent can do
+*progressive disclosure* over a flat pile (open a branch, descend to the coordinate it needs)
+instead of loading all of it.
+
+It uses skilltree's OWN coordinate code — `assign_coords` / `skill_name` / `compose_summary`
+from `model.py`. There is no vendored copy: one source of truth for the `<coord>-<name>` scheme.
+
+    skilltree map ~/.claude/skills            # print the map
+    skilltree map ~/.claude/skills --write     # write CLAUDE.md into the folder
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from .model import TreeNode, assign_coords, compose_summary, skill_name
+
+_DESC = re.compile(r"^description:\s*(.+)$", re.I | re.M)
+
+
+def read_description(d: Path) -> str:
+    """Best-effort one-line description for a directory node: the `description:` frontmatter of
+    SKILL.md/README, else the first real line/heading of any markdown in the dir."""
+    for fn in ("SKILL.md", "README.md"):
+        f = d / fn
+        if f.is_file():
+            txt = f.read_text(encoding="utf-8", errors="ignore")
+            m = _DESC.search(txt)
+            if m:
+                return m.group(1).strip().strip("\"'")[:160]
+            for line in txt.splitlines():
+                s = line.strip()
+                if s and not s.startswith("---"):
+                    return s.lstrip("# ").strip()[:160]
+    for f in sorted(d.glob("*.md")):
+        for line in f.read_text(encoding="utf-8", errors="ignore").splitlines():
+            s = line.strip()
+            if s and not s.startswith("---"):
+                return s.lstrip("# ").strip()[:160]
+    return ""
+
+
+def build_tree(folder: str | Path) -> TreeNode:
+    """Mirror the directory nesting as skilltree `TreeNode`s. A node = a subdirectory; the dir
+    path rides in `skill_src`. Hidden dirs (dotfiles) are skipped."""
+    root_path = Path(folder)
+    root = TreeNode(name=root_path.name, kind="sc", description="(root)", skill_src=str(root_path))
+
+    def add(parent: TreeNode) -> None:
+        for d in sorted(p for p in Path(parent.skill_src).iterdir()
+                        if p.is_dir() and not p.name.startswith(".")):
+            child = TreeNode(name=d.name, kind="skill",
+                             description=read_description(d) or None, skill_src=str(d))
+            parent.children.append(child)
+            add(child)
+
+    add(root)
+    return root
+
+
+def _folder_map(root: TreeNode) -> str:
+    lines = [f"{root.coord}  {root.name}/"]
+
+    def rec(node: TreeNode, prefix: str) -> None:
+        n = len(node.children)
+        for i, c in enumerate(node.children):
+            last = i == n - 1
+            branch = "└─ " if last else "├─ "
+            desc = f"  — {c.description}" if c.description else ""
+            lines.append(f"{prefix}{branch}{c.coord}  {c.name}{desc}")
+            rec(c, prefix + ("   " if last else "│  "))
+
+    rec(root, "")
+    return "\n".join(lines)
+
+
+def _index(root: TreeNode) -> str:
+    rp = Path(root.skill_src)
+    rows = ["| Coord | Skill | Address | What it does | Path |", "|---|---|---|---|---|"]
+    for n in root.walk():
+        if n is root:
+            continue
+        rel = Path(n.skill_src).relative_to(rp)
+        rows.append(f"| `{n.coord}` | {n.name} | `{skill_name(n)}` | {n.description or '—'} | `{rel}/` |")
+    return "\n".join(rows)
+
+
+def _branches(root: TreeNode) -> str:
+    rows = [f"- `{n.coord}` **{n.name}** → {compose_summary(n)}"
+            for n in root.walk() if n.children]
+    return "\n".join(rows) or "_(flat — every skill is a leaf at depth 1)_"
+
+
+def build_map(folder: str | Path) -> str:
+    """Render the folder as ONE coordinate-addressed CLAUDE.md (Folder Map + Index + Branches)."""
+    root = assign_coords(build_tree(folder))
+    nodes = list(root.walk())
+    n_skills = len(nodes) - 1
+    depth = max((n.coord.count(".") for n in nodes), default=0)
+    return (f"# {root.name} — skill map\n\n"
+            f"*Auto-generated by `skilltree map`. {n_skills} skills, depth {depth}. Each skill has a "
+            f"coordinate address — open a branch, descend to the coordinate you need. Don't load the "
+            f"whole pile; navigate it.*\n\n"
+            f"## Folder Map\n\n```\n{_folder_map(root)}\n```\n\n"
+            f"## Index (addressable)\n\n{_index(root)}\n\n"
+            f"## Branches (what each opens to)\n\n{_branches(root)}\n")
+
+
+def write_map(folder: str | Path) -> Path:
+    """Write the map to `<folder>/CLAUDE.md`; returns the path."""
+    dest = Path(folder) / "CLAUDE.md"
+    dest.write_text(build_map(folder), encoding="utf-8")
+    return dest

skilltree/marketplace.py

@@ -0,0 +1,86 @@
+"""Marketplace — a programmatic registry for skills, trees, and exchanges.
+
+The real, local half of the roadmap's marketplace: you `publish()` an artifact to
+a registry (a JSON file), mark it `public` if you want, and `search()` it. The
+registry GROWS as artifacts are added. Whenever something is published public, a
+`notify` hook fires — that hook is where a hosted service ("our system") plugs in.
+
+Aspirational (needs a backend, not built here): the hosted marketplace endpoint
+the notify hook would POST to, and cross-user discovery.
+"""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+import datetime as _dt
+import json
+from pathlib import Path
+from typing import Callable
+
+KINDS = ("skill", "tree", "exchange")
+
+
+@dataclass
+class Entry:
+    name: str
+    kind: str
+    path: str
+    version: str = "0.1.0"
+    public: bool = False
+    published_at: str = ""
+    tags: list[str] = field(default_factory=list)
+
+
+def _load(registry: Path) -> list[dict]:
+    return json.loads(registry.read_text(encoding="utf-8")) if registry.is_file() else []
+
+
+def _save(registry: Path, rows: list[dict]) -> None:
+    registry.parent.mkdir(parents=True, exist_ok=True)
+    registry.write_text(json.dumps(rows, indent=2), encoding="utf-8")
+
+
+def publish(
+    registry: str | Path,
+    name: str,
+    path: str | Path,
+    *,
+    kind: str = "skill",
+    public: bool = False,
+    version: str = "0.1.0",
+    tags: list[str] | None = None,
+    notify: Callable[[Entry], None] | None = None,
+    now: str | None = None,
+) -> Entry:
+    """Add (or update) an artifact in the registry. Fires `notify` if it's public."""
+    if kind not in KINDS:
+        raise ValueError(f"kind must be one of {KINDS}, got {kind!r}")
+    registry = Path(registry)
+    entry = Entry(name=name, kind=kind, path=str(Path(path)), version=version, public=public,
+                  published_at=now or _dt.datetime.now().isoformat(timespec="seconds"),
+                  tags=tags or [])
+    rows = [r for r in _load(registry) if r.get("name") != name]   # upsert by name
+    rows.append(asdict(entry))
+    _save(registry, rows)
+    if public and notify is not None:
+        notify(entry)          # ← where the hosted "notify our system" service plugs in
+    return entry
+
+
+def search(registry: str | Path, query: str | None = None, *, public_only: bool = False) -> list[dict]:
+    rows = _load(Path(registry))
+    if public_only:
+        rows = [r for r in rows if r.get("public")]
+    if query:
+        q = query.lower()
+        rows = [r for r in rows if q in r["name"].lower() or any(q in t.lower() for t in r.get("tags", []))]
+    return rows
+
+
+def log_notify(log_path: str | Path) -> Callable[[Entry], None]:
+    """A local stand-in for the hosted notifier: append public publishes to a log."""
+    def _notify(entry: Entry) -> None:
+        p = Path(log_path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        with p.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(asdict(entry)) + "\n")
+    return _notify

skilltree/materialize.py

@@ -0,0 +1,88 @@
+"""Materialize a SkillTree as nested dirs wired by `cat`-breadcrumbs.
+
+The auto-loader only ever loads the ROOT (it won't descend a nested `.claude`).
+So each node's SKILL.md body carries the `cat` commands that tell you how to read
+its children — the breadcrumb links. The tree is nested dirs; traversal is manual
+`cat` following the breadcrumbs. Layout for a node N with children C1..Ck:
+
+    <N_dir>/.claude/skills/<N>/SKILL.md          # N's skill + `cat` links to each child
+    <N_dir>/<C1>/.claude/skills/<C1>/SKILL.md     # child dir is a SIBLING of N's .claude
+    <N_dir>/<C2>/...
+
+The root node's dir IS the tree root; root skill at <root>/.claude/skills/<root>/.
+Leaves carry the actual skill content (from skill_src); no further breadcrumbs.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+import shutil
+
+from .model import SkillTree, TreeNode, assign_coords, compose_summary, skill_name
+
+# A breadcrumb line is parseable by validate.py: `- <name> (<kind>): Read `<abspath>``
+# The verb is **Read** (the Read tool), NOT `cat`: only the Read tool injects a dir's
+# .claude layer — a Bash `cat` reads the bytes but loads nothing (verified 2026-06-18).
+_CRUMB = "- {name} ({kind}): Read `{path}`"
+
+
+def node_skill_md(node_dir: Path, node_name: str) -> Path:
+    return node_dir / ".claude" / "skills" / node_name / "SKILL.md"
+
+
+def _front(name: str, description: str, body: str) -> str:
+    return f"---\nname: {name}\ndescription: {description}\n---\n\n{body.rstrip()}\n"
+
+
+def _write_node(node: TreeNode, node_dir: Path, root: Path) -> None:
+    sname = skill_name(node)                      # coord-prefixed identity (or plain name)
+    skill_md = node_skill_md(node_dir, sname)
+    skill_md.parent.mkdir(parents=True, exist_ok=True)
+
+    # base body: the node's own skill content (from src) or a stub
+    if node.skill_src and (Path(node.skill_src) / "SKILL.md").exists():
+        src = (Path(node.skill_src) / "SKILL.md").read_text(encoding="utf-8")
+        # strip frontmatter from the source body; we re-emit our own
+        base = src.split("---", 2)[-1].strip() if src.lstrip().startswith("---") else src.strip()
+        desc = node.description or f"{node.kind} node {node.name}"
+    else:
+        base = f"SkillTree {node.kind} node `{node.name}`."
+        desc = node.description or f"{node.kind} node {node.name} in a SkillTree."
+    if node.children:
+        # index (branch) node: a deterministic subtree summary makes it retrievable
+        # by any descendant's terms (the RAPTOR win, no LLM).
+        if not node.description:
+            desc = compose_summary(node, full=False)
+        summary = compose_summary(node, full=True)
+        crumbs = [_CRUMB.format(name=skill_name(c), kind=c.kind,
+                                path=node_skill_md(node_dir / c.name, skill_name(c)).resolve())
+                  for c in node.children]
+        body = (f"{base}\n\n## Index summary\n{summary}\n\n"
+                f"## Descend — the next layer ({len(node.children)})\n"
+                "Only this layer is loaded now. To descend, use the **Read tool** on a child "
+                "below — that injects the child's layer (its persona + skills). A Bash `cat` "
+                "reads the bytes but loads nothing; you must use the Read tool:\n\n"
+                + "\n".join(crumbs))
+    else:
+        body = base + "\n\n_(leaf — this is an actual skill.)_"
+
+    if node.coord:
+        desc = f"[{node.coord}] {desc}"
+
+    skill_md.write_text(_front(sname, desc, body), encoding="utf-8")
+
+    # recurse: each child's dir is a sibling of this node's .claude (tree-path uses plain name)
+    for child in node.children:
+        _write_node(child, node_dir / child.name, root)
+
+
+def materialize(tree: SkillTree, root: str | Path, *, overwrite: bool = True,
+                coords: bool = False, base: str = "0") -> Path:
+    root = Path(root)
+    if coords:
+        assign_coords(tree.root, base)            # address every node before writing
+    if overwrite and root.exists():
+        shutil.rmtree(root)
+    root.mkdir(parents=True, exist_ok=True)
+    _write_node(tree.root, root, root)          # root node's dir IS the tree root
+    tree.save(root / "skilltree.json")
+    return root

skilltree/model.py

@@ -0,0 +1,114 @@
+"""SkillTree model — a tree of skill dirs wired by LINKS, not nesting.
+
+Every node is a skill dir (`<name>/SKILL.md`) of any type (ac/cor/sc/skill).
+Edges are links: each node lives in its OWN `.claude/skills/` root, and a node's
+direct children are symlinked into that root. Auto-load reaches a root + its
+direct children only — never deeper (a skill dir won't auto-load a nested
+`.claude`). To descend, you REDIRECT the active skills root to the child's root.
+
+Because the platform won't traverse this, the tree's integrity is not guaranteed
+by the filesystem — it must be validated programmatically (see validate.py).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import json
+from pathlib import Path
+
+KINDS = ("ac", "cor", "sc", "skill")
+
+
+@dataclass
+class TreeNode:
+    name: str                       # slug; also the tree-path dir name
+    kind: str = "skill"             # ac | cor | sc | skill
+    skill_src: str | None = None    # existing `<name>/SKILL.md` dir to carry as content (else a stub)
+    description: str | None = None   # SKILL.md description (so it auto-loads / is searchable)
+    coord: str | None = None         # hierarchical address (e.g. "0.1.2"); set by assign_coords
+    children: list["TreeNode"] = field(default_factory=list)
+
+    def walk(self):
+        yield self
+        for child in self.children:
+            yield from child.walk()
+
+    def edges(self):
+        for child in self.children:
+            yield (self.name, child.name)
+            yield from child.edges()
+
+
+def skill_name(node: "TreeNode") -> str:
+    """The skill's identity (frontmatter name + skill-dir name).
+
+    With a coord, it is `<coord>-<name>` — so the flat skills list is coord-sorted,
+    reveals the tree, and each node is addressable by its coordinate. The tree-PATH
+    dir stays the plain `name`; only the skill identity carries the coord.
+    """
+    return f"{node.coord}-{node.name}" if node.coord else node.name
+
+
+def compose_summary(node: "TreeNode", *, full: bool = False) -> str:
+    """A DETERMINISTIC semantic summary of an index (branch) node — a template
+    filled with its coordinate, children, and reachable descendants.
+
+    This is the RAPTOR "internal nodes carry a summary" retrieval-win, gotten for
+    free (no LLM): the branch's body becomes dense with its subtree's vocabulary,
+    so a query about any descendant matches the branch that leads to it. `full`
+    adds the flattened reachable-leaf list (for the indexed body); the short form
+    (for the description) lists just the immediate children.
+    """
+    kids = ", ".join(f"{c.name} ({c.kind})" for c in node.children) or "(none)"
+    short = f"opens to {len(node.children)} branch(es): {kids}"
+    if not full:
+        return short
+    reachable = [d.name for d in node.walk() if d is not node]
+    return (f"[{node.coord or '?'}] {node.name} — a {node.kind} index node; {short}. "
+            f"Reachable below: {', '.join(reachable)}.")
+
+
+def assign_coords(root: "TreeNode", base: str = "0") -> "TreeNode":
+    """Give every node a hierarchical coordinate: root=base, child i (1-based)=parent.i."""
+    def walk(n: "TreeNode", coord: str) -> None:
+        n.coord = coord
+        for i, child in enumerate(n.children, 1):
+            walk(child, f"{coord}.{i}")
+    walk(root, base)
+    return root
+
+
+@dataclass
+class SkillTree:
+    root: TreeNode
+
+    # ---- manifest (source of truth for validation) ----
+    def to_manifest(self) -> dict:
+        def enc(n: TreeNode) -> dict:
+            return {"name": n.name, "kind": n.kind, "skill_src": n.skill_src,
+                    "description": n.description, "coord": n.coord,
+                    "children": [enc(c) for c in n.children]}
+        return {"skilltree": enc(self.root)}
+
+    @staticmethod
+    def from_manifest(data: dict) -> "SkillTree":
+        def dec(d: dict) -> TreeNode:
+            return TreeNode(name=d["name"], kind=d.get("kind", "skill"),
+                            skill_src=d.get("skill_src"), description=d.get("description"),
+                            coord=d.get("coord"),
+                            children=[dec(c) for c in d.get("children", [])])
+        return SkillTree(dec(data["skilltree"]))
+
+    def save(self, path: str | Path) -> Path:
+        p = Path(path)
+        p.write_text(json.dumps(self.to_manifest(), indent=2), encoding="utf-8")
+        return p
+
+    @staticmethod
+    def load(path: str | Path) -> "SkillTree":
+        return SkillTree.from_manifest(json.loads(Path(path).read_text(encoding="utf-8")))
+
+    def nodes(self) -> list[TreeNode]:
+        return list(self.root.walk())
+
+    def edges(self) -> list[tuple[str, str]]:
+        return list(self.root.edges())