Package a Plugin

Bundle related primitives into a distributable plugin with marketplace metadata, validation, and CI/CD publishing.

Prerequisites

Node.js 22+
FrootAI repo cloned
Existing primitives to bundle

Step 1: Create the Plugin Folder


mkdir -p plugins/document-intelligence


plugins/document-intelligence/
├── plugin.json          # Required — plugin manifest
├── README.md            # Required — documentation
├── CHANGELOG.md         # Recommended — version history
└── assets/              # Optional — icons

Step 2: Create plugin.json

plugins/document-intelligence/plugin.json


{
  "name": "document-intelligence",
  "description": "End-to-end document processing with Azure AI Document Intelligence, OCR, and PII detection.",
  "version": "1.0.0",
  "author": {
    "name": "FrootAI Contributors",
    "url": "https://frootai.dev"
  },
  "license": "MIT",
  "keywords": ["document-intelligence", "ocr", "extraction", "pii-detection"],
  "agents": [
    "../../agents/fai-document-processor.agent.md",
    "../../agents/fai-extraction-reviewer.agent.md"
  ],
  "instructions": [
    "../../instructions/python-waf.instructions.md"
  ],
  "skills": [
    "../../skills/fai-document-indexer/"
  ],
  "hooks": [
    "../../hooks/fai-pii-redactor/"
  ],
  "plays": ["06", "15"]
}

Step 3: Required Fields

Field	Type	Rules
`name`	string	Lowercase-hyphen, 3–64 chars, must match folder
`description`	string	10–500 characters
`version`	string	Semver: `MAJOR.MINOR.PATCH`
`author.name`	string	Required
`license`	string	SPDX identifier (`MIT`, `Apache-2.0`)

Step 4: Write the README

plugins/document-intelligence/README.md


# Document Intelligence Plugin
 
End-to-end document processing for enterprise workloads.
 
## What's Included
| Primitive | Name | Purpose |
|-----------|------|---------|
| Agent | fai-document-processor | Multi-format document ingestion |
| Agent | fai-extraction-reviewer | Validates extracted data |
| Instruction | python-waf | WAF-aligned Python patterns |
| Skill | fai-document-indexer | Index documents into AI Search |
| Hook | fai-pii-redactor | Redact PII before storage |

Step 5: Validate


npm run validate:primitives

Fix common errors:

Error	Fix
`name must match pattern`	Use only lowercase, numbers, hyphens
`description too short`	Write at least 10 characters
`author.name is required`	Add `"author": { "name": "..." }`
`agents[0] path not found`	Ensure referenced file exists

Step 6: Regenerate Marketplace


node scripts/generate-marketplace.js
 
# Verify
node -e "
  const m = require('./marketplace.json');
  const p = m.plugins.find(p => p.name === 'document-intelligence');
  console.log(p ? '✅ Found: ' + p.name : '❌ Not found');
"

Step 7: Versioning

Change Type	Bump	Example
Bug fix in agent prompt	PATCH	`1.0.0` → `1.0.1`
Add new instruction	MINOR	`1.0.1` → `1.1.0`
Remove agent or rename paths	MAJOR	`1.1.0` → `2.0.0`

Step 8: Reference in a Play

fai-manifest.json


{
  "primitives": {
    "plugins": ["../../plugins/document-intelligence/"]
  }
}

Best Practices

One plugin per domain — bundle related primitives, not everything
Always include a README — the marketplace displays it as the detail page
Reference real primitives — broken paths fail validation
Version on every change — never ship without bumping
Keep CHANGELOG updated — consumers need to know what changed