Introduction

Sync AI coding skills across tools. Discover skills from Claude Code plugins, standalone directories, and custom locations — then distribute them to every AI coding tool that supports the SKILL.md format.

Why

AI coding tools (Claude Code, Codex, Antigravity) each use SKILL.md packages to provide context. But skills get siloed:

• Plugin skills live in cache directories you never see
• Standalone skills only exist for one tool
• Switching tools means losing access to your skill library

tome consolidates all skills into a single library and distributes them everywhere.

Install

Homebrew (macOS/Linux):

brew install MartinP7r/tap/tome

Quick Start

# Interactive setup — discovers sources, configures targets
tome init

# Sync skills to all configured targets (with interactive triage)
tome sync

# Check what's configured
tome status

How It Works

graph LR
    subgraph Sources
        S1["Plugin cache<br/>(23 skills)"]
        S2["~/.claude/skills<br/>(8 skills)"]
        S3["~/my-skills<br/>(18 skills)"]
    end

    subgraph Library
        L["Consolidated<br/>skill library<br/>(copies + symlinks)"]
    end

    subgraph Targets
        T1["Antigravity<br/>(symlinks)"]
        T2["Codex<br/>(symlinks)"]
        T3["OpenClaw<br/>(symlinks)"]
    end

    S1 --> L
    S2 --> L
    S3 --> L
    L --> T1
    L --> T2
    L --> T3

1. Discover — Scan configured sources for */SKILL.md directories
2. Consolidate — Gather skills into a central library: local skills are copied, managed (plugin) skills are symlinked; deduplicates with first source winning
3. Distribute — Create symlinks in each target tool’s skills directory (respects per-machine disabled list)
4. Cleanup — Remove stale entries and broken symlinks from library and targets

License

MIT

Commands

Global Flags

Command Details

tome sync

Runs the full pipeline: discover skills from sources, 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 list

tome config

Configuration

Main Config

TOML at ~/.tome/tome.toml:

library_dir = "~/.tome/skills"
exclude = ["deprecated-skill"]

[[sources]]
name = "claude-plugins"
path = "~/.claude/plugins/cache"
type = "claude-plugins"

[[sources]]
name = "standalone"
path = "~/.claude/skills"
type = "directory"

[targets.antigravity]
enabled = true
method = "symlink"
skills_dir = "~/.gemini/antigravity/skills"

Fields

Source Types

Target Methods

Targets are data-driven — any tool can be added without code changes. The tome init wizard auto-discovers common tool locations via a built-in KnownTarget registry.

Machine Preferences

Per-machine opt-in/opt-out at ~/.config/tome/machine.toml (intentionally kept separate from ~/.tome/ — machine-specific preferences should not be in the portable tome home directory):

disabled = ["noisy-skill", "work-only-skill"]
disabled_targets = ["openclaw"]

Disabled skills remain in the library but are skipped during distribution.

This allows sharing a single library (e.g., via git) across machines while customizing which skills are active on each one.

tome sync automatically diffs the lockfile and offers interactive triage when new or changed skills are detected. The --machine <path> global flag overrides the default machine preferences path.

Lockfile

tome sync generates a tome.lock file in the tome home directory (~/.tome/tome.lock). This lockfile captures a reproducible snapshot of all skills — their names, content hashes, sources, and provenance metadata. Each sync diffs the new lockfile against the previous one and surfaces changes interactively.

The lockfile is designed to be committed to version control alongside the library, enabling multi-machine workflows where tome sync on a new machine can detect what changed since the last sync.

Library .gitignore

tome sync automatically generates a .gitignore in the library directory:

• Managed skills (symlinked from package managers) are gitignored — they are recreated by tome sync
• Local skills (copied into the library) are tracked in version control
• Temporary files (tome.lock.tmp) are always ignored

This allows the library directory to serve as a git repository for portable skill management while keeping transient entries out of version control.

Development Workflow

tome uses a lightweight layered workflow for substantial changes:

• GitHub Issues track product intent, roadmap placement, and user-visible scope.
• OpenSpec tracks the change proposal, requirements, design notes, and implementation checklist.
• Beads tracks live execution state: what is ready, what is claimed, what is blocked, and what is done.
• Git commits / PRs are the implementation evidence.

This is meant to improve traceability, not create process theater. If the workflow becomes bureaucratic sludge, scale it back.

When to Use This Workflow

Use the full OpenSpec + Beads flow for:

• new features
• significant refactors
• architecture-impacting changes
• process or documentation changes that affect future development behavior
• any change where requirements/design should be reviewed before implementation

You do not need the full workflow for:

• typo fixes
• tiny bug fixes with obvious scope
• narrowly scoped internal cleanups
• mechanical edits with no design impact

For small fixes, issue → code → PR is fine.

Role of Each Layer

GitHub Issues

Use GitHub Issues for:

• deciding what to work on
• roadmap / milestone planning
• discussion with humans
• repository-visible backlog management

GitHub Issues answer: why does this work exist at all?

OpenSpec

Use OpenSpec for:

• change proposals
• requirement deltas
• design decisions
• implementation checklists for substantial changes

OpenSpec answers: what are we changing, and why does the shape of the change make sense?

Typical artifact layout:

openspec/changes/<change-id>/
├── proposal.md
├── design.md
├── tasks.md
└── specs/<capability>/spec.md

Core OpenSpec flow

# create a new change scaffold
openspec new change <change-id>

# inspect what exists
openspec list
openspec show <change-id>
openspec status --change <change-id>

# validate before implementation / archival
openspec validate <change-id>

# after implementation is complete
openspec archive <change-id>

Beads

Use Beads for:

• turning an OpenSpec task checklist into live executable tasks
• claiming work
• tracking dependencies / blocking relationships
• recording closure notes tied to implementation

Beads answers: what should be worked on next, who owns it, and what already landed?

Minimal command flow used in tome:

# see unblocked work
bd ready

# inspect a task
bd show <task-id>

# claim work
bd update <task-id> --claim

# close work with an implementation note
bd close <task-id> "Done in commit <sha>"

When creating Beads tasks from an OpenSpec change, set spec_id to the OpenSpec change id.

Default Flow for Significant Changes

1. Start from a GitHub issue or clear idea.
2. Create an OpenSpec change for the substantial work.
3. Write or refine:
   • proposal.md
   • design.md
   • tasks.md
   • any relevant spec delta files
4. Create Beads tasks for the executable work items.
5. Use bd ready / bd update --claim / bd close during implementation.
6. Land code in normal git commits / PRs.
7. Archive the OpenSpec change when the work is complete.

Traceability Convention

For meaningful changes, link the layers explicitly.

In Beads

• set spec_id to the OpenSpec change id
• use task descriptions that reference the actual repo artifact being changed
• close tasks with a note that includes the commit hash when possible

In commits or PR descriptions

Include the IDs when they exist:

Refs #123
OpenSpec: document-openspec-beads-workflow
Beads: tome-8vs.1

Recommended PR footer shape:

Closes #123
OpenSpec: <change-id>
Beads: <task-id>[, <task-id>...]

This gives a practical audit trail across backlog, planning, execution, and code history.

Practical Rule of Thumb

• GitHub Issue = backlog / business reason
• OpenSpec = requirements + design + checklist
• Beads = execution state
• git / PR = shipped evidence

Don’t stack ceremony for its own sake. Use the minimum structure needed to stop future-you from asking, “What the hell were we doing here?”

Architecture

System Diagram (Excalidraw) — interactive diagram showing the two-tier source → library → target flow.

Rust workspace (edition 2024) with a single crate producing one binary.

crates/tome — CLI (tome)

The main binary. All domain logic lives here as a library (lib.rs re-exports all modules) with a thin main.rs that parses CLI args and calls tome::run().

Sync Pipeline

The core flow that tome sync and tome init both invoke (lib.rs::sync):

1. Discover (discover.rs) — Scan configured sources for */SKILL.md dirs. Two source types: ClaudePlugins (reads installed_plugins.json) and Directory (flat walkdir scan). First source wins on name conflicts; exclusion list applied.
2. Consolidate (library.rs) — Two strategies based on source type: managed skills (ClaudePlugins) are symlinked from library → source dir (package manager owns the files); local skills (Directory) are copied into the library (library is the canonical home). A manifest (.tome-manifest.json) tracks SHA-256 content hashes for idempotent updates: unchanged skills are skipped, changed skills are re-copied or re-linked. Stale directory state (e.g., a plain directory where a symlink should be) is automatically repaired.
3. Distribute (distribute.rs) — Push library skills to target tools via symlinks in each target’s skills directory. Skills disabled in machine preferences are skipped.
4. Cleanup (cleanup.rs) — Remove stale entries from library (skills no longer in any source), broken symlinks from targets, and disabled skill symlinks from target directories. Verifies symlinks point into the library before removing.
5. Lockfile (lockfile.rs) — Generate tome.lock capturing a reproducible snapshot of the library state for diffing during tome sync.

Other Modules

• wizard.rs — Interactive tome init setup using dialoguer (MultiSelect, Input, Confirm, Select). Auto-discovers known source locations (~/.claude/plugins/cache, ~/.claude/skills, ~/.codex/skills, ~/.gemini/antigravity/skills).
• config.rs — TOML config at ~/.tome/tome.toml. Config::load_or_default handles missing files gracefully. All path fields support ~ expansion.
• doctor.rs — Diagnoses library issues (orphan directories, missing manifest entries, broken legacy symlinks) and missing source paths; optionally repairs.
• status.rs — Read-only summary of library, sources, targets, and health. Single-pass directory scan for efficiency.
• manifest.rs — Library manifest (.tome-manifest.json): tracks provenance, content hashes, and sync timestamps for each skill. Provides hash_directory() for deterministic SHA-256 of directory contents.
• lockfile.rs — Generates and loads tome.lock files. Each entry records skill name, content hash, source, and provenance metadata. Uses atomic temp+rename writes to prevent corruption.
• machine.rs — Per-machine preferences (~/.config/tome/machine.toml). Tracks a disabled set of skill names and a disabled_targets set of target names. Uses atomic temp+rename writes. Loaded during sync to filter skills.
• update.rs — Lockfile diffing and interactive triage logic, invoked by tome sync to surface added/changed/removed skills and offer to disable unwanted new skills.
• paths.rs — Symlink path utilities: resolves relative symlink targets to absolute paths and checks whether a symlink points to a given destination.

Key Patterns

• Two-tier model: Sources →(consolidate)→ Library →(distribute)→ Targets. The library is the source of truth. Managed skills (from package managers like Claude plugins) are symlinked from library → source dir (the package manager owns the files); local skills (from directory sources) are copied into the library (the library is canonical home). Distribution to targets always uses symlinks pointing into the library. This means the project is Unix-only (std::os::unix::fs::symlink).
• Targets are data-driven: config::targets is a BTreeMap<String, TargetConfig> — any tool can be added as a target without code changes. The wizard uses a KnownTarget registry for auto-discovery of common tools.
• dry_run threading: Most operations accept a dry_run: bool that skips filesystem writes but still counts what would change. Results report the same counts either way.
• Error handling: anyhow for the application. Missing sources/paths produce warnings (stderr) rather than hard errors.

Testing

Unit tests are co-located with each module (#[cfg(test)] mod tests). Integration tests in crates/tome/tests/cli.rs exercise the binary via assert_cmd. Tests use tempfile::TempDir for filesystem isolation — no cleanup needed.

CI

GitHub Actions runs on both ubuntu-latest and macos-latest: fmt check, clippy with -D warnings, tests, and release build.

AI Coding Tool Landscape

Research into agent file formats (skills, rules, memory, hooks, agents, plugins), invocation methods, context loading strategies, and format differences across AI coding tools — informing tome’s connector architecture.

Last updated: March 2026

1. The Full Taxonomy

AI coding tools have up to seven layers of configuration. Most discussions focus on the first three, but the extended structures (hooks, agents, plugins, MCP) are where the real divergence happens.

Key insight: Skills and MCP are the two truly portable layers. Everything else is tool-specific.

2. Tool-by-Tool Breakdown

Claude Code

Vendor: Anthropic | Type: CLI agent | SKILL.md: Full standard + extensions

Unique skill extensions beyond the standard:

• disable-model-invocation: true — user-only invocation
• user-invocable: false — model-only (background knowledge)
• context: fork + agent: Explore — run skill in isolated subagent
• `!command` syntax — inject shell output into skill content before sending to model
• $ARGUMENTS, $0, $1 — argument substitution
• hooks — lifecycle hooks scoped to the skill

Extended structures:

• Hooks — 12 lifecycle events (SessionStart, PreToolUse, PostToolUse, Stop, etc.) with 3 hook types: command, prompt, agent. Configured in settings.json at global/project/local levels.
• Agents — .claude/agents/*.md with YAML frontmatter (11+ fields: tools, model, maxTurns, hooks, mcpServers, permissionMode, etc.). Isolated subagents with own context/tools/model.
• Plugins — plugin.json manifest bundling skills + agents + hooks + MCP + LSP servers + output styles. Marketplace discovery via /plugin. Three install scopes: user/project/local.
• Commands — .claude/commands/*.md (legacy, superseded by skills but still supported). Simple markdown, no frontmatter.
• Settings — Three-level hierarchy: ~/.claude/settings.json → .claude/settings.json → .claude/settings.local.json. Permissions, hooks, MCP servers. JSON schema available.
• MCP — .mcp.json at project root or in settings. Supports stdio/http/sse. Env var expansion: ${VAR}, ${VAR:-default}.

Codex CLI

Vendor: OpenAI | Type: CLI agent | SKILL.md: Standard + agents/openai.yaml

agents/openai.yaml adds Codex-specific configuration:

interface:
  display_name: "User-facing name"
  icon_small: "./assets/logo.svg"
  brand_color: "#3B82F6"
policy:
  allow_implicit_invocation: false   # Disable auto-matching
dependencies:
  tools:
    - type: "mcp"
      value: "toolName"
      url: "https://example.com"

Antigravity

Vendor: Google | Type: IDE agent | SKILL.md: Standard

Key pattern: Antigravity emphasizes narrow, precise descriptions with explicit “do not use” clauses to reduce false activation.

Cursor

Vendor: Anysphere | Type: IDE | SKILL.md: Adopted via agentskills.io (2026)

.mdc rule example:

---
description: Python API conventions
globs: ["*.py", "src/**/*.py"]
alwaysApply: false
---
Use type hints on all function signatures...

Evolution: .cursorrules (2023) → .cursor/ folder with index.mdc (2024) → Multi-file .cursor/rules/*.mdc (2025) → Context-aware rules with MCP integration (2026)

Windsurf

Vendor: Codeium | Type: IDE | SKILL.md: Not documented

Activation modes:

OpenCode

Vendor: SST (open source) | Type: CLI agent | SKILL.md: Via standard

OpenClaw

Vendor: Open source | Type: Autonomous agent | SKILL.md: Supported

OpenClaw has the richest file taxonomy — 8 separate config files loaded at session start into the system prompt. This gives fine-grained control but means more files for tome to discover and potentially sync.

Nanobot (HKUDS)

Vendor: HKUDS (open source) | Type: Lightweight CLI agent | SKILL.md: Via OpenClaw compat

Nanobot is essentially an OpenClaw-compatible agent in a fraction of the code. Same file conventions, same workspace structure.

PicoClaw

Vendor: Open source | Type: Ultra-lightweight agent | SKILL.md: Not documented

PicoClaw prioritizes extreme minimalism. For tome, it would likely be an MCP target rather than a skill directory target.

Gemini CLI

Vendor: Google | Type: CLI agent | SKILL.md: Standard

Extensions (2026): gemini-extension.json packaging prompts, MCP servers, and commands. Extension settings allow user-prompted configuration on install with env var mapping.

Shell execution: !{command} syntax for shell injection with auto-escaping of {{args}}. Argument substitution via {{args}} (not $ARGUMENTS).

Gemini CLI is the simplest format for instructions — plain markdown files concatenated into context. No frontmatter, no structured fields. The @file.md import syntax and !{command} execution are unique.

Skills (2026): Gemini CLI now supports SKILL.md directory scanning. Personal skills at ~/.gemini/skills/ and the portable ~/.agents/skills/ path. For tome, Gemini CLI is a Symlink target via ~/.gemini/skills/.

VS Code Copilot

Vendor: GitHub (Microsoft) | Type: IDE agent | SKILL.md: Full standard (since Jan 2026)

Copilot Workspace (GitHub Next): Running coding agents via GitHub Actions — agent workflows as CI/CD.

Amp

Vendor: Sourcegraph | Type: CLI/IDE agent | SKILL.md: Standard (migrating to)

Amp is a useful case study — their migration from custom commands to Agent Skills demonstrates the industry consolidation trend.

Goose

Vendor: Block (Square) | Type: Autonomous agent | SKILL.md: Standard

Goose now supports SKILL.md directory scanning alongside its MCP-centric extension model. For tome, Goose is a Symlink target via ~/.config/goose/skills/.

Aider

Vendor: Open source | Type: CLI pair programmer | SKILL.md: Not documented

Aider is minimal — no skills, no hooks, no agents. Pure configuration-driven.

3. Instruction Files (Rules)

Each tool reads project-level instructions from a differently-named markdown file. The content is plain markdown (no frontmatter) and is always loaded into context.

What this means for tome

A “rule” that should apply everywhere needs to exist as up to 5 different files:

• CLAUDE.md (Claude Code)
• AGENTS.md (Codex, OpenCode, OpenClaw)
• GEMINI.md (Antigravity, Gemini CLI)
• .github/copilot-instructions.md (VS Code Copilot)
• .cursor/rules/*.mdc or .windsurf/rules/*.md (IDE-specific)

Symlinks can unify the markdown-based ones, but Cursor/Windsurf require format transforms.

AGENTS.md as open standard

AGENTS.md has emerged as an open instruction-file standard under the Linux Foundation / Agentic AI Foundation. It is adopted by Codex, OpenCode, OpenClaw, and configurable in Gemini CLI — the instruction-file equivalent of the SKILL.md skills standard. The portable path ~/.agents/ (and its skills/ subdirectory) is scanned by Codex, Goose, Gemini CLI, OpenCode, Amp, and Cursor.

4. SKILL.md Standard (agentskills.io)

The Agent Skills format originated at Anthropic in late 2025 and was released as an open standard. It defines a portable way to package reusable instructions, scripts, and resources for AI coding agents. As of February 2026, 27+ tools have adopted it.

Who supports it

Invocation methods

Required frontmatter

---
name: my-skill          # 1-64 chars, lowercase + hyphens, must match directory name
description: |          # 1-1024 chars. When to use this skill.
  What it does and when the agent should activate it.
---

Optional frontmatter

license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
compatibility: Requires poppler-utils
allowed-tools: Read Grep Bash(git:*)

Skill directory structure

skill-name/
├── SKILL.md           # Required — instructions + frontmatter
├── scripts/           # Optional — executable code
├── references/        # Optional — detailed docs loaded on demand
└── assets/            # Optional — templates, data files

Discovery paths

5. Parsing Differences (The Details That Break Things)

5.1 YAML Frontmatter

Delimiters: All tools require --- (three hyphens) at start and end.

Unknown fields: Silently ignored by all tools following the Agent Skills standard. Claude Code has occasionally thrown errors on unexpected keys in non-standard positions.

Case sensitivity: All field names are case-sensitive and must be lowercase. SKILL.md filename must be exact uppercase — skill.md won’t be discovered.

Multiline descriptions — MAJOR GOTCHA:

Claude Code’s YAML parser breaks on Prettier-formatted multiline descriptions:

# BROKEN — Claude Code can't parse this (Prettier-wrapped):
---
description: This is a long description that Prettier
  wraps across multiple lines without a block scalar
---

# WORKS — single line:
---
description: This is a long description kept on one line  # prettier-ignore
---

# WORKS — explicit block scalar:
---
description: |
  This is a long description using
  a YAML block scalar indicator.
---

Other tools (Codex, Cursor, Windsurf, Gemini CLI) handle standard YAML multiline correctly.

Workaround: Keep descriptions single-line, or use # prettier-ignore comment, or disable Prettier’s proseWrap for SKILL.md files.

5.2 Markdown Body

Code blocks: All tools prefer triple backticks with language tags. Indented code blocks (4 spaces) work but lack syntax highlighting.

XML tags: Claude is fine-tuned to recognize XML tags (<example>, <system-reminder>, etc.) as structural elements. No other tool does this. Skills that rely on XML structure for Claude won’t parse the same way in Codex/Copilot.

Shell execution in content:

Argument substitution:

Claude Code parser bug: ! inside inline code backticks can be misinterpreted as a bash command. Avoid ! in code spans within SKILL.md files meant for Claude Code.

5.3 Rules Formats (Cursor & Windsurf)

Cursor .mdc files:

---
description: Python API conventions
globs: ["*.py", "src/**/*.py"]
alwaysApply: false
---
Use type hints on all function signatures...

Four activation modes:

Windsurf rules:

Four activation modes: Manual (@-mention), Model Decision (AI decides), Glob (file pattern), Always On.

Limits: Both Cursor and Windsurf enforce 6,000 chars per rule file, 12,000 chars combined. Content beyond the limit is silently truncated.

5.4 VS Code Copilot .instructions.md

---
description: 'Purpose of these instructions (1-500 chars)'
applyTo: '**/*.py'
---
Natural language instructions here...

• description and applyTo are the main frontmatter fields
• excludeAgent: "code-review" or "coding-agent" for agent targeting
• No char limit documented, but recommended to stay under 2 pages
• Glob patterns in applyTo use standard glob syntax

5.5 File Encoding

UTF-8: All tools assume UTF-8. Claude Code has documented bugs with UTF-8 corruption (especially CJK characters via MultiEdit tool). Non-UTF-8 files (Windows-1252) get silently corrupted.

BOM: Use UTF-8 without BOM. VS Code can handle BOM but other tools may not.

Line endings: Use LF (\n). Cursor has a known bug converting CRLF → LF. Enforce via .gitattributes.

Skill names: Must be [a-z0-9-]+ (lowercase alphanumeric + hyphens). No emoji, no unicode, no uppercase.

6. Memory & Persistence

Memory is the least portable layer — every tool has its own mechanism with zero interoperability.

Claude Code

Codex CLI

Cursor

Windsurf

Antigravity

VS Code Copilot

OpenClaw / Nanobot

Summary Table

7. Context Loading Strategies

How each tool manages token budget:

The key difference: SKILL.md-based tools use progressive disclosure (metadata → body → resources), while rules-based tools (Cursor, Windsurf) front-load everything up to their char limits.

Progressive Disclosure Flow

Skills use a three-tier loading strategy to minimize context window consumption:

graph LR
    subgraph "Session Start (~100 tokens/skill)"
        A["Scan skill directories"]
        B["Read frontmatter only<br/>(name + description)"]
    end

    subgraph "Task Matching"
        C{"User prompt matches<br/>skill description?"}
        D["Skill stays dormant"]
    end

    subgraph "Activation (<5000 tokens)"
        E["Load full SKILL.md body"]
        F["Execute instructions"]
    end

    subgraph "On Demand (variable)"
        G["Load references/<br/>scripts/ assets/"]
    end

    A --> B --> C
    C -- No --> D
    C -- Yes --> E --> F
    F -. "if needed" .-> G

8. MCP vs Skills: Efficiency

The Token Problem

MCP servers add tool definitions to context at session start. Each tool includes its name, description, parameter schema, and usage hints — all in natural language so the model understands when and how to use them.

When to Use Which

They’re complementary, not competitive. MCP provides capabilities (tools the agent can call). Skills provide knowledge (instructions the agent follows). A skill can even declare MCP tool dependencies in its frontmatter.

Progressive Disclosure is the Key

The fundamental difference: skills let agents load context incrementally based on what’s actually needed, while MCP front-loads everything. For a library of 50 skills, progressive disclosure means ~5000 tokens at session start vs. potentially hundreds of thousands for equivalent MCP tool definitions.

9. Hooks & Lifecycle Events

Hooks let tools run shell commands or logic at specific points in the agent lifecycle. This is the fastest-growing area of divergence.

Claude Code — 12 Events, 3 Hook Types

Location: ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json

Events:

Hook types:

Matchers target specific tools:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash(npm run *)",
      "type": "command",
      "command": "echo 'npm command detected'"
    }]
  }
}

Patterns support: exact ("Bash"), specifier ("Bash(npm run lint)"), wildcards ("Bash(curl *)"), regex-like ("mcp__.*__write.*").

Exit codes: 0 = success, 2 = block action (stderr becomes error message).

Codex CLI — Notify Hooks

Location: Configuration or CLI flags

Codex has a simpler hook system called “notify”:

• Executes external programs on lifecycle events (e.g., agent-turn-complete)
• Less granular than Claude’s 12 events
• Focused on notification rather than validation/blocking

Windsurf — Cascade Hooks

Location: Settings/configuration

• Shell commands at workflow lifecycle points
• Receives JSON context via stdin (similar to Claude)
• Supports user prompt events and policy violation blocking
• Enterprise distribution via cloud dashboard + MDM deployment (Feb 2026)

Amp — Tool Execution Hooks

Location: Settings ("amp.hooks")

{
  "amp.hooks": {
    "tool:post-execute": "npm run lint"
  }
}

• Event format: "tool:post-execute"
• Simpler than Claude’s matcher system

Other Tools

Cross-Tool Hook Comparison

10. Agents & Subagents

Agents are isolated execution contexts with their own tools, model, and permissions. This is distinct from skills (which provide instructions within the main context).

Claude Code — Most Mature Agent System

Location: ~/.claude/agents/*.md (global), .claude/agents/*.md (project)

Format: YAML frontmatter + markdown body

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: [Read, Glob, Grep]
model: sonnet
maxTurns: 10
---
You are a code reviewer focused on...

Frontmatter fields (11+):

Key difference from skills: Agents run in isolated context with their own model and tool restrictions. Skills inject instructions into the current context.

VS Code Copilot — Custom Agents

Location: .github/agents/

GitHub Copilot supports custom agents with:

• Custom tools and prompts
• MCP server access
• Agent targeting via excludeAgent field in instructions
• Two built-in agent types: coding-agent and code-review

Cursor — Parallel Subagents

Location: .cursor/agents/

• Up to 8 parallel agents via Git worktree isolation
• Agents get their own worktree branch for conflict-free parallel work
• Configured similarly to Claude agents

Antigravity — Agent Manager

• Dispatches up to 5 agents simultaneously on separate features
• Multi-model support (Gemini 3 Pro, Claude Sonnet 4.5, GPT-OSS)
• Agent Manager UI for orchestration (not file-based configuration)
• Claims 5-10x productivity from parallel agent execution

Codex CLI — Sandbox Agents

Codex takes a security-first approach:

• Dual-layer security: OS-level sandbox (what’s possible) + approval policy (when to ask)
• Three approval modes: suggest (read-only), auto-edit (edits approved, commands need approval), full-auto
• Agents run within sandbox constraints

OpenClaw/Nanobot — Workspace Files as “Agent Personality”

Rather than defining subagents, OpenClaw defines the main agent’s personality via 8 workspace files:

This is philosophically different — OpenClaw treats the AI as an entity with personality and rituals, rather than a tool with configurations.

Cross-Tool Agent Comparison

11. Plugins & Extensions

Plugins bundle multiple configuration objects (skills, agents, hooks, MCP servers) into a single installable package.

Claude Code — Plugin Ecosystem

Location: .claude-plugin/plugin.json at plugin root

Manifest format:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "Plugin description",
  "author": { "name": "Author", "email": "dev@example.com" },
  "commands": "./commands/",
  "agents": "./agents/",
  "skills": ["skill1", "skill2"],
  "hooks": "./hooks.json",
  "mcpServers": "./.mcp.json",
  "lspServers": "./.lsp.json",
  "outputStyles": "./styles/"
}

What plugins can contain: Skills, agents, hooks, commands (legacy), MCP servers, LSP servers, output styles.

Discovery: /plugin command → Discover tab. Official + community marketplaces. Three installation scopes: user (default), project, local.

Note: Manifest is optional — Claude Code auto-discovers components if absent.

Cursor — Plugin Marketplace

• Packages skills, subagents, MCP servers, hooks, rules into single install
• 10,000+ tools on Agnxi.com marketplace
• 1,800+ MCP servers available

VS Code Copilot — Extensions

Two flavors:

1. Skillsets — lightweight: tools, prompts, knowledge
2. Full agents — autonomous: multi-step workflows, GitHub App integration

Built as GitHub Apps using the Copilot API. Chat participants (@workspace, @terminal) are built-in extensions.

Gemini CLI — Extensions

Location: Extension directory with gemini-extension.json

{
  "name": "my-extension",
  "prompts": ["./prompts/"],
  "mcpServers": { ... },
  "commands": ["./commands/"]
}

Extension settings (2026): User-prompted configuration on install with environment variable mapping.

Goose — Six Extension Types

100+ MCP servers in toolkit catalog. Auto-OAuth on 401 for HTTP extensions.

Amp — Skills Migration

Amp (Sourcegraph) is actively consolidating:

• Deprecated (Jan 2026): Custom commands, toolboxes
• Replacing with: Agent Skills (SKILL.md standard)
• Migration path: .agents/commands/*.md → .agents/skills/*/SKILL.md
• Key motivation: on-demand loading (zero tokens until needed) vs toolbox overhead

Cross-Tool Plugin Comparison

12. MCP Server Configuration

MCP (Model Context Protocol) is the most universally supported integration mechanism — every major tool supports it.

Configuration Formats

Claude Code MCP Config

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["path/to/server.js"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

Environment variable expansion: ${VAR} (required), ${VAR:-default} (optional), ${CLAUDE_PLUGIN_ROOT} (plugin-relative).

Key Differences

• Antigravity: MCP Hub with 1,500+ pre-configured servers — UI-driven setup
• Goose: MCP is the primary extension mechanism (not just an add-on)
• Claude Code: Most flexible — supports project, global, and plugin-scoped MCP configs
• Cursor: Stored in .cursor/mcp.json separate from other settings

13. Settings & Permission Systems

Claude Code — Three-Level Settings

Hierarchy (last wins): ~/.claude/settings.json → .claude/settings.json → .claude/settings.local.json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(npm run lint)", "Read(~/.zshrc)"],
    "ask": ["Bash(curl *)"],
    "deny": ["Read(./.env)", "Edit(.env*)"]
  },
  "hooks": { ... },
  "mcpServers": { ... },
  "model": "sonnet",
  "maxTurns": 25
}

Permission modes: ask (default), acceptEdits, plan, bypassPermissions (“YOLO”).

Automatic timestamped backups (5 most recent retained).

Codex CLI — Dual-Layer Security

Cursor — Settings in .cursor/

• .cursor/rules/*.mdc for rules (covered in section 5.3)
• .cursor/mcp.json for MCP servers
• .cursor/agents/ for agent definitions
• Notepads: persistent context notes referenced with @, survive across sessions (beta)

Windsurf — Enterprise Distribution

• Cloud dashboard for enterprise hook/rule distribution
• MDM deployment support (Feb 2026)
• Policy enforcement via Cascade hooks

Gemini CLI — Extension Settings

~/.gemini/settings.json:

{
  "context": { "fileName": "GEMINI.md" },
  "mcpServers": { ... }
}

Supports custom naming for context files. Extension settings (2026) allow user-prompted configuration on install.

14. Unique Structures by Tool

Some tools have first-class configuration objects that exist nowhere else.

OpenClaw’s Behavioral Workspace

OpenClaw’s 8-file system is philosophically unique — it treats the AI agent as having personality and rituals:

Cursor Notepads (Beta)

Persistent context notes that:

• Are referenced with @notepad-name in chat
• Survive across sessions
• Act like pinned context without consuming always-on token budget
• Distinct from rules (which activate automatically) and skills (which activate on match)

Copilot Workspace (GitHub Next)

Running coding agents via GitHub Actions — agent workflows as CI/CD:

• Agent gets a PR, makes changes, runs tests
• Operates in GitHub’s infrastructure, not local machine
• Distinct from Copilot Chat / VS Code integration

Goose Auto-OAuth

HTTP extensions automatically handle OAuth flows on 401 responses — no manual token management.

Antigravity Multi-Model

Agent Manager supports dispatching agents on different LLM backends simultaneously:

• Gemini 3 Pro, Claude Sonnet 4.5, GPT-OSS
• Choose model per agent based on task characteristics

15. Full Cross-Tool Comparison Matrix

Legend: Full+ = standard with extensions, Std+ = standard with extra config, Std = standard, Compat = compatible, Adopted = recently added, — = not supported

16. Diagrams

Format Family Tree

graph TD
    Standard["Agent Skills Standard<br/>(agentskills.io)"]

    subgraph "SKILL.md Family"
        CC["Claude Code<br/>(standard + extensions)"]
        Codex["Codex CLI<br/>(standard + openai.yaml)"]
        AG["Antigravity<br/>(standard)"]
        OC_skill["OpenCode<br/>(standard)"]
        Cursor_skill["Cursor<br/>(adopted 2026)"]
        Copilot_skill["VS Code Copilot<br/>(full, Jan 2026)"]
        Amp_skill["Amp<br/>(migrating to)"]
    end

    subgraph "AGENTS.md Family"
        Codex_agents["Codex CLI"]
        OC_agents["OpenCode<br/>(CLAUDE.md fallback)"]
        OClaw["OpenClaw<br/>(+ SOUL.md, IDENTITY.md, ...)"]
        Nano["Nanobot<br/>(OpenClaw subset)"]
    end

    subgraph "Custom Rules"
        Cursor_rules["Cursor<br/>(.mdc with globs)"]
        Windsurf_rules["Windsurf<br/>(4 activation modes)"]
        Copilot_rules["VS Code Copilot<br/>(.instructions.md with applyTo)"]
    end

    subgraph "Plain Markdown"
        Claude_md["Claude Code<br/>(CLAUDE.md)"]
        Gemini_md["Gemini CLI<br/>(GEMINI.md + @imports)"]
        Copilot_md["VS Code Copilot<br/>(copilot-instructions.md)"]
    end

    subgraph "MCP-Only"
        Goose_mcp["Goose<br/>(6 extension types)"]
        Pico_mcp["PicoClaw"]
    end

    Standard --> CC
    Standard --> Codex
    Standard --> AG
    Standard --> OC_skill
    Standard --> Cursor_skill
    Standard --> Copilot_skill
    Standard --> Amp_skill
    OClaw --> Nano

tome Connector Mapping

graph LR
    subgraph "Source Connectors"
        S1["Claude Plugins<br/>(installed_plugins.json)"]
        S2["SKILL.md directories"]
        S3["Cursor .mdc rules"]
        S4["Windsurf rules"]
        S5["OpenClaw workspace"]
        S6["Copilot .instructions.md"]
    end

    subgraph "tome Library"
        L["Canonical format<br/>(SKILL.md standard)"]
    end

    subgraph "Target Connectors"
        T1["Symlink targets<br/>(Claude, Codex, Antigravity,<br/>OpenClaw, Copilot, OpenCode, Amp)"]
        T2["MCP targets<br/>(Goose, PicoClaw)"]
        T3["Format transform targets<br/>(Cursor .mdc, Windsurf rules,<br/>Copilot .instructions.md)"]
    end

    S1 --> L
    S2 --> L
    S3 -. "transform<br/>.mdc → SKILL.md" .-> L
    S4 -. "transform<br/>rules → SKILL.md" .-> L
    S5 --> L
    S6 -. "transform<br/>.instructions.md → SKILL.md" .-> L

    L --> T1
    L --> T2
    L -. "transform<br/>SKILL.md → native" .-> T3

17. Guidelines for Writing Portable Skills

Do

• Keep descriptions single-line to avoid Claude Code’s YAML multiline parser bug
• Stay under 5,000 tokens per SKILL.md body (recommended by agentskills.io)
• Stay under 6,000 chars if you also target Cursor/Windsurf
• Use [a-z0-9-]+ for skill names — lowercase, hyphens only, matching directory name
• Use triple-backtick code blocks with language tags
• Use UTF-8 without BOM, LF line endings
• Include trigger keywords in descriptions so semantic matching works across tools
• Move detailed content to references/ for progressive disclosure
• Version control your skills — they’re the most portable artifact
• Stick to standard frontmatter fields: name, description, license, metadata, compatibility, allowed-tools

Don’t

• Don’t rely on XML tags for structure — only Claude parses them
• Don’t use !command or $ARGUMENTS in skills meant for multiple tools
• Don’t put emoji or unicode in skill names (descriptions are fine)
• Don’t assume multiline YAML works — test across tools
• Don’t put secrets in skills/rules — they’re version-controlled markdown
• Don’t use tool-specific frontmatter (disable-model-invocation, agents/openai.yaml, globs, alwaysApply) in cross-platform skills — move these to tool-specific config
• Don’t exceed 200 lines for auto-loaded memory files (Claude truncates beyond that)

The Portability Hierarchy

Most portable ──────────────────────────── Least portable

   SKILL.md          Instruction files       Memory
   (agentskills.io)  (CLAUDE.md, etc.)       (tool-specific)

   20+ tools         Symlink across 3-4      Zero interop
   Same format       Cursor/Windsurf need    Every tool different
   Same directory    format transforms       File, DB, or API
   structure

Tool-Specific Features to Use Sparingly

18. Common Pitfalls

Dead Rules

Path globs break after refactoring. Renamed directories cause rules to silently stop matching. Audit regularly.

Memory Poisoning

Auto-generated memories can be manipulated (prompt injection via committed files). Review auto-memory content before trusting it.

Size Bloat

Auto-memories grow unbounded. Large instruction files consume context budget, leaving less room for actual conversation. Claude Code’s 200-line auto-load limit is a safeguard.

LLM Inconsistency

Cursor rules behave differently depending on which LLM backend is active. The same .mdc rule may work with Claude but fail with GPT-4. Agent Skills are more consistent because the SKILL.md body is pure natural language.

Migration Pain

No tool provides automatic format conversion. Moving from .cursorrules to SKILL.md, or from Windsurf rules to anything else, requires manual work. This is the gap tome aims to fill.

19. What This Means for tome

Format Families to Support

Based on this research, tome’s connector architecture needs to handle four format families:

Syncable Structures (Today)

Syncable with Transforms (Future)

Not Syncable (Tool-Specific)

Connector Design Recommendations

1. SKILL.md as canonical format — The library stores everything in Agent Skills standard format. This is already what most tools natively understand. As of Feb 2026, 7+ major tools read SKILL.md natively.

2. Symlink-first for SKILL.md tools — Claude Code, Codex, Copilot, Antigravity, OpenCode, and Amp all read SKILL.md natively. Symlinks from library to target skill directory are zero-cost and keep everything in sync.

3. Transform pipeline for custom rules — Three tools need format transforms:

   • Cursor: Generate .mdc files with description, globs, and alwaysApply frontmatter from SKILL.md metadata
   • Windsurf: Generate rules with appropriate activation mode from skill description
   • Copilot: Generate .instructions.md with description and applyTo frontmatter

4. MCP config for tool-based targets — Tools that consume skills via MCP get a config entry pointing at the tome MCP server rather than direct file access. Goose is the primary MCP-only target.

5. OpenClaw/Nanobot as special cases — Their 8-file workspace model means a connector needs to map skills into the appropriate slot (AGENTS.md for instructions, TOOLS.md for capabilities, etc.) or just target their skills directory.

What’s Portable vs. What’s Not

Tool-specific skill extensions are lost in translation — tome should preserve them in metadata when syncing between tools of the same type, but can safely drop them when translating to a different format family.

The Convergence Trend

As of Feb 2026, the industry is consolidating around:

1. Agent Skills (SKILL.md) for portable instructions — the clear winner
2. MCP for portable tool integrations — universal adoption
3. Markdown instruction files for project rules — same concept, different filenames

Everything else (hooks, agents, plugins, memory) remains fragmented with no signs of standardization. For tome, this means the v1 focus on skills + MCP + instruction files covers the portable surface area. Extended structures would require per-tool connectors with no format translation possible.

20. Skill Installers: npx skills (Vercel Labs)

npx skills is a JavaScript-based skill installer with a polished interactive CLI. It supports 41 agent targets and uses a two-tier architecture remarkably similar to tome’s library model.

Registry: skills.sh — browsable skill registry with per-skill detail pages.

Architecture

Canonical copies are stored in .agents/skills/<name>/ (the emerging universal path) or tool-specific directories. Distribution to individual tools uses symlinks from their native skill dirs back to the canonical location.

Install flow: clone repo → select skills → select targets → choose scope (project/global) → choose method (symlink/copy) → security assessment → install.

.skill-lock.json (v3)

Lockfile at .agents/.skill-lock.json tracks installed skills with provenance and content hashes:

{
  "version": 3,
  "skills": {
    "skill-name": {
      "source": "owner/repo",
      "sourceType": "github",
      "sourceUrl": "https://github.com/owner/repo.git",
      "skillPath": "skills/skill-name/SKILL.md",
      "skillFolderHash": "c2f31172b6f256272305a5e6e7228b258446899f",
      "installedAt": "2026-03-06T12:49:32.629Z",
      "updatedAt": "2026-03-06T12:49:32.629Z"
    }
  },
  "dismissed": { ... },
  "lastSelectedAgents": ["amp", "cline", "codex", "cursor", "..."]
}

Key fields: sourceType + sourceUrl for provenance, skillFolderHash for content-based idempotency (similar to tome’s SHA-256 manifest hashes), installedAt/updatedAt timestamps.

Agent Targets (41 total)

Universal agents (share .agents/skills/ as project-scoped path):

Additional agents (tool-specific paths):

CLI Commands

Security Assessment

The installer integrates security risk assessment with three providers:

Each skill gets a security rating before installation, with a link to details on skills.sh.

Implications for tome

1. .agents/skills/ is the emerging universal path — 9 agents converge on it. Tome’s Directory source type can discover skills there today.
2. Lockfile as prior art for tome.lock — .skill-lock.json v3 tracks the same concepts tome needs: content hashes for idempotency, source provenance, install timestamps.
3. Symlink vs copy choice — npx skills offers both, recommending symlink. Tome already uses this model (library copies + symlink distribution).
4. Security assessment — interesting prior art for a future tome audit command.
5. 41-agent coverage — significantly expands the known agent landscape beyond tome’s current connector list.

Sources

Standards & Specifications

• Agent Skills Open Standard — format specification
• Agent Skills Specification
• Model Context Protocol — tool integration standard

Claude Code

• Skills Docs — full frontmatter reference
• Memory Docs
• Hooks Reference — lifecycle events
• Hooks Guide — hook types and matchers
• Subagents — agent configuration
• Plugins Reference — plugin manifest
• MCP Configuration — MCP server setup
• Settings — permission system
• GitHub Issues: #10589, #11322, #17119, #13932, #2154

Codex CLI

• Skills — discovery and invocation
• CLI Features — hooks, sandbox, telemetry
• AGENTS.md Guide — instruction file format

VS Code Copilot

• Custom Instructions — instruction files
• Agent Skills — SKILL.md support
• Agent Mode — agents
• Copilot Memories — memory system
• Building Extensions — plugin system

Cursor & Windsurf

• Cursor Rules Guide — .mdc format and activation modes
• Windsurf Rules
• Windsurf Cascade Memories — rules and activation
• Windsurf Cascade Hooks — lifecycle events

Gemini CLI & Antigravity

• Gemini CLI Context Files
• Gemini CLI GEMINI.md — context files
• Gemini CLI Extensions — extension system
• Antigravity MCP Integration

OpenClaw, Amp, Goose, Aider, Others

• OpenCode Rules — AGENTS.md format
• OpenClaw Memory Files — SOUL.md, HEARTBEAT.md, etc.
• Amp Skills Migration — commands → skills
• Goose Extensions — MCP-based extensions
• Aider Configuration — YAML config
• Nanobot (HKUDS) — OpenClaw-compatible agent
• PicoClaw — ultra-lightweight agent

Skill Installers

• npx skills (Vercel Labs) — 41-agent skill installer with lockfile and security assessment
• skills.sh — skill registry with per-skill detail pages and security ratings

Analysis & Security

• Skills Are More Context-Efficient Than MCP — token comparison
• MCP Token Problem — efficiency analysis
• Claude Skills vs MCP — technical comparison
• Why Cursor Rules Failed and Claude Skills Succeeded — format comparison
• The Memory Manipulation Problem
• Hidden Unicode Backdoors in Agent Skills

Frontmatter Compatibility

SKILL.md files use YAML frontmatter to declare metadata. The base standard comes from the Agent Skills spec, but each platform extends it with its own fields. This page documents the current state of compatibility across tools.

Base Standard (agentskills.io)

Platform Extensions

These fields are valid on their respective platforms but will be silently ignored (or warned about) elsewhere.

Codex uses a separate agents/openai.yaml file instead of extending SKILL.md frontmatter.

Non-Standard Fields Found in the Wild

These appear in community skills but are not part of any spec. They will be silently ignored by standard-compliant tools.

Known Bugs & Gotchas

VSCode validator flags valid fields

The VS Code Copilot extension’s skill validator has an outdated schema that flags allowed-tools as unsupported, even though it’s part of the base spec. This is a known issue.

Multiline YAML descriptions break on Claude Code

Claude Code’s SKILL.md parser does not handle implicit YAML folding (Prettier-style wrapped lines). Descriptions that span multiple lines without an explicit block scalar will be silently truncated.

Breaks:

---
description: This is a long description that has been
  wrapped by Prettier across multiple lines
---

Works:

---
description: This is a long description on a single line
---

Also works (explicit block scalar):

---
description: |
  This is a long description that uses
  an explicit block scalar indicator
---

Unknown fields are silently ignored

All standard-compliant tools silently ignore unknown frontmatter fields. The VS Code extension is an exception — it shows warnings for unrecognized fields. This means non-standard fields won’t cause errors but also won’t do anything.

Case sensitivity

• All field names must be lowercase
• The filename must be exactly SKILL.md (uppercase)

Platform Limits

How tome Uses This

tome currently symlinks skill directories as-is without parsing frontmatter. The v0.3.x release will add:

• Frontmatter parsing during discovery
• tome lint command with tiered validation (errors, warnings, info)
• tome doctor frontmatter health checks
• tome status metadata summary per skill

See the Roadmap for details.

Vercel Skills Comparison

Research into vercel-labs/skills (npx skills) — the closest comparable project to tome. Both manage AI coding skills across multiple tools. This doc catalogs features and tooling patterns tome is missing to inform roadmap decisions.

Last updated: March 2026

1. Overview

Core philosophical difference: Tome treats the library as the source of truth — skills are consolidated into a local library, then distributed to targets. Vercel Skills is an installer — it fetches from remote sources and symlinks directly into agent directories. There’s no intermediate “library” abstraction.

2. Feature Comparison

3. Notable Features Tome Lacks

3.1 Remote Git Sources

Vercel’s source parser accepts multiple formats:

skills add owner/repo                    # GitHub shorthand
skills add owner/repo@skill-name         # specific skill from repo
skills add owner/repo/tree/main/skills/  # subpath targeting
skills add https://gitlab.com/org/repo   # GitLab
skills add git@github.com:owner/repo.git # SSH
skills add ./local-path                  # local directory

Branch/tag targeting via /tree/<ref> syntax. Subpath extraction lets users install a single skill from a multi-skill repo.

Tome status: Planned for v0.6 (Git Sources). Vercel’s UX — especially the shorthand syntax and subpath targeting — is worth studying when designing tome add.

3.2 Skill Scaffolding (skills init)

npx skills init my-skill

Generates a SKILL.md template with frontmatter boilerplate. Low complexity, high convenience for skill authors.

Tome status: Not on roadmap. Would be a simple addition — tome new <name> that creates <name>/SKILL.md with a frontmatter template. Consider adding as a quick win.

3.3 Public Search & Registry

skills find [query] provides:

• Interactive terminal UI with keyboard navigation
• API-backed search at https://skills.sh/ (top 10 results, sorted by install count)
• Debounced queries with formatted output

The registry at skills.sh acts as a public directory of community skills. This creates a discovery loop: authors publish, users search, install counts drive ranking.

Tome status: Not on roadmap. A public registry is a significant undertaking. However, integrating with skills.sh as a read-only source could be a lighter-weight option — tome could query the same API without building its own registry.

3.4 Remote Update Checking

skills check POSTs to a backend API with current lockfile state, compares GitHub tree SHAs to detect available updates. skills update then fetches and replaces.

Tome status: tome sync exists but only diffs the local lockfile against the current discovery state. It doesn’t check remote sources for newer versions. Once git sources land (v0.6), remote update checking should follow naturally.

3.5 Well-Known Providers

Vercel supports RFC 8615 /.well-known/skills/index.json endpoints — any HTTP server can advertise available skills by hosting a JSON manifest at a well-known URL. This enables decentralized skill distribution without a central registry.

Tome status: Not on roadmap. Novel approach worth considering for the connector architecture. Could be a lightweight alternative to a full registry.

3.6 Agent Target Coverage (50+)

Vercel supports 50+ agents. Their agents.ts defines per-agent configuration including:

• Project and global skill paths
• Whether the agent shares the universal .agents/skills/ directory
• Installation detection method

Agents in Vercel not in tome’s KnownTarget list:

Many share the universal .agents/skills/ path. Tome’s data-driven target config already supports arbitrary agents, but expanding KnownTarget auto-discovery would improve the wizard experience.

Notable exception — OpenClaw: Unlike most tools that have a single skills path, OpenClaw has a two-level structure: a shared .openclaw/skills/ directory across all agents plus per-agent skills/ directories under each agent’s workspace. This may require a multi-path target model or an OpenClaw-specific connector extension.

Design consideration — per-target skill selection: Vercel’s --agent flag filters which agents receive a skill at install time, but the assignment is not persisted — their lockfile has no per-skill agent tracking. lastSelectedAgents is just a UX hint for the next prompt. Changing which agents have a skill requires reinstalling. This is a significant limitation.

Tome can do better by managing assignments entirely in machine.toml (no skill frontmatter changes needed). Proposed resolution model with layered precedence:

# machine.toml

# Global: applies to all targets unless overridden (existing behavior)
[disabled]
skills = ["noisy-skill"]

# Per-target: disable additional skills for this target
[targets.codex]
disabled = ["claude-only-skill"]

# Per-target allowlist: ONLY these skills go to this target
[targets.openclaw-agent-x]
enabled = ["specialized-skill"]

Resolution order:

1. Skill is enabled by default for all targets
2. Global disabled removes it everywhere (existing machine.toml behavior)
3. Per-target disabled removes it from specific targets only
4. Per-target enabled (if present) acts as an allowlist — only listed skills reach that target

This keeps the common case simple (everything goes everywhere) while supporting opt-out at two granularity levels. The enabled allowlist is only needed for niche cases like OpenClaw’s per-agent workspaces. All managed in tome settings — no skill frontmatter modifications required.

Tome status: Partially addressed in #248 (audit known targets against platform docs). The data-driven config means users can add any target manually, but wizard auto-discovery only covers 7 agents.

3.7 npm/node_modules Sync

skills experimental_sync scans node_modules/ for packages containing skills. This supports distributing skills as npm packages — a novel distribution channel.

Tome status: Not on roadmap. Low priority given the Rust ecosystem focus, but the concept of “skills as packages” in language-specific package managers is worth noting.

3.8 Plugin Manifest Compatibility

Vercel reads .claude-plugin/marketplace.json and .claude-plugin/plugin.json to discover skills bundled with Claude plugins. This enables compatibility with the Claude plugin marketplace ecosystem.

Tome status: Tome reads installed_plugins.json from the Claude plugin cache directory (a different integration point). The .claude-plugin/ manifest format is not currently parsed. Both approaches achieve plugin-sourced skill discovery, but through different mechanisms.

4. Tooling & DX Patterns

Source Parser

Vercel’s source-parser.ts normalizes diverse input formats into a unified ParsedSource type:

type ParsedSource = {
  owner: string;
  repo: string;
  provider: 'github' | 'gitlab' | 'local';
  ref?: string;           // branch/tag
  subpath?: string;       // path within repo
  skillName?: string;     // specific skill
}

This decouples source resolution from installation logic. When tome implements git sources, a similar parser would be valuable.

Lockfile Versioning

Vercel’s lockfile has a version field (currently v3). When an old-format lockfile is detected, it’s wiped entirely — users must reinstall. This aggressive migration strategy avoids complex upgrade code at the cost of user inconvenience.

Tome’s tome.lock doesn’t yet have a version migration strategy. Worth adding a version field early to avoid future pain.

Agent Auto-Detection

Vercel detects installed agents asynchronously by checking for agent-specific markers (config directories, binaries). This enables smart defaults during installation — only install to agents the user actually has.

Tome’s wizard does basic path existence checks for known source/target locations, but doesn’t detect agents as a first-class concept. The wizard could benefit from a richer detection step.

Security: Path Sanitization

Vercel’s sanitizeName() prevents directory traversal via skill names, and isSubpathSafe() rejects .. segments. Tome’s SkillName type rejects path separators (/, \) at parse time, achieving the same goal through the type system. Tome’s approach is arguably stronger — invalid names can’t even be constructed.

5. Architectural Differences

Key takeaway: Tome’s library abstraction adds complexity but enables features Vercel can’t easily replicate (multi-machine sync, lockfile diffing, automated cleanup, diagnostics). Vercel’s installer model is simpler but single-machine.

6. Recommendations

Prioritized by effort-to-value ratio, mapped to existing roadmap items where applicable.

Quick Wins (small effort, immediate value)

1. Expand KnownTarget list — Add 15–20 more agents from Vercel’s list to wizard auto-discovery. Data-only change in wizard.rs. (Extends #248)

2. tome new <name> scaffolding — Generate a <name>/SKILL.md template with standard frontmatter. Simple new command. (New issue)

3. Lockfile version field — Add "version": 1 to tome.lock now, before we need migration logic. (New issue)

Medium-Term (aligns with existing roadmap)

4. Per-target skill selection — Extend machine.toml with per-target disabled/enabled lists. Layered resolution: global disabled → per-target disabled → per-target enabled allowlist. Enables OpenClaw per-agent workspaces and general skill-to-agent affinity. Vercel’s --agent flag is install-time-only with no persistence — tome can do better. (#253)

5. Source parser for git remotes — Study Vercel’s shorthand syntax (owner/repo, @skill-name, /tree/branch) when designing tome add. (Informs v0.6: Git Sources, #58)

6. Remote update checking — Extend tome sync to check remote sources, not just local lockfile diffs. (After v0.6)

7. Agent auto-detection — Upgrade wizard to detect installed agents dynamically rather than just checking path existence. (Enhancement to wizard)

Future Consideration (worth watching)

8. Well-known providers — RFC 8615 skill endpoints could complement git sources as a lightweight discovery mechanism. Novel and decentralized.

9. skills.sh integration — Read-only integration with Vercel’s public registry as a discovery source. Avoids building our own registry while providing discoverability.

10. Copy fallback — Vercel supports copy when symlinks fail. Tome is Unix-only and symlink-only. Worth considering if Windows support ever becomes a goal.

Test Setup

tome has two layers of tests: unit tests co-located with each module, and integration tests that exercise the compiled binary end-to-end. All tests run in CI on both Ubuntu and macOS.

Test Architecture

graph TB
    subgraph CI["GitHub Actions CI (ubuntu + macos)"]
        FMT["cargo fmt --check"]
        CLIP["cargo clippy -D warnings"]
        TEST["cargo test --all"]
        BUILD["cargo build --release"]
        FMT --> CLIP --> TEST --> BUILD
    end

    subgraph TEST_SUITE["cargo test --all"]
        UNIT["Unit Tests<br/><i>214 tests across 15 modules</i>"]
        INTEG["Integration Tests<br/><i>32 tests in tests/cli.rs</i>"]
    end

    TEST --> TEST_SUITE

Two Test Types

Unit Tests (co-located, #[cfg(test)])

Each module has a mod tests block that tests its public functions in isolation. These tests create temporary directories with tempfile::TempDir and never touch the real filesystem.

Integration Tests (tests/cli.rs)

These compile the tome binary and run it as a subprocess using assert_cmd. They verify the full CLI flow: argument parsing, config loading, pipeline execution, and output formatting.

graph LR
    subgraph Integration["tests/cli.rs"]
        CMD["assert_cmd<br/>spawns tome binary"]
        TMP["assert_fs::TempDir<br/>isolated filesystem"]
        PRED["predicates<br/>stdout assertions"]
        CMD --> TMP
        CMD --> PRED
    end

    subgraph Unit["#[cfg(test)] modules"]
        TEMP["tempfile::TempDir<br/>isolated filesystem"]
        SYML["unix_fs::symlink<br/>real symlink ops"]
        TEMP --> SYML
    end

Module-by-Module Breakdown

Note: Test counts below reflect a point-in-time snapshot. Run cargo test for current counts.

graph TB
    subgraph unit_tests["Unit Tests (214)"]
        CONFIG["config.rs<br/>─────────<br/>25 tests"]
        DISCOVER["discover.rs<br/>─────────<br/>17 tests"]
        LIBRARY["library.rs<br/>─────────<br/>31 tests"]
        DISTRIBUTE["distribute.rs<br/>─────────<br/>12 tests"]
        CLEANUP["cleanup.rs<br/>─────────<br/>8 tests"]
        DOCTOR["doctor.rs<br/>─────────<br/>20 tests"]
        STATUS["status.rs<br/>─────────<br/>18 tests"]
        LOCKFILE["lockfile.rs<br/>─────────<br/>15 tests"]
        MANIFEST["manifest.rs<br/>─────────<br/>8 tests"]
        MACHINE["machine.rs<br/>─────────<br/>12 tests"]
        UPDATE["update.rs<br/>─────────<br/>8 tests"]
        WIZARD["wizard.rs<br/>─────────<br/>6 tests"]
        PATHS["paths.rs<br/>─────────<br/>8 tests"]
        BROWSE["browse/<br/>─────────<br/>14 tests"]
        LIB["lib.rs<br/>─────────<br/>12 tests"]
    end

    subgraph integration_tests["Integration Tests (32)"]
        CLI["tests/cli.rs<br/>─────────<br/>32 tests"]
    end

    style CONFIG fill:#e8f4e8
    style DISCOVER fill:#e8f4e8
    style LIBRARY fill:#e8f4e8
    style DISTRIBUTE fill:#e8f4e8
    style CLEANUP fill:#e8f4e8
    style DOCTOR fill:#e8f4e8
    style STATUS fill:#e8f4e8
    style LOCKFILE fill:#e8f4e8
    style MANIFEST fill:#e8f4e8
    style MACHINE fill:#e8f4e8
    style UPDATE fill:#e8f4e8
    style WIZARD fill:#e8f4e8
    style PATHS fill:#e8f4e8
    style BROWSE fill:#e8f4e8
    style LIB fill:#e8f4e8
    style CLI fill:#e8e4f4

config.rs — 25 tests

Tests config loading, serialization, tilde expansion, validation, and target parsing.

discover.rs — 17 tests

Tests skill discovery from both Directory and ClaudePlugins source types, plus skill name validation.

library.rs — 31 tests

Tests the consolidation step — copying local skills and symlinking managed skills into the library.

distribute.rs — 12 tests

Tests the distribution step — pushing skills from library to target tools.

cleanup.rs — 8 tests

Tests stale symlink and manifest cleanup from library and targets.

doctor.rs — 20 tests

Tests library diagnostics and repair.

lockfile.rs — 15 tests

Tests lockfile generation, loading, and serialization.

machine.rs — 12 tests

Tests per-machine preferences loading, saving, and disabled skill/target tracking.

Run cargo test -p tome -- machine::tests --list for the full current list.

manifest.rs — 8 tests

Tests library manifest operations and content hashing.

status.rs — 18 tests

Tests status gathering and health checks.

update.rs — 8 tests

Tests lockfile diffing and triage logic used by tome sync.

wizard.rs — 6 tests

Tests wizard auto-discovery and overlap detection.

lib.rs — 12 tests

Tests orchestration-level functions (disabled skill cleanup, commit message generation, tome home resolution).

tests/cli.rs — 32 integration tests

Each test compiles and runs the tome binary in a temp directory with a custom config.

Filesystem Isolation Strategy

Every test creates its own TempDir that is automatically cleaned up when the test ends. This means:

• Tests never interfere with each other (no shared state)
• Tests never touch the real ~/.tome/
• No manual cleanup is needed
• Tests can run in parallel safely

graph TB
    subgraph test_env["Each Test Gets Its Own World"]
        TD["TempDir::new()"]
        TD --> CONFIG_FILE["config.toml<br/>(points library_dir to temp)"]
        TD --> SOURCE_DIR["source/<br/>skill-a/SKILL.md<br/>skill-b/SKILL.md"]
        TD --> LIBRARY_DIR["library/<br/>(copies + symlinks created here)"]
        TD --> TARGET_DIR["target/<br/>(symlinks distributed here)"]
    end

    subgraph assertions["Assertions"]
        FS["Filesystem checks<br/>is_symlink(), exists(),<br/>read_link(), read_to_string()"]
        COUNTS["Result struct counts<br/>created, unchanged,<br/>updated, linked, removed"]
        OUTPUT["CLI stdout<br/>predicate::str::contains()"]
    end

    test_env --> assertions

Test Dependencies

Defined in the workspace Cargo.toml and used via [dev-dependencies]:

How to Run Tests

# All tests (unit + integration)
make test              # or: cargo test

# Just one crate
cargo test -p tome

# A specific test by name
cargo test test_name

# Tests in a specific module
cargo test -p tome -- discover::tests

# Only integration tests
cargo test -p tome --test cli

# With output (see println! from tests)
cargo test -- --nocapture

CI Pipeline

GitHub Actions runs on every push to main and every PR, on both ubuntu-latest and macos-latest:

graph LR
    subgraph matrix["Matrix: ubuntu + macos"]
        A["cargo fmt --check"] --> B["cargo clippy -D warnings"]
        B --> C["cargo test --all"]
        C --> D["cargo build --release"]
    end

    PUSH["Push to main<br/>or PR"] --> matrix

The full pipeline is defined in .github/workflows/ci.yml. Running it locally is equivalent to:

make ci    # runs: fmt-check + lint + test

Roadmap

v0.1.x — Polish & UX

• Wizard interaction hints: Show keybinding hints in MultiSelect prompts (space to toggle, enter to confirm) — embedded in prompt text to work around dialoguer’s limitation.
• Clarify plugin cache source: Clarified in v0.4.1 (#312).
• Wizard visual polish: Color, section dividers, and summary output via console::style() — implemented in wizard.rs.
• Modern TUI with welcome ASCII art: Evaluate ratatui vs console + indicatif before committing to a framework. → Decision: ratatui + nucleo for interactive commands (tome browse), plain text for non-interactive commands. See v0.2.1 and v0.4.1.
• Progress spinners for sync (indicatif): Spinners during discover → consolidate → distribute → cleanup steps, implemented in lib.rs.
• Table-formatted output (tabled): tabled::Table used for tome list and tome status output.
• Explain symlink model in wizard: Clarify that the library uses symlinks (originals are never moved or copied), so users understand there’s no data loss risk.
• Optional git init for library: Wizard asks whether to git init the library directory for change tracking — implemented in wizard.rs.
• Fix installed_plugins.json v2 parsing: Current parser expects a flat JSON array (v1); v2 wraps plugins in { "version": 2, "plugins": { "name@registry": [...] } } — discovery silently finds nothing. Support both formats going forward.
• Finalize tool name: Decided on tome — “Cook once, serve everywhere.”
• GitHub Pages deployment: Add CI workflow to build and deploy mdBook + cargo doc to GitHub Pages.

v0.2 — Scoped SOT

Make the library the source of truth for local skills. tome sync copies skill directories into the library instead of creating symlinks back to sources. Distribution to targets still uses symlinks (target → library).

• Library as canonical home (#37): Local skills live directly in the library (real directories, not symlinks). tome sync copies from sources into library, making the library the single source of truth.
• Git-friendly library directory (#42): Library directory works as a git repo — local skills tracked in git, distribution symlinks are separate.
• Two-tier symlink model: Sources → (copy) → Library → (symlink) → Targets. Sources are read-only inputs; the library owns the canonical copies; targets get symlinks into the library.
• Idempotent copy semantics: Only copy when source content has changed (compare timestamps or content hashes). Skip unchanged skills to keep syncs fast.

Not in scope (deferred to v0.5): lockfile, tome update, per-machine preferences, managed source support, git-backed backup.

v0.2.1 — Output Layer ✓

Decouple output rendering from business logic. Prerequisite for tome browse (v0.4.1) and --json output (#167), ensuring new connectors in v0.3 get clean data separation from day one.

• Renderer trait (ui/mod.rs): Abstract output interface for sync reporting, skill listing, status display, doctor diagnostics, warnings, and confirmations — Closed as superseded (#183). Data struct extraction was the real prerequisite; ratatui (v0.4.1) will consume data structs directly rather than going through a trait.
• Data struct extraction: status::gather() -> StatusReport, doctor::diagnose() -> DoctorReport, sync pipeline returns SyncReport — pure computation separated from rendering
• Warning collection: Replace scattered eprintln! in discover/library/distribute with Vec<Warning> returned alongside results
• TerminalRenderer: Reimplements current output using console/indicatif/tabled/dialoguer — identical user-facing behavior, routed through the trait — Superseded along with Renderer trait.
• QuietRenderer: Replaces quiet: bool parameter threading with a renderer that suppresses non-error output — Closed as superseded (#188). Not needed without the Renderer trait; quiet parameter threading is sufficient.
• --json for tome list (#167): Trivially enabled once data structs exist — serialize Vec<SkillRow> directly

v0.3 — Connector Architecture ✓

Replaced the hardcoded Targets struct with a flexible, data-driven target configuration. Originally scoped as a full connector trait architecture, but the pragmatic first step — config flexibility — shipped as the milestone deliverable.

Delivered

• Generic [[targets]] array: Replaced the hardcoded Targets struct with BTreeMap<String, TargetConfig> (#175). Each target has a name, path, method (symlink/mcp), and connector-specific options. Data-driven KnownTarget registry in the wizard enables custom target support without code changes.
• npm-based skill source research (#97): Investigated npx skills (Vercel Labs). Confirmed: canonical copies in .agents/skills/<name>/, lockfile at .agents/.skill-lock.json (v3) with content hashes and provenance. A Directory source pointed at ~/.agents/skills/ works for basic discovery; a dedicated source type would preserve provenance metadata from the lockfile.
• .agents/skills/ as emerging universal path: 9 agents converge on .agents/skills/ as the project-scoped canonical skills directory. Documented in tool-landscape research.

Moved forward

• Connector trait → #192. Unified source/target interface. The BTreeMap solved config flexibility; the trait solves architectural abstraction.
• Built-in connectors → Part of #192. Claude, Codex, Antigravity, Cursor, Windsurf, Amp, Goose, etc.
• Format awareness per connector → Captured in #57 (Format Transforms).
• .claude/rules/ syncing → #193. Managed from ~/.tome/rules/, distributed to each target’s rules dir. See Tentative — Format Transforms.
• Instruction file syncing → #194. Managed from ~/.tome/instructions/, mapped to tool-specific filenames. See Tentative — Format Transforms.

v0.3.x — Portable Library (MVP) ✓

Complete the multi-machine skill management story. The lockfile (#38, shipped early) provides the diff mechanism; this milestone adds the interactive UX and per-machine control.

• Per-machine preferences (#39) (~/.config/tome/machine.toml): Per-machine opt-in/opt-out for skills — machine A uses skills 1,2,3 while machine B only wants 1 and 3. Disabled skills stay in the library but are skipped during distribution.
• tome update command (#40): Reads lockfile, diffs against local state, surfaces new/changed/removed skills interactively. Offers to disable unwanted new skills. Notification-only for managed plugins — auto-install deferred to v0.5.

v0.4.1 — Browse

Interactive skill browser. Depends on v0.2.1 output layer for clean data access.

tome browse — Interactive TUI (#162)

Full-screen interactive skill browser using ratatui for rendering and nucleo (Helix editor’s fuzzy engine) for matching. skim was ruled out because it owns the terminal and can’t be embedded in a ratatui layout.

• Basic list with fuzzy search (#164): fzf-style interactive filtering of library skills
• Preview panel (#165): Split-pane layout showing SKILL.md content alongside the list
• Sorting and grouping (#166): Sort by name/source/last synced, group by source
• Detail screen with actions (#169): Per-skill actions (view source, copy path, disable/enable)

Other v0.4.1 Items

• Enhance tome status display (#168): Health indicators (✓/✗/⚠), tilde-collapsed paths
• Clarify plugin cache source wording (#312): Clarified as “active plugins installed from Claude Code marketplace”

v0.4.2 — Skill Validation & Linting

YAML frontmatter parsing and a tome lint command that catches cross-tool compatibility issues. See Frontmatter Compatibility for the full spec comparison. Tracked in #47 and #176.

Frontmatter Parsing

• Add serde_yaml dependency
• Create SkillFrontmatter struct with typed fields (name, description, license, compatibility, metadata, allowed-tools, Claude Code extensions)
• skill.rs module: extract and parse YAML frontmatter from --- delimiters, capture unknown fields via #[serde(flatten)]
• Parse frontmatter during discovery (enrich DiscoveredSkill) — deferred to follow-up
• Store parsed metadata for status display — deferred to follow-up

tome lint Command

• lint.rs module with tiered validation (error/warning/info)
• tome lint CLI command with --format text|json and optional PATH argument
• Exits with code 1 on errors (CI-friendly)
• Missing name is a warning (Claude Code infers from directory), name mismatch is an error
• Unicode Tag codepoint scanning (U+E0001–U+E007F)
• Non-standard field detection (version, category, tags, etc.)
• Platform limit warnings (description >500 chars for Copilot, body >6000 chars for Windsurf)

Enhance Existing Commands

• tome doctor: Add frontmatter health checks alongside existing symlink diagnostics — parse all library skills and report validation results
• tome status: Show parsed frontmatter summary per skill — name, description (truncated), field count, and any validation issues inline

Target-Aware Warnings (Future)

Requires the v0.3 connector architecture. When distributing to specific targets, warn about:

• Fields unsupported by that target
• Description length exceeding target’s limit
• Body syntax incompatible with target (e.g., XML tags, !command, $ARGUMENTS)

v0.5 — Managed Sources ✓

Auto-install managed plugins, remote sync, and unified tome sync flow. Builds on the portable library foundation from v0.3.x.

• Auto-install managed plugins (#347, #355): tome sync detects missing managed plugins from the lockfile, prompts to install via claude plugin install <registry_id>. Runs before discovery so newly installed plugins are found immediately.
• Git repo scope to ~/.tome/ (#348, #350): Backup git repo moved from ~/.tome/skills/ to ~/.tome/, tracking skills, tome.toml, tome.lock, and future config. Top-level .gitignore excludes .tome-manifest.json.
• Remote sync in tome sync (#349, #353): Pull from remote before sync, push after commit. Fast-forward-only merges — diverged histories bail with actionable error. tome backup init offers remote setup wizard.
• Collapse tome sync and tome update (#352): tome update removed (breaking). tome sync now includes lockfile diffing and interactive triage. --no-triage flag for CI/scripts.
• Claude marketplace first (#41): Managed source targeting the Claude plugin marketplace. Version pinning via version string and git commit SHA (gitCommitSha). Lockfile records registry_id, version, and git_commit_sha for full reproducibility.
• Git-backed backup & restore (#94): tome backup init/snapshot/list/restore/diff with optional auto_snapshot pre-sync snapshots via [backup] config section.
• Portable config paths: Wizard writes ~/-prefixed paths in tome.toml for portability across machines.
• Shell completions (#208): tome completions <shell> for bash, zsh, fish, PowerShell via clap_complete
• Demote lockfile write failure to warning (#224): Lockfile write failures demoted to warning
• Skill lifecycle (#252): Forking, evaluation, and publishing workflow — unscoped, deferred

v0.6 — Git Sources

• Git sources (#58): Add type = "git" source for remote skill repositories with clone/pull on sync, caching, branch/tag/SHA pinning, and private repo support via SSH keys or token auth. Store source_url, git_ref, git_commit, skill_path_in_repo in manifest/lockfile.
• Standalone SKILL.md import (#92): Import standalone SKILL.md from arbitrary GitHub repos without requiring plugin.json
• Update skill source after the fact: Allow changing a skill’s source (e.g. from local directory to git repo) without removing and re-adding. Use case: “I started with a local copy, now I want to track their git repo instead.”

v0.7 — Skill Composition (“Wolpertinger”)

Highly experimental. Generate custom skills by combining or synthesizing content from multiple skill authors/sources.

• Multi-source skill synthesis (#267): Select parts from multiple skills (GitHub repos, Claude marketplace, npx skills) and let an LLM create a merged “franken-skill”
• ACP-based authentication: LLM calls go through an Agent Communication Protocol (ACP) flow — authenticate via existing CLIs the user already has (codex-cli, claude-code, gemini CLI) rather than requiring a separate OAuth/API-key setup
• Skill evaluation/creation skill (#268): A companion skill that agents can use to evaluate, validate, and author skills against the agent skills standard — dogfooding the format
• tome lint standard validation (extension): Extend tome lint (v0.4.1) to validate against the emerging agent skills standard, not just cross-tool frontmatter compat

Dependencies: v0.5 (managed sources for marketplace access), v0.6 (git sources for GitHub repos), v0.4.1 (lint infrastructure)

Tentative — Per-Target Skill Management

Convenient UX for managing which skills are active per target, and whether per-target config should live centrally or locally. Builds on #253 (per-target skill selection in machine.toml).

• Target skill management commands: Convenient CLI for adding/removing active skills per target without editing TOML by hand. E.g. tome target claude enable my-skill, tome target codex disable my-skill, or interactive via tome browse actions.
• Package-level toggling: Enable/disable all skills from a package at once (e.g. tome target codex disable --package axiom-ios-skills). Requires the package/repo label from SkillProvenance.registry_id. Also support glob patterns (e.g. asc-*). In machine.toml, this could be disabled_packages = [...] alongside the existing disabled skill set.
• Local per-target config: Investigate whether per-target config should live in the target folder itself (e.g. ~/.claude/tome.toml) instead of only centrally. Trade-offs:
  • Central (~/.tome/tome.toml): single source of truth, easy to version-control, but needs namespacing for per-target overrides
  • Local (e.g. ~/.claude/tome.toml): self-contained per tool, discoverable where the tool lives, but scattered across filesystem
  • Hybrid: local overrides central if present — local file wins for that target’s skill selection, central file is the default. Central config would need a [targets.<name>.skills] section or similar namespacing.
  • Current leaning: local replaces central for simplicity — if a local tome.toml exists in the target folder, it fully owns that target’s skill selection. No merge semantics to reason about.
  • Remaining question: How does this interact with machine.toml per-machine preferences?

Tentative — Format Transforms

Not yet scheduled. Needs more design work before committing to a milestone.

• Rules syncing (#193): Manage tool-specific rule files from ~/.tome/rules/, distributed via symlinks to each target’s rules directory (.claude/rules/, .cursor/rules/, etc.)
• Instruction file syncing (#194): Manage root-level instruction files (CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules) from ~/.tome/instructions/. High complexity — each tool expects a different filename and format; needs a mapping layer and conflict handling.
• Connector trait (#192): Unified source/target interface as an architectural abstraction over the existing BTreeMap config.
• Pluggable transform pipeline: Connectors declare input/output formats; the pipeline resolves the translation chain. Preserves original format — transforms are output-only.
• Copilot .instructions.md format: Copilot’s .instructions.md as a transform target alongside Cursor .mdc and Windsurf rules.
• Deprecate DistributionMethod::Mcp: Removed in #262. No known targets used MCP distribution — all major AI coding tools read SKILL.md files from disk via symlinks. The tome-mcp binary, tome serve command, and TargetMethod::Mcp distribution path were removed along with the rmcp and tokio dependencies. MCP support can be re-added if a concrete use case emerges.

Tentative — Expand Wizard Auto-Discovery

Scope needs clarifying before committing. The question: which global home-dir skill paths exist for tools not yet covered by the wizard (e.g. ~/.cursor/skills/, Windsurf’s equivalent, etc.)? Per-project paths (.github/skills/, .cursor/rules/) are explicitly out of scope — only global home-dir paths qualify.

• Audit which global home-dir paths exist across all major tools
• Add any confirmed paths to KNOWN_SOURCES in wizard.rs

Tentative — Watch Mode

Not yet scheduled. Low priority until core sync pipeline stabilizes.

• tome watch for auto-sync on filesystem changes (#59)
• Debounced fsnotify-based watcher
• Optional desktop notification on sync

Future — Companion macOS App

Native macOS skill manager app (inspired by CodexSkillManager):

• Browse & manage library: View all skills in the tome library with rendered Markdown previews using swift-markdown-ui
• Visual skill editing: Edit skill frontmatter and body with live preview
• Sync trigger: Run tome sync from the GUI with status feedback
• Source & target management: Configure sources and targets visually instead of editing tome.toml
• Health dashboard: Surface tome doctor and tome status diagnostics in a native UI
• Import/export: Import skills from folders or zip files; export skills for sharing
• Tech stack: SwiftUI (macOS 15+), swift-markdown-ui for rendering, invokes tome CLI under the hood

Future Ideas

• Plugin registry: Browse and install community skill packs (precursor to v0.7 Wolpertinger)
• Conflict resolution UI: Interactive merge when skills collide
• Shell completions: Shipped in v0.4.1 (#208)
• Homebrew formula: brew install tome
• Backup snapshots: Moved to v0.5 as git-backed backup (#94)
• Token budget estimation: Show estimated token cost per skill per target tool in tome status output
• Security audit command: tome audit to scan skills for prompt injection vectors, hidden unicode, and suspicious patterns
• Portable memory extraction: Suggest MEMORY.md entries that could be promoted to reusable skills (tome suggest-skills)
• Plugin output generation: Package the skill library as a distributable Claude plugin, Cursor plugin, etc.
• Publish on crates.io: Make tome installable via cargo install tome from the crates.io registry
• Improve doc comments for cargo doc: Module-level //! coverage is uneven across modules; no # Examples sections. Low priority polish.
• Syntax highlighting in browse preview: Render SKILL.md with markdown/YAML syntax highlighting in the tome browse detail panel (e.g. via syntect or tree-sitter-highlight). Low priority polish.
• Package/repo label for skills: Surface the plugin name (e.g. martinp7r/axiom-ios-skills) or git repo slug as a searchable package field in browse. Currently SkillProvenance.registry_id stores this for marketplace skills but it doesn’t reach the browse UI or fuzzy search. Would also enable “group by package” in browse.
• tome relocate (#333): Shipped in v0.3.7
• tome eject (#334): Shipped in v0.3.7
• Library inside a parent git repo: Superseded by the “git repo scope” item in v0.5. Open design question: scope git to just skills, or broader ~/.tome/ home including hooks/commands/agents.
• Plugin marketplace discovery (#309): Make tome skills discoverable in the Claude Code marketplace
• Vercel skills.sh format compatibility (#304): Evaluate mapping tome lockfile to/from Vercel’s skills-lock.json for cross-ecosystem compatibility
• Central library architecture (#306): Source skills should not be used directly — always go through the library as single source of truth
• Skill-scribe extraction (#307): Extract format conversion into a standalone skill-scribe package. See also format transform pipeline (#57)

API Reference

The full Rust API documentation is generated by cargo doc and hosted alongside these docs.

View API Reference