FDAA CLI

File-Driven Agent Architecture — Reference Implementation

Build, verify, sign, and publish AI agent skills with cryptographic proof.

📄 Whitepaper | 🔐 ACC Spec | 🏢 Substr8 Labs

Installation

pip install fdaa

Requires Python 3.10+

Quick Start

For Skill Developers

1. Create a signing key (one-time)

fdaa keygen mykey

2. Write your skill

my-skill/
├── SKILL.md          # What it does
├── scripts/
│   └── run.py        # The code
└── references/       # Supporting docs (optional)

3. Quick check (instant feedback)

fdaa check ./my-skill

4. Full verification + signing

fdaa pipeline ./my-skill --key mykey

5. Publish

fdaa publish ./my-skill --name @you/my-skill --version 1.0.0

For Skill Users

Install a verified skill

fdaa install @someone/cool-skill

Signature is verified automatically. Tampered skills are rejected.

---

Commands

Verification Pipeline

Command	Description
fdaa check <path>	Fast pattern check (~1s)
fdaa verify <path>	Guard Model security scan
fdaa sandbox <path>	Run in isolated container
fdaa pipeline <path>	Full Tier 1-4 verification

Signing & Keys

Command	Description
fdaa keygen <name>	Generate Ed25519 key pair
fdaa sign <path>	Sign a skill

Registry

Command	Description
fdaa install <spec>	Install a skill
fdaa publish <path>	Publish to registry
fdaa search <query>	Search skills
fdaa list-skills	List installed skills

Tracing (OpenTelemetry)

Command	Description
fdaa traced-pipeline <path>	Run pipeline with tracing
fdaa trace <id>	View a trace
fdaa trace --list	List recent traces

Agent Workspaces

Command	Description
fdaa init <name>	Create agent workspace
fdaa chat <workspace>	Chat with agent
fdaa files <workspace>	List files
fdaa read <workspace> <file>	Read file
fdaa export <workspace>	Export as zip
fdaa import <zip>	Import from zip

---

Verification Tiers

FDAA uses defense-in-depth with 4 verification tiers:

Tier	What It Does	Speed
1. Fast Pass	Pattern matching, known signatures	~100ms
2. Guard Model	LLM semantic analysis	~3-5s
3. Sandbox	Isolated execution, behavior monitoring	~1-2s
4. Registry	Cryptographic signing, hash verification	~100ms

# Run all tiers
fdaa pipeline ./my-skill --key mykey

# Skip expensive steps during development
fdaa pipeline ./my-skill --skip-sandbox --skip-sign

---

Tracing & Observability

Every pipeline run can be traced with OpenTelemetry:

fdaa traced-pipeline ./my-skill

# Output:
# Trace ID: f8112ae3...
# View with: fdaa trace f8112ae3

View trace details:

fdaa trace f8112ae3

# Shows:
# - Duration per tier
# - LLM tokens & cost
# - Sandbox metrics
# - Verification results

Export to Jaeger:

fdaa traced-pipeline ./my-skill --jaeger-host localhost

---

Skill Format

A minimal skill:

my-skill/
├── SKILL.md
└── scripts/
    └── run.py

SKILL.md

---
name: my-skill
description: Does something useful
version: 1.0.0
---

# My Skill

Use this skill to do X.

## Usage

\`\`\`bash
my-skill --input foo
\`\`\`

After signing, a MANIFEST.json is added:

{
  "name": "@you/my-skill",
  "version": "1.0.0",
  "sha256": "7a3f2b...",
  "signature": "Kx8mQ2...",
  "publicKey": "a1b2c3...",
  "signedAt": "2026-02-18T00:00:00Z"
}

---

W^X Security

FDAA enforces Write XOR Execute:

File	Agent Can Modify
SKILL.md	❌ No
SOUL.md	❌ No
IDENTITY.md	❌ No
MEMORY.md	✅ Yes
scripts/*	❌ No

Agents cannot modify their own identity or capabilities.

---

Environment Variables

# LLM Providers (one required for verify/pipeline)
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...

# Optional
export FDAA_REGISTRY_URL=https://registry.fdaa.dev
export JAEGER_AGENT_HOST=localhost

---

API Server

For web deployments:

pip install fdaa[server]

export MONGODB_URI="mongodb+srv://..."
export ANTHROPIC_API_KEY="sk-ant-..."

uvicorn fdaa.server:app --host 0.0.0.0 --port 8000

See API docs for endpoints.

---

Examples

Verify a skill before installing:

fdaa verify ./untrusted-skill --provider anthropic

Create and publish a skill:

fdaa keygen mykey
mkdir my-skill && cd my-skill
echo "# My Skill" > SKILL.md
fdaa pipeline . --key mykey
fdaa publish . --name @me/my-skill --version 1.0.0

Debug a failing verification:

fdaa traced-pipeline ./my-skill
fdaa trace <trace-id>

Install from GitHub (Phase 0 registry):

fdaa install github:substr8-labs/skill-code-review

---

License

MIT

---

Built by Substr8 Labs

Research: FDAA Whitepaper | ACC Spec

Registry (Phase 0)

Skills live on GitHub. Install directly:

fdaa install github:Substr8-Labs/skill-hello-world

Browse available skills: https://github.com/Substr8-Labs/fdaa-registry

DCT — Delegation Capability Tokens

Cryptographic permission delegation between agents.

# Create a token granting specific permissions
fdaa dct create "file:read:/home/user/*" "api:call:weather" --expires 60

# Verify a token
fdaa dct verify ./token.json

# Check if a permission is granted
fdaa dct check ./token.json "file:read:/home/user/doc.txt"

# Delegate a subset to another agent (monotonic attenuation)
fdaa dct attenuate ./parent.json "file:read:/home/user/docs/*" --expires 30

Key properties:

• Ed25519 signatures (tamper-proof)
• Time-bounded (expires)
• Monotonic attenuation (can only delegate subsets, never escalate)
• Delegation chains tracked (audit trail)