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

Tier 0 — SKILL.lite.md

~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.

Tier 1 — INDEX.md

~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.

Tier 2 — per-namespace, per-mode

~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

The minimum viable agent

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

AI Agents Guide

Hoody AI Overview

Authentication