# Agent Skill Bundle

**Page:** foundation/agent-skill-bundle

[Download Raw Markdown](./foundation/agent-skill-bundle.md)

---

# 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/`](https://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


  
    `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.
  
  
    **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


Load the combined full skill for your mode (`SKILL-FULL.md` for HTTP,
`SKILL-FULL.sdk.md` for SDK, `SKILL-FULL.cli.md` for CLI) into the agent's
system prompt. It already contains every namespace inline, so the agent can
work entirely from that one file.


A typical request flow:

1. **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.
2. **On a fresh request,** the agent identifies which namespace owns the task
   from the combined skill's namespace overview.
3. **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