Harbor

Operating instructions for AI agents.

Harbor skills are short markdown files that teach an agent when to reach for the CLI, which command to run, and when to load a narrower topic skill. This page is the human-facing index; the machine path is /skill.md and /skills.md.

Last updated

Three audiences, one canonical bundle.

  • For people

    Use this page to understand the public site and find the dashboard.

  • For agents

    Read /skill.md or /skills.md when you need the machine path.

  • For teams

    Treat workspace state, plugins, and traces as the primary product objects.

What a Harbor skill is

A Harbor skill is an agent-facing markdown file that teaches an LLM when and how to use Harbor. Skills are bundled with the @zonko-ai/harbor package and refreshed by hrbr update. The public site exposes the canonical skill bundle at /.well-known/agent-skills/, /skill.md, and /skills.md. Harnesses that prefer SHA-256-pinned skill content can fetch a digest-addressed copy.

How Harbor skills work

What is a Harbor skill?

A Harbor skill is a markdown file with a small YAML frontmatter (name, description) and a body that tells an AI agent when to reach for Harbor and which commands to run. The canonical Harbor skill is harbor.md— it explains how to install the CLI, check auth state, search for tools, and decide between hrbr inspect (control-plane reads) and hrbr exec (traced execution).

Beyond the root skill, Harbor ships narrower topic skills the agent loads on demand: harbor-plugins, harbor-exec, harbor-jobs, harbor-apps, and harbor-orbit. Skills are intentionally short and prescriptive. They are not documentation; they are operating instructions the agent reads at session start and consults again when a task matches a particular surface.

How are skills delivered to agents?

Three paths, all backed by the same canonical bundle:

  1. Local install. npm i -g @zonko-ai/harbor installs the CLI and writes the bundled skills to ~/.agents/skills/<skill-name>/SKILL.md. hrbr update refreshes them in place via the package’s postinstall hook.
  2. Well-known web routes. The marketing domain serves https://tryharbor.ai/skill.md (Harbor meta skill body), https://tryharbor.ai/skills.md (alias), and the /.well-known/agent-skills/ directory with index.json plus per-skill assets.
  3. Docs mirror. https://docs.tryharbor.ai/.well-known/agent-skills/harbor/SKILL.md carries the same content for clients that prefer the docs domain.

Can I version-pin a skill?

Yes. Each published skill ships with a SHA-256 content digest. The /.well-known/agent-skills/index.json manifest carries the digest alongside the skill URL, and the per-skill route returns the same content the manifest digest covers. A harness that needs reproducibility can fetch by URL, verify the SHA-256 against the manifest entry, and refuse to load if the digest drifts.

For local CLI installs, pinning is package-version-based: npm i -g @zonko-ai/harbor@<version> pins the bundled skills to that release. hrbr update --check reports whether a newer bundle is available.

Which agents can load Harbor skills today?

Anything that reads markdown skill files from ~/.agents/skills/ or fetches them over HTTP can load Harbor skills. Concretely:

  • Claude Code— auto-loads skills from the standard ~/.agents/skills/ path and consults topic skills based on task content.
  • Codex CLI— loads skill content alongside its own context.
  • Cursor and Windsurf— load Harbor skills via their MCP integration.
  • Custom harnesses— anything that resolves https://tryharbor.ai/skill.md or the /.well-known/agent-skills/ routes can consume the bundle.

The same bundle works whether the harness reads the local file or fetches the public URL — content parity is enforced because the CLI postinstall pulls from the same source tree that the well-known routes serve.

Available Harbor skills.

One-sentence descriptions per skill, drawn from packages/skills/content/meta/.