Understanding the FAI Protocol — The package.json for AI
Every Node.js project has a package.json. Every Docker image has a Dockerfile. Every Terraform project has a main.tf. But what does an AI project have?
Today, the answer is: nothing standardized. Your agents live in one folder, prompts in another, guardrails in a config file, evaluation pipelines in a notebook, and the wiring between them lives in tribal knowledge.
The FAI Protocol changes that.
What is fai-manifest.json?
fai-manifest.json is a single file that declares everything about your AI solution:
``json
{
"play": "01-enterprise-rag",
"version": "2.0.0",
"context": {
"knowledge": ["rag-patterns.md", "azure-best-practices.md"],
"waf": ["reliability", "security", "cost-optimization"]
},
"primitives": {
"agents": ["./agents/builder.agent.md", "./agents/reviewer.agent.md"],
"skills": ["./skills/index-documents/SKILL.md"],
"instructions": ["./instructions/rag-quality.instructions.md"],
"hooks": ["./hooks/guardrails.json"]
},
"guardrails": {
"groundedness": 0.8,
"relevance": 0.75,
"safety": 0.95
},
"infrastructure": {
"provider": "azure",
"services": ["azure-openai", "azure-ai-search", "cosmos-db"]
}
}
`
Why This Matters
1. Discoverability
When a new developer joins, they read fai-manifest.json and instantly understand: what agents exist, what skills they use, what quality thresholds are enforced, and what infrastructure is required.2. Composability
Primitives are standalone but auto-wire when used inside a play. An agent file works in any project. But inside a play with a manifest, it gains context — it knows about the domain, the guardrails, and the other agents it can hand off to.3. Validation
Run npm run validate:primitives and the manifest tells you if your agent references a skill that doesn't exist, if your guardrail thresholds are within range, or if your WAF alignment is incomplete.4. Distribution
Package your play as a plugin (plugin.json), publish to the FAI Marketplace, and anyone can install it: npx frootai install enterprise-rag. The manifest handles all the wiring.The Primitive Types
| Type | File Pattern | Purpose |
|------|-------------|---------|
| Agents |
.agent.md | Behavioral instructions for AI assistants |
| Skills | SKILL.md in folders | Multi-step procedures agents can execute |
| Instructions | .instructions.md | Domain knowledge applied via applyTo globs |
| Hooks | hooks.json | Event-driven automation (SessionStart, etc.) |
| Workflows | .yml | Multi-step CI/CD-style pipelines |
| Plugins | plugin.json` | Bundled distribution packages |What's Next
The FAI Protocol is version 1.0 — we're actively iterating based on community feedback. Key areas:
- FAI Engine — Runtime that reads manifests and auto-configures AI environments - FAI Factory — CI/CD pipeline for validating, testing, and publishing primitives - Cross-platform support — Works with VS Code, Cursor, Windsurf, and any MCP-compatible tool
Read the full spec at docs.frootai.dev/concepts/fai-protocol