diff options
Diffstat (limited to '')
| -rw-r--r-- | .agents/skills/plugin-structure/references/component-patterns.md | 567 | ||||
| -rw-r--r-- | .agents/skills/plugin-structure/references/manifest-reference.md | 552 |
2 files changed, 1119 insertions, 0 deletions
diff --git a/.agents/skills/plugin-structure/references/component-patterns.md b/.agents/skills/plugin-structure/references/component-patterns.md new file mode 100644 index 0000000..a58a7b4 --- /dev/null +++ b/.agents/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 diff --git a/.agents/skills/plugin-structure/references/manifest-reference.md b/.agents/skills/plugin-structure/references/manifest-reference.md new file mode 100644 index 0000000..40c9c2f --- /dev/null +++ b/.agents/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 |