agent-skilltree 0.3.0__tar.gz → 0.4.0__tar.gz

{agent_skilltree-0.3.0/src/agent_skilltree.egg-info → agent_skilltree-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-skilltree
-Version: 0.3.0
+Version: 0.4.0
 Summary: A coordinate-addressed tree of agent skill dirs wired by Read-tool breadcrumbs, with programmatic validation.
 Author: Isaac Wostrel-Rubin
 License: MIT
@@ -83,9 +83,10 @@ One CLI for the whole skill-substrate toolkit — `skilltree <command> …`:
 | `map <folder> [--write]` | render a flat folder into **one** coordinate-addressed `CLAUDE.md` (Folder Map + addressable Index + branch summaries) — progressive disclosure over a flat pile |
 | `search <folder> <query> [--scope <coord>]` | FTS5/BM25 over **any** folder; `--scope` restricts to a coordinate subtree when the folder carries skilltree coordinates (a plain folder = coordinate-free search) |
 | `fold <framework_dir> --into <node> --tree <root>` | **bind** a framework (its skill dir) into a volume node's `## Frameworks` tome table — idempotent, one row per framework; the manifest is the source of truth and the node's SKILL.md is regenerated from it |
-| `project <root> <target> [--policy flat\|progressive] [--link absolute\|relative] [--node N]` | **deploy** a tree into a skills dir as symlinks: `progressive` surfaces root + first-layer branches (the former `link_tree`); `flat` projects a volume's tome rows + holder so every held framework auto-discovers top-level (the former nomicon-atomize) |
+| `project <root> <target> [--policy flat\|progressive] [--link absolute\|relative] [--node N]` | **deploy** a tree into a skills dir as symlinks: `progressive` surfaces root + first-layer branches (the former `link_tree`); `flat` projects a volume's tome rows + holder so every held framework auto-discovers top-level (the former nomicon-atomize). Projecting is an install, so it localizes the tree's breadcrumbs first |
+| `relink <root> [--localize]` | rewrite only the breadcrumb paths: **portable** (the default and the shipped form — relative to each node's folder, no machine's path in any file) or `--localize` (absolute for this machine — the install-time step) |
 | `cohere <root>` | report drift between the on-disk tree and its coherent shape |
-| `emit <root> [--root-forest]` | re-cohere in place; `--root-forest` tree-ifies a bare forest (lossless, journaled) |
+| `emit <root> [--root-forest] [--localize]` | re-cohere in place; `--root-forest` tree-ifies a bare forest (lossless, journaled); breadcrumbs portable unless `--localize` |
 | `unemit <root>` | reverse the last `emit`, byte-for-byte |
 | `discover` · `validate` · `build` · `notify` · `watch` | read a tree · gate breadcrumb-resolvability · materialize from a manifest · write the notification rule · run the decoherence cron |
 
@@ -130,6 +131,12 @@ Two papers document the project:
 
 ## Changelog
 
+### v0.4.0 — 2026-10-23
+- **Trees ship portable.** Every breadcrumb names its child relative to the node's folder (the folder holding the SKILL.md's `.claude/`), and the manifest stores `skill_src` relative to itself, so a materialized tree carries no machine's path and validates wherever it is copied — with no step. `materialize`, `emit` and `exchange build` take `localize=True` (`--localize`) to write absolute paths for one machine; the new `relink` rewrites only the paths, either way; `project` localizes the tree it projects (a projected tree is read through a symlink, where only an absolute path resolves). `validate` accepts both forms. 80 tests (7 new, in `tests/test_portable.py`).
+- **Developed in one source home and published here.** This repository and PyPI `agent-skilltree` are the published output of SkillTree's source home; changes arrive as releases, each with a version and an entry here.
+- Frontmatter quotes YAML-unsafe scalars (#1), merged after 0.3.0 and not yet released.
+- The figure script writes beside itself instead of to a fixed folder; a test comment names the author by role.
+
 ### v0.3.0 — 2026-07-09
 - **The tome bind ops (SkillVolume/SkillTome).** A node can now HOLD frameworks: `TreeNode.frameworks`
   rows live in the manifest and render as a generated `## Frameworks` pointer-table (`| Framework |

{agent_skilltree-0.3.0 → agent_skilltree-0.4.0}/README.md

@@ -69,9 +69,10 @@ One CLI for the whole skill-substrate toolkit — `skilltree <command> …`:
 | `map <folder> [--write]` | render a flat folder into **one** coordinate-addressed `CLAUDE.md` (Folder Map + addressable Index + branch summaries) — progressive disclosure over a flat pile |
 | `search <folder> <query> [--scope <coord>]` | FTS5/BM25 over **any** folder; `--scope` restricts to a coordinate subtree when the folder carries skilltree coordinates (a plain folder = coordinate-free search) |
 | `fold <framework_dir> --into <node> --tree <root>` | **bind** a framework (its skill dir) into a volume node's `## Frameworks` tome table — idempotent, one row per framework; the manifest is the source of truth and the node's SKILL.md is regenerated from it |
-| `project <root> <target> [--policy flat\|progressive] [--link absolute\|relative] [--node N]` | **deploy** a tree into a skills dir as symlinks: `progressive` surfaces root + first-layer branches (the former `link_tree`); `flat` projects a volume's tome rows + holder so every held framework auto-discovers top-level (the former nomicon-atomize) |
+| `project <root> <target> [--policy flat\|progressive] [--link absolute\|relative] [--node N]` | **deploy** a tree into a skills dir as symlinks: `progressive` surfaces root + first-layer branches (the former `link_tree`); `flat` projects a volume's tome rows + holder so every held framework auto-discovers top-level (the former nomicon-atomize). Projecting is an install, so it localizes the tree's breadcrumbs first |
+| `relink <root> [--localize]` | rewrite only the breadcrumb paths: **portable** (the default and the shipped form — relative to each node's folder, no machine's path in any file) or `--localize` (absolute for this machine — the install-time step) |
 | `cohere <root>` | report drift between the on-disk tree and its coherent shape |
-| `emit <root> [--root-forest]` | re-cohere in place; `--root-forest` tree-ifies a bare forest (lossless, journaled) |
+| `emit <root> [--root-forest] [--localize]` | re-cohere in place; `--root-forest` tree-ifies a bare forest (lossless, journaled); breadcrumbs portable unless `--localize` |
 | `unemit <root>` | reverse the last `emit`, byte-for-byte |
 | `discover` · `validate` · `build` · `notify` · `watch` | read a tree · gate breadcrumb-resolvability · materialize from a manifest · write the notification rule · run the decoherence cron |
 
@@ -116,6 +117,12 @@ Two papers document the project:
 
 ## Changelog
 
+### v0.4.0 — 2026-10-23
+- **Trees ship portable.** Every breadcrumb names its child relative to the node's folder (the folder holding the SKILL.md's `.claude/`), and the manifest stores `skill_src` relative to itself, so a materialized tree carries no machine's path and validates wherever it is copied — with no step. `materialize`, `emit` and `exchange build` take `localize=True` (`--localize`) to write absolute paths for one machine; the new `relink` rewrites only the paths, either way; `project` localizes the tree it projects (a projected tree is read through a symlink, where only an absolute path resolves). `validate` accepts both forms. 80 tests (7 new, in `tests/test_portable.py`).
+- **Developed in one source home and published here.** This repository and PyPI `agent-skilltree` are the published output of SkillTree's source home; changes arrive as releases, each with a version and an entry here.
+- Frontmatter quotes YAML-unsafe scalars (#1), merged after 0.3.0 and not yet released.
+- The figure script writes beside itself instead of to a fixed folder; a test comment names the author by role.
+
 ### v0.3.0 — 2026-07-09
 - **The tome bind ops (SkillVolume/SkillTome).** A node can now HOLD frameworks: `TreeNode.frameworks`
   rows live in the manifest and render as a generated `## Frameworks` pointer-table (`| Framework |

{agent_skilltree-0.3.0 → agent_skilltree-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-skilltree"
-version = "0.3.0"
+version = "0.4.0"
 description = "A coordinate-addressed tree of agent skill dirs wired by Read-tool breadcrumbs, with programmatic validation."
 readme = "README.md"
 license = { text = "MIT" }

{agent_skilltree-0.3.0 → agent_skilltree-0.4.0/src/agent_skilltree.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-skilltree
-Version: 0.3.0
+Version: 0.4.0
 Summary: A coordinate-addressed tree of agent skill dirs wired by Read-tool breadcrumbs, with programmatic validation.
 Author: Isaac Wostrel-Rubin
 License: MIT
@@ -83,9 +83,10 @@ One CLI for the whole skill-substrate toolkit — `skilltree <command> …`:
 | `map <folder> [--write]` | render a flat folder into **one** coordinate-addressed `CLAUDE.md` (Folder Map + addressable Index + branch summaries) — progressive disclosure over a flat pile |
 | `search <folder> <query> [--scope <coord>]` | FTS5/BM25 over **any** folder; `--scope` restricts to a coordinate subtree when the folder carries skilltree coordinates (a plain folder = coordinate-free search) |
 | `fold <framework_dir> --into <node> --tree <root>` | **bind** a framework (its skill dir) into a volume node's `## Frameworks` tome table — idempotent, one row per framework; the manifest is the source of truth and the node's SKILL.md is regenerated from it |
-| `project <root> <target> [--policy flat\|progressive] [--link absolute\|relative] [--node N]` | **deploy** a tree into a skills dir as symlinks: `progressive` surfaces root + first-layer branches (the former `link_tree`); `flat` projects a volume's tome rows + holder so every held framework auto-discovers top-level (the former nomicon-atomize) |
+| `project <root> <target> [--policy flat\|progressive] [--link absolute\|relative] [--node N]` | **deploy** a tree into a skills dir as symlinks: `progressive` surfaces root + first-layer branches (the former `link_tree`); `flat` projects a volume's tome rows + holder so every held framework auto-discovers top-level (the former nomicon-atomize). Projecting is an install, so it localizes the tree's breadcrumbs first |
+| `relink <root> [--localize]` | rewrite only the breadcrumb paths: **portable** (the default and the shipped form — relative to each node's folder, no machine's path in any file) or `--localize` (absolute for this machine — the install-time step) |
 | `cohere <root>` | report drift between the on-disk tree and its coherent shape |
-| `emit <root> [--root-forest]` | re-cohere in place; `--root-forest` tree-ifies a bare forest (lossless, journaled) |
+| `emit <root> [--root-forest] [--localize]` | re-cohere in place; `--root-forest` tree-ifies a bare forest (lossless, journaled); breadcrumbs portable unless `--localize` |
 | `unemit <root>` | reverse the last `emit`, byte-for-byte |
 | `discover` · `validate` · `build` · `notify` · `watch` | read a tree · gate breadcrumb-resolvability · materialize from a manifest · write the notification rule · run the decoherence cron |
 
@@ -130,6 +131,12 @@ Two papers document the project:
 
 ## Changelog
 
+### v0.4.0 — 2026-10-23
+- **Trees ship portable.** Every breadcrumb names its child relative to the node's folder (the folder holding the SKILL.md's `.claude/`), and the manifest stores `skill_src` relative to itself, so a materialized tree carries no machine's path and validates wherever it is copied — with no step. `materialize`, `emit` and `exchange build` take `localize=True` (`--localize`) to write absolute paths for one machine; the new `relink` rewrites only the paths, either way; `project` localizes the tree it projects (a projected tree is read through a symlink, where only an absolute path resolves). `validate` accepts both forms. 80 tests (7 new, in `tests/test_portable.py`).
+- **Developed in one source home and published here.** This repository and PyPI `agent-skilltree` are the published output of SkillTree's source home; changes arrive as releases, each with a version and an entry here.
+- Frontmatter quotes YAML-unsafe scalars (#1), merged after 0.3.0 and not yet released.
+- The figure script writes beside itself instead of to a fixed folder; a test comment names the author by role.
+
 ### v0.3.0 — 2026-07-09
 - **The tome bind ops (SkillVolume/SkillTome).** A node can now HOLD frameworks: `TreeNode.frameworks`
   rows live in the manifest and render as a generated `## Frameworks` pointer-table (`| Framework |

{agent_skilltree-0.3.0 → agent_skilltree-0.4.0}/src/agent_skilltree.egg-info/SOURCES.txt

@@ -33,6 +33,7 @@ tests/test_glyph_search.py
 tests/test_mapper.py
 tests/test_marketplace.py
 tests/test_notifications.py
+tests/test_portable.py
 tests/test_registry.py
 tests/test_reports.py
 tests/test_search.py

{agent_skilltree-0.3.0 → agent_skilltree-0.4.0}/src/skilltree/cli.py

@@ -55,11 +55,14 @@ def cohere_cmd(root: Path) -> None:
 @click.argument("root", type=click.Path(exists=True, file_okay=False, path_type=Path))
 @click.option("--root-forest", is_flag=True, help="tree-ify a bare forest (synthesize + save a root)")
 @click.option("--name", "forest_name", default=None, help="name for the synthesized root")
-def emit_cmd(root: Path, root_forest: bool, forest_name: str | None) -> None:
+@click.option("--localize", is_flag=True,
+              help="write breadcrumbs absolute for THIS machine (install time); default is portable")
+def emit_cmd(root: Path, root_forest: bool, forest_name: str | None, localize: bool) -> None:
     """Re-cohere IN PLACE: reassign coords + rewrite breadcrumbs/index from the
-    canonical shape (non-destructive). With --root-forest, root a bare forest."""
+    canonical shape (non-destructive). With --root-forest, root a bare forest.
+    Breadcrumbs are portable (relative to each node's folder) unless --localize."""
     from .cohere import emit
-    report = emit(root, root_forest=root_forest, forest_name=forest_name)
+    report = emit(root, root_forest=root_forest, forest_name=forest_name, localize=localize)
     if not report.get("ok"):
         click.echo(f"✗ {report.get('error')}")
         raise SystemExit(1)
@@ -70,6 +73,21 @@ def emit_cmd(root: Path, root_forest: bool, forest_name: str | None) -> None:
         click.echo(f"  journal: {report['journal']}  (reverse with `skilltree unemit`)")
 
 
+@main.command(name="relink")
+@click.argument("root", type=click.Path(exists=True, file_okay=False, path_type=Path))
+@click.option("--localize", is_flag=True, help="absolute paths for THIS machine (install time)")
+def relink_cmd(root: Path, localize: bool) -> None:
+    """Rewrite only the breadcrumb paths, in place: portable (the shipped form, relative to
+    each node's folder) or --localize (absolute, the install-time step). Nothing else moves."""
+    from .cohere import relink
+    report = relink(root, localize=localize)
+    if not report.get("ok"):
+        click.echo(f"✗ {report.get('error')}")
+        raise SystemExit(1)
+    form = "localized (absolute)" if localize else "portable (relative)"
+    click.echo(f"✓ relinked {report['nodes']} node(s): {form}")
+
+
 @main.command(name="unemit")
 @click.argument("root", type=click.Path(exists=True, file_okay=False, path_type=Path))
 def unemit_cmd(root: Path) -> None:
@@ -216,10 +234,12 @@ def reports_cmd(reports_path, kind):
 @main.command(name="build")
 @click.argument("manifest", type=click.Path(exists=True, dir_okay=False, path_type=Path))
 @click.argument("root", type=click.Path(path_type=Path))
-def build_cmd(manifest: Path, root: Path) -> None:
+@click.option("--localize", is_flag=True,
+              help="write breadcrumbs absolute for THIS machine; default is portable")
+def build_cmd(manifest: Path, root: Path, localize: bool) -> None:
     """Materialize a SkillTree from a JSON MANIFEST into ROOT, then validate."""
     tree = SkillTree.load(manifest)
-    materialize(tree, root)
+    materialize(tree, root, localize=localize)
     issues = validate(root)
     errors = [v for v in issues if v.severity == "error"]
     click.echo(f"built {len(tree.nodes())} nodes at {root}")
@@ -276,7 +296,8 @@ def fold_cmd(framework_dir: Path, into: str, tree_root: Path, what_for: str | No
 @click.option("--node", default=None, help="(flat) the volume node to project (name or coord; default root)")
 def project_cmd(tree_root: Path, target: Path, policy: str, link: str, node: str | None) -> None:
     """Project TREE_ROOT into TARGET (a skills dir) as symlinks — progressive
-    disclosure, or a volume's flat auto-discoverable deployment."""
+    disclosure, or a volume's flat auto-discoverable deployment. Projecting is an install:
+    TREE_ROOT's breadcrumbs are localized (absolute) for this machine first."""
     from .forest import project
     links = project(tree_root, target, policy=policy, link=link, node=node)
     click.echo(f"✓ projected {len(links)} link(s) ({policy}, {link}) into {target}")

{agent_skilltree-0.3.0 → agent_skilltree-0.4.0}/src/skilltree/cohere.py

@@ -24,7 +24,8 @@ import shutil
 from dataclasses import dataclass, field
 from pathlib import Path
 
-from .model import SkillTree, TreeNode, assign_coords, compose_summary, skill_name, tome_table
+from .model import (PORTABLE_NOTE, SkillTree, TreeNode, assign_coords, compose_summary, crumb_path,
+                    skill_name, tome_table)
 
 # dirs that are never tree nodes
 _SKIP = {".claude", "kb", "__pycache__", ".git", "node_modules", ".aios.src"}
@@ -217,7 +218,7 @@ def cohere(root: str | Path) -> list[Finding]:
 
 
 # ── emit: rewrite coords + breadcrumbs + index IN PLACE (non-destructive) ─────
-def _rewrite_node_md(smd: Path, node: TreeNode, node_dir: Path) -> None:
+def _rewrite_node_md(smd: Path, node: TreeNode, node_dir: Path, localize: bool = False) -> None:
     """Refresh ONLY the coord prefix + Index/Descend sections of an existing
     SKILL.md, preserving the hand-written body above them. Creates the file (a
     stub) if absent (e.g. a freshly synthesized forest root)."""
@@ -245,13 +246,15 @@ def _rewrite_node_md(smd: Path, node: TreeNode, node_dir: Path) -> None:
     if node.children:
         crumbs = [_CRUMB.format(
             name=skill_name(c), kind=c.kind,
-            path=(node_dir / c.name / ".claude" / "skills" / skill_name(c) / "SKILL.md").resolve())
+            path=crumb_path(node_dir / c.name / ".claude" / "skills" / skill_name(c) / "SKILL.md",
+                            node_dir, localize=localize))
             for c in node.children]
         tail = (f"\n\n## Index summary\n{compose_summary(node, full=True)}\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. A Bash `cat` reads the bytes but loads "
-                "nothing; you must use the Read tool:\n\n" + "\n".join(crumbs))
+                "nothing; you must use the Read tool."
+                + ("" if localize else f" {PORTABLE_NOTE}") + "\n\n" + "\n".join(crumbs))
     else:
         tail = ""
     if node.frameworks:                     # regenerate the tome table from the model rows
@@ -260,11 +263,47 @@ def _rewrite_node_md(smd: Path, node: TreeNode, node_dir: Path) -> None:
     smd.write_text(out, encoding="utf-8")
 
 
+def relink(root: str | Path, *, localize: bool = False) -> dict:
+    """Rewrite ONLY the breadcrumb paths of a materialized tree, in place: PORTABLE (relative
+    to each node's folder — the shipped form) or LOCALIZED (absolute for this machine — the
+    install-time step). Coords, names, bodies and tome tables are untouched."""
+    root = Path(root)
+    manifest = root / "skilltree.json"
+    if not manifest.is_file():
+        return {"ok": False, "error": f"no skilltree.json manifest at {root}"}
+    tree = SkillTree.load(manifest)
+    n = 0
+
+    def walk(node: TreeNode, node_dir: Path) -> None:
+        nonlocal n
+        smd = node_dir / ".claude" / "skills" / skill_name(node) / "SKILL.md"
+        if node.children and smd.is_file():
+            text = smd.read_text(encoding="utf-8")
+            for c in node.children:
+                child_md = node_dir / c.name / ".claude" / "skills" / skill_name(c) / "SKILL.md"
+                pat = re.compile(r"^(- " + re.escape(skill_name(c)) + r" \(" + re.escape(c.kind)
+                                 + r"\): Read `)[^`]+(`)", re.M)
+                path = crumb_path(child_md, node_dir, localize=localize)
+                text = pat.sub(lambda m: m.group(1) + path + m.group(2), text)
+            text = text.replace("you must use the Read tool:", "you must use the Read tool.")
+            text = text.replace(" " + PORTABLE_NOTE, "")
+            if not localize:
+                text = text.replace("you must use the Read tool.",
+                                    "you must use the Read tool. " + PORTABLE_NOTE, 1)
+            smd.write_text(text, encoding="utf-8")
+            n += 1
+        for c in node.children:
+            walk(c, node_dir / c.name)
+
+    walk(tree.root, root)
+    return {"ok": True, "nodes": n, "localized": localize}
+
+
 JOURNAL = ".emit-journal.json"   # the reversibility receipt written by a tree-ifying emit
 
 
 def emit(root: str | Path, *, root_forest: bool = False,
-         forest_name: str | None = None) -> dict:
+         forest_name: str | None = None, localize: bool = False) -> dict:
     """Re-cohere the tree IN PLACE: assign coords + rewrite every node's
     breadcrumbs/index from the canonical shape, without destroying content.
 
@@ -272,7 +311,10 @@ def emit(root: str | Path, *, root_forest: bool = False,
     a root, and **tree-ify it**: each flat leaf is MOVED WHOLESALE into its nested
     node-dir (all its files preserved — *not* a body-only re-render), so it stops
     auto-loading. Every move is JOURNALED to `.emit-journal.json` so `unemit` can
-    reverse it exactly (your cache-for-reversibility requirement)."""
+    reverse it exactly (your cache-for-reversibility requirement).
+
+    Breadcrumbs are written PORTABLE (relative to each node's folder) unless `localize=True`,
+    which writes them absolute for the place the tree is installed — the install-time step."""
     root = Path(root)
     manifest = root / "skilltree.json"
     synthesized = False
@@ -311,10 +353,10 @@ def emit(root: str | Path, *, root_forest: bool = False,
                 journal.append({"op": "move", "from": str(old_src), "to": str(target_dir),
                                 "skill_md": orig})
                 shutil.move(str(old_src), str(target_dir))
-            _rewrite_node_md(target_dir / "SKILL.md", node, node_dir)
+            _rewrite_node_md(target_dir / "SKILL.md", node, node_dir, localize)
         else:
             existed = (target_dir / "SKILL.md").exists()
-            _rewrite_node_md(target_dir / "SKILL.md", node, node_dir)
+            _rewrite_node_md(target_dir / "SKILL.md", node, node_dir, localize)
             if synthesized and not existed:        # a freshly-created node (the synth root)
                 journal.append({"op": "create", "path": str(target_dir)})
         n += 1

{agent_skilltree-0.3.0 → agent_skilltree-0.4.0}/src/skilltree/exchange.py

@@ -63,30 +63,35 @@ def _front(name: str, description: str, body: str) -> str:
     return f"---\nname: {name}\ndescription: {description}\n---\n\n{body.rstrip()}\n"
 
 
-def build(exchange: Exchange, repo_dir: str | Path) -> Path:
-    """Materialize every member tree + the master. Returns the master SKILL.md path."""
+def build(exchange: Exchange, repo_dir: str | Path, *, localize: bool = False) -> Path:
+    """Materialize every member tree + the master. Returns the master SKILL.md path.
+    Breadcrumbs are portable (relative to the repo) unless `localize=True`."""
     repo = Path(repo_dir)
     members: list[tuple[str, Path]] = []   # (member name, member root SKILL.md)
     for m in exchange.trees:
         tree = SkillTree.load((exchange.base / m.manifest).resolve())
         tree_dir = repo / "trees" / m.name
-        materialize(tree, tree_dir)
+        materialize(tree, tree_dir, localize=localize)
         members.append((m.name, node_skill_md(tree_dir, tree.root.name).resolve()))
 
     master_md = node_skill_md(repo, exchange.master)
     master_md.parent.mkdir(parents=True, exist_ok=True)
-    crumbs = [f"- {name} (tree): Read `{root_md}`" for name, root_md in members]
+    from .model import PORTABLE_NOTE, crumb_path
+    crumbs = [f"- {name} (tree): Read `{crumb_path(root_md, repo, localize=localize)}`"
+              for name, root_md in members]
     body = (f"Master of the **{exchange.name}** exchange — {len(members)} skill tree(s).\n\n"
             "## Trees — pick one and **Read** (the Read tool) into its root\n"
             "Only this master is loaded. Read a tree's root below to load it (a Bash `cat` won't); "
-            "each tree then walks its own breadcrumbs:\n\n"
+            "each tree then walks its own breadcrumbs." + ("" if localize else f" {PORTABLE_NOTE}")
+            + "\n\n"
             + "\n".join(crumbs))
     master_md.write_text(_front(exchange.master, f"master of the {exchange.name} exchange", body),
                          encoding="utf-8")
 
     (repo / "exchange.lock.json").write_text(json.dumps(
         {"name": exchange.name, "master": exchange.master,
-         "trees": [{"name": n, "root": str(r)} for n, r in members]}, indent=2), encoding="utf-8")
+         "trees": [{"name": n, "root": crumb_path(r, repo, localize=localize)} for n, r in members]},
+        indent=2), encoding="utf-8")
     return master_md
 
 
@@ -104,7 +109,8 @@ def validate(repo_dir: str | Path, exchange: Exchange) -> list[Violation]:
         return out
     if not _has_frontmatter(master_md):
         out.append(Violation("error", exchange.master, "master SKILL.md lacks frontmatter"))
-    found = {Path(p).resolve() for p in _CRUMB_RE.findall(master_md.read_text(encoding="utf-8"))}
+    found = {(Path(p) if Path(p).is_absolute() else repo / p).resolve()
+             for p in _CRUMB_RE.findall(master_md.read_text(encoding="utf-8"))}
     expected = {
         node_skill_md(repo / "trees" / m.name, SkillTree.load((exchange.base / m.manifest).resolve()).root.name).resolve()
         for m in exchange.trees

{agent_skilltree-0.3.0 → agent_skilltree-0.4.0}/src/skilltree/forest.py

@@ -65,6 +65,13 @@ def project(tree_dir: str | Path, target: str | Path, *,
     overwrites cleanly (idempotent). Self-clobber-guarded skips return no link.
     """
     tree_dir = Path(tree_dir)
+    # A projected tree is read THROUGH a symlink, where only an absolute breadcrumb resolves —
+    # so projecting is an install: localize the tree's breadcrumbs for this machine first.
+    # (A committed copy localized this way names this machine until `skilltree emit` is run
+    # again without --localize; the publishing gate refuses machine paths.)
+    if (tree_dir / "skilltree.json").is_file():
+        from .cohere import relink
+        relink(tree_dir, localize=True)
     tree = SkillTree.load(manifest or tree_dir / "skilltree.json")
     target = Path(target)
     rel = link == "relative"
@@ -143,7 +150,8 @@ def build_forest(name: str, members: list[str | Path], *, user_skills_dir: str |
     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")
+    from .materialize import _yaml_scalar as _ys
+    (fdir / "SKILL.md").write_text(f"---\nname: {_ys(name)}\ndescription: {_ys(desc)}\n---\n\n{body}\n", encoding="utf-8")
     return _symlink(Path(user_skills_dir) / name, fdir)
 
 

{agent_skilltree-0.3.0 → agent_skilltree-0.4.0}/src/skilltree/materialize.py

@@ -14,12 +14,15 @@ Leaves carry the actual skill content (from skill_src); no further breadcrumbs.
 """
 from __future__ import annotations
 
+import re
 from pathlib import Path
 import shutil
 
-from .model import SkillTree, TreeNode, assign_coords, compose_summary, skill_name, tome_table
+from .model import (PORTABLE_NOTE, SkillTree, TreeNode, assign_coords, compose_summary, crumb_path,
+                    skill_name, tome_table)
 
-# A breadcrumb line is parseable by validate.py: `- <name> (<kind>): Read `<abspath>``
+# A breadcrumb line is parseable by validate.py: `- <name> (<kind>): Read `<path>`` — the path
+# portable (relative to the node's folder) or localized (absolute); see model.crumb_path.
 # 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}`"
@@ -29,11 +32,24 @@ def node_skill_md(node_dir: Path, node_name: str) -> Path:
     return node_dir / ".claude" / "skills" / node_name / "SKILL.md"
 
 
+def _yaml_scalar(v: str) -> str:
+    """Quote a frontmatter value when bare YAML would misparse it — e.g. a
+    coord-prefixed description `[0.8.4] …` reads as a flow sequence and
+    strict parsers reject the whole file (issue #1). json.dumps yields a
+    valid YAML double-quoted scalar."""
+    import json as _json
+    if re.match(r"[\[\{&*!|>%@`'\"]", v) or ": " in v or v.startswith("- "):
+        return _json.dumps(v)
+    return v
+
+
 def _front(name: str, description: str, body: str) -> str:
-    return f"---\nname: {name}\ndescription: {description}\n---\n\n{body.rstrip()}\n"
+    return (f"---\nname: {_yaml_scalar(name)}\n"
+            f"description: {_yaml_scalar(description)}\n---\n\n"
+            f"{body.rstrip()}\n")
 
 
-def _write_node(node: TreeNode, node_dir: Path, root: Path) -> None:
+def _write_node(node: TreeNode, node_dir: Path, root: Path, localize: bool = False) -> 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)
@@ -54,13 +70,15 @@ def _write_node(node: TreeNode, node_dir: Path, root: Path) -> None:
             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())
+                                path=crumb_path(node_skill_md(node_dir / c.name, skill_name(c)),
+                                                node_dir, localize=localize))
                   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"
+                "reads the bytes but loads nothing; you must use the Read tool."
+                + ("" if localize else f" {PORTABLE_NOTE}") + "\n\n"
                 + "\n".join(crumbs))
     else:
         body = base + "\n\n_(leaf — this is an actual skill.)_"
@@ -78,17 +96,19 @@ def _write_node(node: TreeNode, node_dir: Path, root: Path) -> None:
 
     # 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)
+        _write_node(child, node_dir / child.name, root, localize)
 
 
 def materialize(tree: SkillTree, root: str | Path, *, overwrite: bool = True,
-                coords: bool = False, base: str = "0") -> Path:
+                coords: bool = False, base: str = "0", localize: bool = False) -> Path:
+    """Write the tree as nested dirs. Breadcrumbs are PORTABLE by default (relative to each
+    node's folder — no machine's path in any file); `localize=True` writes them absolute."""
     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
+    _write_node(tree.root, root, root, localize)  # root node's dir IS the tree root
     tree.save(root / "skilltree.json")
     return root

{agent_skilltree-0.3.0 → agent_skilltree-0.4.0}/src/skilltree/model.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass, field
 import json
+import os
 from pathlib import Path
 
 KINDS = ("ac", "cor", "sc", "skill")
@@ -71,6 +72,21 @@ def compose_summary(node: "TreeNode", *, full: bool = False) -> str:
             f"Reachable below: {', '.join(reachable)}.")
 
 
+# A breadcrumb names its child's SKILL.md one of two ways. PORTABLE (the default): relative to
+# the node's folder — the folder that holds this SKILL.md's `.claude/` — so a tree carries no
+# machine's path and validates wherever it is copied. LOCALIZED: absolute, for a tree that is
+# installed or projected (read through a symlink, where only an absolute path resolves).
+PORTABLE_NOTE = ("Each path below is relative to this node's folder — the folder that holds this "
+                 "file's `.claude/` — so join it to that folder before you Read it.")
+
+
+def crumb_path(child_md: Path, node_dir: Path, *, localize: bool = False) -> str:
+    """The path a breadcrumb names (see PORTABLE_NOTE)."""
+    if localize:
+        return str(Path(child_md).resolve())
+    return Path(os.path.relpath(os.path.abspath(child_md), os.path.abspath(node_dir))).as_posix()
+
+
 TOME_HEADING = "## Frameworks"
 
 
@@ -138,13 +154,32 @@ class SkillTree:
         return SkillTree(dec(data["skilltree"]))
 
     def save(self, path: str | Path) -> Path:
+        """Write the manifest. Every `skill_src` is stored RELATIVE to the manifest's own
+        folder, so a committed manifest names no machine's path; `load` resolves it back."""
         p = Path(path)
-        p.write_text(json.dumps(self.to_manifest(), indent=2), encoding="utf-8")
+        data = self.to_manifest()
+        base = os.path.abspath(p.parent)
+
+        def rel(d: dict) -> None:
+            s = d.get("skill_src")
+            if s and os.path.isabs(s):
+                d["skill_src"] = Path(os.path.relpath(os.path.abspath(s), base)).as_posix()
+            for c in d.get("children", []):
+                rel(c)
+        rel(data["skilltree"])
+        p.write_text(json.dumps(data, 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")))
+        """Read a manifest; a relative `skill_src` resolves against the manifest's folder."""
+        p = Path(path)
+        tree = SkillTree.from_manifest(json.loads(p.read_text(encoding="utf-8")))
+        base = os.path.abspath(p.parent)
+        for n in tree.root.walk():
+            if n.skill_src and not os.path.isabs(n.skill_src):
+                n.skill_src = os.path.normpath(os.path.join(base, n.skill_src))
+        return tree
 
     def nodes(self) -> list[TreeNode]:
         return list(self.root.walk())

{agent_skilltree-0.3.0 → agent_skilltree-0.4.0}/src/skilltree/validate.py

@@ -23,7 +23,8 @@ import re
 
 from .model import KINDS, TOME_HEADING, SkillTree, TreeNode, skill_name
 
-# a breadcrumb is `- <name> (<kind>): Read `<abspath>`` — match the backticked SKILL.md path
+# a breadcrumb is `- <name> (<kind>): Read `<path>`` — match the backticked SKILL.md path;
+# the path is relative to the node's folder (portable) or absolute (localized)
 # (verb-agnostic, so it survives wording tweaks; the verb is the Read tool, never `cat`)
 _CRUMB_RE = re.compile(r"`([^`]+/SKILL\.md)`")
 # a tome-table data row: `| name | what-for | name (path) |` (skip header/separator rows)
@@ -64,7 +65,9 @@ def _walk(node: TreeNode, node_dir: Path, out: list[Violation]) -> None:
 
     if node.children:
         text = skill_md.read_text(encoding="utf-8")
-        found = {Path(m).resolve() for m in _CRUMB_RE.findall(text)}
+        # a portable breadcrumb is relative to the node's folder; a localized one is absolute
+        found = {(Path(m) if Path(m).is_absolute() else node_dir / m).resolve()
+                 for m in _CRUMB_RE.findall(text)}
         expected = {_skill_md(node_dir / c.name, skill_name(c)).resolve() for c in node.children}
         for missing in expected - found:
             out.append(Violation("error", node.name, f"no Read breadcrumb for child → {missing}"))

{agent_skilltree-0.3.0 → agent_skilltree-0.4.0}/tests/test_cohere.py

@@ -107,7 +107,7 @@ def test_mixed_coord_flat_forest_is_still_a_bare_forest(tmp_path):
 def test_emit_is_lossless_and_reversible(tmp_path):
     """emit moves the WHOLE skill dir (baggage preserved, unlike the old body-only
     re-render) and journals it; unemit replays the journal backwards for an exact
-    round-trip. (Isaac's 'if we move it we have to cache what happened' requirement.)"""
+    round-trip. (the author's 'if we move it we have to cache what happened' requirement.)"""
     d = tmp_path / "proj"
     cs = d / ".claude" / "skills"
     (cs / "alpha").mkdir(parents=True)

{agent_skilltree-0.3.0 → agent_skilltree-0.4.0}/tests/test_exchange.py

@@ -35,8 +35,10 @@ def test_build_exchange_master_and_members(tmp_path: Path):
     assert exchange_is_valid(repo, ex)
     # master breadcrumbs into each member tree's root
     body = master.read_text()
-    assert str(node_skill_md(repo / "trees" / "cognition", "cognition").resolve()) in body
-    assert str(node_skill_md(repo / "trees" / "writing", "writing").resolve()) in body
+    # portable by default: relative to the master's folder (the repo), no machine path
+    assert "trees/cognition/.claude/skills/cognition/SKILL.md" in body
+    assert "trees/writing/.claude/skills/writing/SKILL.md" in body
+    assert str(tmp_path) not in body
     # each member tree is materialized + valid on its own
     assert node_skill_md(repo / "trees" / "cognition" / "reason", "reason").is_file()
 

agent_skilltree-0.4.0/tests/test_portable.py

@@ -0,0 +1,109 @@
+"""A tree ships PORTABLE — no machine's path in any file — and is LOCALIZED at install.
+
+Portable breadcrumbs are relative to each node's folder; the manifest stores `skill_src`
+relative to itself. A portable tree validates wherever it is copied, with no step at all;
+`localize=True` (materialize / emit) writes absolute breadcrumbs for one machine, and
+projecting a tree (an install read through symlinks) localizes it.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+
+from skilltree import SkillTree, TreeNode, materialize, validate
+from skilltree.cohere import emit, relink
+from skilltree.forest import project
+from skilltree.materialize import node_skill_md
+
+
+def _src(tmp_path: Path, name: str) -> Path:
+    d = tmp_path / "src" / name
+    d.mkdir(parents=True)
+    (d / "SKILL.md").write_text(f"---\nname: {name}\ndescription: the {name} skill\n---\n\nbody of {name}\n")
+    return d
+
+
+def _tree(tmp_path: Path) -> SkillTree:
+    return SkillTree(TreeNode("root", "sc", description="the root", children=[
+        TreeNode("a", "cor", description="branch a", children=[
+            TreeNode("a1", "ac", skill_src=str(_src(tmp_path, "a1")))]),
+        TreeNode("b", "skill", skill_src=str(_src(tmp_path, "b")))]))
+
+
+def _all_text(root: Path) -> str:
+    return "\n".join(p.read_text(encoding="utf-8") for p in root.rglob("*")
+                     if p.is_file() and p.suffix in (".md", ".json"))
+
+
+def _errors(root: Path) -> list:
+    return [v for v in validate(root) if v.severity == "error"]
+
+
+def test_default_tree_names_no_machine_path_and_validates(tmp_path: Path):
+    root = tmp_path / "tree"
+    materialize(_tree(tmp_path), root, coords=True)
+    assert str(tmp_path) not in _all_text(root)          # no absolute path anywhere
+    assert _errors(root) == []
+
+
+def test_portable_tree_validates_after_a_move_with_no_step(tmp_path: Path):
+    root = tmp_path / "tree"
+    materialize(_tree(tmp_path), root, coords=True)
+    moved = tmp_path / "elsewhere" / "deep" / "tree"
+    shutil.copytree(root, moved)
+    shutil.rmtree(root)                                  # the original place is gone
+    assert _errors(moved) == []
+
+
+def test_manifest_stores_skill_src_relative_and_load_resolves_it(tmp_path: Path):
+    root = tmp_path / "tree"
+    materialize(_tree(tmp_path), root)
+    raw = json.loads((root / "skilltree.json").read_text())
+    leaf = raw["skilltree"]["children"][1]
+    assert not Path(leaf["skill_src"]).is_absolute()
+    loaded = SkillTree.load(root / "skilltree.json")
+    assert Path(loaded.root.children[1].skill_src).resolve() == (tmp_path / "src" / "b").resolve()
+
+
+def test_localize_writes_absolute_and_still_validates(tmp_path: Path):
+    root = tmp_path / "tree"
+    materialize(_tree(tmp_path), root, localize=True)
+    body = node_skill_md(root, "root").read_text()
+    assert str(node_skill_md(root / "a", "a").resolve()) in body
+    assert _errors(root) == []
+
+
+def test_emit_switches_between_forms(tmp_path: Path):
+    root = tmp_path / "tree"
+    materialize(_tree(tmp_path), root, coords=True)
+    assert emit(root, localize=True)["ok"]
+    assert str(root.resolve()) in node_skill_md(root, "0-root").read_text()
+    assert _errors(root) == []
+    assert emit(root)["ok"]                              # default: portable again
+    assert str(tmp_path) not in _all_text(root)
+    assert _errors(root) == []
+
+
+def test_project_localizes_the_projected_tree(tmp_path: Path):
+    root = tmp_path / "tree"
+    materialize(_tree(tmp_path), root, coords=True)
+    skills = tmp_path / "user" / "skills"
+    links = project(root, skills, policy="progressive")
+    assert links and all(p.exists() for p in links)
+    seen = (skills / "0-root" / "SKILL.md").read_text()   # read THROUGH the symlink
+    crumb = str(node_skill_md(root / "a", "0.1-a").resolve())
+    assert crumb in seen and Path(crumb).is_file()
+
+
+def test_relink_switches_paths_and_touches_nothing_else(tmp_path: Path):
+    root = tmp_path / "tree"
+    materialize(_tree(tmp_path), root)                   # no coords: names must stay plain
+    before = sorted(str(p.relative_to(root)) for p in root.rglob("SKILL.md"))
+    assert relink(root, localize=True)["ok"]
+    assert str(root.resolve()) in node_skill_md(root, "root").read_text()
+    assert _errors(root) == []
+    assert relink(root)["ok"]
+    assert str(tmp_path) not in _all_text(root)
+    assert sorted(str(p.relative_to(root)) for p in root.rglob("SKILL.md")) == before
+    assert _errors(root) == []

{agent_skilltree-0.3.0 → agent_skilltree-0.4.0}/tests/test_skilltree.py

@@ -30,8 +30,10 @@ def test_root_body_has_cat_breadcrumbs_for_each_child(tmp_path: Path):
     materialize(_tree(), root)
     body = node_skill_md(root, "cc-skill-tree").read_text()
     assert "cat" in body
-    assert str(node_skill_md(root / "a", "a").resolve()) in body
-    assert str(node_skill_md(root / "b", "b").resolve()) in body
+    # portable by default: each child's path relative to this node's folder, no machine path
+    assert "Read `a/.claude/skills/a/SKILL.md`" in body
+    assert "Read `b/.claude/skills/b/SKILL.md`" in body
+    assert str(tmp_path) not in body
 
 
 def test_dead_breadcrumb_is_caught(tmp_path: Path):