# Skill Harbor > Understanding and using Skill Harbor This document contains the full content of all documentation pages for AI consumption. --- ## Introduction **URL:** https://docs.example.com/docs **Description:** The Declarative Skill Setup & Orchestration Engine. ![Skill Harbor Hero](./assets/hero.png) # ⚓ Skill Harbor ⚓ Instead of manual skill installation or fragile global configurations, Skill Harbor uses a declarative manifest to manage your team's "Collective Intelligence." It enables individuals and teams to **gain deep insights** into their skills, **hone** them for specific projects, and **orchestrate** their distribution seamlessly. **It is the intelligence infrastructure layer for professional development workflows.** ## 🏗️ The Harbor Workflow Basic Workflow ```mermaid graph TD Workspace[Your Project] -. "Add new skill" .-> Dock[⚓ skill-harbor dock] Workspace --> Up[⚙️ skill-harbor up] Dock --> Up Up --> Use([Skills Available to Agents]) subgraph "Intelligence & Verification" Use --> Light[🕯️ skill-harbor lighthouse] Use --> Fathom[📏 skill-harbor fathom] Use --> Voyager[⛵ skill-harbor voyager] end ``` ## 🏆 Skill Standards At the heart of the harbor is the **[Skill Standard](/docs/skill-standards)**. We believe that AI context shouldn't be a "black box." Every skill in your fleet follows a strict anatomy centered on: - **Strategic Headers**: `Purpose`, `Trigger`, and `Guidelines` for deterministic routing. - **Semantic Contracts**: Optional `Requires` and `Produces` keys to allow for safe skill chaining. - **Displacement Math**: Automated token counting to keep your "context wake" small. Harbor is intentionally **skills-first**. For the architectural boundary behind that decision, see **[Architecture & Product Boundary](/docs/foundations/architecture)**. ## 🧠 The Necessity of Curated Registries Empirical research suggests that LLMs cannot reliably self-generate procedural knowledge on the fly. In the SkillsBench evaluation, self-generated skills produced negligible or negative benefit on average. Skill Harbor addresses that failure mode by providing a vetted catalog of strategic skills, making a curated registry a safer operating model for reliable agent success. If you want the deeper comparison, see the FAQ entry: **[How does Skill Harbor align with SkillsBench?](/docs/faq/skillsbench)**. ## 🔍 What This Looks Like in Practice A new developer joins your team. Without Skill Harbor, they spend time manually copying prompt files into `.claude/skills/`, hoping they grabbed the right versions, and have no idea which skills their teammates are using. With Skill Harbor, they clone the repo and run one command: ```bash skill-harbor up ``` That single command reads the committed `.harbor/harbor-manifest.json`, fetches the latest versions of every skill, adapts them for each agent platform (Claude, Cursor, Codex), and berths them into the right configuration folders. Every developer on the team now has identical agent context. Later, a tech lead wants to verify the fleet before merging a PR that adds a new skill: ```bash # Does the new skill bloat the context window? skill-harbor fathom --report --max-tokens 15000 # Do the I/O contracts between skills still align? skill-harbor fathom --contracts # Does the agent actually use the right tools for this query? skill-harbor voyager -f harbor-voyager-test.yaml ``` If any check fails, the process exits with code 1 — ready to block CI. --- ## ⚓ Why You & Your Team Benefit Skill Harbor is built for the **Solo Captain** and the **Full Fleet Command**. ### 🚢 For Teams (Fleet Command) - **The Synced Brain**: Commit a `harbor-manifest.json` once, and every developer gets the same specialized skills and context instantly. No more "Works on my machine" agent behavior. - **Collaborative Governance**: Enforce strict `--lockdown` rules and semantic contract validation across your entire repository. - **Atomic Standardization**: Ensure all agents (Claude, Cursor, Codex, Antigravity) are playing by the same set of maritime rules. ### 🚣 For Individuals (Solo Captains) - **Skill Honing**: Use the **Loft Master** and **Fleet Surgeon** to right-size and refactor your personal skills for maximum performance. - **Context Insights**: Understand exactly how much "displacement" (tokens) your skills are consuming and avoid reasoning degradation. - **Global Fleet**: Manage a persistent user-level manifest to sync your personal brand of intelligence across every project you touch. --- ## ✨ Features at a Glance - **🚣 Insights & Refinement**: Mathematically audit your intelligence layer for token bloat and semantic collisions with **Fathom**. - **🚢 Enterprise Skill Sync Engine**: Standardize AI context rules for your entire repo. - **🏗️ Multi-Platform Support**: Automatic distribution to **Claude Code**, **Cursor**, **Codex**, and **Antigravity**. - **⚡ Parallel Synchronization**: Sync your entire fleet of skills concurrently for maximum performance. - **🌍 Global Fleet Control**: Manage personal and organization-wide skills across any project workspace. - **🛠️ Cross-Platform Transpilation**: Powered by `skill-porter` to convert skill formats between Gemini and Claude seamlessly. - **🔌 Idempotent**: Run `skill-harbor up` safely to pull down the latest adapted skill updates. --- ## ❓ Related FAQ - **[Benchmarking Overview](/docs/benchmarking/overview)** - **[Voyager vs Fathom](/docs/benchmarking/voyager-vs-fathom)** - **[How does Skill Harbor align with SkillsBench?](/docs/faq/skillsbench)** - **[Why Not Skills.sh?](/docs/faq/comparison)** - **[Why Not Agent Skill Harbor?](/docs/faq/agent-skill-harbor)** --- *Reference: Li, X., et al. (2026). SkillsBench: Benchmarking How Well Agent Skills Work Across Diverse Tasks. https://www.skillsbench.ai/skillsbench.pdf* --- ## Quickstart **URL:** https://docs.example.com/docs/quickstart **Description:** Initialize your harbor and sync your fleet in 3 easy steps. # 🚀 Quickstart Initialize your harbor and sync your fleet in record time. --- ## 🏗️ Next Steps --- ## Skill Standards **URL:** https://docs.example.com/docs/skill-standards **Description:** Understanding the harbor certified skill anatomy. # ⚓ Skill Standards Skill Harbor enforces a standardized anatomy for AI agent skills to ensure they are **platform-agnostic**, **auditable**, and **ready for automated chaining**. By following these standards, your skills are "Harbor Certified" and can be precision-engineered by the `up` command for various environments. Every skill is a combination of strategic markdown headers and optional metadata that define its purpose, constraints, and operational boundaries. ### 🌍 The Value of Portability File-based skills using the `SKILL.md` standard can improve performance across diverse commercial agent harnesses (including Claude Code, Gemini, and Codex) when they are well-authored and well-curated. By utilizing Skill Harbor as the middle layer, your team can manage and distribute skills universally while avoiding proprietary vendor lock-in. --- ## 🏗️ Skill Structure (Anatomy) Standardization is the key to deterministic agent behavior. Each `SKILL.md` file should include the following structural elements. ### 1. Strategic Headers These headers provide the core logic that agents use to understand their tools. --- ## 🤝 Semantic Contracts (I/O) To safely chain skills together, Harbor monitors **Engagements** via input/output contracts. You can define contracts in two ways. ### Method 1: Frontmatter (Recommended) Place a `contracts` block directly inside your skill's YAML frontmatter: ```yaml --- name: fetch-logs description: Fetches application logs from AWS Cloudwatch contracts: requires: aws_region: string service_name: string produces: log_stream: json array --- ``` ### Method 2: Markdown Sections Use `## Requires` and `## Produces` headers with an unordered list of code-ticked variable names: ```markdown ## Requires - `project_root`: path - `target_file`: path ## Produces - `refactor_log`: json - `new_component`: string ``` ### Validation Rules Contracts now participate in the default command model like this: - **`skill-harbor check`** validates contract structure by default. - **`skill-harbor check --strict`** escalates missing or underspecified contracts more aggressively. - **`skill-harbor fathom`** surfaces contract health as part of normal fleet analysis. - **`skill-harbor fathom --contracts`** acts as a stricter / more focused contract-audit mode during the migration period. That means: - **Missing Standards**: If no `contracts` frontmatter or `## Requires`/`## Produces` sections are found, the skill is surfaced as a warning by default. - **Malformed Structure**: If contract sections are malformed or declared types are invalid, `check` should fail. - **Missing Inputs**: If a skill requires a variable that no other skill produces, Fathom raises a **Warning** (the input may come from the user prompt). - **Type Mismatches**: If Skill A produces `user_id` as `integer` but Skill B requires it as `string`, Fathom can treat that as a fleet health problem and fail report gating. ### Customization You can change the header names to fit your team's nomenclature via `profiler.yaml`: ```yaml # profiler.yaml contracts: requiresHeader: "Inputs" producesHeader: "Outputs" ``` --- ## 🚢 Ship Classes (Displacement) We classify the scale of a skill by its **Token Displacement** to ensure the fleet remains light and efficient. | Class | Token Range | Payload Description | | :--- | :--- | :--- | | 🛶 **Dinghy** | < 500 | Lightweight utility or single-purpose prompt. | | ⛵ **Schooner** | < 1,500 | Standard tool definition with clear boundaries. | | 🚤 **Brigantine** | < 3,500 | Complex skill with multiple auxiliary sections. | | 🛳️ **Frigate** | < 7,000 | Heavyweight context; requires strict triggers to avoid bloat. | | 🚢 **Galleon** | 7,000+ | Massive cargo; use with caution in multi-tool environments. | --- ## 🛠️ Management & Control While the **Skill Standard** defines the *content* of a skill, the **[Manifest & .harbor Folder](/docs/foundations/manifest)** defines how that skill is tracked, versioned, and delivered to your agent fleet. --- *Reference: Li, X., et al. (2026). SkillsBench: Benchmarking How Well Agent Skills Work Across Diverse Tasks. https://www.skillsbench.ai/skillsbench.pdf* For the broader alignment story, see **[How does Skill Harbor align with SkillsBench?](/docs/faq/skillsbench)**. --- ## Benchmarking Overview **URL:** https://docs.example.com/docs/benchmarking/overview **Description:** How Skill Harbor approaches benchmarking, evaluation, and what it contributes beyond raw benchmark execution. # 📊 Benchmarking in Skill Harbor Skill Harbor is **not** trying to become a public leaderboard or replace benchmark projects like SkillsBench. Instead, Skill Harbor treats benchmarking as an **operational capability** inside a team workflow: - define what should be evaluated - run those evaluations repeatably - keep the evaluated skill set governed and portable - use the results to improve what the team actually ships That is the core difference. ## The basic idea A benchmark is only useful if it can survive contact with a real team: - the skill set must be known - the evaluated context must be reproducible - the results must be inspectable later - the benchmark should fit local development and CI, not only a research harness Skill Harbor's role is to make those conditions true. ## What Skill Harbor brings ### 1. Governed evaluation inputs Before you benchmark anything, you need to know **which skills are actually in play**. Skill Harbor gives you: - a manifest-driven source of truth - provenance for skill sources - consistent berthing across supported agent targets - fleet-level inspection and validation That means benchmarking is attached to a **known fleet**, not an ad hoc pile of prompt files. ### 2. Reproducible scenario evaluation Skill Harbor's contribution is not merely “run a benchmark.” It is to make evaluation: - **local-first** - **CI-friendly** - **portable** - **artifact-producing** That is why Voyager now grows toward **Harbor-native benchmark packs** instead of depending immediately on an external task format. ### 3. Clear separation between measurement and prediction Skill Harbor intentionally separates two different questions: 1. **What happened on a scenario?** 2. **What is this fleet likely to help or hurt?** Those belong to different surfaces: - **Voyager** answers the first question through scenario execution and result comparison. - **Fathom** answers the second question through heuristics, audits, token analysis, and routing-risk signals. See **[Voyager vs Fathom](/docs/benchmarking/voyager-vs-fathom)** for the boundary. ## Why this matters Without that separation, benchmarking tools tend to become muddy: - evaluators start acting like heuristic linters - heuristic tools start claiming benchmark truth - teams lose confidence in what each command is actually telling them Skill Harbor tries to keep the model clean: - **Voyager = empirical scenario evaluation** - **Fathom = predictive audit and fleet analysis** - **Skill Harbor overall = the governed system that makes both useful in practice** ## How this aligns with SkillsBench SkillsBench is a strong research and evaluation lens. Skill Harbor takes the lessons of that lens and makes them **operational**: - benchmark-style scenarios can be run locally - packs can be checked into a repo - teams can use CI to keep evaluation repeatable - evaluation can be tied back to the governed fleet they actually use So the goal is not “be SkillsBench inside Skill Harbor.” The goal is: > make benchmark-style learning actionable inside a real engineering workflow. ## Current direction The current Benchmarking direction in Skill Harbor is: 1. **Voyager compare mode** for with-skills vs without-skills uplift 2. **Harbor-native benchmark packs** for deterministic local/CI scenario evaluation 3. **Fathom usefulness heuristics** informed later by empirical evaluation data 4. **SkillsBench interop later**, as an adapter problem rather than a foundation dependency ## Related pages - **[Voyager vs Fathom](/docs/benchmarking/voyager-vs-fathom)** - **[Voyager](/docs/foundations/voyager)** - **[Fathom](/docs/foundations/fathom)** - **[How does Skill Harbor align with SkillsBench?](/docs/faq/skillsbench)** --- ## Voyager vs Fathom **URL:** https://docs.example.com/docs/benchmarking/voyager-vs-fathom **Description:** The product boundary between empirical scenario evaluation and predictive fleet analysis. # 🧭 Voyager vs Fathom One of the easiest ways to confuse Skill Harbor's evaluation story is to blur **Voyager** and **Fathom** together. They are related, but they do different jobs. ## Short version - **Voyager** measures what happens in a scenario. - **Fathom** analyzes what is likely to help or hurt before or across those scenarios. That distinction should stay intact even when Voyager adds deterministic benchmark packs. ## Voyager: empirical scenario evaluation Voyager is the place for questions like: - Did the skill-enabled path outperform the no-skills path? - Did the agent invoke the expected tools? - Did the scenario pass or fail? - What trace did the run produce? - Can this evaluation be reproduced in CI? So Voyager owns: - scenario execution - branch comparison - traces - assertions - pass/fail outcomes - benchmark-pack results ## Fathom: predictive and audit analysis Fathom is the place for questions like: - Is this fleet too large or too noisy? - Are skills colliding semantically? - Is the routing surface too vague? - How much context bloat is this adding? - Which skills look risky or promising before deeper evaluation? So Fathom owns: - heuristics - token/context analysis - contract validation - routing-risk signals - fleet-wide reports - predictive usefulness guidance ## Why benchmark packs still belong in Voyager It may feel surprising that **offline deterministic packs** are still a Voyager feature. But the important boundary is **not**: - online = Voyager - offline = Fathom The real boundary is: - **scenario outcomes = Voyager** - **predictive audit = Fathom** A deterministic benchmark pack still asks a Voyager question: > what happened in this scenario, and how did the with-skills branch compare to the without-skills branch? That is still empirical evaluation, even when the evaluation is fixture-driven and reproducible in CI. ## How they should work together The intended flow is: 1. **Govern the fleet with Skill Harbor** 2. **Inspect and predict with Fathom** 3. **Measure scenario outcomes with Voyager** 4. **Feed what you learn back into fleet refinement** In other words: - **Fathom** helps you decide what looks worth evaluating or trimming. - **Voyager** tells you what the scenario evidence actually says. ## A practical rule If a command produces: - scenario traces - branch outcomes - assertion results - uplift/regression evidence it belongs in **Voyager**. If a command produces: - heuristics - token/collision reports - probabilistic routing confidence - fleet-level recommendations it belongs in **Fathom**. ## Non-goal of Voyager benchmark packs Voyager benchmark packs should **not** become: - fleet health scores - heuristic usefulness scores - predictive deployment recommendations Those belong in Fathom. ## Related pages - **[Benchmarking Overview](/docs/benchmarking/overview)** - **[Voyager](/docs/foundations/voyager)** - **[Fathom](/docs/foundations/fathom)** --- ## Why Not Agent Skill Harbor? **URL:** https://docs.example.com/docs/faq/agent-skill-harbor **Description:** How Skill Harbor differs from Agent Skill Harbor, where they overlap, and when it makes sense to use both # Why Not Agent Skill Harbor? This question comes up because both projects use the word **Harbor**, both are about **agent skills**, and both help teams standardize AI context. The short answer is: > **Agent Skill Harbor is primarily a catalog and governance layer. Skill Harbor is primarily a sync, conversion, and runtime delivery layer.** They overlap, but they are not the same product. > **Positioning answer:** If someone asks *"Why not just use Agent Skill Harbor?"*, the cleanest answer is: **because a catalog is not the same thing as a deployment engine**. Agent Skill Harbor helps teams organize and govern skills across repositories. Skill Harbor helps teams actually fetch, convert, berth, isolate, and restore those skills in live agent runtimes. --- ## The shortest answer If your question is: - *"How do we collect, review, classify, and publish skills across a team or org?"* → **Agent Skill Harbor** is aimed more directly at that problem. - *"How do we make sure the right skills actually land in Claude, Cursor, Codex, Gemini, Continue, Windsurf, Copilot, or Rulesync on developer machines?"* → **Skill Harbor** is aimed more directly at that problem. A useful mental model is: - **Agent Skill Harbor** = **catalog / governance / marketplace** - **Skill Harbor** = **delivery engine / orchestrator / berth manager** --- ## Quick comparison | Area | Agent Skill Harbor | Skill Harbor | | --- | --- | --- | | Primary role | Catalog and governance layer | Sync and runtime delivery layer | | Main operating model | Separate control-plane repo for collecting and publishing skills | Repo-adjacent manifests plus live target synchronization | | Best for | Org-wide discovery, provenance, approval, publication | Installing the right skills into real agent targets | | Works across many repos | Yes, as a catalog/control plane | Yes, via manifests and global fleet sync | | Lives alongside a working repo | Not as its main identity | Yes, explicitly | | Converts skills for targets | Not its primary value proposition | Yes | | Manages live root skill folders | Not as its primary surface | Yes | | Cleanup / restore operations | Not clearly a first-class workflow | Yes: `stow`, `unstow`, `undock`, `--lockdown` | --- ## When should I use which? Use **Agent Skill Harbor** when your main need is: - building a browsable internal skill catalog - collecting skills from many repositories - tracking provenance, approval, and publication - managing skill discovery at the organization level Use **Skill Harbor** when your main need is: - declaring the skill fleet a repo should use - syncing skills into real agent runtimes - converting skills for different targets - isolating workspace state with manifests and lockdown - cleaning up, restoring, or auditing installed skill folders Use **both** when you want: - a central system of record for what is approved - plus a deterministic way to install that approved fleet into live developer environments --- ## Where they overlap Both projects help with: - organizing agent skills for teams - sharing skills through Git and repository workflows - improving consistency across developers - making governance and standardization more explicit If all you need is a broad answer to *"Do these repos live in the same space?"* the answer is **yes**. --- ## Where Skill Harbor is different Skill Harbor is built around the operational workflow of: 1. **declaring skills in a manifest** 2. **fetching them into harbor-controlled staging** 3. **processing or converting them for the target runtime** 4. **berthing them into real agent directories** 5. **checking, stowing, restoring, and governing that installed state** That is why the center of Skill Harbor is commands like: - `dock` - `up` - `check` - `fathom` - `stow` - `unstow` - `undock` This is a strong fit when you care about: - deterministic rollout into live agent environments - one-command workspace synchronization - multi-target delivery - target-aware conversion between agent ecosystems - local, project, and global harbor layering - install-time governance and workspace isolation --- ## Where Agent Skill Harbor appears stronger At a high level, Agent Skill Harbor appears more focused on: - cataloging skills across repositories - provenance and publication - approval/governance workflows - organization-level browsing and discovery - marketplace-style visibility into what skills exist That is a different value proposition from *"take this declared fleet and install it into my actual agent berths."* --- ## Why not just use Agent Skill Harbor? Because a **catalog** is not the same thing as a **deployment engine**. Knowing that a skill exists, is approved, or is recommended is valuable. But a team still has to answer questions like: - How does that skill get onto a developer's machine? - How does it get transformed for Claude vs. Gemini vs. Codex? - How do we keep project-specific skills from bleeding across client workspaces? - How do we detect missing berths or drift in installed state? - How do we restore or lock down the environment safely? Those are the kinds of problems Skill Harbor is designed to solve directly. --- ## Can both make sense together? Yes — and this is often the best way to think about them. A practical split is: - use **Agent Skill Harbor** as the **system of record** for cataloging, provenance, review, and approval - use **Skill Harbor** as the **runtime delivery engine** that syncs the approved fleet into actual agent targets In that model, the two projects are **complementary** rather than redundant. --- ## Do both help manage or clean up user root skills? Not in the same way. ### Skill Harbor: yes, explicitly Skill Harbor directly manages the **installed state** in real agent roots and project berths. That includes things like: - a project manifest at `.harbor/harbor-manifest.json` - a global manifest at `~/.harbor/harbor-manifest.json` - syncing into active agent targets with `up` - cleaning and restoring state with `stow`, `unstow`, and `undock` - isolating sensitive workspaces with `up --lockdown` So if your question is *"Can this tool help me control what is actually sitting in `.claude/skills`, `.agents/skills`, or similar folders?"* the answer for Skill Harbor is **yes**. ### Agent Skill Harbor: not as its primary surface Agent Skill Harbor appears stronger as a **catalog, provenance, and governance layer** than as a direct manager of live root skill folders. From its public documentation, it clearly supports: - collection - cataloging - governance labels - post-collect analysis plugins - drift-oriented auditing in the catalog pipeline But it does **not** present itself primarily as a tool for: - stowing and restoring local root skills - purging live agent berths - managing installed skills directly inside local runtime folders So the practical distinction is: > **Skill Harbor manages live installed skill state. Agent Skill Harbor manages catalog and governance state.** --- ## Which one is more mature? That depends on **which layer** you mean. - If you mean **catalog, governance, and publication UX**, Agent Skill Harbor may be the more natural comparison point. - If you mean **multi-target sync, target conversion, and live workspace delivery**, Skill Harbor is solving a more specific operational problem. So the better question is usually not *"Which one wins?"* but *"Which layer of the workflow do we need to own?"* --- ## Another important comparison area One of the most important comparison areas is **install-time policy enforcement**. Not just: - *Can we mark skills as approved or discouraged?* But also: - *Can we prevent prohibited skills from being installed?* - *Can we detect drift between approved state and installed state?* - *Can we revoke or replace installed skills reliably?* That is where catalog tooling and delivery tooling usually diverge the most. --- ## Bottom line If someone says **"Why not just use Agent Skill Harbor?"**, the most accurate short answer is: > Because Agent Skill Harbor helps you manage and publish a skill catalog, while Skill Harbor helps you actually sync, convert, berth, and govern those skills in live agent runtimes. Use **Agent Skill Harbor** when your primary problem is **cataloging and governance**. Use **Skill Harbor** when your primary problem is **operational rollout into real agent targets**. Use **both** when you want a catalog **and** a deterministic delivery path. --- ## Why Not Skills.sh? **URL:** https://docs.example.com/docs/faq/comparison **Description:** A detailed breakdown of the differences between Skill Harbor and Vercel's skills.sh # Why Not Skills.sh? This document provides a detailed breakdown of the differences between **Skill Harbor**, Vercel's **skills.sh**, and the low-level **skill.fish** utility. It clarifies why you would choose one over the other, and specifically why I do *not* use `skills.sh` under the hood for Skill Harbor. --- ## Why use Skills.sh vs Skill Harbor While both tools deal with "Agent Skills," their core purposes, target audiences, and architectural philosophies are fundamentally different. **Think of the difference as `npm` (Package Manager) vs. `Docker Compose` (Environment Orchestrator).** ### 📦 When to use Skills.sh (The Package Manager) **`skills.sh`** (built by Vercel Labs) is a massive, centralized registry and CLI designed for discovering and installing community skills. * **Core Purpose**: Fast discovery and installation of one-off skills. * **How it works**: You run `npx skills add `, and it searches its online directory, downloads the skill, and drops the raw files directly into your local IDE folder (like `.claude` or `.cursor`). * **Best for**: Individual developers looking to enhance their personal workflow. If your goal is simply: *"I need a React skill I saw on a leaderboard, and I want it in my Claude agent right now,"* then `skills.sh` is the absolute best tool for the job. ### ⚓ When to use Skill Harbor (The Orchestrator) **`Skill Harbor`** was built to solve the **Enterprise & Team Synchronization Problem**. It governs the entire lifecycle of an AI agent's context across a shared repository. * **Core Purpose**: Enforcing strict consistency and governance across an entire engineering team, regardless of which AI agent each developer prefers. * **How it works**: A repository maintains a declarative `harbor-manifest.json`. Developers run a single `skill-harbor up` command. Harbor then fetches the exact skills defined in the manifest, cross-compiles them for the developer's specific agent (Claude, Cursor, Gemini), safely stows away any conflicting personal skills, and automatically generates a "Lighthouse" system prompt to teach the agent how to use its new capabilities. * **Best for**: Team workspaces. If your goal is: *"I need all 50 engineers on my team to share the exact same custom AI coding standards, strictly locked down, and cross-compiled for 4 different IDEs without manual configuration,"* then you need Skill Harbor. Harbor is intentionally **skills-first**, not a general-purpose synchronizer for every AI config artifact. For that product boundary, see **[Architecture & Product Boundary](/docs/foundations/architecture)**. --- ## Why I didn't use Skills.sh inside of Skill Harbor Given that `skills.sh` fetches files, it might seem logical for Skill Harbor to simply wrap `skills.sh` under the hood to handle downloading. However, doing so would completely break the enterprise architecture Skill Harbor provides. Instead, I rely on low-level utilities like **`skill.fish`** (for fetching) and **`skill-porter`** (for transpiling). Here is the detailed engineering breakdown of why I rejected `skills.sh` as an internal dependency: ### 1. The "Monolithic" Delivery Problem Skill Harbor's architecture requires strict separation of concerns into three phases: **Moor** (Fetch) ➔ **Process** (Adapt) ➔ **Berth** (Distribute). `skills.sh` is highly monolithic. When executed, it automatically drops the downloaded files *directly into your agent directories natively* (e.g., dropping them straight into `.claude/skills`). Because it forcefully handles the final delivery, it prevents Skill Harbor from intercepting the files. By contrast, `skill.fish` is a *pure fetcher*. It downloads raw repository files into a temporary staging area and intentionally stops there, handing the baton back to Harbor. ### 2. Loss of Cross-Platform Adaptation Because `skills.sh` natively installs the files, it entirely bypasses my **Process** phase (powered by `skill-porter`). Skill Harbor relies on this processing phase to translate skill formats between different AI agents. For example, fixing Markdown vs. XML structural differences between Claude Code and Google's Antigravity agent. If `skills.sh` places the files itself, I lose the ability to guarantee cross-platform compatibility. ### 3. Bypassing Strict Workspace Governance Skill Harbor treats agent context as ephemeral and highly sensitive. My `--lockdown` and `stow`/`unstow` engine guarantees that a developer's global, personal skills do not bleed into isolated client repositories. Because `skills.sh` writes directly to the local machine's configuration folders, it circumvents my sandboxing and governance layers completely. ### 4. Blinding the Lighthouse Intelligence Engine One of Skill Harbor's most powerful features is the **Master Fleet Manifest**. Every time Harbor orchestrates a sync, it analyzes all the incoming skills and generates a dynamic `000-fleet-intelligence.md` file—a "Zero-Tier" map that acts as a system prompt, teaching your AI agent exactly what capabilities it has and how to trigger them. If `skills.sh` handles the fetching and installation independently, Skill Harbor cannot accurately intercept, read, and synthesize the metadata from those skills, effectively "blinding" the Lighthouse engine. ### Summary Verdict `skills.sh` is an incredible tool for individual discovery and package management. However, its monolithic approach to fetching and immediately installing makes it incompatible as an underlying dependency for Skill Harbor, which must remain the sovereign "General Contractor" over the fetch, adapt, govern, and distribute lifecycle. --- ## Related FAQ - If you're specifically evaluating Skill Harbor against the newer SkillsBench research, see **[How does Skill Harbor align with SkillsBench?](/docs/faq/skillsbench)**. - If you're comparing catalog/governance platforms versus runtime delivery, see **[Why Not Agent Skill Harbor?](/docs/faq/agent-skill-harbor)**. --- ## How does Skill Harbor align with SkillsBench? **URL:** https://docs.example.com/docs/faq/skillsbench **Description:** Where Skill Harbor already aligns with the SkillsBench research, and where the benchmark points us next. # How does Skill Harbor align with SkillsBench? **Short answer:** Skill Harbor and SkillsBench are complementary.[^paper] - **SkillsBench** helps evaluate whether skills improve agent outcomes. - **Skill Harbor** helps teams **source, govern, distribute, and standardize** those skills across agents and repositories. In other words: SkillsBench is a research and evaluation lens. Skill Harbor is the operational system that makes high-quality skills usable in the real world.[^blog] --- ## Where Skill Harbor is already winning ### 1. Preventing runtime improvisation from becoming your skill strategy One of the clearest SkillsBench findings is that models are poor at inventing their own procedural scaffolding at runtime. In the paper's evaluation, **self-generated skills produced a negligible or negative effect on average, roughly -1.3 percentage points**.[^blog][^paper] The real implication is not just “self-generated skills are bad.” It is that teams should not treat last-second model improvisation as a substitute for shared operational knowledge. That is exactly where Skill Harbor is strongest: - skills are selected deliberately instead of invented in the moment - provenance is visible - the same vetted workflows can be reused across the team So the advantage is not merely curation in the abstract. The advantage is that Skill Harbor turns procedural knowledge into a **managed asset** instead of a runtime guess. ### 2. Converting a noisy public ecosystem into a trustworthy internal fleet The SkillsBench research also suggests that the broader public skill ecosystem has a quality problem: many skills are vague, bloated, or operationally weak. In the paper's scoring, the public ecosystem averaged only **6.2 out of 12**.[^paper] That creates a very practical team problem: even if great skills exist somewhere, most organizations still need a way to decide which ones deserve to become part of their standard operating context. Skill Harbor addresses that by giving teams a place to: - track provenance - standardize what is actually in use - validate and profile the fleet with tools like Fathom and Voyager - keep strong skills in circulation while keeping weak or noisy ones out So the win is not just “quality matters.” The win is that Skill Harbor gives a team the operational layer needed to turn a noisy public ecosystem into a **trusted internal skill supply chain**. ### 3. Turning portability into something teams can actually operate The important takeaway is not just that file-based skills *can* travel across different harnesses. The stronger point is that portability only becomes valuable when a team can distribute, adapt, and govern those same artifacts consistently.[^paper][^contrib] That aligns directly with Skill Harbor's architecture: - Harbor treats `SKILL.md`-style artifacts as portable cargo in a shared manifest-driven system - Harbor adapts and distributes the same skill set across multiple berths - Harbor preserves one source of truth while still handling platform-specific differences and governance controls So the win is not merely “skills are portable.” The win is that Skill Harbor turns portability into an **operational capability**: one governed fleet, many agent runtimes, consistent deployment. --- ## What SkillsBench reinforces about Skill Harbor's product direction The SkillsBench findings do **not** suggest that Skill Harbor should become a benchmark site.[^paper] They *do* reinforce several directions that fit Harbor well: 1. **Voyager compare mode** Run the same scenario with and without skills to measure actual uplift. 2. **Portable benchmark packs** Create local, self-contained scenario packs that teams can run in CI. 3. **Fathom usefulness heuristics** Score compactness, overlap risk, and the presence of examples/resources, not just raw token size. In practice, that means: - **Skill Harbor** manages and governs the fleet - **Voyager** measures whether the fleet helps - **Fathom** predicts where the fleet is likely to help or hurt --- ## So is Skill Harbor trying to replace SkillsBench? No. Skill Harbor is better understood as the system that makes SkillsBench-style lessons **actionable inside a team workflow**: - choose better skills - distribute them consistently - validate them across agents - measure whether they are actually helping That is why we treat SkillsBench as an important research input and evaluation model, while Skill Harbor remains focused on **governance, portability, and operational deployment**. --- ## References [^paper]: Li, X., et al. (2026). *SkillsBench: Benchmarking How Well Agent Skills Work Across Diverse Tasks*. SkillsBench paper: https://www.skillsbench.ai/skillsbench.pdf [^blog]: *Introducing SkillsBench: The First Benchmark for Agent Skills*. SkillsBench blog, February 10, 2026: https://www.skillsbench.ai/blogs/introducing-skillsbench [^contrib]: *Contributing | SkillsBench* — overview of SkillsBench's task model, skill composition goals, and the open skill standard context: https://www.skillsbench.ai/docs/contributing --- ## Architecture & Product Boundary **URL:** https://docs.example.com/docs/foundations/architecture **Description:** What Skill Harbor is, what it is not, and how that shapes the system. # ⚓ Architecture & Product Boundary Skill Harbor works best when its scope stays sharp. This page defines what Skill Harbor **is**, what it **is not**, and how that boundary shapes the architecture of the system. --- ## What Skill Harbor is Skill Harbor is a **skills-first orchestration and governance system** for engineers and engineering teams. More specifically, it is: - a **trusted internal skill supply chain** - a **skills refinement and distribution engine** - a **team standardization layer** for `SKILL.md`-style artifacts - a place to **learn better skill technique** through curation, validation, profiling, and authoring guidance That means Harbor is not just a place to copy files. It is the layer that helps teams: - fetch the right skills - adapt them for different agent environments - berth them consistently - validate them - profile their quality and cost - keep strong skills in circulation --- ## What Skill Harbor is not Skill Harbor is **not**: - a general-purpose rules engine - a subagent-management framework - a broad workspace configuration synchronizer - a replacement for every downstream tool's full ecosystem model Harbor may integrate with tools that support those broader surfaces, but Harbor itself remains centered on **skills**. That distinction matters because product sprawl would weaken the thing Harbor is trying to be best at: helping individuals and teams use skills well. --- ## The architectural consequence Because Harbor is skills-first, the architecture should preserve a strict boundary: 1. **Moor** — fetch raw skill cargo 2. **Process** — refine/adapt skill cargo for a target environment 3. **Berth** — place the adapted skill cargo into the right destination Harbor stays the system that owns that flow. External tools may help with part of the pipeline, but they should not erase Harbor's responsibility for: - skill orchestration - skill refinement - skill validation - skill governance - skill education and documentation If an integration makes Harbor less authoritative about skills, it is probably the wrong integration shape. --- ## Why this matters for RuleSync RuleSync is useful, but Harbor should only adopt it in ways that remain **skills-only**. That means the important question is not: > "Should Harbor become a full RuleSync-style context orchestrator?" It is: > "Should Harbor support a skills-only RuleSync integration path where that improves skill delivery without weakening Harbor's refinement and governance role?" Within that boundary, Harbor can support three increasingly strong shapes: ### 1. Target-only support Harbor berths processed skills into RuleSync-managed skill locations such as `~/.rulesync/skills`. ### 2. Skills-only RuleSync-backed processing Harbor may optionally support a more explicit RuleSync-backed skills path, but only if the implementation still preserves Harbor's ownership of skill refinement and verification. ### 3. Optional bridge behavior Harbor may optionally trigger a post-`up` RuleSync command, but only as an opt-in workflow enhancement and not as a default behavior for all users. --- ## What Harbor should explicitly reject Even if a downstream tool supports them, Harbor should reject scope creep into: - general rules distribution - subagent synchronization - non-skill workspace config management - broad "one tool for every AI config artifact" positioning Those capabilities may be useful elsewhere, but they are not Harbor's center of gravity. --- ## Harbor's long-term differentiation The strongest version of Skill Harbor is not "the tool that touches the most artifact types." It is: - the tool that understands **skills** best - the tool that helps teams **govern** skills - the tool that helps engineers **learn better skill technique** - the tool that turns a pile of prompt files into a **portable, auditable, high-signal skill fleet** That is the product boundary this architecture should protect. --- ## Related reading - [Manifest & `.harbor` Folder](/docs/foundations/manifest) - [Governance](/docs/foundations/governance) - [The Toolkit (Meta-Skills)](/docs/foundations/toolkit) - [Why Not Skills.sh?](/docs/faq/comparison) --- ## Fathom: Skill Insights & Audits **URL:** https://docs.example.com/docs/foundations/fathom **Description:** Measure skill quality, token saturation, and semantic contract alignment. # 📏 Fathom As your ecosystem of AI agent tools grows, injecting too many skills causes **"context bloat,"** which degrades model reasoning, increases latency, and raises API costs. Furthermore, overlapping tool definitions cause catastrophic semantic collisions and unpredictable agent behavior. The `fathom` command provides a rigorous, mathematical audit of your intelligence layer to guarantee your multi-tool ecosystem remains efficient, deterministic, and safe from context exhaustion. ## ⚓ Fathom TL;DR ```bash # Basic Heuristic Audit (Offline, Instant) skill-harbor fathom # Detailed Audit with Sonar (Probabilistic) skill-harbor fathom --query "Can you help me refactor this React code?" --details ``` --- ## 🧮 The Science of Fathom While Fathom leverages libraries like `js-tiktoken` for raw tokenization, the core "Intelligence Audit" is powered by custom heuristic formulas: --- ## 🛡️ Governance & CI/CD Gates Fathom can be used as a **Pull Request Gate** to prevent context exhaustion or quality degradation. When thresholds are breached, Fathom will **exit with process code 1**, effectively blocking CI/CD pipelines. - **`--max-tokens `**: Fail if total fleet tokens exceed limit. - **`--max-bloat

`**: Fail if GPT-4o context saturation exceeds percentage. - **`--min-score `**: Fail if average fleet quality score falls below threshold. - **default contract health**: contract warnings, invalid declarations, and mismatch data are part of normal Fathom analysis. - **`--contracts`**: Run a stricter or more contract-focused audit mode during the migration period. - **`--format json`**: Output machine-parsable data for programmatic consumption. --- ## 🤝 Semantic Contracts (Chaining Validation) To prevent hallucinations when passing unstructured data between linked skills, Fathom includes a **Semantic Contract Validation** engine. Contract health is now part of the normal Fathom model: - default output can show whether a skill's contracts are healthy, missing, or invalid - `--report` can surface fleet-level contract coverage, warnings, and mismatches - severe cross-skill mismatches can affect fleet health status Use `skill-harbor fathom --contracts` when you want a stricter or more focused contract audit during the migration period. If any explicit type mismatch is found (e.g., Skill A produces `json`, but Skill B requires `string`), Fathom can treat that as a hard fleet integrity problem. --- ## 👻 Ghost Skill Discovery For the broader mental model behind ghosts, friendly ghosts, and when to use the primary `skill-harbor ghosts` workflow versus `fathom --ghosts`, see [Ghosts](/docs/foundations/ghosts). A **Ghost** is any skill folder containing a valid `SKILL.md` that exists inside your agent berths (e.g., `.claude/skills/`, `.cursor/skills/`) or stowage but is **not registered** in your harbor manifest. Ghosts appear when skills are manually copied into agent folders, left behind after an undock, or created outside of the `dock` workflow. They represent untracked context that can affect agent behavior without being governed by your manifest. ### How it works When you run `skill-harbor fathom --ghosts`, Fathom: 1. Scans all **active agent berths** (Claude, Cursor, Codex, etc.) for directories containing a `SKILL.md`. 2. Scans **stowage berths** (`.harbor/stowage/`) for the same. 3. Compares discovered skill names against the selected manifest scope (merged local scope by default, or the global manifest with `--global`). 4. Any skill found in a berth but **not** in the manifest is flagged as a Ghost. Ghosts are included in the individual skill analysis output, tagged with a `[Ghost]` label. If `--report` is also active, ghost skill paths are merged into the health report scan. Berth and stowage status now use the same concise location-aware style throughout Fathom, for example: - `Berthed: Codex | .codex` - `Stowed: Codex | .stowage/codex` ### Scan mode `fathom --ghosts` supports the same ghost scan modes as `skill-harbor ghosts`: ```bash skill-harbor fathom --ghosts --scan-mode targets-only ``` - `autodetect` is the default and scans every detected berth/stowage location in the selected scope - `targets-only` restricts discovery to the selected manifest's resolved `targets` - `targets-only` with no declared targets performs **no scan** - `--scan-mode` is only meaningful when `--ghosts` is enabled ### Interactive Docking After the scan, if ghosts are found, Fathom can prompt you to **dock them** into the selected manifest scope: ```bash skill-harbor fathom --ghosts # 👻 Ghost Alert: Found 2 unregistered ghost skills in the local scope. # 🤔 Would you like to dock these to your local manifest now? (y/N) ``` Selecting `y` registers each ghost in the currently selected manifest scope (`local` by default, `global` with `--global`). --- ## 📡 Sonar: Probabilistic Confidence Fathom includes a **Sonar** engine that moves beyond local heuristics to measure real-world model behavior. By providing a sample user query, Fathom hits an LLM provider (OpenAI, Groq, Gemini, or Ollama) and extracts the exact **logprobs** (mathematical likelihood) of that skill triggering. - **`--query `**: Run a Sonar audit against all skills for a specific query. - **`--model `**: Override the model configured in `profiler.yaml`. --- ## 📊 Output Modes By default, Fathom prints a per-skill breakdown showing displacement, heuristic confidence, sonar confidence, and contract status for each skill in your manifest. ### `--report` Switches to an aggregate **Harbor Health Report** that summarizes the entire fleet in one view: total tokens, average confidence scores, ship class distribution, context window saturation across models (GPT-4o, Claude Sonnet, GPT-4o-mini), and fleet status (berthed / stowed / dry dock). Use this for a quick fleet-wide health check. ```bash # Fleet-wide summary skill-harbor fathom --report ``` When combined with `--details`, the report is printed first followed by the individual skill breakdowns. The pretty report also includes a bounded **Vessel Placements** section so you can see concise berth/stowage placement detail without losing the overall fleet counts. ### `--format json` Outputs all data as machine-parsable JSON instead of the styled terminal output. Works with both default and `--report` modes. Useful for piping into dashboards or CI scripts. Report JSON now includes an additive `vesselPlacements` field with structured berth/stowage detail: ```json { "name": "voice-to-structured-data", "berthed": [{ "label": "Codex", "location": ".agents" }], "stowed": [] } ``` ```bash # JSON output for CI consumption skill-harbor fathom --report --format json ``` --- ## ⚓ Why Use Fathom? Manually inspecting skill files for token bloat is impossible at scale. Fathom acts as your **Intelligence Auditor**: ### 🚢 The Fleet Scale (Displacement) | Class | Token Range | Payload Description | | :--- | :--- | :--- | | 🛶 **Dinghy** | < 500 | Lightweight utility or single-purpose prompt. | | ⛵ **Schooner** | < 1,500 | Standard tool definition with clear boundaries. | | 🚤 **Brigantine** | < 3,500 | Complex skill with multiple auxiliary sections. | | 🛳️ **Frigate** | < 7,000 | Heavyweight context; requires strict triggers to avoid bloat. | | 🚢 **Galleon** | 7,000+ | Massive cargo; use with caution in multi-tool environments. | --- ## Ghosts **URL:** https://docs.example.com/docs/foundations/ghosts **Description:** Understand unmanaged skills, how Fathom and Voyager surface them, and when to use ghost docking. # 👻 Ghosts Ghosts are one of the most important governance concepts in Skill Harbor. They explain why a workspace can behave differently than the manifest suggests, and why tools like **Fathom** and **Voyager** sometimes discover skill context you did not explicitly dock. Sometimes the harbor is not empty after all. Sometimes it is haunted. Not by cursed ships or sea monsters — by **skills you forgot were there**, copied by hand, left behind after an undock, or drifting around outside the manifest while still whispering instructions into your agents' ears. --- ## TL;DR - A **Ghost** is an unmanaged skill directory that exists in a berth or related scan scope but is not registered in your Harbor manifest. - `skill-harbor ghosts` is the primary explicit ghost-discovery workflow. - `skill-harbor fathom --ghosts` remains the ghost-aware inspection path inside Fathom. - Commands like **Fathom** and **Voyager** can still surface ghosts during their scans. - `voyager` can also surface ghosts automatically when it cannot find a clean manifested fleet to work with. --- ## What is a Ghost? A **Ghost** is any skill folder containing a valid `SKILL.md` that exists in a Harbor-relevant location but is **not** registered in the manifest Harbor is currently using. Common examples: - a skill manually copied into `.claude/skills/` - a skill left behind after an `undock` - a local skill added outside the `dock` workflow - a skill sitting in stowage or another scanned berth that Harbor is not governing yet Ghosts matter because they still affect agent behavior even though they are not governed by your manifest. In practice, that means a ghost can still haunt the harbor even when Harbor did not load it intentionally from your declared fleet. --- ## How commands surface ghosts Different Harbor commands can surface ghosts in different operational contexts. - **Fathom** surfaces ghosts during explicit governance and berth scanning - **Voyager** surfaces ghosts during fleet preparation when unmanaged local skills interfere with simulation readiness The important point is simple: > they are all still just **Ghosts** Harbor does **not** currently store a separate persistent object type for a “command ghost.” --- ## Ghosts vs folder-backed sources Do not confuse these: - **Ghost** = unmanaged, discovered during a scan - **Folder-backed source** = intentionally docked and managed by Harbor For example: - `skill-harbor dock ~/.rulesync/skills` - creates a managed folder-backed source - `skill-harbor fathom --ghosts` - discovers unmanaged local skill directories and offers to dock them If the folder is your real ongoing source of truth, prefer a **folder-backed source**. If skills are just sitting around locally and Harbor has not manifested them yet, use **ghost discovery**. See also: [Sources & Targets](/docs/foundations/sources-and-targets) --- ## How Fathom discovers ghosts When you run: ```bash skill-harbor fathom --ghosts ``` Fathom: 1. scans active agent berths 2. scans stowage berths 3. compares discovered skill names against the selected manifest scope 4. flags anything unmanaged as a ghost That means Fathom’s ghost model is berth-oriented and governance-oriented. ### Fathom scan scope Fathom checks: - active berths such as Claude, Cursor, Codex, Gemini, RuleSync, etc. - stowage under `.harbor/stowage/` - by default, every detected berth in the selected local or global scope (`autodetect`) - or only the selected manifest's declared `targets` when you pass `--scan-mode targets-only` If you choose `targets-only` and the selected manifest has no targets, Harbor performs **no ghost scan** instead of widening back to autodetect. ### Fathom output behavior - ghosts appear in individual analysis output tagged as `[Ghost]` - if `--report` is also enabled, ghost paths are merged into the health report scan - in interactive TTY runs, Fathom can then prompt you to dock them into the selected local or global manifest This makes Fathom the best explicit “show me unmanaged skill context” command in Harbor today. See also: [Fathom](/docs/foundations/fathom) --- ## `skill-harbor ghosts` Ghosts now has a dedicated entry point: ```bash skill-harbor ghosts ``` This is the primary explicit Ghosts workflow. ### Default behavior By default, `skill-harbor ghosts`: - shows active ghosts in the main section - shows a summary count of friendly ghosts - stays interactive and non-destructive - uses `--scan-mode autodetect`, which scans every detected berth/stowage location in the selected scope - shows berth/stowage placement in the same concise style used by Fathom, for example `berth: Codex | .codex` ### `--scan-mode` Use: ```bash skill-harbor ghosts --scan-mode targets-only ``` to limit ghost discovery to the selected manifest's declared `targets`. - `autodetect` is the default - `targets-only` uses the selected manifest's resolved `targets` exactly - if there are no declared targets, `targets-only` performs no scan - non-interactive runs never prompt for scan mode; use the default or pass the flag explicitly ### `--friendly` Use: ```bash skill-harbor ghosts --friendly ``` to reveal a separate friendly-ghost section with calmer/checkmark-style presentation. Friendly ghosts are still known to Harbor, but they are not docked, deleted, or mutated just because they were marked friendly. When a ghost is in stowage, Harbor keeps that semantic explicit in the display, for example `stowage: Codex | .stowage/codex`. ### `--details` Use: ```bash skill-harbor ghosts --details ``` to expand each displayed ghost with: - its full filesystem path - parsed `SKILL.md` frontmatter metadata when present If no frontmatter metadata is present, Harbor shows `metadata: none`. ### Relationship to Fathom `skill-harbor fathom --ghosts` still exists and follows the same scan-mode rules. Use it when you want ghost inspection inside a Fathom profiling run. Use `skill-harbor ghosts` when you want Ghosts as the primary workflow. --- ## How Voyager discovers ghosts Voyager’s ghost behavior is a little different. Voyager first tries to build an integration test surface from active berthed skills. If it cannot find a usable fleet, it may perform ghost discovery and offer to dock unmanaged skills. ### Voyager scan behavior Voyager: - scans the relevant local base directory for skills - excludes Harbor’s own cache (`.harbor/skills`) - treats unmanaged discovered skills as candidates for docking So Voyager’s command-ghost behavior is more workflow-oriented: - “I can’t simulate a clean fleet yet” - “I found skills you probably meant Harbor to manage” This is why Voyager ghost docking feels like a recovery/onboarding helper rather than a dedicated governance scan. See also: [Voyager](/docs/foundations/voyager) --- ## Ghost docking Once ghosts are found, Harbor can offer to dock them. ### Fathom ghost docking ```bash skill-harbor fathom --ghosts ``` If you accept the prompt, Harbor docks each discovered ghost into the currently selected manifest scope. ### Voyager ghost docking Voyager can also prompt to dock unmanaged skills when it discovers them during test preparation. That is especially useful when: - a team has local skills already present - Harbor was not yet fully manifested - you want quick insight workflows without manually docking each skill first --- ### What docking does Docking is how you bring a ghost under Harbor’s control. Once a ghost is docked, it stops being stray unmanaged context and becomes part of a manifest-governed workflow. Depending on scope, Harbor may write the resulting entry into: - the local project manifest - the global manifest That is why ghost docking is not just discovery — it is the step that converts a haunted berth into governed Harbor state. --- ## Ghosts, stowage, and bringing them under control Ghosts are not only found in active berths. Fathom also checks **stowage**, which means unmanaged skills can keep haunting a workspace even after they have been moved out of the active berth. ### How `stow` fits in `stow` is not a ghost-discovery command by itself. Its job is to move current agent context out of the active berth and into Harbor-managed backup storage. But that still matters for ghosts because: - unmanaged skills may end up in stowage during cleanup-oriented workflows - later, `fathom --ghosts` can surface them from stowage - then Harbor can offer to dock them properly into the manifest So: - **`stow`** helps control where unmanaged context lives - **`fathom --ghosts`** helps discover it - **`dock`** is how you bring it under Harbor governance ### Practical control paths If you want to bring ghosts under control, the common paths are: 1. **Scan for ghosts** ```bash skill-harbor fathom --ghosts ``` 2. **Dock the discovered ghosts** - accept the interactive prompt 3. **Or dock the durable source directly** - if the unmanaged skills actually come from a real ongoing source of truth ```bash skill-harbor dock ~/.rulesync/skills ``` That distinction matters: - use **ghost docking** when Harbor discovered unmanaged local context - use **source docking** when you want Harbor to manage the actual source over time --- ## Configuration and command options Ghost behavior is mostly controlled through **command options**, not through a large standalone ghost config system. ### Fathom options relevant to ghosts - `--ghosts` - enables ghost discovery - `--report` - includes ghost paths in the aggregate health report when ghost scanning is active - `--format json` - useful if you want machine-readable output around ghost-related scans - `--global` - changes which manifest scope Harbor compares against ### Voyager behavior relevant to ghosts Voyager does not currently expose a dedicated `--ghosts` flag. Instead, ghost docking happens as part of Voyager’s preparation flow when it detects unmanaged local skills. ### Scope matters Ghosts are always relative to the manifest scope being used: - **local/project scope** - **global scope** A skill can be a ghost in one scope and governed in another. That is why Harbor distinguishes: - local/project manifest state - global manifest state - override-layer state And that is why the same skill might show up as: - a Ghost in one scope - governed in another scope - or sitting in stowage waiting to be inspected and docked intentionally --- ## When to use ghosts vs managed sources ### Use ghost workflows when - you suspect unmanaged skills are affecting agents - you want a quick cleanup/discovery pass - you are onboarding a workspace that already has local skill state ### Use managed sources when - the source should remain durable over time - Harbor should keep rescanning or refreshing it - you want repeatable sync behavior through `up` / `freshen` --- ## v1 safety boundaries Ghost workflows are intentionally conservative. They should help Harbor discover and govern unmanaged skills, but they should **not** become magical cleanup systems. In practice, that means: - ghost docking is interactive - unmanaged skills are surfaced before Harbor governs them - Harbor does not silently rewrite unrelated config just because ghosts exist For RuleSync-backed teams in particular: - ghost discovery is a good fallback and onboarding helper - but a docked folder-backed source is the better long-term solution when the folder is the true source of record --- ## Practical guidance ### “I think local skill state is affecting my agents” Use: ```bash skill-harbor fathom --ghosts ``` Then decide whether you want to: - dock the discovered ghosts directly - dock the durable folder source they really came from - or leave them unmanaged and clean them up separately ### “Voyager says it can’t find a clean fleet” Let Voyager surface and dock ghost skills if that matches your intent. ### “Our team keeps skills in `~/.rulesync/skills`” If that folder is the real ongoing source of truth, dock it as a **folder-backed source**. If skills are merely lying around unmanaged, use **ghost docking** first. ### “I used `stow` / lockdown and now I want to understand what’s still around” Use: ```bash skill-harbor fathom --ghosts ``` because Fathom inspects both active berths and stowage, making it the best current command for finding unmanaged skills that may still be haunting the harbor from either location. --- ## Mental model Use this simple frame: - **Ghost** = unmanaged skill context Harbor discovered - **Command ghost** = the same ghost, surfaced by a particular command run - **Managed source** = intentionally docked source Harbor is expected to govern over time That distinction helps teams avoid conflating: - accidental local drift - intentional source-of-truth workflows - temporary onboarding helpers --- ## Global Fleet **URL:** https://docs.example.com/docs/foundations/global-fleet **Description:** Sync your personal agent skills across every project you touch. # 🌍 Global Fleet Managing skills shouldn't be limited to a single repository. Skill Harbor allows you to maintain a **Global Manifest** to synchronize your personal utilities, refactoring rules, and documentation helpers across every project in your workspace. ## ⚓ The Global/Local Duality Skill Harbor recognizes two distinct levels of orchestration: 1. **Project Manifest**: Stored at `.harbor/harbor-manifest.json`. Defines the skills every developer on the team needs. 2. **Global Manifest**: Stored at `~/.harbor/harbor-manifest.json`. Defines your personal "synced brain" that follows you from project to project. --- ## ⚓ Usage and the `--global` Flag By default, all commands target the local project manifest. To target the user-level manifest, use the `--global` or `-g` flag. ### Syncing Anywhere Run `skill-harbor up --global` in *any* directory to instantly berth your personal global skills into your local agent folders (Claude, Cursor, etc.). ```bash # Sync your personal brain into the current project workspace skill-harbor up --global # Sync both local and global fleets simultaneously skill-harbor up && skill-harbor up --global ``` ### Registering Personal Skills Use the `-g` flag with `dock` to save a skill to your global manifest instead of the current repository. ```bash # Register a personal skill globally skill-harbor dock https://github.com/my-org/my-rules --global ``` --- ## ⚓ Why Use Global Fleet? 1. **Personal Governance**: Keep your project manifests clean and professional, while still having access to your custom keybindings and automation scripts. 2. **Context Portability**: Your personal intelligence layer is no longer tethered to a single machine or repository. 3. **Zero-Tier Discovery**: Global skills are automatically included in the `000-fleet-intelligence.md` Master Manifest produced by `up`, allowing agents to discover your personal tools even when they aren't part of the core team repo. ```bash # List all skills in your global fleet skill-harbor list --global ``` --- ## Governance & Lockdown **URL:** https://docs.example.com/docs/foundations/governance **Description:** Isolate agent context and enforce team-wide skill standards. # 🛡️ Governance & Lockdown In a professional development environment, ensuring that your AI agent is operating with the correct set of specialized skills—and *only* those skills—is critical for security, performance, and reproducibility. Skill Harbor provides a robust governance system that allows you to isolate your agent's context using **Lockdown Mode**, **Stowage**, and **Unstowing**. ## ⚓ The Governance Lifecycle ```mermaid graph LR Local[Project Manifest] --> Lockdown[skill-harbor up --lockdown] Lockdown --> Stow[Stow Existing Skills] Stow --> Berth[Berth Manifest Skills] Berth --> Unstow[skill-harbor unstow] Unstow --> Restore[Original Environment] ``` --- ## 🔒 Lockdown Mode (`--lockdown`) When you run `skill-harbor up --lockdown`, Harbor treats your `harbor-manifest.json` as the **exclusive** source of truth. Any existing skills in your agent's configuration folders that are *not* defined in the manifest are moved into a secure backup location (Stowage). ### Why use Lockdown? - **Client Confidentiality**: Switching from a personal project to a client project with strict rules. - **Reproducibility**: Ensuring every developer on a team has the exact same context for a specific task. - **Security**: Preventing agents from accidentally using unvetted or "ghost" skills in a sensitive repository. ```bash # Sync and enforce a manifest-only environment skill-harbor up --lockdown ``` --- ## 📦 Stowage & Unstowing If you need a clean slate for a limited time but don't want to permanently delete your existing skills, you can use the `stow` and `unstow` commands. ### `skill-harbor stow` Moves all current skills in your agent's directory into the Skill Harbor metadata folder (`.harbor/stowage`). This effectively "clears the deck" for a fresh session. ### `skill-harbor unstow` The "Unlock" command. It restores your previously stowed skills, merging them back into your agent's active configuration. This is typically run after you've finished a lockdown session. ```bash # Manually back up current skills skill-harbor stow # Restore stowed skills skill-harbor unstow ``` --- ## ⚓ Why Use Governance? 1. **Consistency**: One developer adding a 10,000-token skill can ruin the token economy for the whole team. Lockdown prevents this. 2. **Context Hygiene**: Agents perform better when their context is "right-sized." Governance helps you keep the "displacement" (token usage) low. 3. **Auditability**: By using a declarative manifest and --lockdown, you can audit exactly what logic was available to an agent during any specific development phase. 4. **Quality & Governance**: The broader public skill ecosystem currently suffers from low average quality (6.2/12 in the SkillsBench scoring). Skill Harbor's provenance and governance tracking is critical for enterprise deployment to ensure agents only utilize vetted, verified skills. ```bash # Combining global and local governance skill-harbor up --global --lockdown ``` --- *Reference: Li, X., et al. (2026). SkillsBench: Benchmarking How Well Agent Skills Work Across Diverse Tasks. https://www.skillsbench.ai/skillsbench.pdf* For the broader product comparison, see **[How does Skill Harbor align with SkillsBench?](/docs/faq/skillsbench)**. --- ## The Manifest & .harbor **URL:** https://docs.example.com/docs/foundations/manifest **Description:** Mastering the control system and directory structure of Skill Harbor. # 📖 The Manifest & .harbor Folder Skill Harbor manages your fleet of agent skills via a **Declarative Control System**. This system is powered by two main components: the `harbor-manifest.json` file and the hidden `.harbor/` folder in your project or home directory. The manifest identifies which skills to pull and how to track them, while the `.harbor/` folder provides the infrastructure for caching, versioning, and environment isolation. --- ## ⚓ The Three-Layer Manifest Architecture Skill Harbor merges three manifest layers into a single resolved view every time you run `up`, `fathom`, or any command that reads the manifest. Later layers override earlier ones. Before going deeper, keep one distinction clear: - **Source** = where a skill comes from - **Target** = where Harbor generates/berths it to For the full mental model, see [Sources & Targets](/docs/foundations/sources-and-targets). ### 1. Global Manifest (`~/.harbor/harbor-manifest.json`) Your **personal fleet** — skills that follow you across every project on your machine. Registered with `skill-harbor dock --global` and synced with `skill-harbor up --global`. See [Global Fleet](/docs/foundations/global-fleet) for details. ### 2. Project Manifest (`.harbor/harbor-manifest.json`) The **shared team configuration** for a specific repository. Committed to Git so every developer gets the same skills. Overrides any Global skill with the same name. ### 3. Overrides Manifest (`.harbor/harbor-manifest.overrides.json`) Your **personal overrides** for this specific project — swap a skill version, add a debugging tool, or test a branch without affecting teammates. This file is automatically ignored by Git. Overrides both Project and Global skills with the same name. ### Merge Priority ```mermaid graph LR Global["1. Global
(lowest priority)"] --> Shared["2. Project
(overrides Global)"] Shared --> Local["3. Local
(highest priority)"] Local --> Merged["Merged Manifest"] Merged --> UP["skill-harbor up"] ``` When a skill name exists in multiple layers, the highest-priority layer wins. Overridden skills are flagged in the `up` output: ``` ⚠️ Overrides Active: The following skills are being overridden by personal definitions: - my-skill ``` Targets (agent platforms) are merged as a union across all three layers. --- ## 🏗️ The `.harbor/` Folder Structure Skill Harbor keeps all its internal control files and cached "cargo" in the `.harbor/` directory. --- ## ⚙️ How Skills are Managed (Control) Skill Harbor does more than just copy files; it ensures your agent environment is deterministic and auditable. ### 1. Cryptographic Tracking Every skill entry in the manifest contains a `lastSyncHash`. This hash is a composite of the source URL and the file system state. If a remote skill is updated (or a local file is modified), Harbor detects the drift and prompts for a `freshen` or automatic sync. ### 2. Zero-Tier Discovery Upon every successful sync (`up`), Skill Harbor generates a **Master Fleet Manifest** (`000-fleet-intelligence.md`) and berths it directly into your agent configuration. This manifest allows agents to discover and route to all berthed skills even if they don't have native multi-tool indexing support. ### 3. Lockdown Governance By using the `--lockdown` flag, you force your environment to mirror the manifest **exactly**. This is the highest level of control, ideal for production-sensitive repositories or client-facing projects with strict security requirements. ```bash # Sync and enforce the manifest-only environment skill-harbor up --lockdown ``` --- ## 🚀 Migrating from Root-Level Manifests Earlier versions of Skill Harbor stored `harbor-manifest.json` at the project root. The current standard consolidates everything under `.harbor/` for consistency with the broader AI tooling ecosystem (`.claude/`, `.cursor/`, `.github/`). If Skill Harbor detects a root-level manifest during `up`, it will display a recommendation: ``` 💡 Recommendation: Found harbor-manifest.json at project root. Run 'skill-harbor migrate' or 'skill-harbor up --migrate' to automate the transition. ``` ### What `migrate` does The migration engine interactively walks through three steps: 1. **Manifest relocation** — Moves `harbor-manifest.json` into `.harbor/` and renames any legacy `harbor-manifest.local.json` file to `.harbor/harbor-manifest.overrides.json`. 2. **Skills cache reorganization** — Moves loose skill directories from `.harbor/` into `.harbor/skills/` so that cache and config are cleanly separated. 3. **Gitignore update** — Replaces a blanket `.harbor/` ignore with granular rules so your manifest and hooks can be committed while the cache stays ignored. ```bash # Run the interactive migration skill-harbor migrate # Or trigger it during a sync skill-harbor up --migrate ``` --- ## Sources & Targets **URL:** https://docs.example.com/docs/foundations/sources-and-targets **Description:** Understand where skills come from, where Harbor generates them to, and how folder-backed sources work. # 🧭 Sources vs Targets Skill Harbor works best when two ideas stay distinct: - **Source** = where a skill comes from - **Target** = where Skill Harbor generates or berths that skill for an agent This distinction matters because Harbor can manage the same source for multiple targets, and a single target can receive skills from many different sources. --- ## Source A **source** is the origin Harbor reads from. Examples: - a GitHub repository - a local single-skill folder - a local **folder-backed source** containing many child skills Examples: ```bash # GitHub source skill-harbor dock https://github.com/my-org/react-skills # Local single-skill source skill-harbor dock ./skills/my-local-skill # Folder-backed source skill-harbor dock ~/.rulesync/skills ``` When you dock a folder-backed source, Harbor treats that folder as a collection source and discovers nested child skills under it. --- ## Target A **target** is the destination Harbor generates or berths skills into for a specific agent/runtime. Examples: - Codex → `.agents/skills` - Claude → `.claude/skills` - Cursor → `.cursor/skills` - RuleSync berth target → `~/.rulesync/skills` Targets are what `up` syncs **into**. So in one sentence: > Harbor reads from **sources** and generates/berths into **targets**. --- ## RuleSync example For teams using RuleSync, these two ideas often get conflated: - `~/.rulesync/skills` can be a **target berth** - and it can also be used as a **source folder** Those are different workflows. ### RuleSync as a target If Harbor is syncing **to** RuleSync, then `~/.rulesync/skills` is a target berth. ### RuleSync as a source If your team already keeps skills in `~/.rulesync/skills` and wants to use Harbor for Fathom, Voyager, and related workflows, then you can dock that folder as a **source**: ```bash skill-harbor dock ~/.rulesync/skills ``` Harbor then treats it as a folder-backed source and rescans it during normal Harbor flows. --- ## Folder-backed sources A **folder-backed source** is a local directory that contains child skill folders with `SKILL.md` files inside them. For example: ```text ~/.rulesync/skills/ team-a/ SKILL.md team-b/ SKILL.md ``` When that folder is docked: - Harbor records the folder as the authoritative manifest source - Harbor discovers the child skills under it - `up` rescans it during normal sync - `freshen` force-refreshes it This helps teams avoid drift between the folder they actually maintain and the skills Harbor analyzes and syncs. --- ## When to use folder-backed sources vs ghost docking ### Prefer a folder-backed source when - the directory is a real ongoing source of truth - you want Harbor to keep rescanning it - you want `up` / `freshen` to refresh it automatically ### Prefer `fathom --ghosts` when - skills are already sitting in berths but are not manifested yet - you need a quick one-time interactive discovery path - you are cleaning up unmanaged local skill state ```bash skill-harbor fathom --ghosts ``` `voyager` can also trigger ghost docking when it discovers unmanaged skills. --- ## Refresh behavior Folder-backed sources are designed to reduce drift: - **`up`** → rescans the folder during normal sync - **`freshen`** → forces a refresh of that rescan path That means Harbor can keep following the folder as it changes over time, instead of treating it like a one-time import. --- ## v1 safety boundaries Folder-backed sources are intentionally conservative. Version 1 should **not**: - mutate RuleSync config itself - import non-skill files - auto-delete manually added manifest entries - auto-resolve conflicts silently The goal is to make refresh safe and explicit, not magical or destructive. --- ## Practical mental model Use this mental model when explaining Harbor to a team: 1. **Dock a source** 2. **Run `up` to sync into targets** 3. **Use Fathom / Voyager / Lighthouse on the resulting fleet** For RuleSync-backed teams: ```bash # Dock the source folder skill-harbor dock ~/.rulesync/skills # Sync to your chosen agent targets skill-harbor up # Analyze and validate skill-harbor fathom --report skill-harbor voyager -f harbor-voyager-test.yaml ``` If the folder was not docked yet and skills are just sitting around locally, use: ```bash skill-harbor fathom --ghosts ``` as the quickest discovery-and-dock fallback. --- ## The Toolkit (Meta-Skills) **URL:** https://docs.example.com/docs/foundations/toolkit **Description:** AI-native tools to help you design, refactor, and certify your agent fleet. # 🧰 The Harbormaster's Toolkit Skill Harbor is not just a sync engine—it is an **Agent Authoring Partner**. Instead of manual scaffolding, we provide a set of **AI-Native Meta-Skills** (Tools) that can be docked directly into your harbor to help you build, evaluate, and standardize your fleet. These tools reinforce Harbor's role as a **skills-first** system. They are meant to improve how teams author, audit, and operate skills—not to broaden Harbor into a general rules or workspace-config platform. See [Architecture & Product Boundary](/docs/foundations/architecture). ## ⚓ The Toolkit Collection These meta-skills aren't part of the CLI itself—they are **Doctor-Sourced Skills** that you run with your favorite agent (Claude, Cursor, Codex, Antigravity) to help manage your other skills. --- ## ⚓ Usage: How to Dock the Toolkit You can dock the entire toolkit at once or individual pieces. Since these are provided by the official Skill Harbor library, they integrate seamlessly with our governance features. ```bash # Dock a skill from a remote repository skill-harbor dock https://github.com/johntimothybailey/sia/skills/catch-22 --global # Run up to berth these skills into your agent folders skill-harbor up --global ``` --- ## ⚓ Authoring Workflow 1. **Lofting**: Start by prompting your agent with **Loft Master**. Describe the new skill you want to create. It will guide you through the prompt design and contract definition. 2. **Surgeons & Refactoring**: When **Fathom** reports a "Storm Surge" (Collision Risk), call the **Fleet Surgeon**. Provide the offending skill file, and it will give you a refactor plan to reduce its "displacement" (token usage). 3. **Certification**: Before a major release or team rollout, use the **Contract Notary** to certify every connection point in your multi-tool fleet. --- ## ⚓ Interactive Ghost Docking When running `skill-harbor fathom --ghosts`, Harbor acts as a proactive assistant. If it discovers a local skill folder that isn't manifested, it will identify it as a **"Ghost"** and provide an interactive prompt to `dock` it immediately. ```bash # Scan for ghosts and dock them interactively skill-harbor fathom --ghosts ``` For details on what counts as a ghost, how commands surface them, and how ghost docking differs from managed folder-backed sources, see [Ghosts](/docs/foundations/ghosts). --- ## Voyager: Integration Testing **URL:** https://docs.example.com/docs/foundations/voyager **Description:** Simulate an autonomous agent's loop to verify integration and tool-chaining. # ⛵ Voyager While Fathom provides fast heuristic and single-skill probabilistic checks, **Voyager** is a dedicated integration testing suite for your agent skills. It simulates an entire agent loop to verify that the LLM uses the correct sequence of tools to reach the expected end state. Voyager reads your active agent berths, constructs JSON Schema tool definitions, and passes mock context payloads to ensure your "fleet" is ready for real-world deployment. If Voyager discovers unmanaged local skills while preparing that fleet, it can also surface them as ghost-docking candidates. For the conceptual model behind that—and for the new primary `skill-harbor ghosts` workflow—see [Ghosts](/docs/foundations/ghosts). **At a high level, Voyager:** - loads active skills from berths - exposes them as tools - runs a model loop - validates expected tool usage sequence ## ⚓ Voyager TL;DR ```bash # Run a specific integration test file skill-harbor voyager -f harbor-voyager-test.yaml # Run an ad-hoc query simulation skill-harbor voyager "Check if the codebase is portable." ``` --- ## 🛠️ Defining a Voyager Test Voyager tests are defined in YAML files (typically `harbor-voyager-test.yaml`). This allows you to define the user query, specify which tools *must* be invoked, and provide mock responses for those tools. ### Test Structure Example ```yaml # harbor-voyager-test.yaml query: "Check if the codebase is portable and then generate a report on any hidden skills." expected_tools: - Scryer - Fathom mocks: Scryer: "Portable issues found: None. The codebase looks clean." Fathom: "Hidden skills report: 2 ghost skills found." ``` ### Key Parameters: - **`query`**: The initial prompt sent to the agent. - **`expected_tools`**: A list of tool names that the agent **must** call (in any order) to pass the test. - **`mocks`**: A mapping of tool names to their simulated return values. This prevents the agent from actually executing destructive commands during the test. --- ## 🧪 Benchmark Packs Voyager now supports a **Harbor-native benchmark-pack** format for deterministic, fixture-driven scenario evaluation in local and CI environments. This complements the existing live single-scenario flow without replacing it. - **Legacy scenario files** remain the current single-test YAML shape (`query`, `expected_tools`, `mocks`, assertions). - **Benchmark-pack files** use a versioned Harbor-native root with `kind`, `version`, `pack`, and `scenarios`. - Pack execution is **offline and API-key-free** in v1: it evaluates scenario outcomes from fixtures rather than running the live provider loop. ### Product boundary - **Voyager** owns empirical scenario evaluation: traces, branch outcomes, assertions, uplift/regression. - **Fathom** owns predictive and audit-style analysis: heuristics, token/context analysis, routing confidence, fleet recommendations. That means benchmark packs still belong in Voyager: they make **scenario evaluation reproducible**, but they do **not** compute Fathom-style usefulness heuristics. ### Benchmark-pack example ```yaml kind: harbor.voyager.benchmark-pack version: 1 pack: id: sample-benchmark-pack name: Sample Voyager Benchmark Pack scenarios: - id: tool-uplift query: "Check if the codebase is portable and then generate a report on any hidden skills." fixtures: with_skills: ... without_skills: ... assertions: with_skills: ... without_skills: ... delta: ... ``` Use a checked-in pack such as `harbor-voyager-benchmark-pack.yaml` to run deterministic benchmark-style evaluations in CI. ## 🛡️ Governance & CI/CD Voyager is designed to be a **Pull Request Gate**. If the agent deviates from the `expected_tools` or fails to reach a terminal state, Voyager will **exit with process code 1**, blocking your CI/CD pipeline. - **`--file `**: Provide a custom test definition file. - **`--model `**: Override the model used for the simulation (e.g., `gpt-4o-mini`). - **`--baseUrl `**: Point to a different LLM provider (Groq, Ollama, etc.). --- ## ⚓ Why Use Voyager? 1. **Regression Testing**: Ensure that adding a new skill doesn't break the routing logic for existing skills. 2. **Chaining Validation**: Verify that the output of one tool is correctly utilized by the next tool in a multi-step journey. 3. **Mocking Destructive Actions**: Test agents that use non-idempotent tools (like `rm` or `git commit`) without actually modifying your environment. 4. **Team Standards**: Commit your voyager tests to Git so every developer can verify the fleet's integrity before merging. ```bash # Run Voyager with a specific model override skill-harbor voyager -f harbor-voyager-test.yaml --model gpt-4o ``` --- *Reference: Li, X., et al. (2026). SkillsBench: Benchmarking How Well Agent Skills Work Across Diverse Tasks. https://www.skillsbench.ai/skillsbench.pdf* For the broader alignment story, see **[How does Skill Harbor align with SkillsBench?](/docs/faq/skillsbench)**. --- ## CLI Reference **URL:** https://docs.example.com/docs/reference/commands **Description:** 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 ` Register a skill's source in the manifest. `` 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](/docs/foundations/sources-and-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:** ```bash 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 `: 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:** ```bash 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 `: 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 `: 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](/docs/foundations/fathom).* **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 `: 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](/docs/foundations/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 ` **Flags:** - `-f, --file `: 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 `: Output `pretty` or `json`. - `--save-trace [dir]`: Persist run artifacts. Pack runs write a top-level `summary.json` plus per-scenario artifacts. - `--model `: Override the model used for live Voyager simulation. - `--baseUrl `: 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](/docs/foundations/voyager).* --- ## `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. *For context on why the `.harbor/` layout exists, see [The Manifest & .harbor](/docs/foundations/manifest#-migrating-from-root-level-manifests).* --- ## Links - [GitHub](https://github.com/johntimothybailey/skill-harbor) - [Discord](https://discord.gg/zST7he9N)