FAI learning resource

FAI Plugins & Marketplace

Install themed primitive bundles with one command — plugins across multiple categories.

L10·12 min read·High

What Are Plugins?

A plugin is a themed bundle of FAI primitives — agents, instructions, skills, and hooks — packaged together for a specific use case. Instead of installing 8 individual primitives for an enterprise RAG setup, you install one plugin: npx frootai install enterprise-rag.

Plugins solve the discovery problem. With agents, instructions, and skills in the ecosystem, finding the right combination for your use case is overwhelming. Plugins are curated compositions — tested combinations of primitives that work together and share context through the FAI Protocol.

plugin.json Schema

Every plugin is defined by a plugin.json file in its own folder under plugins/:

plugins/enterprise-rag/plugin.json

{  "name": "enterprise-rag",  "version": "1.0.0",  "description": "Complete RAG primitive bundle for enterprise deployments",  "author": { "name": "FrootAI" },  "license": "MIT",  "category": "play",  "tags": ["rag", "azure", "enterprise", "ai-search"],  "primitives": {    "agents": [      "fai-rag-architect",      "fai-azure-ai-search-expert",      "fai-azure-openai-expert"    ],    "instructions": [      "python-waf",      "bicep-waf",      "rag-best-practices"    ],    "skills": [      "fai-play-initializer",      "deploy-01-enterprise-rag"    ],    "hooks": [      "fai-secrets-scanner",      "fai-cost-guardian"    ]  }}

Field	Required	Validation
name	Yes	Must match folder name, lowercase-hyphen
version	Yes	Valid semver (e.g. 1.0.0)
description	Yes	10+ characters
author.name	Yes	Non-empty string
license	Yes	Valid SPDX identifier
primitives	Yes	At least one primitive reference

Installing Plugins

The frootai install command copies all referenced primitives into your project's .github/ directory structure:

Terminal — Plugin Installation

# Install a specific pluginnpx frootai install enterprise-rag
# Install multiple pluginsnpx frootai install enterprise-rag azure-essentials security-hardened
# Browse available plugins by keywordnpx frootai list azurenpx frootai list ragnpx frootai list devops
# See what a plugin contains before installingnpx frootai info enterprise-rag
# Output:# enterprise-rag v1.0.0# Category: play | License: MIT# Agents:       3 (rag-architect, ai-search-expert, openai-expert)# Instructions: 3 (python-waf, bicep-waf, rag-best-practices)# Skills:       2 (play-initializer, deploy-01-enterprise-rag)# Hooks:        2 (secrets-scanner, cost-guardian)# Total:       10 primitives

Marketplace Overview

The FAI Marketplace hosts plugins containing bundled items across 10 categories:

Category	Plugins	Description	Example
Play	23	Complete primitive sets per solution play	enterprise-rag, multi-agent
MCP	10	MCP server integrations and tool packs	mcp-essentials, mcp-azure
Azure	8	Azure service-specific expertise	azure-ai, azure-infra
Language	8	Language-specific coding standards	python-pro, typescript-pro
AI/ML	6	Machine learning and AI patterns	rag-toolkit, eval-suite
Architecture	4	Architecture patterns and templates	microservices, event-driven
DevOps	5	CI/CD, IaC, and deployment	github-actions, bicep-pro
Testing	3	Testing and evaluation frameworks	ai-eval, load-testing
Meta	4	Plugin tooling and framework-level	fai-essentials, starter-kit
Community	6	Community-contributed plugins	healthcare-ai, fintech-rag

Creating Your Own Plugin

Build a custom plugin in 4 steps:

Terminal — Create a Plugin

# 1. Create the plugin foldermkdir -p plugins/my-custom-plugin
# 2. Create plugin.jsoncat > plugins/my-custom-plugin/plugin.json << 'EOF'{  "name": "my-custom-plugin",  "version": "1.0.0",  "description": "Custom plugin for my team's workflow",  "author": { "name": "Your Name" },  "license": "MIT",  "category": "custom",  "tags": ["team", "custom"],  "primitives": {    "agents": ["fai-code-reviewer"],    "instructions": ["python-waf"],    "skills": ["fai-play-initializer"],    "hooks": ["fai-secrets-scanner"]  }}EOF
# 3. Add a README.mdecho "# My Custom Plugin" > plugins/my-custom-plugin/README.md
# 4. Validatenpm run validate:primitives

Publishing Workflow

To publish a plugin to the FAI Marketplace, your plugin must pass all quality gates:

Schema validation — plugin.json passes the plugin schema check
Primitive resolution — All referenced agents, instructions, skills, and hooks exist in the repo
README required — A README.md must describe the plugin's purpose and contents
Naming convention — Folder name matches plugin.json name, lowercase-hyphen
No secrets — No API keys, tokens, or connection strings in any file
Marketplace generation — Run npm run generate:marketplace to rebuild the marketplace index

Terminal — Publish Steps

# Validate the pluginnpm run validate:primitives
# Regenerate the marketplace indexnode scripts/generate-marketplace.js
# Commit and submit PRgit add plugins/my-custom-plugin/git commit -m "feat: add my-custom-plugin"git push origin feature/my-plugin
# Marketplace auto-rebuilds on merge to main

Quality Gates Per Plugin

Every plugin in the marketplace is validated against these quality criteria:

Gate	Check	Failure Action
Schema	plugin.json matches JSON schema	Block: PR cannot merge
References	All primitives exist in repo	Block: broken references
Naming	Folder = name, lowercase-hyphen	Block: rename required
Secrets	No API keys or tokens in files	Block: security violation
Docs	README.md exists with content	Warn: PR reviewers flagged
Semver	Version is valid semver	Block: invalid version

The Essentials Plugin

The fai-essentials plugin is the recommended starting point. It bundles the most commonly used primitives for enterprise AI development:

npx frootai install fai-essentials

# What you get:# Agents (6):#   fai-architect, fai-code-reviewer,#   fai-rag-architect, fai-azure-openai-expert,#   fai-security-expert, fai-cost-optimizer## Instructions (4):#   python-waf, typescript-waf, bicep-waf, dockerfile-waf## Skills (3):#   fai-play-initializer, fai-eval-runner,#   fai-deploy-to-azure## Hooks (4):#   fai-secrets-scanner, fai-tool-guardian,#   fai-cost-guardian, fai-pii-redactor## Total: 17 primitives installed to .github/

Plugin Lifecycle

Plugins follow a clear lifecycle from creation to marketplace publication:

Author — Create plugin.json + README.md in a named folder
Validate — Run npm run validate:primitives to check schema and references
Materialize — Run node scripts/materialize-plugins.js to resolve all primitive references
Test — Install the plugin locally with npx frootai install my-plugin --local
Publish — Submit PR, pass CI quality gates, merge to main
Discover — Plugin appears on marketplace with search, pagination, and modal preview

Community Plugins

Community-contributed plugins live in the community-plugins/ directory and follow the same schema as first-party plugins. To contribute:

Contributing a Community Plugin

# 1. Fork the FrootAI repo# 2. Create your plugin in community-plugins/mkdir -p community-plugins/my-team-plugin
# 3. Add plugin.json with your primitives# 4. Add README.md with usage guide# 5. Run validation: npm run validate:primitives# 6. Submit PR to main
# Community plugins are reviewed for:# - Schema compliance (plugin.json)# - No secrets or credentials# - Clear documentation# - Valid primitive references

Learning Hub Browse Primitives Back to FrootAI