skill-harbor
Skill Harbor

Documentation

CLI Reference

Detailed documentation for all Skill Harbor CLI commands and flags.

⚓ CLI Reference

Explore the full suite of Skill Harbor commands designed for skill orchestration, synchronization, and governance.

dock <source>

Register a skill's source in the manifest.

<source> may be:

  • a GitHub repository
  • a local single-skill path
  • a local folder-backed source containing nested child skills

If a docked local folder contains child SKILL.md directories, Skill Harbor treats it as a collection source and rescans it during up. freshen forces a refresh of that rescan path.

For the conceptual model behind this, see Sources & Targets.

Flags:

  • -g, --global: Register the skill in the global manifest (~/.harbor/harbor-manifest.json).
  • -o, --override: Register the skill in the project overrides manifest (.harbor/harbor-manifest.overrides.json).

Example:

skill-harbor dock https://github.com/skill-mill/react-hooks --global

# Local filesystem source
skill-harbor dock ./skills/my-local-skill

# Folder-backed local source
skill-harbor dock ~/.rulesync/skills

# Project-only override entry
skill-harbor dock ./skills/my-debug-skill --override

Already have unmanaged skills living in active berths? skill-harbor fathom --ghosts and skill-harbor ghosts can discover them with the default autodetect scan mode or the narrower --scan-mode targets-only mode.

up

The Core Engine. Synchronizes, adapts, and berths skills into your agent's configuration folders.

Flags:

  • -l, --lockdown: Enforces a strict, manifest-only environment. Moves non-manifested skills to stowage.
  • -m, --migrate: Triggers the migration engine if legacy manifests or structures are detected.
  • -g, --global: Targets the user-level global manifest instead of the local project manifest.
  • -t, --target <name>: Restrict sync to one or more specific target berths. Accepts a single key like codex, a comma-separated list like codex,cursor, or repeated flags like --target codex --target cursor.

Example:

skill-harbor up --lockdown

# Sync only Codex
skill-harbor up --target codex

# Sync Codex and Cursor
skill-harbor up --target codex,cursor

# Also supported: repeat the flag
skill-harbor up --target codex --target cursor

freshen

Force-syncs fresh cargo. Bypasses the local hash cache to ensure you have the absolute latest versions of all remote and local skills.

Flags:

  • -g, --global: Freshen the global fleet instead of the local project fleet.

fathom

The skill intelligence and profiling engine. Measures token saturation, quality scores, and contract alignment.

Flags:

  • --report: Generates a high-level Harbor Health Report.
  • --details: Provides a deep heuristic breakdown for every skill.
  • --query <text>: Conducts a probabilistic Sonar audit using the configured LLM provider.
  • --contracts: Runs a stricter or more contract-focused semantic I/O audit mode during migration.
  • --ghosts: Scans agent folders for unregistered "Ghost" skills and offers to dock them.
  • --scan-mode <mode>: Ghost-only scan mode for --ghosts. autodetect is the default; targets-only uses the selected manifest's declared targets exactly.

Notes:

  • Fathom now includes contract health in default output and report modes.
  • --contracts is now a stricter / more focused contract-audit surface rather than the only way to see contract health.

For more details on the science behind Fathom, see the Fathom Deep Dive.

Status formatting note: Fathom renders berth/stowage placement in the concise form Label | .folder, and report JSON includes additive placement detail under vesselPlacements.

ghosts

Primary ghost inspection workflow for unmanaged skills discovered in active berths and stowage.

Flags:

  • -g, --global: Inspect ghosts against the global manifest.
  • --friendly: Reveal the separate friendly-ghost section instead of only showing the summary count.
  • -d, --details: Show the full ghost path and parsed SKILL.md frontmatter metadata when available.
  • --scan-mode <mode>: Choose autodetect (default) or targets-only.

Notes:

  • Default output shows active ghosts and summarizes friendly ghosts by count.
  • autodetect scans every detected berth/stowage location in the selected scope.
  • targets-only scans only the selected manifest's resolved targets; with no targets, it performs no scan.
  • Non-interactive runs never prompt for scan mode; use the default or pass the flag explicitly.
  • Friendly ghosts are a non-destructive classification; they are not docked, removed, or mutated by being marked friendly.
  • fathom --ghosts still exists as the ghost-aware inspection mode inside Fathom and follows the same scan-mode rules.
  • Ghost rows use the same concise placement format as Fathom while still distinguishing berth vs stowage.

For the conceptual model, see Ghosts.

voyager

End-to-end integration testing suite for agent-skill loops and deterministic benchmark-pack evaluation.

Usage:

  • skill-harbor voyager [query]
  • skill-harbor voyager -f <path>

Flags:

  • -f, --file <path>: Provide either a legacy single-scenario YAML definition or a Harbor-native benchmark-pack file.
  • -c, --compare: Run the same legacy scenario with and without skills, then report the delta.
  • --format <type>: Output pretty or json.
  • --save-trace [dir]: Persist run artifacts. Pack runs write a top-level summary.json plus per-scenario artifacts.
  • --model <name>: Override the model used for live Voyager simulation.
  • --baseUrl <url>: Override the API base URL for live Voyager simulation.

Notes:

  • Legacy single-scenario files and inline queries still use the live Voyager flow.
  • Benchmark-pack files are fixture-driven and API-key-free in v1, making them suitable for deterministic local/CI evaluation.
  • Direct SkillsBench ingestion is deferred; benchmark packs are Harbor-native.

For more details on integration testing, see the Voyager Deep Dive.

lighthouse

Generates a "Master Fleet Intelligence" prompt snippet. This is designed to be pasted into the project context of agents that don't support native skill discovery (like ChatGPT or basic Claude instances).

stow / unstow

Manage your agent's environment state.

  • stow: Safely backs up all current agent skills to .harbor/stowage.
  • unstow: Restores previously stowed skills to their original locations.

check

Verifies that all berthed skills have valid metadata and are correctly indexed for agent discovery.

Flags:

  • -g, --global: Check skills from the global manifest.
  • --strict: Escalate missing or underspecified contracts in addition to malformed ones.

Notes:

  • check now validates contract structure by default as part of skill correctness.
  • Missing contracts are warnings by default.
  • Malformed or contradictory contract declarations fail the command.

list

Shows a breakdown of all skills currently tracked by Skill Harbor, including their source URLs and local paths.

Flags:

  • -g, --global: List skills from the global manifest.

undock

Destructive. Purges the agent's skill folders of all currently berthed manifest items. This is useful for resetting a cluttered environment.

migrate

Interactive migration engine that modernizes a project from the legacy root-level layout to the consolidated .harbor/ standard.

The engine detects and offers to move:

  1. Root manifests — harbor-manifest.json plus any legacy harbor-manifest.local.json files are moved into .harbor/, with the legacy local filename renamed to harbor-manifest.overrides.json.
  2. Loose skill caches — Skill directories sitting directly in .harbor/ are relocated to .harbor/skills/.
  3. Broad gitignore rules — A blanket .harbor/ ignore is replaced with granular rules (.harbor/skills/, .harbor/stowage/) so that manifests and hooks can be committed.

Every step is interactive — nothing moves without confirmation.

Tip

You can also trigger migration during sync with skill-harbor up --migrate.

For context on why the .harbor/ layout exists, see The Manifest & .harbor.