Agent Capability Standard

Grounded Agency: A framework for building AI agents that know what they don't know.

Versioning: The spec version (v1.1.0, Candidate Standard; v1.0.0 still supported) tracks the standard itself. The plugin version (v2.0.0) tracks the Claude Code implementation. The Python package (grounded-agency) uses its own SemVer. See GOVERNANCE.md for the versioning policy.

# Install as Claude Code plugin
claude plugin marketplace add synaptiai/synapti-marketplace
claude plugin install agent-capability-standard

What Is This?

Agent Capability Standard is the technical specification. Grounded Agency is the philosophy behind it.

Most AI agent systems fail in production because:

• Composition is implicit (no contracts between capabilities)
• State is ungrounded (no provenance for claims)
• Conflict resolution is undefined (no trust model)
• Safety is retrofitted (no checkpoints or rollback)

This standard fixes that by making reliability structural—not optional.

The Core Idea

Every agent action should be:

1. Grounded — backed by evidence, not hallucination
2. Auditable — with provenance and lineage
3. Safe — mutations require checkpoints
4. Composable — typed contracts between capabilities

The Periodic Table of Agent Capabilities

Just as chemistry has ~118 elements that compose into infinite molecules, this standard defines 36 atomic capabilities that compose into infinite workflows.

┌─────────────────────────────────────────────────────────────────────────┐
│ CAPABILITIES (atoms)              →  WORKFLOWS (molecules)              │
│                                                                         │
│  observe + search + plan          →  debug_code_change                  │
│  + checkpoint + execute                                                 │
│  + verify + rollback                                                    │
│                                                                         │
│  receive + transform + integrate  →  digital_twin_sync_loop             │
│  + detect + plan                                                        │
│  + checkpoint + mutate + audit                                          │
└─────────────────────────────────────────────────────────────────────────┘

Capabilities are atoms: Irreducible primitives with defined I/O contracts.

Workflows are molecules: Compositions that solve real problems.

The goal isn't more atoms—it's better molecules.

Why 36?

The 36 capabilities were systematically derived from first principles:

1. Cognitive architecture analysis (BDI, SOAR, ReAct patterns)
2. Industry tool patterns (MCP, LangChain, Claude Skills)
3. Rigorous atomicity testing (cannot be decomposed further)

Each capability:

• Performs exactly one irreducible cognitive operation
• Has a well-defined I/O contract with evidence anchors
• Maps to how agents actually work in production

Domain specializations become parameters, not separate capabilities. detect(domain: anomaly) rather than detect-anomaly.

For the full derivation methodology, see docs/methodology/FIRST_PRINCIPLES_REASSESSMENT.md.

Why This Matters

The Problem

AI agents in production fail silently. When a retrieval step hallucinates, downstream actions proceed with bad data. When conflicts arise between sources, there's no resolution strategy. When mutations fail, there's no rollback.

These aren't edge cases—they're the norm. Most agent systems lack structural safeguards, so failures are discovered after the damage is done.

The Cost

• Debug time: Hours tracing why an agent made a decision with no audit trail
• Data corruption: Unrecoverable state from failed mutations without checkpoints
• Trust erosion: Users lose confidence after unexplained failures
• Compliance risk: Auditors ask "why did the agent do X?" and you can't answer

The Solution

This standard makes failures visible and recoverable:

• Every claim traces to evidence (or explicitly marks uncertainty)
• Every mutation has a checkpoint (rollback is always possible)
• Every conflict has a resolution strategy (trust model decides)
• Every decision has lineage (audit answers "why")

When to Use This

Quick Start

Option 1: Claude Code Plugin (Recommended)

Install from the Synapti marketplace:

# Add the marketplace (one-time)
claude plugin marketplace add synaptiai/synapti-marketplace

# Install the plugin
claude plugin install agent-capability-standard

This gives you:

• 36 atomic capability skills organized by layer
• Workflow patterns that compose capabilities
• Safety hooks (checkpoint enforcement, audit logging)

Option 2: Standalone Validation

Use the validator independently:

# Clone the repository
git clone https://github.com/synaptiai/agent-capability-standard.git
cd agent-capability-standard

# Set up Python environment (Python >= 3.10; builds the Rust core, so Rust >= 1.86 is required)
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]" -c constraints.txt

# Validate workflows (defaults to schemas/workflow_catalog.yaml; --catalog PATH for another file)
python tools/validate_workflows.py
# → VALIDATION PASS

# Run conformance tests
python scripts/run_conformance.py
# → Conformance PASSED

Next: See QUICKSTART.md for a guided walkthrough.

Choose Your Path

What's Included

36 Atomic Capabilities

Organized across 9 cognitive layers with explicit input/output schemas:

Workflow Patterns

Capabilities compose into reusable workflow patterns:

See WORKFLOW_PATTERNS.md for the complete pattern catalog.

12 Composed Workflows

Reference workflow compositions defined in the workflow catalog, with gates, failure modes that roll back on error, and typed bindings. Five of these are also available as composed skills for direct invocation:

Domain Profiles

Pre-configured trust weights, risk thresholds, and checkpoint policies for specific industries:

Canonical Schemas

• Capability Ontology — 36 atomic capabilities with I/O contracts (ontology)
• Workflow DSL — Typed bindings, gates, failure modes and recovery loops (no reference workflow uses a loop; see STANDARD §5.12)
• World State — Observations with provenance and uncertainty
• Trust Model — Authority ranking with time decay

Safety Hooks

Hooks implementing SAFETY layer capabilities:

Documentation

For Users

For Implementers

For Contributors

Methodology

Background

Directory Structure

agent-capability-standard/
├── skills/                  # 36 atomic capability skills (flat structure)
│   ├── retrieve/SKILL.md    # PERCEIVE layer
│   ├── search/SKILL.md
│   ├── observe/SKILL.md
│   ├── detect/SKILL.md      # UNDERSTAND layer
│   ├── classify/SKILL.md
│   ├── plan/SKILL.md        # REASON layer
│   ├── state/SKILL.md       # MODEL layer
│   ├── generate/SKILL.md    # SYNTHESIZE layer
│   ├── mutate/SKILL.md      # EXECUTE layer
│   ├── verify/SKILL.md      # VERIFY layer
│   ├── checkpoint/SKILL.md
│   ├── persist/SKILL.md     # REMEMBER layer
│   ├── delegate/SKILL.md    # COORDINATE layer
│   └── ...                  # (36 total skills)
├── schemas/                 # Ontology + workflow + world state schemas
│   ├── capability_ontology.yaml     # 36-capability ontology
│   ├── workflow_catalog.yaml
│   ├── world_state_schema.yaml
│   ├── interop/                       # Framework interoperability mappings
│   │   └── oasf_mapping.yaml          # OASF skill code mapping
│   └── transforms/          # Type coercion mappings
├── core/                    # Rust crate: validator and executor, compiled into grounded_agency._core
├── grounded_agency/         # Python package (SDK integration)
├── hooks/                   # Safety hooks (checkpoint, audit)
├── tools/                   # Validator CLI (thin wrapper over core/)
├── tests/                   # Conformance fixtures
├── spec/                    # Standard documentation
├── docs/                    # User documentation + methodology
│   ├── guides/                        # User guides
│   └── proposals/                     # Extension proposals
├── examples/                # Usage examples
└── templates/               # Skill templates

Claude Agent SDK Integration

The Grounded Agency capability standard integrates with the Claude Agent SDK to provide safety-first agent execution:

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from grounded_agency import GroundedAgentAdapter, GroundedAgentConfig

# Create adapter with strict checkpoint enforcement
adapter = GroundedAgentAdapter(GroundedAgentConfig(strict_mode=True))

# Create checkpoint before mutations
adapter.create_checkpoint(scope=["src/*.py"], reason="Before refactoring")

# Wrap SDK options with safety layer
options = adapter.wrap_options(
    ClaudeAgentOptions(allowed_tools=["Read", "Write", "Edit", "Bash"])
)

# Use SDK as normal - safety is enforced automatically
async with ClaudeSDKClient(options) as client:
    await client.query("Refactor the authentication module")

Features:

• Permission callbacks that block mutations without checkpoints
• Evidence anchors that track provenance for grounded decisions
• Skill tracking that updates checkpoint state when checkpoint skill is invoked
• Audit trails for compliance and debugging

See docs/integrations/claude_agent_sdk.md for the full integration guide.

Install the Python package:

pip install grounded-agency
# Or with SDK support:
pip install grounded-agency[sdk]

The package includes a compiled Rust extension; installing from a source distribution needs a Rust toolchain (>= 1.86).

Installation

Claude Code Plugin

Add the Synapti marketplace to your Claude Code setup.

# Add the Synapti marketplace (one-time)
claude plugin marketplace add synaptiai/synapti-marketplace

# Install the plugin
claude plugin install agent-capability-standard

What the plugin provides:

Local Development

git clone https://github.com/synaptiai/agent-capability-standard.git
cd agent-capability-standard
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]" -c constraints.txt   # needs Python >= 3.10 and Rust >= 1.86

Validation

# Validate workflow definitions (writes tools/validator_suggestions.json)
python tools/validate_workflows.py

# Validate another catalog; --strict makes warnings fail
python tools/validate_workflows.py --catalog path/to/catalog.yaml --strict

# Generate patch suggestions
python tools/validate_workflows.py --emit-patch

# Run conformance tests
python scripts/run_conformance.py

Design Philosophy

This standard embodies the Grounded Agency approach:

1. Grounded Claims — Every claim is evidence-backed or explicitly inferred
2. Auditable Transforms — Deterministic or documented loss
3. Safety by Construction — Mutation requires checkpoints; actions require plans
4. Composable Atoms — Workflows orchestrate; capabilities do one thing
5. Explicit Contracts — I/O schemas are first-class

License

Apache License 2.0. See LICENSE for details.

Citation

If you use this standard in research, please cite:

@misc{agentcapabilitystandard2026,
  title={Agent Capability Standard: A Framework for Grounded Agency},
  author={Bentes, Daniel},
  year={2026},
  url={https://github.com/synaptiai/agent-capability-standard}
}

Contributing

See CONTRIBUTING.md for guidelines and spec/GOVERNANCE.md for the RFC process.

Status: Candidate Standard v1.1.0 (accepted by RFC-0003 and RFC-0004; v1.0.0, released 2026-01-24, still supported)