Skill Sync

Overview

This skill guides you through syncing Overdeck skills to its supported agent harnesses. The sync process copies complete, manifest-managed skill bundles from ~/.overdeck/skills/ into each native discovery directory.

Auto-Sync

pan up runs pan sync --if-changed automatically after the dashboard starts.
The startup sync skips work when sync inputs are unchanged. You rarely need to
run pan sync manually. Manual sync is useful when:

• You added new skills and want to sync without restarting the dashboard
• You want to preview changes with --dry-run
• You need to force-overwrite with --force

How Sync Works

~/.overdeck/skills/          (Overdeck skills cache)
        ↓ pan sync (manifest-managed copies)
~/.claude/skills/            (Claude Code)
~/.agents/skills/            (Codex, Pi, Oh My Pi)

~/.overdeck/workspaces/       (Workspace directories)
        ↓ pan sync (renders managed context)
~/.overdeck/context/{claude,pi,codex}-global.md
        ↓ managed launch (explicit harness transport)
Agent receives global, project, workspace, role, and briefing context

Key points:

• Skill bundles are copied recursively, including their scripts, references, and templates; empty source directories are ignored.
• Manifest ownership lets pan sync update Overdeck-managed files without overwriting user-owned skills.
• When a bundled skill, agent, rule, or hook is removed, the next sync prunes its managed cache and harness copies. Hooks in ~/.overdeck/bin/ are tracked by ~/.overdeck/bin/.overdeck-manifest.json; only hooks sync wrote are ever removed (PAN-3881).
• User-modified stale files are preserved, released from manifest ownership, and listed in the sync output.
• Claude Code discovers ~/.claude/skills/; Codex, Pi, and Oh My Pi discover the shared Agent Skills standard directory at ~/.agents/skills/.
• New harness sessions see changes after pan sync; already-running sessions keep the skill catalog loaded at launch.
• Invocation syntax belongs to the harness: Claude uses /skill-name, while Codex uses $skill-name or natural-language skill selection.
• Herdr (the default terminal backend, PAN-3956): sync verifies the herdr binary (installs it from
  https://herdr.dev/install.sh when missing), sets [session] resume_agents_on_restore = false in
  ~/.config/herdr/config.toml, makes sure this home's session server runs (overdeck-herdr.service
  on systemd hosts), and installs the pilot integrations (pi, omp, kimi, opencode) for installed
  harnesses. It updates the binary only when no session server is running for this home, and never
  restarts a running server — it prints the manual steps instead. Skipped under an explicit tmux backend,
  CI, or Vitest; --dry-run only prints what it would do.

Commands

Preview Sync (Dry Run)

pan sync --dry-run

Shows what would be synced without making changes:

Sync Plan (dry run):

claude:
  + skill/pan-help
  + skill/pan-up
  + skill/feature-work
  ! skill/my-custom [conflict]

Run without --dry-run to apply changes.

Execute Sync

pan sync

Output:

✓ Synced 24 Claude items and 24 shared skill files

Manual pan sync always runs a full sync, even when startup sync would skip.

Which tree sync distributes from

Hooks, bundled rules, skills, and templates all ship from sync-sources/. Sync
names the tree it read and how many files actually changed:

✔ Synced 23 hooks to ~/.overdeck/bin/ (2 updated, 21 unchanged)
  from /home/you/Projects/overdeck/sync-sources/hooks

0 updated means the deploy was a no-op — the deployed copies already matched.

The global pan symlink resolves into a pan reload deployment generation,
which is a detached worktree frozen at the commit it was built from. Sync
redirects to the checkout that generation was built from, and says so:

This `pan` is running from a `pan reload` deployment generation, which is frozen at the commit it was built from:
  /home/you/.overdeck/deployments/dashboard/.pan-reload-generation-b
  Syncing from the checkout it was built from: /home/you/Projects/overdeck/sync-sources

If no checkout is recorded, sync warns that it is about to distribute the frozen
copy and that merged fixes will not deploy — run pan reload first. To check
deployed hooks against the source tree at any time, run pan doctor and read the
Deployed Hooks row.

When sync distributes from a git checkout, it fetches that checkout's upstream
and warns when the checkout is behind it, or is on a branch other than the
remote's default branch (PAN-3881). It only warns; it never pulls or switches
branches, because the checkout may hold unpushed or uncommitted work:

WARNING: pan sync is distributing from /home/you/Projects/overdeck/sync-sources, which may be stale:
  - sync sources checkout /home/you/Projects/overdeck is 12 commits behind origin/main (and 1 ahead); merged skill, rule, agent, and hook changes (including deletions) will not be distributed.
  Update that checkout (e.g. `git -C /home/you/Projects/overdeck pull --ff-only` on main) and re-run `pan sync`.

pan doctor reports the same thing in its Sync Sources Checkout row. Doctor
does not fetch: it compares with the last-fetched upstream ref and says so, so
run git fetch in the checkout (or pan sync, which fetches) for a current gap.

Git hooks in sync-sources/hooks/git-hooks/ are installed as symlinks in each
registered project's .git/hooks/. When a git hook is deleted from the sources,
the next sync removes its dangling symlink and lists it in the output. Only
symlinks that point into Overdeck's own git-hook source dir and whose target is
gone are removed; other hooks and .backup copies are never touched (PAN-3881).

Startup Sync (Skip When Unchanged)

pan sync --if-changed

Used by pan up for the deferred background sync. If the sync-source inputs
are unchanged, it exits quickly:

[sync] skipped — inputs unchanged

Do not use --if-changed when you need to force a full refresh; run pan sync
or pan sync --force instead.

Force Sync (Overwrite Conflicts)

pan sync --force

Warning: This overwrites any conflicting skills in target directories.

Backup Only

pan sync --backup-only

Creates a backup without syncing.

Sync Targets

Bundled skills always reach every supported Overdeck agent harness; this is not an opt-in target list.

Discovery contract	Directory	Harnesses
Claude Code	~/.claude/skills/	Claude Code
Agent Skills standard	~/.agents/skills/	Codex, Pi, Oh My Pi

Bundled Claude Code Plugins

Some capabilities ship as Claude Code marketplace plugins rather than
file-copied skills (e.g. codex@openai-codex from openai/codex-plugin-cc,
which adds /codex:review and Codex task delegation). These are declared in
Overdeck's bundled sync-sources/plugins.json and installed by a pan sync
step through the claude plugin CLI:

• Missing marketplaces are added (claude plugin marketplace add), then the
  plugin is installed at user scope (claude plugin install <id> --scope user).
• Already-installed plugins are left untouched (delta operation).
• If the claude binary is missing or the network install fails, sync prints
  a warning and continues — plugin provisioning never fails a sync.

Verify with claude plugin list. Plugins load in new Claude Code
sessions, like all sync output.

Conflict Handling

A conflict occurs when an Overdeck-managed skill file was modified after installation. A pre-existing skill that Overdeck does not own is preserved.

Detecting Conflicts

pan sync --dry-run
# Look for lines with [conflict]

Resolving Conflicts

Option 1: Rename your custom skill

mv ~/.claude/skills/feature-work ~/.claude/skills/my-feature-work
pan sync

Option 2: Force overwrite (loses custom skill)

pan sync --force

Option 3: Keep both (rename Overdeck skill)

# Not recommended - better to use unique names

Workflow

Initial Setup

# 1. Initialize Overdeck (copies bundled skills)
pan init

# 2. Preview what will be synced
pan sync --dry-run

# 3. Execute sync
pan sync

# 4. Verify in your AI tool
# Claude: /skill-name; Codex: $skill-name

After Adding Custom Skills

# 1. Add skill to Overdeck directory
mkdir -p ~/.overdeck/skills/my-skill
# Create SKILL.md with proper frontmatter

# 2. Sync to all tools
pan sync

# 3. Verify
pan skills

After Updating Overdeck

# 1. Update package
npm update -g @overdeck/core

# 2. Re-run init to get new bundled skills
pan init

# 3. Sync to tools
pan sync

Backups

By default, Overdeck creates backups before syncing.

Backup Location

~/.overdeck/backups/
  2024-01-15T10-30-00/
    claude/
      skills/
    codex/
      skills/

Restore from Backup

# List backups
ls ~/.overdeck/backups/

# Restore specific backup (manual)
cp -r ~/.overdeck/backups/2024-01-15T10-30-00/claude/skills/* ~/.claude/skills/

Disable Backups

# In ~/.overdeck/config.toml
[sync]
backup_before_sync = false

Troubleshooting

Problem: Skills not appearing in AI tool
Solution:

1. Run pan sync (not just pan init)
2. Check target is in config: cat ~/.overdeck/config.toml
3. Verify symlinks exist: ls -la ~/.claude/skills/

Problem: Managed launch context is missing
Solution:

1. Run pan context diff to inspect the rendered sources; pan sync refreshes Overdeck-owned artifacts and never copies native instruction Markdown.
2. Check the context artifacts: ls -la ~/.overdeck/context/
3. Start a fresh managed session so it receives the current context.

Problem: Sync reports conflicts
Solution:

1. Check what's conflicting: pan sync --dry-run
2. Rename your custom skill or use --force

Problem: Symlinks broken after moving directories
Solution:

1. Remove broken symlinks: find ~/.claude/skills -xtype l -delete
2. Re-run sync: pan sync

Problem: Permission denied
Solution:

1. Check directory permissions: ls -la ~/.claude/
2. Ensure you own the directories

Reserved Skill Names

These names are reserved by Overdeck. Don't use them for custom skills:

Pan operations: pan-down, pan-help, pan-install, pan-issue, pan-plan, pan-quickstart, pan-setup, pan-status, pan-up, pan-config, pan-tracker, pan-projects, pan-sync, pan-docker, pan-network, pan-approve, pan-tell, pan-kill, pan-doctor, pan-diagnose, pan-logs, pan-rescue

Workflow skills: pan-task, bug-fix, claude-skill-creator, code-review, code-review-performance, code-review-security, dependency-update, feature-work, incident-response, onboard-codebase, refactor, release, session-health, web-design-guidelines, work-complete

Related Skills

• /pan:config - Configure sync targets
• /pan:help - List all available skills
• /pan:install - Initial setup