SPECs: how your agents learn

An agent in your Pod isn't born knowing how to research a market, read a PDF, or place an order. And you don't teach it by programming. You hand it a SPEC.

A SPEC is a sealed package of capability. Tools, skills, views and permissions — versioned, immutable, checksum-verified. Install one into an agent and the agent knows the trade. Remove it and the knowledge is gone, cleanly.

What's inside

Open a SPEC and you'll find four things:

Tools — the verbs. search, watch_url, create_checkout. Each one is a precise action the agent can take, with a declared description the model reads and a real implementation the runtime executes. No verb in the SPEC, no action in the agent.

Skills — the craft. Working notes written for the agent: a research workflow with citation discipline, a code-review protocol, a document style guide. Tools say what an agent can do; skills say how it should be done well.

Views — the presentation. A SPEC declares how its results should render in your journal: a table, a form, a confirmation card. The agent doesn't improvise UI; the SPEC ships it.

Permissions — the contract. Every capability a SPEC needs is declared up front, with a reason: "http_request — web search reaches external URLs to retrieve sources." You see the full list at install time and you grant it explicitly. No SPEC gets more than it asked for, and none asks silently.

The registry

SPECs live in a registry, like packages — because that's what they are. Each has a scope and a name — @platform/research-toolkit, @platform/document-suite — and a version that can never be overwritten: published once, a version is immutable, and every artifact is SHA-256 verified before a single tool loads. A scope belongs to whoever published it first, forever.

Today the registry holds 69 SPECs: research, documents, code, images, knowledge graphs, commerce, trading vocabularies, safety packs. Browse them at snaga.ai/specs — no account needed.

How your Pod uses them

Your Head Agent is deliberately not a specialist. It carries a curated orchestration set — create an agent, delegate a run, check the result — and its tool surface is kept narrow on purpose: a router that does everything does nothing well.

The pattern is simple: when work arrives, the Head Agent finds the right SPEC for the domain, spawns a specialist with exactly that SPEC, and delegates. A research agent carries the research toolkit. A billing agent carries commerce. Nobody carries everything.

Each plan tier ships a SPEC bundle out of the box — every Pod starts with the essentials installed, and higher tiers unlock the heavier suites.

Bounded by design

Three rules keep SPECs honest:

1. The constitution outranks every SPEC. No installed package can override your tenant’s rules, your budgets, or platform limits — the runtime enforces this ordering, not etiquette.
2. Allowlists narrow the surface. An install can carry a tool allowlist: the agent advertises only the verbs it needs from a SPEC, not the whole catalogue.
3. Immutability is the audit trail. The version your agent ran yesterday is byte-for-byte the version in the registry today. There is no “the package changed under you.”

Why it matters

Capability you can read before you grant it. Versions that can’t shift under your feet. Specialists that know one trade deeply instead of forty shallowly.

That’s how a Pod grows: not by making one agent smarter, but by handing the right sealed knowledge to the right member — and keeping you, the operator, signing every grant.