Defining Capabilities
This guide covers everything you need to write well-designed capabilities for your Zakardo application.
Anatomy of a Capability
Section titled “Anatomy of a Capability”Every capability has two parts: a definition (what it does) and an implementation (how it does it).
Definition
Section titled “Definition”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;Implementation
Section titled “Implementation”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 };};Schema Design
Section titled “Schema Design”Schemas use JSON Schema (Draft 2020-12) with x-zakardo extensions. Every property must have a description.
Input Schema
Section titled “Input Schema”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
requiredarray - Add
descriptionto every property — the Planner uses these to understand capabilities - Use
formatannotations (email,date,uri) for validation
Output Schema
Section titled “Output Schema”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' },},Choosing an Effect Class
Section titled “Choosing an Effect Class”| If your capability… | Use |
|---|---|
| Only reads data | READ |
| Creates or updates data in your database | WRITE_INTERNAL |
| Calls an external API, sends email, posts webhook | WRITE_EXTERNAL |
| Permanently deletes data or performs irreversible operations | DESTRUCTIVE |
When in doubt, choose the higher severity — it is safer to over-govern than under-govern.
Choosing a Boundary
Section titled “Choosing a Boundary”| 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 device | USER_ENV |
Adding Interaction Specs
Section titled “Adding Interaction Specs”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.
Naming Conventions
Section titled “Naming Conventions”Follow the domain_action pattern:
contacts_list ← domain: contacts, action: listcontacts_create ← domain: contacts, action: createdeals_update_stage ← domain: deals, action: update_stageemail_send ← domain: email, action: sendTesting Capabilities
Section titled “Testing Capabilities”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); });});Registration
Section titled “Registration”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: [],});Further Reading
Section titled “Further Reading”- Capabilities Concept — conceptual overview
- Effect Classes — governance implications
- Capability System Specification — full specification