Agent Pack v1.0 · Stable

What is an Agent Pack

Most agent code never leaves a chat window or a laptop. Once it has to run against real company data, for more than one person, someone asks: which version is this, what can it touch, and whose permissions is it using?

An Agent Pack answers that as a versioned artifact: prompt, skills, tools, engine, and permissions — small enough to review and roll back like any other production change. This page defines the manifest only. Deploy targets, runtimes, and infrastructure are generated from a pack by tooling, not declared in it. See Why Agent Pack.

Anatomy

Only agent.yaml is required by this spec.

Prompt (AGENTS.md)

The pack prompt is always AGENTS.md at the pack root. There is no spec.prompt (or similar) field in agent.yaml.

That is intentional. Skills and MCP need path lists because there can be many, with varying names. The prompt is singular and canonical — the same pattern as Dockerfile or README.md: the filename is the contract. Declaring prompt: ./AGENTS.md on every pack would be boilerplate, not information.

Tooling and validators that care about the prompt look for that fixed path (and may record a hash such as computed.promptsSignature). Alternate filenames are out of scope for v1.

Claude Code and project rules

Claude Code (and similar coding agents) often load instructions from well-known files — AGENTS.md, CLAUDE.md, and rule trees under the project. An Agent Pack folder can completely satisfy that model for a given agent:

• Put operating instructions in pack-root AGENTS.md (versioned with the pack).
• Bundle skills and MCP under the pack so tools travel with the same identity.
• Pin engine and model in agent.yaml (spec.engine, optional spec.engineVersion / spec.model).

When the pack is the working tree (or is mounted as the agent’s project root), Claude Code–style loaders that already honor AGENTS.md pick up the same prompt the Pack format treats as canonical. Rules that would otherwise live as ad-hoc files across a repo can be closed inside the pack folder and schema — one reviewable unit — while AGENTS.md remains the entry point those engines already know how to read.

Subagents

Weak nested “subagent” blobs (a name + a paragraph inside a parent config) are not the recommended shape. A subagent should be another Agent Pack: its own agent.yaml, its own AGENTS.md, its own engine, model, permissions, and tools.

That keeps every worker reviewable, swappable, and attributable the same way as the parent. Delegation when to call whom stays in prose (AGENTS.md); what the subagent is stays entirely in the child pack’s manifest. A future dependency list field (spec.subagents) may enumerate those packs by name/path — see Changelog — but it does not invent a second, weaker descriptor format.

Manifest reference

Fields of agent.yaml, in document order. A conforming pack validates against the published JSON Schema.

Full example

Read-only warehouse analyst with per-user (OBO) SQL access.

# yaml-language-server: $schema=https://packs.agenthippo.ai/schema/v1/agent.json
apiVersion: agenthippo.ai/v1
kind: Agent
metadata:
  name: warehouse-analyst
  version: 0.1.0
  author: AgentHippo
  description: Read-only warehouse analyst — answers questions against the warehouse via per-user (OBO) SQL access.
spec:
  engine: claude
  engineVersion: 2.1.209
  model: claude-fable-5
  permissions:
    fileAccess: read-only
  mcp:
    - name: databricks
      config: ./mcp/databricks.mcp.json
  skills:
    - path: ./skills/sql-query

Engine

spec.engine identifies the Agent Engine that runs the turn loop. Same pack, same permissions and tools — change one line to retarget:

  spec:
    engine: cursor
    engine: codex

claude and codex are built-in. The rest install as adapters from the public engines catalog — or ship your own engine.mjs that implements the turn contract. Either way, spec.engine is the same string field. Optional spec.engineVersion pins the engine binary (for built-in Claude, the Claude Code version).

Remote

When spec.remote.url is set, the pack runs at that URL instead of executing spec.engine locally. Engine and model in effect are whatever is running there.

spec:
  engine: claude  # used only if spec.remote is absent
  remote:
    url: https://warehouse-analyst.example.com

Validation

Point editors that support yaml-language-server at the schema for inline validation and autocomplete:

# yaml-language-server: $schema=https://packs.agenthippo.ai/schema/v1/agent.json

Validate with npx @agenthippo-ai/pack-validate or GitHub Action uses: agenthippoai/[email protected] (schema from the same commit — no drift).

Badge

![Packaged as an Agent Pack](https://packs.agenthippo.ai/packs/badge.svg)

Deploy targets

deploy/ is not a manifest field and is not validated by this schema. Compliant tooling may generate deploy artifacts from a conformant pack for a chosen target:

Generated files should carry pack identity forward — headers such as # Generated from Agent Pack <name>@<version> — packs.agenthippo.ai and OCI labels ai.agenthippo.pack.name / ai.agenthippo.pack.version.

License

Spec text and JSON Schema are CC BY 4.0. Implement freely — commercial or not — with attribution and a link to the canonical URL. This is a published specification, not an open-standard foundation process. The AgentHippo registry, certification program, and managed runtime remain separate commercial products.

Changelog