leo-claude-mktplace/.claude/skills/claude-plugin-developer/references/manifest-schema.md

Plugin Manifest Schema

Complete JSON schema reference for .claude-plugin/plugin.json files.

Required Fields

Basic Information

{
  "name": "string",
  "version": "string",
  "description": "string",
  "author": {
    "name": "string",
    "email": "string (optional)",
    "url": "string (optional)"
  }
}

Field Specifications

name

• Type: string
• Pattern: ^[a-z][a-z0-9-]*$
• Description: Plugin identifier in kebab-case
• Example: "deploy-tools"

version

• Type: string
• Format: Semantic versioning (MAJOR.MINOR.PATCH)
• Example: "1.0.0"

description

• Type: string
• Max length: 200 characters
• Purpose: Brief explanation of plugin functionality

author

• Type: object
• Required: name field
• Optional: email, url fields

Optional Fields

Dependencies

{
  "dependencies": {
    "node": ">=18.0.0",
    "python": ">=3.9",
    "docker": ">=20.0.0"
  }
}

Configuration

{
  "config": {
    "default_shell": "bash",
    "require_safety_check": true,
    "environment": {
      "NODE_ENV": "production",
      "PLUGIN_HOME": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

Permissions

{
  "permissions": {
    "file_access": ["read", "write"],
    "network_access": true,
    "shell_access": true
  }
}

Scripts

{
  "scripts": {
    "install": "npm install",
    "test": "npm test",
    "build": "npm run build"
  }
}

Complete Example

{
  "name": "deploy-automation",
  "version": "2.1.0",
  "description": "Automated deployment tools for cloud platforms",
  "author": {
    "name": "Your Name",
    "email": "plugins@example.com",
    "url": "https://example.com"
  },
  "license": "MIT",
  "keywords": ["deployment", "automation", "cloud", "devops"],
  "homepage": "https://github.com/yourorg/deploy-automation",
  "repository": {
    "type": "git",
    "url": "https://github.com/yourorg/deploy-automation.git"
  },
  "bugs": {
    "url": "https://github.com/yourorg/deploy-automation/issues"
  },
  "dependencies": {
    "node": ">=18.0.0",
    "aws-cli": ">=2.0.0",
    "terraform": ">=1.0.0"
  },
  "config": {
    "default_shell": "bash",
    "require_safety_check": true,
    "timeout": 300,
    "environment": {
      "DEPLOY_ENV": "production",
      "LOG_LEVEL": "info"
    }
  },
  "permissions": {
    "file_access": ["read", "write"],
    "network_access": true,
    "shell_access": true,
    "env_access": ["AWS_*", "DEPLOY_*"]
  },
  "scripts": {
    "install": "./scripts/install.sh",
    "test": "./scripts/test.sh",
    "validate": "./scripts/validate.sh"
  }
}

Validation Rules

Name Validation

• Must start with lowercase letter
• Can contain lowercase letters, numbers, hyphens
• Cannot end with hyphen
• Cannot contain consecutive hyphens
• Length: 2-40 characters

Version Validation

• Must follow semantic versioning
• Format: MAJOR.MINOR.PATCH
• Optional pre-release: -alpha, -beta, -rc.1
• Optional build metadata: +build.123

Description Validation

• Required field
• Maximum 200 characters
• Should describe what the plugin does
• Should include primary use cases

Author Validation

• Name is required
• Email must be valid format if provided
• URL must be valid HTTP(S) URL if provided

Security Considerations

Restricted Fields

These fields require special marketplace approval:

{
  "privileged": true,
  "system_access": true,
  "unrestricted_network": true
}

Environment Variables

• Use ${CLAUDE_PLUGIN_ROOT} for plugin paths
• Never hardcode sensitive data
• Document all required env vars

Path Resolution

• All paths relative to plugin root
• No parent directory traversal (../)
• No absolute paths unless documented

Migration Guide

From v1 to v2

• Add author object (previously string)
• Update dependencies format
• Add permissions field

Legacy Support

• Old manifests auto-upgraded
• Deprecation warnings shown
• Grace period: 6 months