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
hoody.com/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-HTTP-FULL.md, SKILL-SDK-FULL.md, and SKILL-CLI-FULL.md. Each is
the everything-in-one-file reference for that mode: what Hoody is, the auth
model, the public URL scheme, and every namespace inlined. Pick the one that
matches your runtime.
Per-namespace, per-mode
Fetched on demand. Files named SKILL-HTTP/<ns>.md (HTTP),
SKILL-SDK/<ns>.md (SDK), and SKILL-CLI/<ns>.md (CLI), each with the
actual signatures, payloads, examples, and gotchas for that one surface.
The bundle is served under /SKILLS/:
/SKILLS/├── SKILL-HTTP.md ← basic skill, HTTP mode (intro + core ops + index)├── SKILL-HTTP-FULL.md ← combined full skill, HTTP mode (every namespace inlined)├── SKILL-HTTP/<ns>.md ← per-namespace deep dive, HTTP mode│├── SKILL-SDK.md / SKILL-SDK-FULL.md / SKILL-SDK/<ns>.md ← SDK mode├── SKILL-CLI.md / SKILL-CLI-FULL.md / SKILL-CLI/<ns>.md ← CLI mode│├── SKILL.md ← mode-blend chooser├── SKILL.lite.md ← condensed mode-blend skill├── INDEX.md ← the whole surface at a glance└── ONBOARDING.md ← first-run orientationAll three modes cover the same 20 service namespaces (a namespace with no CLI surface ships a short pointer instead of commands). 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:
SKILL-HTTP/<ns>.md, SKILL-SDK/<ns>.md, or SKILL-CLI/<ns>.md)
for the method signatures and payload shapes in 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-sdk package | SKILL-SDK-FULL.md / SKILL-SDK/<ns>.md |
| Any language with an HTTP client | SKILL-HTTP-FULL.md / SKILL-HTTP/<ns>.md |
A shell, or hoody CLI is on the path | SKILL-CLI-FULL.md / SKILL-CLI/<ns>.md |
The three modes describe the same operations and differ only in how you 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 generated deterministically in hoody-sdk 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, and 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. |
The same inputs produce byte-identical output, with no LLM in the path. A reviewer can diff two builds to see exactly what a prose change altered.
https://hoody.com/SKILLS/SKILL-HTTP-FULL.md
(and the SKILL-SDK-FULL.md, SKILL-CLI-FULL.md equivalents) and the
SKILL-HTTP/<ns>.md / SKILL-SDK/<ns>.md / SKILL-CLI/<ns>.md files are
considered a public surface. Renaming or moving files in this bundle is
treated as a breaking API change for agents.