# 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.icu/skills/`](https://hoody.icu/skills/) (and the equivalent CDN path
in every realm), 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 only needs the
lightweight tier-0 skill loaded into every context. Heavier files are fetched
on demand when the agent encounters something the lightweight skill cannot
fully answer.

## The three tiers


  
    **~2 000 tokens · always loaded.** What Hoody is, the auth model, the four
    default operations (signup/login, list/create container, scoped client
    handle, public-URL story), and a one-liner per namespace pointing at
    where to look for more.
  
  
    **~7 000 tokens · fetched on demand.** Full routing manifest: every one of
    Hoody's 19 service namespaces gets a short paragraph describing what it
    owns, when to reach for it, and which other namespace it is most often
    confused with. Bundled with a "routing hints" appendix that disambiguates
    the most common overlapping cases.
  
  
    **~500–2 000 tokens each · fetched on demand.** Three flavors per
    namespace (SDK, HTTP, CLI), each with the actual signatures, payloads,
    examples, and gotchas for that one surface. 19 namespaces × 3 modes = 57
    files.
  


There is also a fourth file — **`SKILL.md`** — that is a mode-blend chooser:
a short document for agents that have not yet decided whether they want to
talk to Hoody via SDK, HTTP, or CLI. It links the three full mode skills
side-by-side and is the file most agents discover first via search engines.

## Bundle layout

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

```
/skills/
├── SKILL.lite.md             ← tier 0 — always-load this
├── INDEX.md                  ← tier 1 — routing manifest + hints
├── SKILL.md                  ← mode-blend chooser
│
├── SKILL-SDK.md              ← basic SDK skill (intros + core ops)
├── SKILL-SDK-FULL.md         ← SDK skill bundled with every namespace
├── SKILL-SDK/<ns>.md         ← 19 per-namespace deep dives
│
├── SKILL-HTTP.md
├── SKILL-HTTP-FULL.md
├── SKILL-HTTP/<ns>.md
│
├── SKILL-CLI.md
├── SKILL-CLI-FULL.md
└── SKILL-CLI/<ns>.md
```

Every link inside the bundle uses absolute URLs so a file copy-pasted into a
prompt can still resolve deeper detail.

## How agents should use it


Load `SKILL.lite.md` into the agent's system prompt. That is it. The
lightweight skill itself instructs the agent to fetch `INDEX.md` or a
tier-2 file whenever it needs more detail than the one-liners can carry.


A typical request flow:

1. **Pre-loaded.** The agent always has `SKILL.lite.md` in context — about
   2 000 tokens. It already knows what Hoody is, how to authenticate, and
   which namespaces exist.
2. **On a fresh request,** the agent reads `SKILL.lite.md`'s one-liner table
   to identify which namespace owns the task.
3. **If the namespace match is ambiguous** (typical for sentences mentioning
   files vs. notes vs. SQLite), the agent fetches `INDEX.md` for the routing
   hints and a stronger paragraph per namespace.
4. **Once the namespace is locked in,** the agent fetches
   `SKILL-{MODE}/{namespace}.md` to read the actual method signatures and
   payload shapes for the chosen mode.

For most one-shot operations, steps 1 and 4 suffice; step 3 only enters for
genuinely ambiguous prompts.

## Picking a mode

| If the agent's runtime is… | Use |
|---|---|
| JavaScript/TypeScript with the `@hoody-ai/hoody-sdk` package | `SKILL-SDK/<ns>.md` |
| Any language with an HTTP client | `SKILL-HTTP/<ns>.md` |
| A shell, or `hoody` CLI is on the path | `SKILL-CLI/<ns>.md` |

The three modes describe the same operations — they only differ in how to
call them. The mode-blend `SKILL.md` shows the three side-by-side in case
the agent wants to commit later.

## 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 lightweight skill, the INDEX, the per-namespace gotchas, the intros and 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. |
| Public OpenAPI document | `generated/openapi.public.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.icu/skills/SKILL.lite.md` is
  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,
  timestamps in body, or LLM calls at build time. A given commit always
  produces the same bytes.
- **Tier-0 size is enforced.** A bundle test asserts `SKILL.lite.md` stays
  under the ~3 000-token ceiling. If a prose edit pushes it over, the build
  fails — pressure to keep the always-loaded skill cheap.

## What's next