The ZeroHuman Protocol
An open protocol (file formats + resolution rules) and implementation pattern (catalogue, factory, runtime, middleware, governance) for running structured AI operations at scale.
The protocol gives you a way to: (1) express "what exists" (catalogue manifests), (2) express "what is allowed" (policy manifests), (3) express "how to work" (skills + heartbeat routines), and (4) record "what actually happened" (artefacts + traces).
Architecture
The central technical challenge — coordinating automatic tool creation, automatic review, manual steering, and automatic iteration with artefacts — is addressed by separating responsibilities into three components.
Capability Factory
An explicit lifecycle with gates for drafting, reviewing, testing, and publishing capabilities. Skills and tools are scanned, pinned, and tested like code.
Catalogue / Indexer
Validates and moderates published packages with trust tiers and security scanning. CLI-driven installation and anonymous aggregated telemetry for ranking.
Runtime
Assembles a profile at execution-time using precedence rules, policies, and progressive disclosure. Deterministic boot sequence from profile to artefact.
Design Principles
Grounded in three converging ecosystems — instruction layering standards (AGENTS.md), skill marketplaces with progressive disclosure, and orchestration systems that treat agent work as governable operations.
Progressive disclosure by default
Load metadata early; load full content only when needed. Descriptions act as activation rules — full procedures are loaded on demand.
Typed tool surfaces + explicit approvals
Tools carry JSON schemas and are gateable at runtime with per-call approvals, network restrictions, and guardrails.
"Most restrictive wins" for permissions
Allow text overrides, but never allow policy overrides to broaden permissions at lower scopes. Essential for third-party skill safety.
Everything is testable
Treat skills like prompts that must be continuously evaluated with captured traces and artefacts, not "vibes".
Every run is auditable
Traces + artefacts + usage accounting are first-class. Opt-outs (e.g., Zero Data Retention) must be explicit.
Governance is part of the protocol
Publishing, moderation, trust tiers, and rollback prevent supply-chain compromise in skill ecosystems.
Terminology & Roles
The protocol is agnostic of specific suppliers. These generic terms are used throughout:
The development-time environment and scaffolding framework used to generate, test, and package skills and tools.
The production environment that executes the run loop, manages state, enforces policies, and invokes tools.
A command-line interface provided by an agent framework to interact with the agent locally.
The end-to-end pipeline (CI/CD) where capabilities are drafted, reviewed, tested, and published.
Canonical Object Model
Nine canonical objects define the complete operational model. Manifests are expressed as YAML, with embedded JSON Schema 2020-12 to define tool I/O and artefact shapes.
Tools
tool.yaml
Typed integration surfaces with schema, auth, permissions, and runtime gating.
Skills
SKILL.md
Reusable procedural knowledge in YAML frontmatter + Markdown.
Capabilities
capability.yaml
Versioned compositions of tools + skills + policies + tests.
Profiles
profile.yaml
Role configuration: model/runtime, budgets, concurrency, memory, and which capabilities are enabled.
Heartbeats
HEARTBEAT.md
Run-loop checklists that prevent blank-slate drift and ensure consistent routines.
Souls
SOUL.md
Identity, values, and boundaries that should change rarely.
Policies
policy.yaml
Enforceable rules: permissions, approval requirements, network policy, data sensitivity, logging, retention.
Artifacts
artifact.json
Immutable records of what was produced and how — with trace IDs and lineage.
Entity Relationships
Canonical Schemas
Compact examples of the core file formats. Each is designed for immediate adoption and interoperability across runtimes.
Root Manifest
Every package starts with a zerohuman.yaml declaring identity, contents, trust, and entrypoints.
Required Fields
protocol— Protocol identifierprotocol_version— Spec versionkind— Package typename— Human-readable package nameversion— Package versionentrypoints— Primary manifests to load
Optional Fields
summary— Package summarylicense— Licenserepository— Source repositorytrust— Trust & signing configindexing— Catalogue indexing
Hover over a field to see details
# zerohuman.yaml — Root Manifest
protocol: zerohuman
protocol_version: 0.1.0
kind: capability_package
name: my-agent-pack
version: 1.0.0
summary: "A collection of production-ready agent capabilities"
license: MIT
repository:
forge: github
org: your-org
repo: my-agent-pack
entrypoints:
capabilities:
- capabilities/frontend-dev/capability.yaml
skills:
- skills/react-optimization/SKILL.md
tools:
- tools/deploy/tool.yaml
trust:
publisher: community
signatures:
required: true
indexing:
discoverable: true
tags: [frontend, react, deployment]
Tool Definition
Typed integration surfaces with JSON Schema interfaces, OAuth auth, network permissions, and approval gates.
Required Fields
kind— Object kindname— Tool nameversion— Tool versiondescription— Tool description
Optional Fields
transport— Transport protocolauth— Authentication configpermissions— Permission manifestapproval— Approval gateimplementation— Code bindinginterface— I/O schema
Hover over a field to see details
# tools/acmecrm/tool.yaml
kind: tool
name: acmecrm_api
version: 0.4.0
description: Typed REST API integration for AcmeCRM.
transport: http
auth:
scheme: oauth2
token_source: secret_store
scopes: [contacts:read, contacts:write, campaigns:read]
permissions:
network:
allowed_domains: ["acmecrm.example.com"]
data:
default_classification: pii
approval:
required: true
implementation:
language: python
entrypoint: handler.py
function: handle
interface:
input_schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
operation:
type: string
enum: [get_contact, upsert_contact, list_segments]
payload:
type: object
required: [operation, payload]
output_schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
ok: { type: boolean }
result: { type: object }
error: { type: string }
required: [ok]
Policy
Enforceable rules that map to runtime guardrails, tool approvals, and network restrictions. "Most restrictive wins" across scopes.
Required Fields
kind— Object kindname— Policy nameversion— Policy version
Optional Fields
data_sensitivity— Data classification rulestool_controls— Tool access rulesnetwork_policy— Network egress rulesobservability— Observability config
Hover over a field to see details
# policies/pii-and-outbound.policy.yaml
kind: policy
name: pii_and_outbound_controls
version: 0.3.0
data_sensitivity:
classifications:
pii:
redaction: required
retention_days: 30
tool_controls:
default_needs_approval: true
allow:
- tool: acmecrm_api
operations: [get_contact, upsert_contact, list_segments]
deny:
- tool: acmecrm_api
operations: [create_campaign_export]
unless:
human_gate: true
network_policy:
deny_by_default: true
allow_domains: ["acmecrm.example.com"]
observability:
tracing: enabled
log_tool_io: redacted
Capability Bundle
Versioned compositions that reference tools, skills, policies by path. Declares required evals and emitted artefact types.
Required Fields
kind— Object kindname— Capability nameversion— Capability versiondescription— What this capability does
Optional Fields
tools— Tool referencesskills— Skill referencespolicies— Policy referencesevals— Evaluation suiteartefacts— Emitted artefact types
Hover over a field to see details
# capabilities/acmecrm-specialist/capability.yaml
kind: capability
name: acmecrm_specialist
version: 1.2.0
description: >
Execute segmented marketing ops in AcmeCRM
with policy-compliant tooling.
tools:
- ref: tools/acmecrm/tool.yaml
skills:
- ref: skills/acmecrm-segmentation/SKILL.md
- ref: skills/acmecrm-campaign-export/SKILL.md
policies:
- ref: policies/pii-and-outbound.policy.yaml
evals:
suite: evals/acmecrm-specialist/
required:
- golden_happy_path
- auth_failure_path
- rate_limit_recovery
artefacts:
emits:
- type: segment_definition
- type: acmecrm_export_zip
- type: campaign_audit_note
Profile & Agent Configuration
Role configuration with runtime engine, model, budgets, concurrency, and references to soul + heartbeat. Agents have jobs, not chat tabs.
Required Fields
kind— Object kindname— Profile namerole— Agent role
Optional Fields
runtime— Runtime engine configmodel— Model configurationbudgets— Resource budgetsconcurrency— Concurrency limitscapabilities— Enabled capabilitiesidentity— Identity (Soul)operation— Operational routinememory— Memory strategyhandoffs— Agent handoffs
Hover over a field to see details
# profiles/acmecrm-specialist/profile.yaml
kind: profile
name: acmecrm_specialist_agent
role: marketing_ops_specialist
runtime:
engine: target_agent_runtime
language: python
model:
default: gpt-5.4
budgets:
per_run_tokens_max: 120000
monthly_usd_max: 200
concurrency:
max_active_tasks: 2
capabilities:
- ref: capabilities/acmecrm-specialist/capability.yaml
identity:
soul: profiles/acmecrm-specialist/SOUL.md
operation:
heartbeat: profiles/acmecrm-specialist/HEARTBEAT.md
memory:
strategy: session
store: sqlite
handoffs:
- profile: deploy_agent
description: Hand off when CI passes and a release is ready.
Skill
Reusable procedural knowledge in YAML frontmatter + Markdown. Descriptions act as activation rules — full procedures are loaded on demand.
Required Fields
name— Skill namedescription— Activation descriptionmetadata— Skill metadatasemver— Skill version
Hover over a field to see details
# skills/triage-routing/SKILL.md
---
name: triage-routing
description: >
Classify a support request, choose a specialist,
and hand off with structured input.
Use for any new inbound ticket that needs routing.
metadata:
semver: 0.8.0
---
# Triage Routing
Route inbound support tickets to the right specialist
agent based on intent, urgency, and customer impact.
## Inputs needed
- Ticket ID and full ticket content
- Customer context (account tier, history) if available
## Steps
1. Identify intent — billing | refunds | technical | account
2. Assess urgency — low | medium | high | critical
3. Handle ambiguity — escalate, do not guess
4. Prepare handoff input — structured summary
5. Draft customer reply — acknowledgment only
6. Emit artifacts
## Done when
- Ticket is routed OR escalated
- All artifacts are emitted
Heartbeat
Run-loop checklists that prevent blank-slate drift and ensure consistent routines. Agents wake on schedules, check work, enforce budgets, and operate within governance.
Required Fields
Confirm— Identity confirmationCheck— Queue inspectionProcess— Task executionStop— Termination signal
Optional Fields
Respect— Concurrency guardBudget— Budget checkSummarise— Run summary
Hover over a field to see details
# profiles/support-triage/HEARTBEAT.md
# Support Triage Heartbeat
On every wake:
1. Confirm identity — verify active policy name
and version. Stop if policy missing.
2. Check queue — fetch unrouted tickets ordered
by urgency (critical first, then SLA deadline).
3. Process next ticket:
a. Read full ticket content and customer context
b. Activate the triage-routing skill
c. Follow skill procedure to completion
d. Emit all required artifacts before next ticket
4. Respect concurrency — do not exceed
max_active_tasks. Wait for a slot if at capacity.
5. Budget check — if token usage approaches
per_run_tokens_max, stop and report queue depth.
6. Summarise:
- Tickets routed (count by specialist type)
- Tickets escalated (count with reasons)
- Remaining queue depth
7. Stop — do not loop. Next wake handles new tickets.
Soul
Identity, values, and boundaries that should change rarely. Loaded at boot, the soul defines who the agent is and what it must never do.
Required Fields
Non-negotiables— Hard constraints
Optional Fields
Values— Behavioral prioritiesBoundaries— Operational scope
Hover over a field to see details
# profiles/acmecrm-specialist/SOUL.md
# AcmeCRM Specialist Soul
You are a compliance-first marketing operations
specialist.
## Non-negotiables
- Never exfiltrate secrets or PII outside declared
policy boundaries.
- Never call tools outside the declared policy.
- Prefer reversible changes; document every
irreversible change as an artifact note.
- If uncertain, request human approval and explain
the risk.
- Never fabricate data.
## Values
- Accuracy over speed — verify before reporting.
- Traceability over cleverness — every action
should be auditable.
- Least privilege — request only needed permissions.
- Transparency — state assumptions explicitly.
## Boundaries
- Operate only within the AcmeCRM domain.
- No external services not in the tool manifest.
- Never store credentials in context or logs.
Artifact
Immutable records of what was produced and how — with trace IDs, lineage, policy checks, and approval logs. The audit backbone of the protocol.
Required Fields
kind— Object kindartifact_id— Unique artifact IDtype— Artifact typecreated_at— Creation timestamptrace— Trace contextinputs— Execution inputsoutputs— Produced outputs
Optional Fields
checks— Policy & approval checks
Hover over a field to see details
{
"kind": "artifact",
"artifact_id": "artifact_01HZY3XKQM9V7WNBT4P2RJCE8A",
"type": "campaign_audit_note",
"created_at": "2026-03-28T10:04:12Z",
"trace": {
"trace_id": "trace_01HZY3XKQM9V7WNBT4P2RJCE8B",
"workflow": "crm_ops"
},
"inputs": {
"task_id": "task_crm_segmentation_042",
"profile": "acmecrm_specialist_agent",
"capabilities": ["[email protected]"],
"skills_activated": ["[email protected]"],
"tools_invoked": ["[email protected]"]
},
"outputs": {
"summary": "Updated segment 'high-value-q1'...",
"links": [
{ "rel": "crm-segment", "href": "crm://segments/high-value-q1" }
],
"files": []
},
"checks": {
"policy": "[email protected]",
"data_classification": "pii",
"redaction_applied": true,
"approvals": [
{
"tool": "acmecrm_api",
"operation": "upsert_contact",
"approved_by": "human",
"at": "2026-03-28T10:02:01Z"
}
]
}
}
Resolution & Precedence
Deterministic, explainable resolution rules mirror AGENTS.md-style layering for instruction text and enforce "most restrictive wins" for security and permissions.
Skills: Progressive Disclosure
Only load metadata initially. Load full SKILL.md body only when the agent activates the skill. Descriptions act as activation rules.
Tools: Token Safety
When tool surfaces are large, use namespaces and deferred loading. The runtime supports tool search, deferred tool loading, and tool namespaces to reduce tokens.
Versioning & Compatibility
Protocol objects use Semantic Versioning (MAJOR.MINOR.PATCH) for all published packages. Execution engines are treated as pluggable — the protocol records which engine executed a run.
Compatibility Contract
- ·
protocol_versionin zerohuman.yaml is SemVer - ·Each object declares
version(SemVer) - ·
requires.protocol: ">=0.1.0 <0.2.0" - ·
requires.runtime.engineand optionalmin_version
Resolution Algorithm
- 1.Prefer pinned versions (exact)
- 2.Else select the highest compatible version within ranges
- 3.Security patch preference: if a higher PATCH is available, prefer it — but require CI re-validation
Runtime Boot Sequence
A deterministic boot sequence combines progressive disclosure and policy gating. Congruent with standard run loop semantics (LLM call → tool calls/handoffs → repeat until final output).
Capability Factory Lifecycle
The factory implements a canonical state machine for the full capability lifecycle — from request to published package to observed production use. Every transition is explicit, stateful, and observable.
| Stage | Required Artefacts | Automated Checks | Human Gate |
|---|---|---|---|
| Requested | request.md, initial risk.md | Schema skeleton validation | Optional |
| SpecDraft | tool.yaml, capability.yaml, policy.yaml, draft skills | Lint (YAML/JSON), policy completeness | Required for high-risk |
| SpecReview | Frozen spec + interface schemas | Interface contract tests | Required |
| Scaffolded | Repo layout + stubs + zerohuman.yaml | Build passes | Optional |
| Implemented | Code + tests + docs | Unit tests; static analysis; secret scans | Optional |
| AutoReviewed | Eval suite + golden outputs | Eval run; failure-path tests; security scan | Optional |
| Sandboxed | Sandbox run artefacts + trace | Policy enforcement + runtime checks | Required if outbound/PII |
| HumanGate | Approval record | Cryptographic signing | Required |
| Published | Release notes, SBOM/attestations | Indexer validation | Optional |
| Observed | Telemetry + incident reports | Anomaly detection | Optional |
| Iterating | New PRs + updated versions | Regression evals | Per-change |
Security & Governance
Supply-chain security is no longer hypothetical. Skills registries are under active attack. ZeroHuman adopts a layered control model aligned with OWASP AST10 baseline controls.
Publisher Identity
Require signed releases for trusted tiers. Cryptographic signing at the HumanGate stage.
Permission Manifests
tool.yaml and policy.yaml declare outbound domains, data classification, and approval requirements.
Isolation
High-risk tools run in sandbox/containers with network policies and allowlists. OCI-compliant containers or Wasm modules.
Network Egress
Deny-by-default policy. Allowlisted domains. Domain-secret patterns where supported by the runtime.
Redaction
Log tool I/O in redacted form for PII. Full payloads kept in secure stores with scoped access.
Observability
Three correlated records: traces (end-to-end runs), artefacts (immutable outputs), and usage/cost accounting.
Protocol Track
File formats + resolution rules
RFCs → spec releases
Ecosystem Track
Listings, trust, moderation
Discussions → PRs
Framework Track
Reference implementation
Versioned releases
Full Examples
Two complete capability packages demonstrating the protocol end-to-end — from manifest to profiles, tools, skills, policies, and evals.
AcmeCRM Specialist
A realistic tool + skills + policy + profile bundle for AcmeCRM — an open-source marketing automation project. One tool (REST API via OAuth), two skills (segmentation and campaign export). Policies enforce PII handling and restrict outbound network access. The runtime records artefacts (segment changes, export bundles) and traces.
# capabilities/acmecrm-specialist/capability.yaml
kind: capability
name: acmecrm_specialist
version: 1.2.0
description: >
Execute segmented marketing ops in AcmeCRM
with policy-compliant tooling.
tools:
- ref: tools/acmecrm/tool.yaml
skills:
- ref: skills/acmecrm-segmentation/SKILL.md
- ref: skills/acmecrm-campaign-export/SKILL.md
policies:
- ref: policies/pii-and-outbound.policy.yaml
evals:
suite: evals/acmecrm-specialist/
required:
- golden_happy_path
- auth_failure_path
- rate_limit_recovery
artefacts:
emits:
- type: segment_definition
- type: acmecrm_export_zip
- type: campaign_audit_noteSupport Triage
A generic triage agent that receives new tickets, classifies intent, hands off to specialist sub-agents (billing/refunds/technical), uses tool approvals for high-impact actions (customer record edits), and requires evals that test both routing correctness and "no harmful action without approval".
# capabilities/support-triage/capability.yaml
kind: capability
name: support_triage
version: 0.8.0
description: >
Classify inbound tickets and route to specialist
agents with guarded tool actions.
tools:
- ref: tools/ticketing/tool.yaml
skills:
- ref: skills/triage-routing/SKILL.md
policies:
- ref: policies/support.policy.yaml
evals:
suite: evals/support-triage/
required:
- route_correctness
- no_unapproved_updates
- escalation_on_ambiguity
artefacts:
emits:
- triage_decision
- customer_reply_draft
- escalation_noteFull example files (souls, heartbeats, skills, tools, policies, profiles) for both capabilities are available in the protocol repository.
Dive deeper
The full specification includes CI/CD pipeline templates, runtime binding examples, catalogue architecture, and middleware design.