The agent skill bundle is the machine-readable manual that teaches an AI agent
how to drive Hoody. It is published as static files at
docs.hoody.com/documentation/skills/,
so agents can fetch it without any authentication, embed URLs into prompts, and
load deeper detail on demand.
The bundle is built around progressive disclosure: an agent loads the combined full skill for its preferred mode, then fetches a single per-namespace file on demand when it needs the exact signatures and payloads for one service.
Combined full skill (per mode)
SKILL-FULL.md (HTTP), SKILL-FULL.sdk.md (SDK), and
SKILL-FULL.cli.md (CLI). Each is the everything-in-one-file reference
for that mode: what Hoody is, the auth model, the public-URL story, and
every namespace inlined. Pick the one that matches your runtime.
Per-namespace, per-mode
Fetched on demand. Flat files named hoody-<ns>.md (HTTP),
hoody-<ns>.sdk.md (SDK), and hoody-<ns>.cli.md (CLI), each with the
actual signatures, payloads, examples, and gotchas for that one surface.
The complete bundle is served under /documentation/skills/:
/documentation/skills/├── SKILL-FULL.md ← combined full skill, HTTP mode├── SKILL-FULL.sdk.md ← combined full skill, SDK mode├── SKILL-FULL.cli.md ← combined full skill, CLI mode│├── hoody-<ns>.md ← per-namespace deep dive, HTTP mode├── hoody-<ns>.sdk.md ← per-namespace deep dive, SDK mode└── hoody-<ns>.cli.md ← per-namespace deep dive, CLI modeHTTP and SDK cover all 19 service namespaces; CLI covers 16 (hoody-app,
hoody-pipe, and hoody-proxyLogs have no CLI surface, so no CLI files are
generated for them). Per-namespace links inside the combined skills are
absolute URLs so a file copy-pasted into a prompt can still resolve deeper
detail.
A typical request flow:
hoody-<ns>.md, hoody-<ns>.sdk.md, or
hoody-<ns>.cli.md — to read the actual method signatures and payload
shapes for the chosen mode.For most one-shot operations the combined skill alone is enough; the per-namespace files are there when an agent wants a focused, lower-noise view of a single service.
| If the agent’s runtime is… | Use |
|---|---|
JavaScript/TypeScript with the @hoody-ai/hoody-sdk package | SKILL-FULL.sdk.md / hoody-<ns>.sdk.md |
| Any language with an HTTP client | SKILL-FULL.md / hoody-<ns>.md |
A shell, or hoody CLI is on the path | SKILL-FULL.cli.md / hoody-<ns>.cli.md |
The three modes describe the same operations — they only differ in how to call them. Load the combined full skill for your mode and reach for the matching per-namespace file when you need a single service in detail.
The skill bundle is regenerated deterministically from three sources:
| Source | Lives in | What it contributes |
|---|---|---|
| Handwritten prose | hoody-sdk-generator/hoody-sdk/skills-source/ | The intros, the per-namespace gotchas, and the appendices. |
| SDK and CLI mappings | sdk-mappings.json, cli-mappings.json | Method names, signatures, parameter tables, command syntax — auto-emitted into the per-namespace deep dives. |
| OpenAPI document | generated/openapi.json | HTTP endpoint paths, request/response schemas, body shapes for the HTTP per-namespace files. |
Same inputs → byte-identical output. A reviewer can diff two builds to see exactly what a prose change altered.
https://docs.hoody.com/documentation/skills/SKILL-FULL.md
(and the SKILL-FULL.sdk.md, SKILL-FULL.cli.md equivalents) and the
hoody-<ns>.md / hoody-<ns>.sdk.md / hoody-<ns>.cli.md files are
considered a public surface. Renaming or moving files in this bundle is
treated as a breaking API change for agents.