ZeroHuman
Protocol v0.1.0

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.

01

Progressive disclosure by default

Load metadata early; load full content only when needed. Descriptions act as activation rules — full procedures are loaded on demand.

02

Typed tool surfaces + explicit approvals

Tools carry JSON schemas and are gateable at runtime with per-call approvals, network restrictions, and guardrails.

03

"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.

04

Everything is testable

Treat skills like prompts that must be continuously evaluated with captured traces and artefacts, not "vibes".

05

Every run is auditable

Traces + artefacts + usage accounting are first-class. Opt-outs (e.g., Zero Data Retention) must be explicit.

06

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:

Agent Builder (Builder SDK)

The development-time environment and scaffolding framework used to generate, test, and package skills and tools.

Target Runtime (Agent Runtime)

The production environment that executes the run loop, manages state, enforces policies, and invokes tools.

Agent CLI

A command-line interface provided by an agent framework to interact with the agent locally.

Capability Factory

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.

Entity Relationships

→zerohuman.yaml → lists → Capabilities
→Capability → references → Tools
→Capability → includes → Skills
→Capability → constrained by → Policies
→Profile → enables → Capabilities
→Profile → executes → Heartbeat
→Profile → defines → Soul
→Run → emits → Artefacts
→Run → records → Traces
→Policy → allows/denies → Tool Rules

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 identifier
  • protocol_version — Spec version
  • kind — Package type
  • name — Human-readable package name
  • version — Package version
  • entrypoints — Primary manifests to load

Optional Fields

  • summary — Package summary
  • license — License
  • repository — Source repository
  • trust — Trust & signing config
  • indexing — Catalogue indexing

Hover over a field to see details

zerohuman.yamlyaml
# 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 kind
  • name — Tool name
  • version — Tool version
  • description — Tool description

Optional Fields

  • transport — Transport protocol
  • auth — Authentication config
  • permissions — Permission manifest
  • approval — Approval gate
  • implementation — Code binding
  • interface — I/O schema

Hover over a field to see details

tool.yamlyaml
# 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 kind
  • name — Policy name
  • version — Policy version

Optional Fields

  • data_sensitivity — Data classification rules
  • tool_controls — Tool access rules
  • network_policy — Network egress rules
  • observability — Observability config

Hover over a field to see details

policy.yamlyaml
# 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 kind
  • name — Capability name
  • version — Capability version
  • description — What this capability does

Optional Fields

  • tools — Tool references
  • skills — Skill references
  • policies — Policy references
  • evals — Evaluation suite
  • artefacts — Emitted artefact types

Hover over a field to see details

capability.yamlyaml
# 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 kind
  • name — Profile name
  • role — Agent role

Optional Fields

  • runtime — Runtime engine config
  • model — Model configuration
  • budgets — Resource budgets
  • concurrency — Concurrency limits
  • capabilities — Enabled capabilities
  • identity — Identity (Soul)
  • operation — Operational routine
  • memory — Memory strategy
  • handoffs — Agent handoffs

Hover over a field to see details

profile.yamlyaml
# 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 name
  • description — Activation description
  • metadata — Skill metadata
  • semver — Skill version

Hover over a field to see details

SKILL.mdyaml
# 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 confirmation
  • Check — Queue inspection
  • Process — Task execution
  • Stop — Termination signal

Optional Fields

  • Respect — Concurrency guard
  • Budget — Budget check
  • Summarise — Run summary

Hover over a field to see details

HEARTBEAT.mdmarkdown
# 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 priorities
  • Boundaries — Operational scope

Hover over a field to see details

SOUL.mdmarkdown
# 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 kind
  • artifact_id — Unique artifact ID
  • type — Artifact type
  • created_at — Creation timestamp
  • trace — Trace context
  • inputs — Execution inputs
  • outputs — Produced outputs

Optional Fields

  • checks — Policy & approval checks

Hover over a field to see details

artifact.jsonjson
{
  "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.

1Explicit User/Task Input
2Task-Local Overrides
3Profile Overlays
4Capability Package Content
5Organisation Global Policy
6Runtime Defaults

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_version in zerohuman.yaml is SemVer
  • ·Each object declares version (SemVer)
  • ·requires.protocol: ">=0.1.0 <0.2.0"
  • ·requires.runtime.engine and optional min_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).

01Load profile.yaml
02Load SOUL.md (identity + non-negotiables)
03Load HEARTBEAT.md (operational routine)
04Resolve capabilities and verify versions/compatibility
05Load tool metadata and skill metadata only (progressive disclosure)
06Apply policy: compute effective allow/deny, approvals, network policy
07Fetch next task (ticket) with atomic checkout
08Execute using engine — handoffs for delegation, tool search for large surfaces, approvals for high-impact tools
09Emit artefacts and attach trace IDs
10Update task state, budgets, and learning signals

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.

Requested→ SpecDraft→ SpecReview→ Scaffolded→ Implemented→ AutoReviewed→ Sandboxed→ HumanGate→ Published→ Observed→ Iterating
StageRequired ArtefactsHuman Gate
Requestedrequest.md, initial risk.mdOptional
SpecDrafttool.yaml, capability.yaml, policy.yaml, draft skillsRequired for high-risk
SpecReviewFrozen spec + interface schemasRequired
ScaffoldedRepo layout + stubs + zerohuman.yamlOptional
ImplementedCode + tests + docsOptional
AutoReviewedEval suite + golden outputsOptional
SandboxedSandbox run artefacts + traceRequired if outbound/PII
HumanGateApproval recordRequired
PublishedRelease notes, SBOM/attestationsOptional
ObservedTelemetry + incident reportsOptional
IteratingNew PRs + updated versionsPer-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.

capability.yamlyaml
# 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

Support 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".

capability.yamlyaml
# 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_note

Full 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.