Agent Skill Bundle

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.

The two layers

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.

Bundle layout

The complete bundle is served flat at the top level of /skills/:

/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 mode

The HTTP and SDK modes cover all 19 service namespaces; the CLI mode covers 16 (the app, pipe, and proxyLogs namespaces have no CLI surface). Per-namespace links inside the combined skills are absolute URLs so a file copy-pasted into a prompt can still resolve deeper detail.

How agents should use it

A typical request flow:

Pre-loaded. The agent has the combined full skill for its mode in context. It already knows what Hoody is, how to authenticate, and which namespaces exist.
On a fresh request, the agent identifies which namespace owns the task from the combined skill’s namespace overview.
For a deeper drill-down on one service, the agent fetches the matching per-namespace file — 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.

Picking a mode

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.

How the bundle is built

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.

Stability guarantees

URL paths are stable. https://hoody.com/skills/SKILL-FULL.md and the flat hoody-<ns>.md / .sdk.md / .cli.md files are considered a public surface. Renaming or moving files in this bundle is treated as a breaking API change for agents.
Output is deterministic. The generator does not use random ordering or LLM calls at build time. Given the same inputs, a given commit always produces the same bytes.

What’s next

AI Agents Guide

Hoody AI Overview

Authentication