📏 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

# 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:

Confidence_{Heuristic} = 11 - \max(1, \min(10, Score_{composite}))

Saturation = \left( \frac{\sum Tokens_{fleet}}{ContextLimit_{model}} \right) \times 100

🛡️ 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 <n>: Fail if total fleet tokens exceed limit.
• --max-bloat <p>: Fail if GPT-4o context saturation exceeds percentage.
• --min-score <s>: 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.

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:

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:

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 <text>: Run a Sonar audit against all skills for a specific query.
• --model <name>: 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.

# 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:

{
  "name": "voice-to-structured-data",
  "berthed": [{ "label": "Codex", "location": ".agents" }],
  "stowed": []
}

# 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)