For Agents — Overview

Harbor's docs are written for two audiences:

1. Humans — you reading this page in a browser. The site you're on is for you.
2. Agents — Claude, Cursor, Codex, Gemini, custom LLM hosts. Agents don't read this site; they fetch markdown from canonical URLs and then act on it.

This section documents the agent-facing surface: the markdown URLs an agent should know, the discovery protocol, and the conventions.

The agent surface, in one paragraph

Every Harbor docs page has a stable URL. Agents can fetch the markdown source of any page by appending ?format=md (v1.1 — coming soon). For the canonical operating skill, agents fetch /.well-known/agent-skills/harbor/SKILL.md — a single file that teaches "is hrbr installed?", "are you logged in?", "what plugins are ready?", "use hrbr exec to do X". From there, topic skills (harbor-plugins.md, harbor-exec.md, …) deep-dive specific surfaces.

What's available

What an agent should never do

• Don't scrape this HTML site. Fetch markdown from /llms.txt or /.well-known/agent-skills/.

• Don't invent tool ids. Search first with inspect, and only call ids that come back:

  hrbr inspect 'return await hrbr.tools.search({ query: "<intent>", limit: 5 })'

• Don't persist OAuth tokens or API keys in orbit.storage, orbit.cache, or orbit.db. Credentials live in the vault.

• Don't retry tool failures by guessing arguments. Re-inspect the schema first.

Conventions

• All agent-facing surfaces are stable URLs. We add new ones; we don't rename existing ones without 6+ months notice in Changelog.
• All agent-facing markdown is plain markdown with YAML frontmatter. No JSX, no HTML.
• Cache headers: max-age=300, s-maxage=86400, stale-while-revalidate=2592000.
• All agent-facing routes are served from the docs site (same origin) so CORS is a non-issue.