Commands

Global Flags

Command Details

tome sync

Runs the full pipeline: discover skills from configured directories, consolidate into the library, diff the lockfile to surface changes, distribute to targets, and clean up stale entries. When new or changed skills are detected, an interactive triage prompt lets you disable unwanted skills. Generates a tome.lock lockfile for reproducible snapshots.

tome add

Register a git skill repository in tome.toml. Accepts either a full git URL (https://github.com/owner/repo, git@github.com:owner/repo.git) or a bare GitHub slug (owner/repo), which is expanded to https://github.com/owner/repo (v0.8.2+). The clone is shallow and lives in ~/.tome/repos/<sha256>/.

URL forms

tome add https://github.com/user/skills           # full HTTPS URL
tome add user/skills                              # bare slug → github.com
tome add git@github.com:user/skills.git           # SSH URL
tome add user/skills/tree/main/skills             # /tree/<ref>/<subdir> shortcut (v0.13+)
tome add user/skills --subdir skills              # explicit --subdir flag (v0.13+)

The /tree/<ref>/<subdir> URL form mimics how GitHub renders navigation into a subdirectory in your browser — copy-paste from github.com/owner/repo/tree/main/skills and it just works. Extracted <ref> becomes the default branch; <subdir> becomes the discovery subdirectory. Explicit --branch / --subdir flags override URL-embedded values (with a warning).

Auto-detection of common subdirs (v0.13+)

If tome sync finds zero skills at a directory’s root AND no subdir is configured, it probes common Claude Code plugin layouts (skills/, .claude-plugin/skills/) and emits a subdir = "..." hint if any candidate has skills inside. Catches the “I added a Claude plugin repo and got zero skills” case without forcing the user to know the convention up front.

Flags

--branch, --tag, --rev are mutually exclusive.

Choosing the right role (v0.14+)

The role field decides what tome does with a configured directory:

The defaults bite if you don’t know them. When you omit --role, the directory’s role falls back to its type default:

• claude-plugins → managed
• directory → synced
• git → source

The directory → synced default is the one that surprises people. If you tome add a local directory owned by a package manager (e.g. ~/.pfw/skills/), the synced default writes ~170 distribution symlinks INTO that source directory — polluting it with content tome propagated from other configured directories. Use --role source or --role managed for read-only package manager directories to keep them clean.

# WRONG (default role = synced; tome writes BACK into ~/.pfw/skills/)
tome add ~/.pfw/skills

# OK — discovery only, no write-back, but library entries get
# `managed: false` (treated as a generic local source).
tome add ~/.pfw/skills --role source

# BEST (v0.15+) — Managed semantic: library entries get `managed: true`,
# so reconcile + foreign-symlink protection recognize this as an
# external-package-manager-owned source.
tome add ~/.pfw/skills --role managed

source vs managed for flat-directory package managers (v0.15+)

Both refuse to write back into the source dir, so either keeps ~/.pfw/skills/ clean. The differences are subtle but material if you care about upstream-update semantics down the line:

For today’s needs (just propagating pfw skills to your other tools), both work equivalently. For longer-term integration with pfw’s own update lifecycle, prefer managed.

The success message now echoes the resolved role so you see what you got:

✓ Added directory 'pfw' (git: https://..., role: source)
  → Source (skills discovered here, not distributed here)

tome remove

Split into two subcommands since v0.10 (Phase 14, D-API-2):

tome remove dir <name>

Remove a configured directory entry from tome.toml. Manifest entries owned by that directory transition to Unowned (per LIB-04) — library content is preserved on disk; only the source_name linkage is cleared. Aggregates partial-cleanup failures and exits non-zero with a ⚠ N operations failed summary if any cleanup step fails. For git directories, the cached clone in ~/.tome/repos/<sha256>/ is removed.

tome remove skill <name>

Delete an Unowned skill from the library entirely — clears the manifest entry, removes the library directory, removes downstream distribution symlinks, removes the lockfile entry, and removes any machine.toml memberships. Refuses to operate on Owned skills with a hint to run tome remove dir first (per D-B2).

tome reassign

Reassign a skill to a different directory — useful when the same skill appears under multiple sources and you want to pin which directory owns it. Accepts both Owned skills (re-anchor between configured directories) and Unowned skills (re-anchor a previously-stranded skill back to a configured directory, per UNOWN-01 / D-API-1).

tome fork

Fork a managed (read-only) skill into a local directory so it can be edited. The local copy supersedes the managed one in the library.

tome migrate-library

One-shot migration: convert a v0.9-shape library (where managed skills lived as symlinks pointing into the package manager’s cache) to the v0.10 library-canonical model (real-directory copies). Run once after upgrading from v0.9.x; idempotent on re-run.

Shows a plan summary (skill count + per-skill disk estimate via walkdir + metadata().len()) before any conversion, then prompts for confirmation. Broken symlinks are preserved in place per Phase 11 D-04.

tome list

tome browse

Full-screen interactive skill browser using fuzzy search. Supports sorting, grouping by source, and per-skill actions (view source, copy path, disable/enable).

tome doctor

Diagnose library state. When run interactively (no --no-input, no --dry-run), surfaces issues and offers per-category repair prompts.

Orphan-directory repair (v0.14+)

When tome doctor finds a directory in the library that has no matching manifest entry (an “orphan”), it offers four choices per orphan:

• claim — Register the orphan in the manifest as an Unowned skill (v0.14+). Hashes the directory, writes a SkillEntry::new_unowned, and the entry distributes to your target / synced directories on the next tome sync. This is the proper fix when the orphan represents a real skill you want to keep (e.g., a directory you copied in by hand, or one whose source was removed but you want to preserve it).
• keep — Leave the directory on disk; tome sync will re-register it IF it discovers the orphan from a configured source. Useful when you know the orphan’s source got temporarily disconnected and will come back. Note: for library-canonical orphans with no upstream source, this option is a no-op until you claim it or add a source that covers it.
• delete — Remove the directory from disk permanently.
• skip — Leave the orphan as-is; doctor will surface it again on the next run.

Broken-frontmatter skills (v0.16+)

tome doctor walks every manifest-tracked skill and parses its SKILL.md frontmatter. Failures surface as Library Warnings — for example:

! 'my-skill' has unparsable SKILL.md frontmatter: invalid YAML frontmatter
! 'other-skill' has no SKILL.md file

These are not auto-repairable — the user must edit the SKILL.md file (or remove the skill) by hand. Without this check, the failure was only visible as a one-line stderr warning during tome sync; it now persists in the doctor surface so broken skills get triaged. Use tome lint <PATH> for a deeper per-field frontmatter audit.

Real-dir-in-target repair (v0.16+)

If a distribution directory contains a real directory (not a symlink) whose name matches a library skill, tome doctor hash-compares the two:

• Identical content — Surfaces as an auto-fixable Warning (real directory in target matches library content (should be a symlink)). The auto-repair pass deletes the real directory and replaces it with a symlink into the library. Typical cause: skills copied into the target dir manually before adopting tome, or by hand after the fact.
• Diverging content — Surfaces as a no-repair Warning (real directory in target diverges from library content — reconcile manually). The user must decide whether to overwrite the local edits, fold them back into the library, or remove the target copy.
• No matching library skill — Left alone; tome does not own un-paired directories in target dirs.

tome lint

Validates SKILL.md frontmatter: missing/mismatched names, description length, non-standard fields, Unicode tag codepoints. Exits with code 1 on errors (CI-friendly).

tome config

tome backup

Git-backed backup and restore. Subcommands:

tome eject

Removes all of tome’s symlinks from distribution directories. Reversible — run tome sync to recreate them.

tome relocate

Moves the skill library to a new path, updating symlinks in all distribution directories. Detects cross-filesystem moves and warns when target symlinks need to be re-anchored.

tome completions