Skip to content

Defining Capabilities

This guide covers everything you need to write well-designed capabilities for your Zakardo application.

Every capability has two parts: a definition (what it does) and an implementation (how it does it).

The definition is a JSON object declaring the capability’s contract:

import type { CapabilityDefinition } from '@zakardo/core';
const createInvoice: CapabilityDefinition = {
name: 'invoices_create',
version: '1.0.0',
description: 'Create a new invoice for a customer.',
effect_class: 'WRITE_INTERNAL',
boundary: 'LOCAL',
input_schema: { /* JSON Schema */ },
output_schema: { /* JSON Schema */ },
interaction_spec: null,
anchored_view: null,
tags: ['invoices', 'billing'],
metadata: { author: 'billing-team', created_at: '2026-01-01T00:00:00Z', deprecated: false },
} as CapabilityDefinition;

The implementation is an async function:

import type { CapabilityFn } from '@zakardo/core';
const createInvoiceImpl: CapabilityFn = async (inputs) => {
const invoice = await db.invoices.create({
data: {
customer_id: inputs['customer_id'] as string,
amount: inputs['amount'] as number,
due_date: inputs['due_date'] as string,
},
});
return { id: invoice.id, status: 'created', amount: invoice.amount };
};

Schemas use JSON Schema (Draft 2020-12) with x-zakardo extensions. Every property must have a description.

input_schema: {
type: 'object',
required: ['customer_id', 'amount'],
properties: {
customer_id: { type: 'string', description: 'Customer ID' },
amount: { type: 'number', minimum: 0.01, description: 'Invoice amount in cents' },
due_date: { type: 'string', format: 'date', description: 'Payment due date (ISO 8601)' },
notes: { type: 'string', description: 'Optional invoice notes' },
},
'x-zakardo': { kind: 'capability-input', version: '1.0.0' },
},

Rules:

  • Always include 'x-zakardo': { kind: 'capability-input', version: '...' }
  • Mark required fields in the required array
  • Add description to every property — the Planner uses these to understand capabilities
  • Use format annotations (email, date, uri) for validation
output_schema: {
type: 'object',
properties: {
id: { type: 'string', description: 'Created invoice ID' },
status: { type: 'string', enum: ['created', 'pending'], description: 'Invoice status' },
amount: { type: 'number', description: 'Invoice amount' },
},
'x-zakardo': { kind: 'capability-output', version: '1.0.0' },
},
If your capability…Use
Only reads dataREAD
Creates or updates data in your databaseWRITE_INTERNAL
Calls an external API, sends email, posts webhookWRITE_EXTERNAL
Permanently deletes data or performs irreversible operationsDESTRUCTIVE

When in doubt, choose the higher severity — it is safer to over-govern than under-govern.

If your capability runs…Use
Within the server process (database queries, local computation)LOCAL
By calling an external service (HTTP API, gRPC)REMOTE
In the user’s browser or deviceUSER_ENV

If your capability needs user input mid-execution, declare an interaction spec:

const selectShipping: CapabilityDefinition = {
name: 'shipping_select',
version: '1.0.0',
description: 'Let the user select a shipping method.',
effect_class: 'READ',
boundary: 'LOCAL',
// ...schemas...
interaction_spec: {
type: 'SELECT',
prompt: 'Choose a shipping method',
data_mapping: {
options_from: '$context.steps.step_0.output.shipping_options',
label_field: 'name',
value_field: 'id',
},
constraints: {
min_selections: 1,
max_selections: 1,
timeout_ms: 120_000,
},
},
// ...
} as CapabilityDefinition;

Execution pauses at this step, the runtime sends an A2UI interaction prompt to the frontend, and resumes when the user responds.

Follow the domain_action pattern:

contacts_list ← domain: contacts, action: list
contacts_create ← domain: contacts, action: create
deals_update_stage ← domain: deals, action: update_stage
email_send ← domain: email, action: send

Use @zakardo/testing for isolated capability testing:

import { testCapability, createTestRuntime } from '@zakardo/testing';
import { describe, it, expect } from 'vitest';
describe('invoices_create', () => {
it('should create an invoice', async () => {
const result = await testCapability(createInvoiceImpl, {
customer_id: 'cust_123',
amount: 5000,
due_date: '2026-03-01',
});
expect(result.output).toMatchObject({ status: 'created', amount: 5000 });
expect(result.durationMs).toBeLessThan(1000);
});
});

Register definitions and implementations when creating the server:

const { app, runtime } = await createZakardoApp({
config,
capabilities: [createInvoice, listInvoices],
implementations: [
{ name: 'invoices_create', version: '1.0.0', fn: createInvoiceImpl },
{ name: 'invoices_list', version: '1.0.0', fn: listInvoicesImpl },
],
policies: [],
});