Spec & agent versions

The five object types

File kinds inside a Spec

The Spec is a folder of markdown files. Five kinds — all first-class, all use the same frontmatter conventions Claude Code uses, so skills and subagents you've already built drop in unchanged.

# agents/concierge/AGENT.md
# BayHomes Concierge

You help prospective buyers explore listings.
Address the user as "you". Keep replies under two paragraphs unless asked.
Never quote a final price — always defer to a human agent for pricing.

# agents/concierge/skills/format-listing/SKILL.md
---
name: format-listing
description: Format a property listing card with price, beds, sqft, and one-line pitch
allowed-tools: [Read, lookup_zestimate]
---
When showing a listing, render…

# agents/concierge/workflows/morning-digest.md
---
name: morning-digest
description: Daily 7am email summarizing new listings + price changes
trigger: { kind: schedule, cron: '0 7 * * 1-5' }
requires: [gmail, hubspot]
---
1. Query HubSpot for active buyers…
2. Match against new MLS listings…
3. Draft + send digest emails…

# agents/concierge/commands/handoff.md
---
description: Hand the conversation off to a human agent
argument-hint: "[reason]"
---
Tell the user a human will follow up about $ARGUMENTS, then emit a handoff event.

On every push the entire bundle is uploaded. specs.push stamps a new version only if content actually changed.

Custom subagents — advanced

The runtime delegates side-tasks to a fresh-context worker automatically. You don't configure this, and most agents never need to think about it. Built-in safety: max delegation depth is bounded, recursion is rejected, and per-session cost is capped.

The one reason to declare a named subagent is when you want a predictable, repeatable specialist — a compliance reviewer, a sales-tone checker, a structured research role. Drop a markdown file at subagents/<name>.md using the same format as Claude Code subagents (.claude/agents/*). It's purely additive.

# agents/concierge/subagents/researcher.md
---
name: researcher
description: Looks up market comparables and neighborhood data
tools: [WebSearch, WebFetch, lookup_zestimate]
model: premium
---
You research recent comparable sales…

Import from Claude Code

Existing Claude Code work is directly portable. No converter, no edits — the spec bundle uses the same file layout and frontmatter conventions Claude Code uses.

Skills + commands — copy into your local spec folder

Your agents/<agent-name>/ directory is the local source-of-truth that gets uploaded on the next specs.push (see Where this runs). Copy existing Claude Code files into it:

cp -r ~/projects/my-tool/.claude/skills/*   agents/<agent-name>/skills/
cp -r ~/projects/my-tool/.claude/commands/* agents/<agent-name>/commands/

On the next an.specs.push(loadAgentDir(...)) the files are uploaded to AgentNava as part of a new spec version; after configure + deploy, the agent running on AgentNava infrastructure picks them up. Everything works as-is:

• Skills — YAML frontmatter (name, description, allowed-tools, model, disable-model-invocation) is interpreted identically.
• Commands — $ARGUMENTS substitution, argument-hint, and allowed-tools are honored. Users invoke them with /name in chat.

Subagents (.claude/agents/*) port the same way but are an advanced concept — most agents don't need them. See Custom subagents.

The one Claude-Code-specific concept we don't carry over is CLAUDE.md — we call its equivalent AGENT.md instead. If you're porting a Claude Code project, rename CLAUDE.md → AGENT.md and you're done.

Plugins — install once, attach by name

Claude Code plugins (.claude-plugin/plugin.json bundles of skills, subagents, commands, hooks, and MCP servers) install at the workspace and are referenced from any agent:

// 1) Install at the workspace (one-time, idempotent on tag).
await an.plugins.install('github:owner/repo#v1');
// → { name: 'pr-helper', version: 'v1', skills: 3, subagents: 1, mcpServers: 1 }

// 2) Reference by name from configure.
await an.agents.configure({
  // ...
  plugins: ['pr-helper'],
});

Install sources we accept:

• github:owner/repo, github:owner/repo#v1, github:owner/repo#commit-sha
• https://example.com/plugin.tgz (signed tarball)
• ./vendor/my-plugin (local path)

Once installed, the plugin's bundled skills, subagents, commands, hooks, and MCP servers all become available on every agent that lists it.

MCP servers

Any MCP-compatible server is added as a connection. Three transports supported, same as Claude Code's .mcp.json:

import { connect } from '@agentnava/kit';

await an.agents.configure({
  // ...
  connections: [
    // HTTP / SSE — most managed MCP services
    connect.mcp({ name: 'linear', url: 'https://mcp.linear.app/sse' }),

    // With a bearer token from your workspace secrets
    connect.mcp({
      name: 'jira',
      url: 'https://mcp.example.com',
      headers: { Authorization: `Bearer ${process.env.JIRA_MCP_TOKEN}` },
    }),

    // Stdio — for local-process MCP servers
    connect.mcp({
      name: 'local-fs',
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
    }),
  ],
});

Every tool the MCP server exposes becomes a callable tool for the agent — no wrapping, no conversion. To see what's available, an.connections.tools('linear') returns the live tool list.

The lifecycle in TypeScript

The whole flow is a single file. Each step is an SDK call.

// agents/concierge.ts
import { AgentNava, connect, loadAgentDir } from '@agentnava/kit';

const an = new AgentNava();   // reads process.env.AGENTNAVA_API_KEY

// 1) Push the Spec bundle (AGENT.md + skills + subagents + workflows + commands).
//    loadAgentDir reads the folder and infers each file's kind from its path.
const spec = await an.specs.push(
  loadAgentDir('./agents/concierge', { key: 'concierge' }),
);
// → { id: 'spec_4f1c9a', version: 2 }

// 2) Upload the Knowledge base (.md, .pdf, .txt, images).
const kb = await an.knowledge.upload({
  key:   'bayhomes-handbook',
  files: ['./knowledge/handbook.pdf', './knowledge/policies.md', './knowledge/floorplan.png'],
});
// → { id: 'kb_8b07', version: 3 }

// 3) Configure → returns a new agent version that pins to spec@v2 and kb@v3.
const v = await an.agents.configure({
  key:         'bayhomes-concierge',
  name:        'BayHomes Concierge',
  modelClass:  'standard',
  spec,                                                  // bundle from step 1
  knowledge:   [kb],                                     // agents AND workflows always see this
  triggers:    [{ kind: 'chat' }],
  connections: [connect.slack({ key: 'slack-bayhomes' })],
  secrets:     ['ZILLOW_API_KEY'],
});
// → { agentId: 'agt_2b8e', versionId: 'ver_3c5f' }

// 4) (Optional) deploy to test. Dev-only URL.
const test = await an.agents.deployToTest(v.versionId);
console.log('test:', test.url);

// 5) Deploy to prod when you're happy.
const prod = await an.agents.deployToProd(v.versionId);
console.log('prod:', prod.url);

Re-running the file is safe and idempotent. specs.push only stamps a new version if content changed. agents.configure upserts on key. deployToTest/deployToProd always produce a new instance.

Explicit fields, if you prefer

loadAgentDir is a convenience over the explicit form. Both are valid:

const spec = await an.specs.push({
  key: 'concierge',
  instructions: readFileSync('./agents/concierge/AGENT.md', 'utf8'),
  skills: [
    { name: 'format-listing', content: readFileSync('./agents/concierge/skills/format-listing/SKILL.md', 'utf8') },
  ],
  workflows: [
    { name: 'morning-digest', content: readFileSync('./agents/concierge/workflows/morning-digest.md', 'utf8') },
  ],
  commands: [
    { name: 'handoff',        content: readFileSync('./agents/concierge/commands/handoff.md', 'utf8') },
  ],
  // subagents: [...]  // advanced — see Custom subagents below
});

What configure takes

Every field below is a property of the object you pass to an.agents.configure(...).

key: 'bayhomes-concierge'

name: 'BayHomes Concierge'

spec  // pass the object directly
// or
spec: 'spec_4f1c9a@v2'
// or
spec: 'spec_4f1c9a'   // resolves to latest at configure time, then pinned

knowledge: [kb, 'kb_legal@v5']

modelClass: 'standard'           // rolling — auto-upgrades over time
modelClass: 'standard@2026-05'   // pinned to the May 2026 snapshot
modelClass: 'premium@v3'         // pinned to integer release v3

triggers: [
  { kind: 'chat' },
  { kind: 'webhook' },
  { kind: 'schedule', cron: '0 7 * * 1-5' },
  { kind: 'loop', everySeconds: 600, maxRuns: 24 },
  { kind: 'manual' },
]

connections: [
  connect.slack({ key: 'slack-acme' }),
  connect.gmail({ key: 'gmail-support' }),
  connect.mcp({ url: 'https://mcp.linear.app/sse' }),
]

secrets: ['ZILLOW_API_KEY', 'STRIPE_KEY']

// in a tool handler:
defineTool({
  // ...
  handler: async ({ address }, ctx) => {
    const r = await fetch(`https://zillow…`, {
      headers: { 'X-Key': ctx.secrets.ZILLOW_API_KEY },
    });
  },
});

import { defineTool, t } from '@agentnava/kit';

const lookupZestimate = defineTool({
  name: 'lookup_zestimate',
  description: 'Get the Zillow zestimate for an address',
  input: t.object({ address: t.string() }),
  handler: async ({ address }, ctx) => {
    // ctx.secrets, ctx.sessionId, ctx.user available here
  },
});

tools: [lookupZestimate]

plugins: ['claude-code-review', 'pr-helper@v2']

hooks: [
  { event: 'PreToolUse',  match: { tool: 'Bash' }, run: async (ctx) => { /* approve or block */ } },
  { event: 'PostToolUse', match: { tool: '*' },    run: async (ctx) => { /* log */ } },
]

allowedTools: ['Read', 'WebSearch', 'Task']
// disallowedTools also accepted

meta: {
  deployTarget: 'embed',
  brandColor: '#B91C1C',
  region: 'eu-west',
}

Event stream

The agent runtime emits a typed SSE stream that any host UI can consume. The same shape comes back whether you're hitting a test or a prod deploy.

type AgentEvent =
  | { type: 'message-start'; messageId: string }
  | { type: 'message-delta'; messageId: string; delta: string }
  | { type: 'message-end'; messageId: string; final: string }
  | { type: 'tool-start'; toolId: string; name: string; input: unknown }
  | { type: 'tool-end'; toolId: string; ok: boolean; result?: unknown; error?: string }
  | { type: 'phase'; label: string; state: 'start' | 'end' }
  | { type: 'error'; message: string }
  | { type: 'done' };