Initial commit

skills/plugin-structure/references/component-patterns.md

@@ -0,0 +1,567 @@
+# Component Organization Patterns
+
+Advanced patterns for organizing plugin components effectively.
+
+## Component Lifecycle
+
+### Discovery Phase
+
+When Claude Code starts:
+
+1. **Scan enabled plugins**: Read `.claude-plugin/plugin.json` for each
+2. **Discover components**: Look in default and custom paths
+3. **Parse definitions**: Read YAML frontmatter and configurations
+4. **Register components**: Make available to Claude Code
+5. **Initialize**: Start MCP servers, register hooks
+
+**Timing**: Component registration happens during Claude Code initialization, not continuously.
+
+### Activation Phase
+
+When components are used:
+
+**Commands**: User types slash command → Claude Code looks up → Executes
+**Agents**: Task arrives → Claude Code evaluates capabilities → Selects agent
+**Skills**: Task context matches description → Claude Code loads skill
+**Hooks**: Event occurs → Claude Code calls matching hooks
+**MCP Servers**: Tool call matches server capability → Forwards to server
+
+## Command Organization Patterns
+
+### Flat Structure
+
+Single directory with all commands:
+
+```
+commands/
+├── build.md
+├── test.md
+├── deploy.md
+├── review.md
+└── docs.md
+```
+
+**When to use**:
+- 5-15 commands total
+- All commands at same abstraction level
+- No clear categorization
+
+**Advantages**:
+- Simple, easy to navigate
+- No configuration needed
+- Fast discovery
+
+### Categorized Structure
+
+Multiple directories for different command types:
+
+```
+commands/              # Core commands
+├── build.md
+└── test.md
+
+admin-commands/        # Administrative
+├── configure.md
+└── manage.md
+
+workflow-commands/     # Workflow automation
+├── review.md
+└── deploy.md
+```
+
+**Manifest configuration**:
+```json
+{
+  "commands": [
+    "./commands",
+    "./admin-commands",
+    "./workflow-commands"
+  ]
+}
+```
+
+**When to use**:
+- 15+ commands
+- Clear functional categories
+- Different permission levels
+
+**Advantages**:
+- Organized by purpose
+- Easier to maintain
+- Can restrict access by directory
+
+### Hierarchical Structure
+
+Nested organization for complex plugins:
+
+```
+commands/
+├── ci/
+│   ├── build.md
+│   ├── test.md
+│   └── lint.md
+├── deployment/
+│   ├── staging.md
+│   └── production.md
+└── management/
+    ├── config.md
+    └── status.md
+```
+
+**Note**: Claude Code doesn't support nested command discovery automatically. Use custom paths:
+
+```json
+{
+  "commands": [
+    "./commands/ci",
+    "./commands/deployment",
+    "./commands/management"
+  ]
+}
+```
+
+**When to use**:
+- 20+ commands
+- Multi-level categorization
+- Complex workflows
+
+**Advantages**:
+- Maximum organization
+- Clear boundaries
+- Scalable structure
+
+## Agent Organization Patterns
+
+### Role-Based Organization
+
+Organize agents by their primary role:
+
+```
+agents/
+├── code-reviewer.md        # Reviews code
+├── test-generator.md       # Generates tests
+├── documentation-writer.md # Writes docs
+└── refactorer.md          # Refactors code
+```
+
+**When to use**:
+- Agents have distinct, non-overlapping roles
+- Users invoke agents manually
+- Clear agent responsibilities
+
+### Capability-Based Organization
+
+Organize by specific capabilities:
+
+```
+agents/
+├── python-expert.md        # Python-specific
+├── typescript-expert.md    # TypeScript-specific
+├── api-specialist.md       # API design
+└── database-specialist.md  # Database work
+```
+
+**When to use**:
+- Technology-specific agents
+- Domain expertise focus
+- Automatic agent selection
+
+### Workflow-Based Organization
+
+Organize by workflow stage:
+
+```
+agents/
+├── planning-agent.md      # Planning phase
+├── implementation-agent.md # Coding phase
+├── testing-agent.md       # Testing phase
+└── deployment-agent.md    # Deployment phase
+```
+
+**When to use**:
+- Sequential workflows
+- Stage-specific expertise
+- Pipeline automation
+
+## Skill Organization Patterns
+
+### Topic-Based Organization
+
+Each skill covers a specific topic:
+
+```
+skills/
+├── api-design/
+│   └── SKILL.md
+├── error-handling/
+│   └── SKILL.md
+├── testing-strategies/
+│   └── SKILL.md
+└── performance-optimization/
+    └── SKILL.md
+```
+
+**When to use**:
+- Knowledge-based skills
+- Educational or reference content
+- Broad applicability
+
+### Tool-Based Organization
+
+Skills for specific tools or technologies:
+
+```
+skills/
+├── docker/
+│   ├── SKILL.md
+│   └── references/
+│       └── dockerfile-best-practices.md
+├── kubernetes/
+│   ├── SKILL.md
+│   └── examples/
+│       └── deployment.yaml
+└── terraform/
+    ├── SKILL.md
+    └── scripts/
+        └── validate-config.sh
+```
+
+**When to use**:
+- Tool-specific expertise
+- Complex tool configurations
+- Tool best practices
+
+### Workflow-Based Organization
+
+Skills for complete workflows:
+
+```
+skills/
+├── code-review-workflow/
+│   ├── SKILL.md
+│   └── references/
+│       ├── checklist.md
+│       └── standards.md
+├── deployment-workflow/
+│   ├── SKILL.md
+│   └── scripts/
+│       ├── pre-deploy.sh
+│       └── post-deploy.sh
+└── testing-workflow/
+    ├── SKILL.md
+    └── examples/
+        └── test-structure.md
+```
+
+**When to use**:
+- Multi-step processes
+- Company-specific workflows
+- Process automation
+
+### Skill with Rich Resources
+
+Comprehensive skill with all resource types:
+
+```
+skills/
+└── api-testing/
+    ├── SKILL.md              # Core skill (1500 words)
+    ├── references/
+    │   ├── rest-api-guide.md
+    │   ├── graphql-guide.md
+    │   └── authentication.md
+    ├── examples/
+    │   ├── basic-test.js
+    │   ├── authenticated-test.js
+    │   └── integration-test.js
+    ├── scripts/
+    │   ├── run-tests.sh
+    │   └── generate-report.py
+    └── assets/
+        └── test-template.json
+```
+
+**Resource usage**:
+- **SKILL.md**: Overview and when to use resources
+- **references/**: Detailed guides (loaded as needed)
+- **examples/**: Copy-paste code samples
+- **scripts/**: Executable test runners
+- **assets/**: Templates and configurations
+
+## Hook Organization Patterns
+
+### Monolithic Configuration
+
+Single hooks.json with all hooks:
+
+```
+hooks/
+├── hooks.json     # All hook definitions
+└── scripts/
+    ├── validate-write.sh
+    ├── validate-bash.sh
+    └── load-context.sh
+```
+
+**hooks.json**:
+```json
+{
+  "PreToolUse": [...],
+  "PostToolUse": [...],
+  "Stop": [...],
+  "SessionStart": [...]
+}
+```
+
+**When to use**:
+- 5-10 hooks total
+- Simple hook logic
+- Centralized configuration
+
+### Event-Based Organization
+
+Separate files per event type:
+
+```
+hooks/
+├── hooks.json              # Combines all
+├── pre-tool-use.json      # PreToolUse hooks
+├── post-tool-use.json     # PostToolUse hooks
+├── stop.json              # Stop hooks
+└── scripts/
+    ├── validate/
+    │   ├── write.sh
+    │   └── bash.sh
+    └── context/
+        └── load.sh
+```
+
+**hooks.json** (combines):
+```json
+{
+  "PreToolUse": ${file:./pre-tool-use.json},
+  "PostToolUse": ${file:./post-tool-use.json},
+  "Stop": ${file:./stop.json}
+}
+```
+
+**Note**: Use build script to combine files, Claude Code doesn't support file references.
+
+**When to use**:
+- 10+ hooks
+- Different teams managing different events
+- Complex hook configurations
+
+### Purpose-Based Organization
+
+Group by functional purpose:
+
+```
+hooks/
+├── hooks.json
+└── scripts/
+    ├── security/
+    │   ├── validate-paths.sh
+    │   ├── check-credentials.sh
+    │   └── scan-malware.sh
+    ├── quality/
+    │   ├── lint-code.sh
+    │   ├── check-tests.sh
+    │   └── verify-docs.sh
+    └── workflow/
+        ├── notify-team.sh
+        └── update-status.sh
+```
+
+**When to use**:
+- Many hook scripts
+- Clear functional boundaries
+- Team specialization
+
+## Script Organization Patterns
+
+### Flat Scripts
+
+All scripts in single directory:
+
+```
+scripts/
+├── build.sh
+├── test.py
+├── deploy.sh
+├── validate.js
+└── report.py
+```
+
+**When to use**:
+- 5-10 scripts
+- All scripts related
+- Simple plugin
+
+### Categorized Scripts
+
+Group by purpose:
+
+```
+scripts/
+├── build/
+│   ├── compile.sh
+│   └── package.sh
+├── test/
+│   ├── run-unit.sh
+│   └── run-integration.sh
+├── deploy/
+│   ├── staging.sh
+│   └── production.sh
+└── utils/
+    ├── log.sh
+    └── notify.sh
+```
+
+**When to use**:
+- 10+ scripts
+- Clear categories
+- Reusable utilities
+
+### Language-Based Organization
+
+Group by programming language:
+
+```
+scripts/
+├── bash/
+│   ├── build.sh
+│   └── deploy.sh
+├── python/
+│   ├── analyze.py
+│   └── report.py
+└── javascript/
+    ├── bundle.js
+    └── optimize.js
+```
+
+**When to use**:
+- Multi-language scripts
+- Different runtime requirements
+- Language-specific dependencies
+
+## Cross-Component Patterns
+
+### Shared Resources
+
+Components sharing common resources:
+
+```
+plugin/
+├── commands/
+│   ├── test.md        # Uses lib/test-utils.sh
+│   └── deploy.md      # Uses lib/deploy-utils.sh
+├── agents/
+│   └── tester.md      # References lib/test-utils.sh
+├── hooks/
+│   └── scripts/
+│       └── pre-test.sh # Sources lib/test-utils.sh
+└── lib/
+    ├── test-utils.sh
+    └── deploy-utils.sh
+```
+
+**Usage in components**:
+```bash
+#!/bin/bash
+source "${CLAUDE_PLUGIN_ROOT}/lib/test-utils.sh"
+run_tests
+```
+
+**Benefits**:
+- Code reuse
+- Consistent behavior
+- Easier maintenance
+
+### Layered Architecture
+
+Separate concerns into layers:
+
+```
+plugin/
+├── commands/          # User interface layer
+├── agents/            # Orchestration layer
+├── skills/            # Knowledge layer
+└── lib/
+    ├── core/         # Core business logic
+    ├── integrations/ # External services
+    └── utils/        # Helper functions
+```
+
+**When to use**:
+- Large plugins (100+ files)
+- Multiple developers
+- Clear separation of concerns
+
+### Plugin Within Plugin
+
+Nested plugin structure:
+
+```
+plugin/
+├── .claude-plugin/
+│   └── plugin.json
+├── core/              # Core functionality
+│   ├── commands/
+│   └── agents/
+└── extensions/        # Optional extensions
+    ├── extension-a/
+    │   ├── commands/
+    │   └── agents/
+    └── extension-b/
+        ├── commands/
+        └── agents/
+```
+
+**Manifest**:
+```json
+{
+  "commands": [
+    "./core/commands",
+    "./extensions/extension-a/commands",
+    "./extensions/extension-b/commands"
+  ]
+}
+```
+
+**When to use**:
+- Modular functionality
+- Optional features
+- Plugin families
+
+## Best Practices
+
+### Naming
+
+1. **Consistent naming**: Match file names to component purpose
+2. **Descriptive names**: Indicate what component does
+3. **Avoid abbreviations**: Use full words for clarity
+
+### Organization
+
+1. **Start simple**: Use flat structure, reorganize when needed
+2. **Group related items**: Keep related components together
+3. **Separate concerns**: Don't mix unrelated functionality
+
+### Scalability
+
+1. **Plan for growth**: Choose structure that scales
+2. **Refactor early**: Reorganize before it becomes painful
+3. **Document structure**: Explain organization in README
+
+### Maintainability
+
+1. **Consistent patterns**: Use same structure throughout
+2. **Minimize nesting**: Keep directory depth manageable
+3. **Use conventions**: Follow community standards
+
+### Performance
+
+1. **Avoid deep nesting**: Impacts discovery time
+2. **Minimize custom paths**: Use defaults when possible
+3. **Keep configurations small**: Large configs slow loading

skills/plugin-structure/references/manifest-reference.md

@@ -0,0 +1,552 @@
+# Plugin Manifest Reference
+
+Complete reference for `plugin.json` configuration.
+
+## File Location
+
+**Required path**: `.claude-plugin/plugin.json`
+
+The manifest MUST be in the `.claude-plugin/` directory at the plugin root. Claude Code will not recognize plugins without this file in the correct location.
+
+## Complete Field Reference
+
+### Core Fields
+
+#### name (required)
+
+**Type**: String
+**Format**: kebab-case
+**Example**: `"test-automation-suite"`
+
+The unique identifier for the plugin. Used for:
+- Plugin identification in Claude Code
+- Conflict detection with other plugins
+- Command namespacing (optional)
+
+**Requirements**:
+- Must be unique across all installed plugins
+- Use only lowercase letters, numbers, and hyphens
+- No spaces or special characters
+- Start with a letter
+- End with a letter or number
+
+**Validation**:
+```javascript
+/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/
+```
+
+**Examples**:
+- ✅ Good: `api-tester`, `code-review`, `git-workflow-automation`
+- ❌ Bad: `API Tester`, `code_review`, `-git-workflow`, `test-`
+
+#### version
+
+**Type**: String
+**Format**: Semantic versioning (MAJOR.MINOR.PATCH)
+**Example**: `"2.1.0"`
+**Default**: `"0.1.0"` if not specified
+
+Semantic versioning guidelines:
+- **MAJOR**: Incompatible API changes, breaking changes
+- **MINOR**: New functionality, backward-compatible
+- **PATCH**: Bug fixes, backward-compatible
+
+**Pre-release versions**:
+- `"1.0.0-alpha.1"` - Alpha release
+- `"1.0.0-beta.2"` - Beta release
+- `"1.0.0-rc.1"` - Release candidate
+
+**Examples**:
+- `"0.1.0"` - Initial development
+- `"1.0.0"` - First stable release
+- `"1.2.3"` - Patch update to 1.2
+- `"2.0.0"` - Major version with breaking changes
+
+#### description
+
+**Type**: String
+**Length**: 50-200 characters recommended
+**Example**: `"Automates code review workflows with style checks and automated feedback"`
+
+Brief explanation of plugin purpose and functionality.
+
+**Best practices**:
+- Focus on what the plugin does, not how
+- Use active voice
+- Mention key features or benefits
+- Keep under 200 characters for marketplace display
+
+**Examples**:
+- ✅ "Generates comprehensive test suites from code analysis and coverage reports"
+- ✅ "Integrates with Jira for automatic issue tracking and sprint management"
+- ❌ "A plugin that helps you do testing stuff"
+- ❌ "This is a very long description that goes on and on about every single feature..."
+
+### Metadata Fields
+
+#### author
+
+**Type**: Object
+**Fields**: name (required), email (optional), url (optional)
+
+```json
+{
+  "author": {
+    "name": "Jane Developer",
+    "email": "jane@example.com",
+    "url": "https://janedeveloper.com"
+  }
+}
+```
+
+**Alternative format** (string only):
+```json
+{
+  "author": "Jane Developer <jane@example.com> (https://janedeveloper.com)"
+}
+```
+
+**Use cases**:
+- Credit and attribution
+- Contact for support or questions
+- Marketplace display
+- Community recognition
+
+#### homepage
+
+**Type**: String (URL)
+**Example**: `"https://docs.example.com/plugins/my-plugin"`
+
+Link to plugin documentation or landing page.
+
+**Should point to**:
+- Plugin documentation site
+- Project homepage
+- Detailed usage guide
+- Installation instructions
+
+**Not for**:
+- Source code (use `repository` field)
+- Issue tracker (include in documentation)
+- Personal websites (use `author.url`)
+
+#### repository
+
+**Type**: String (URL) or Object
+**Example**: `"https://github.com/user/plugin-name"`
+
+Source code repository location.
+
+**String format**:
+```json
+{
+  "repository": "https://github.com/user/plugin-name"
+}
+```
+
+**Object format** (detailed):
+```json
+{
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/user/plugin-name.git",
+    "directory": "packages/plugin-name"
+  }
+}
+```
+
+**Use cases**:
+- Source code access
+- Issue reporting
+- Community contributions
+- Transparency and trust
+
+#### license
+
+**Type**: String
+**Format**: SPDX identifier
+**Example**: `"MIT"`
+
+Software license identifier.
+
+**Common licenses**:
+- `"MIT"` - Permissive, popular choice
+- `"Apache-2.0"` - Permissive with patent grant
+- `"GPL-3.0"` - Copyleft
+- `"BSD-3-Clause"` - Permissive
+- `"ISC"` - Permissive, similar to MIT
+- `"UNLICENSED"` - Proprietary, not open source
+
+**Full list**: https://spdx.org/licenses/
+
+**Multiple licenses**:
+```json
+{
+  "license": "(MIT OR Apache-2.0)"
+}
+```
+
+#### keywords
+
+**Type**: Array of strings
+**Example**: `["testing", "automation", "ci-cd", "quality-assurance"]`
+
+Tags for plugin discovery and categorization.
+
+**Best practices**:
+- Use 5-10 keywords
+- Include functionality categories
+- Add technology names
+- Use common search terms
+- Avoid duplicating plugin name
+
+**Categories to consider**:
+- Functionality: `testing`, `debugging`, `documentation`, `deployment`
+- Technologies: `typescript`, `python`, `docker`, `aws`
+- Workflows: `ci-cd`, `code-review`, `git-workflow`
+- Domains: `web-development`, `data-science`, `devops`
+
+### Component Path Fields
+
+#### commands
+
+**Type**: String or Array of strings
+**Default**: `["./commands"]`
+**Example**: `"./cli-commands"`
+
+Additional directories or files containing command definitions.
+
+**Single path**:
+```json
+{
+  "commands": "./custom-commands"
+}
+```
+
+**Multiple paths**:
+```json
+{
+  "commands": [
+    "./commands",
+    "./admin-commands",
+    "./experimental-commands"
+  ]
+}
+```
+
+**Behavior**: Supplements default `commands/` directory (does not replace)
+
+**Use cases**:
+- Organizing commands by category
+- Separating stable from experimental commands
+- Loading commands from shared locations
+
+#### agents
+
+**Type**: String or Array of strings
+**Default**: `["./agents"]`
+**Example**: `"./specialized-agents"`
+
+Additional directories or files containing agent definitions.
+
+**Format**: Same as `commands` field
+
+**Use cases**:
+- Grouping agents by specialization
+- Separating general-purpose from task-specific agents
+- Loading agents from plugin dependencies
+
+#### hooks
+
+**Type**: String (path to JSON file) or Object (inline configuration)
+**Default**: `"./hooks/hooks.json"`
+
+Hook configuration location or inline definition.
+
+**File path**:
+```json
+{
+  "hooks": "./config/hooks.json"
+}
+```
+
+**Inline configuration**:
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Use cases**:
+- Simple plugins: Inline configuration (< 50 lines)
+- Complex plugins: External JSON file
+- Multiple hook sets: Separate files for different contexts
+
+#### mcpServers
+
+**Type**: String (path to JSON file) or Object (inline configuration)
+**Default**: `./.mcp.json`
+
+MCP server configuration location or inline definition.
+
+**File path**:
+```json
+{
+  "mcpServers": "./.mcp.json"
+}
+```
+
+**Inline configuration**:
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/github-mcp.js"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+**Use cases**:
+- Simple plugins: Single inline server (< 20 lines)
+- Complex plugins: External `.mcp.json` file
+- Multiple servers: Always use external file
+
+## Path Resolution
+
+### Relative Path Rules
+
+All paths in component fields must follow these rules:
+
+1. **Must be relative**: No absolute paths
+2. **Must start with `./`**: Indicates relative to plugin root
+3. **Cannot use `../`**: No parent directory navigation
+4. **Forward slashes only**: Even on Windows
+
+**Examples**:
+- ✅ `"./commands"`
+- ✅ `"./src/commands"`
+- ✅ `"./configs/hooks.json"`
+- ❌ `"/Users/name/plugin/commands"`
+- ❌ `"commands"` (missing `./`)
+- ❌ `"../shared/commands"`
+- ❌ `".\\commands"` (backslash)
+
+### Resolution Order
+
+When Claude Code loads components:
+
+1. **Default directories**: Scans standard locations first
+   - `./commands/`
+   - `./agents/`
+   - `./skills/`
+   - `./hooks/hooks.json`
+   - `./.mcp.json`
+
+2. **Custom paths**: Scans paths specified in manifest
+   - Paths from `commands` field
+   - Paths from `agents` field
+   - Files from `hooks` and `mcpServers` fields
+
+3. **Merge behavior**: Components from all locations load
+   - No overwriting
+   - All discovered components register
+   - Name conflicts cause errors
+
+## Validation
+
+### Manifest Validation
+
+Claude Code validates the manifest on plugin load:
+
+**Syntax validation**:
+- Valid JSON format
+- No syntax errors
+- Correct field types
+
+**Field validation**:
+- `name` field present and valid format
+- `version` follows semantic versioning (if present)
+- Paths are relative with `./` prefix
+- URLs are valid (if present)
+
+**Component validation**:
+- Referenced paths exist
+- Hook and MCP configurations are valid
+- No circular dependencies
+
+### Common Validation Errors
+
+**Invalid name format**:
+```json
+{
+  "name": "My Plugin"  // ❌ Contains spaces
+}
+```
+Fix: Use kebab-case
+```json
+{
+  "name": "my-plugin"  // ✅
+}
+```
+
+**Absolute path**:
+```json
+{
+  "commands": "/Users/name/commands"  // ❌ Absolute path
+}
+```
+Fix: Use relative path
+```json
+{
+  "commands": "./commands"  // ✅
+}
+```
+
+**Missing ./ prefix**:
+```json
+{
+  "hooks": "hooks/hooks.json"  // ❌ No ./
+}
+```
+Fix: Add ./ prefix
+```json
+{
+  "hooks": "./hooks/hooks.json"  // ✅
+}
+```
+
+**Invalid version**:
+```json
+{
+  "version": "1.0"  // ❌ Not semantic versioning
+}
+```
+Fix: Use MAJOR.MINOR.PATCH
+```json
+{
+  "version": "1.0.0"  // ✅
+}
+```
+
+## Minimal vs. Complete Examples
+
+### Minimal Plugin
+
+Bare minimum for a working plugin:
+
+```json
+{
+  "name": "hello-world"
+}
+```
+
+Relies entirely on default directory discovery.
+
+### Recommended Plugin
+
+Good metadata for distribution:
+
+```json
+{
+  "name": "code-review-assistant",
+  "version": "1.0.0",
+  "description": "Automates code review with style checks and suggestions",
+  "author": {
+    "name": "Jane Developer",
+    "email": "jane@example.com"
+  },
+  "homepage": "https://docs.example.com/code-review",
+  "repository": "https://github.com/janedev/code-review-assistant",
+  "license": "MIT",
+  "keywords": ["code-review", "automation", "quality", "ci-cd"]
+}
+```
+
+### Complete Plugin
+
+Full configuration with all features:
+
+```json
+{
+  "name": "enterprise-devops",
+  "version": "2.3.1",
+  "description": "Comprehensive DevOps automation for enterprise CI/CD pipelines",
+  "author": {
+    "name": "DevOps Team",
+    "email": "devops@company.com",
+    "url": "https://company.com/devops"
+  },
+  "homepage": "https://docs.company.com/plugins/devops",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/company/devops-plugin.git"
+  },
+  "license": "Apache-2.0",
+  "keywords": [
+    "devops",
+    "ci-cd",
+    "automation",
+    "kubernetes",
+    "docker",
+    "deployment"
+  ],
+  "commands": [
+    "./commands",
+    "./admin-commands"
+  ],
+  "agents": "./specialized-agents",
+  "hooks": "./config/hooks.json",
+  "mcpServers": "./.mcp.json"
+}
+```
+
+## Best Practices
+
+### Metadata
+
+1. **Always include version**: Track changes and updates
+2. **Write clear descriptions**: Help users understand plugin purpose
+3. **Provide contact information**: Enable user support
+4. **Link to documentation**: Reduce support burden
+5. **Choose appropriate license**: Match project goals
+
+### Paths
+
+1. **Use defaults when possible**: Minimize configuration
+2. **Organize logically**: Group related components
+3. **Document custom paths**: Explain why non-standard layout used
+4. **Test path resolution**: Verify on multiple systems
+
+### Maintenance
+
+1. **Bump version on changes**: Follow semantic versioning
+2. **Update keywords**: Reflect new functionality
+3. **Keep description current**: Match actual capabilities
+4. **Maintain changelog**: Track version history
+5. **Update repository links**: Keep URLs current
+
+### Distribution
+
+1. **Complete metadata before publishing**: All fields filled
+2. **Test on clean install**: Verify plugin works without dev environment
+3. **Validate manifest**: Use validation tools
+4. **Include README**: Document installation and usage
+5. **Specify license file**: Include LICENSE file in plugin root