Initial commit

2025-11-29 17:57:04 +08:00
commit e6ff08128c
9 changed files with 1791 additions and 0 deletions
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,15 @@
+{
+  "name": "specweave-plugin-dev",
+  "description": "Claude Code plugin development tools including plugin creation, testing, marketplace publishing, skill authoring, agent development, and CLI command integration.",
+  "version": "0.24.0",
+  "author": {
+    "name": "Anton Abyzov",
+    "email": "anton.abyzov@gmail.com"
+  },
+  "skills": [
+    "./skills"
+  ],
+  "commands": [
+    "./commands"
+  ]
+}
--- a/README.md
+++ b/README.md
@@ -0,0 +1,3 @@
+# specweave-plugin-dev
+
+Claude Code plugin development tools including plugin creation, testing, marketplace publishing, skill authoring, agent development, and CLI command integration.
--- a/commands/plugin-create.md
+++ b/commands/plugin-create.md
@@ -0,0 +1,333 @@
+# /specweave-plugin-dev:plugin-create
+
+Create complete Claude Code plugins with proper structure, configuration, and best practices.
+
+You are an expert Claude Code plugin developer who creates production-ready plugins.
+
+## Your Task
+
+Generate complete plugin scaffolds with commands, skills, agents, and proper configuration.
+
+### 1. Plugin Structure
+
+```
+~/.claude/plugins/my-plugin/
+├── .claude-plugin/
+│   └── plugin.json         # Plugin manifest
+├── commands/
+│   └── my-command.md       # Slash commands
+├── skills/
+│   └── my-skill/
+│       └── SKILL.md        # Auto-activating skills
+├── agents/
+│   └── my-agent/
+│       └── AGENT.md        # Sub-agents
+└── lib/
+    └── vendor/             # Dependencies (if needed)
+```
+
+### 2. plugin.json Format
+
+```json
+{
+  "name": "my-plugin",
+  "description": "Clear description with trigger keywords for skill activation",
+  "version": "1.0.0",
+  "author": {
+    "name": "Your Name",
+    "email": "you@example.com"
+  },
+  "homepage": "https://github.com/user/my-plugin",
+  "repository": "https://github.com/user/my-plugin",
+  "license": "MIT",
+  "keywords": [
+    "keyword1",
+    "keyword2",
+    "claude-code",
+    "plugin"
+  ]
+}
+```
+
+### 3. Command Format (Slash Commands)
+
+```markdown
+# /my-plugin:my-command
+
+Short description of what this command does.
+
+You are an expert [role] who [does what].
+
+## Your Task
+
+Detailed instructions for Claude on what to do when command is invoked.
+
+### 1. First Section
+
+- Key point 1
+- Key point 2
+
+### 2. Code Examples
+
+\```typescript
+// Example code
+\```
+
+### 3. Workflow
+
+1. Step 1
+2. Step 2
+3. Step 3
+
+## Example Usage
+
+**User**: "Do something"
+
+**Response**:
+- Action taken
+- Result provided
+
+## When to Use
+
+- Use case 1
+- Use case 2
+```
+
+**Critical Rules**:
+- Header MUST be `# /plugin-name:command-name`
+- NO YAML frontmatter in commands (only in skills)
+- Clear, actionable instructions
+- Code examples where relevant
+
+### 4. Skill Format (Auto-Activating)
+
+```markdown
+---
+name: skill-name
+description: Expert description with ACTIVATION KEYWORDS. Include what the skill does AND trigger words users might say. Activates for keyword1, keyword2, phrase3.
+---
+
+# Skill Title
+
+You are an expert [role] with deep knowledge of [domain].
+
+## Core Expertise
+
+### 1. Topic Area
+
+Content here...
+
+### 2. Code Examples
+
+\```typescript
+// Examples
+\```
+
+## Best Practices
+
+- Practice 1
+- Practice 2
+
+You are ready to help with [domain]!
+```
+
+**Critical Rules**:
+- MUST have YAML frontmatter with `name` and `description`
+- Description MUST include activation keywords
+- File MUST be named `SKILL.md` (uppercase)
+- File MUST be in subdirectory: `skills/skill-name/SKILL.md`
+
+### 5. Agent Format (Sub-Agents)
+
+```markdown
+---
+name: agent-name
+description: What this agent specializes in
+---
+
+# Agent Title
+
+You are a specialized agent for [purpose].
+
+## Capabilities
+
+1. Capability 1
+2. Capability 2
+
+## Workflow
+
+1. Step 1
+2. Step 2
+```
+
+**Invocation**:
+```typescript
+Task({
+  subagent_type: "plugin-name:agent-folder:agent-yaml-name",
+  prompt: "Task description"
+});
+```
+
+### 6. Plugin Development Workflow
+
+**Step 1: Plan Plugin**
+```yaml
+name: my-awesome-plugin
+purpose: Cost optimization for cloud infrastructure
+target_users: DevOps engineers, FinOps teams
+features:
+  commands:
+    - cost-analyze: Analyze cloud costs
+    - cost-optimize: Implement optimizations
+  skills:
+    - cost-optimization: Auto-activate for cost questions
+    - cloud-pricing: Pricing knowledge
+    - aws-cost-expert: AWS-specific expertise
+```
+
+**Step 2: Create Structure**
+```bash
+mkdir -p ~/.claude/plugins/my-awesome-plugin/{.claude-plugin,commands,skills/{cost-optimization,cloud-pricing,aws-cost-expert}}
+```
+
+**Step 3: Write plugin.json**
+```json
+{
+  "name": "my-awesome-plugin",
+  "description": "Cloud cost optimization for AWS, Azure, GCP. Activates for cost analysis, reduce costs, cloud spending, finops.",
+  "version": "1.0.0"
+}
+```
+
+**Step 4: Create Commands**
+```bash
+cat > commands/cost-analyze.md << 'EOF'
+# /my-awesome-plugin:cost-analyze
+...
+EOF
+```
+
+**Step 5: Create Skills**
+```bash
+cat > skills/cost-optimization/SKILL.md << 'EOF'
+---
+name: cost-optimization
+description: Expert cloud cost optimization. Activates for reduce costs, save money, cloud costs, finops, cost analysis.
+---
+...
+EOF
+```
+
+**Step 6: Test Plugin**
+```bash
+# Restart Claude Code
+# Try slash command: /my-awesome-plugin:cost-analyze
+# Test skill activation: "How can I reduce my AWS costs?"
+```
+
+### 7. Best Practices
+
+**Naming Conventions**:
+- Plugin name: `kebab-case`
+- Command names: `kebab-case`
+- Skill names: `kebab-case`
+- No special characters except hyphens
+
+**Activation Keywords**:
+```yaml
+# ✅ Good: Specific trigger words
+description: Expert Python optimization. Activates for python performance, optimize python code, speed up python, profiling, cProfile.
+
+# ❌ Bad: Too generic
+description: Python expert.
+```
+
+**Directory Structure**:
+```
+# ✅ Correct
+skills/my-skill/SKILL.md
+
+# ❌ Wrong
+skills/SKILL.md  # Missing subdirectory
+skills/my-skill.md  # Wrong filename
+```
+
+**Testing Checklist**:
+- ✅ Plugin loads without errors: `ls ~/.claude/plugins/`
+- ✅ Commands appear: `/` (autocomplete)
+- ✅ Skills activate on keywords
+- ✅ No YAML parsing errors
+- ✅ SKILL.md files in subdirectories
+
+### 8. Common Mistakes
+
+**Mistake 1: YAML in Commands**
+```markdown
+# ❌ Wrong: Commands don't use YAML
+---
+name: my-command
+---
+# /my-plugin:my-command
+
+# ✅ Correct: Only header
+# /my-plugin:my-command
+```
+
+**Mistake 2: Wrong SKILL.md Location**
+```
+# ❌ Wrong
+skills/SKILL.md
+
+# ✅ Correct
+skills/skill-name/SKILL.md
+```
+
+**Mistake 3: Missing Activation Keywords**
+```yaml
+# ❌ Bad
+description: Cloud cost expert
+
+# ✅ Good
+description: Cloud cost expert. Activates for reduce costs, save money, aws costs, azure costs, finops, cost optimization.
+```
+
+### 9. Example Plugin Templates
+
+**Minimal Plugin**:
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+└── commands/
+    └── hello.md
+```
+
+**Full-Featured Plugin**:
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+├── commands/
+│   ├── analyze.md
+│   ├── optimize.md
+│   └── report.md
+├── skills/
+│   ├── skill-1/
+│   │   └── SKILL.md
+│   ├── skill-2/
+│   │   └── SKILL.md
+│   └── skill-3/
+│       └── SKILL.md
+└── agents/
+    └── specialist/
+        └── AGENT.md
+```
+
+## When to Use
+
+- Creating new Claude Code plugins
+- Scaffolding plugin structure
+- Adding commands/skills to existing plugins
+- Migrating features to plugin architecture
+
+Create production-ready Claude Code plugins!
--- a/commands/plugin-publish.md
+++ b/commands/plugin-publish.md
@@ -0,0 +1,339 @@
+# /specweave-plugin-dev:plugin-publish
+
+Publish Claude Code plugins to npm, GitHub, or marketplace with proper packaging and documentation.
+
+You are an expert plugin publisher who prepares and releases production-ready plugins.
+
+## Your Task
+
+Package, document, and publish Claude Code plugins following best practices.
+
+### 1. Pre-Publication Checklist
+
+**Code Quality**:
+- ✅ All commands tested and working
+- ✅ Skills activate on keywords
+- ✅ Agents functional (if any)
+- ✅ No hardcoded secrets
+- ✅ No security vulnerabilities
+- ✅ Plugin loads without errors
+
+**Documentation**:
+- ✅ README.md with installation instructions
+- ✅ CHANGELOG.md with version history
+- ✅ LICENSE file (MIT recommended)
+- ✅ Examples and use cases
+- ✅ Contribution guidelines (if open source)
+
+**Metadata**:
+- ✅ plugin.json complete (name, description, version, author, keywords)
+- ✅ package.json (if publishing to npm)
+- ✅ Semantic versioning (1.0.0, 1.1.0, 2.0.0)
+- ✅ Keywords for discoverability
+
+### 2. Package Structure
+
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+├── commands/
+│   └── *.md
+├── skills/
+│   └── */SKILL.md
+├── agents/ (optional)
+│   └── */AGENT.md
+├── lib/ (optional)
+│   └── vendor/
+├── README.md
+├── CHANGELOG.md
+├── LICENSE
+└── package.json (if npm)
+```
+
+### 3. README Template
+
+```markdown
+# My Awesome Plugin
+
+> Brief tagline (one sentence)
+
+Expert [domain] plugin for Claude Code with [key features].
+
+## Features
+
+- ✅ Feature 1 with `/command1`
+- ✅ Feature 2 with auto-activating skills
+- ✅ Feature 3 with specialized agents
+
+## Installation
+
+**From GitHub** (recommended for development):
+\```bash
+claude plugin add github:username/my-plugin
+\```
+
+**From npm**:
+\```bash
+claude plugin add my-plugin
+\```
+
+**Manual**:
+\```bash
+git clone https://github.com/username/my-plugin ~/.claude/plugins/my-plugin
+\```
+
+## Commands
+
+### /my-plugin:command-name
+
+Description of what this command does.
+
+**Usage**:
+\```
+/my-plugin:analyze
+\```
+
+## Skills
+
+### skill-name
+
+Auto-activates for: keyword1, keyword2, phrase3
+
+Provides expert help with [domain].
+
+## Examples
+
+**Example 1: Use Case**
+\```
+User: "How do I...?"
+Plugin: [Response]
+\```
+
+## Configuration
+
+If plugin requires configuration:
+\```bash
+# Add to ~/.config/claude/config.json
+{
+  "plugins": {
+    "my-plugin": {
+      "apiKey": "your-key-here"
+    }
+  }
+}
+\```
+
+## Development
+
+\```bash
+git clone https://github.com/username/my-plugin
+cd my-plugin
+# Make changes
+cp -r . ~/.claude/plugins/my-plugin
+# Restart Claude Code
+\```
+
+## Contributing
+
+PRs welcome! See CONTRIBUTING.md.
+
+## License
+
+MIT © Author Name
+```
+
+### 4. Publishing to GitHub
+
+**Step 1: Create Repository**
+```bash
+cd my-plugin
+git init
+git add .
+git commit -m "Initial commit"
+git branch -M main
+git remote add origin https://github.com/username/my-plugin.git
+git push -u origin main
+```
+
+**Step 2: Create Release**
+```bash
+# Tag version
+git tag v1.0.0
+git push origin v1.0.0
+
+# Create GitHub release
+gh release create v1.0.0 \
+  --title "v1.0.0" \
+  --notes "Initial release"
+```
+
+**Step 3: Add Installation Instructions**
+```markdown
+## Installation
+
+\```bash
+claude plugin add github:username/my-plugin
+\```
+```
+
+### 5. Publishing to npm
+
+**Step 1: Create package.json**
+```json
+{
+  "name": "claude-plugin-my-plugin",
+  "version": "1.0.0",
+  "description": "Expert [domain] plugin for Claude Code",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"No tests yet\""
+  },
+  "keywords": [
+    "claude-code",
+    "plugin",
+    "keyword1",
+    "keyword2"
+  ],
+  "author": "Your Name <you@example.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/username/my-plugin"
+  },
+  "files": [
+    ".claude-plugin/**/*",
+    "commands/**/*",
+    "skills/**/*",
+    "agents/**/*",
+    "lib/**/*",
+    "README.md",
+    "LICENSE"
+  ]
+}
+```
+
+**Step 2: Publish**
+```bash
+# Login to npm
+npm login
+
+# Publish
+npm publish
+
+# Update
+npm version patch  # 1.0.0 → 1.0.1
+npm publish
+```
+
+### 6. Versioning Strategy
+
+**Semantic Versioning**:
+```
+MAJOR.MINOR.PATCH (1.2.3)
+
+MAJOR: Breaking changes (2.0.0)
+- Remove commands
+- Change skill activation keywords
+- Incompatible API changes
+
+MINOR: New features (1.1.0)
+- Add new commands
+- Add new skills
+- Enhance existing features
+
+PATCH: Bug fixes (1.0.1)
+- Fix typos
+- Fix activation issues
+- Update documentation
+```
+
+### 7. Marketplace Submission
+
+**Step 1: Prepare Submission**
+```yaml
+Plugin Name: my-plugin
+Description: Expert [domain] plugin with [features]
+Category: Development Tools
+Tags: [tag1, tag2, tag3]
+Repository: https://github.com/username/my-plugin
+Documentation: https://github.com/username/my-plugin#readme
+License: MIT
+```
+
+**Step 2: Quality Requirements**
+- ✅ README with clear installation
+- ✅ Working examples
+- ✅ No security issues
+- ✅ No hardcoded secrets
+- ✅ Follows naming conventions
+- ✅ plugin.json complete
+
+**Step 3: Submit**
+```bash
+# Via GitHub
+# Create PR to claude-code/marketplace
+# Add plugin to marketplace.json
+```
+
+### 8. Post-Publication
+
+**Maintenance**:
+```yaml
+Regular Updates:
+  - Security patches
+  - Bug fixes
+  - Feature enhancements
+  - Documentation improvements
+
+Community:
+  - Respond to issues
+  - Review pull requests
+  - Update examples
+  - Write blog posts
+
+Versioning:
+  - Follow semver strictly
+  - Maintain CHANGELOG.md
+  - Tag releases
+  - Document breaking changes
+```
+
+**Analytics**:
+```bash
+# Track:
+- npm downloads: https://npm-stat.com/charts.html?package=my-plugin
+- GitHub stars
+- Issues opened/closed
+- Community contributions
+```
+
+### 9. Best Practices
+
+**Documentation**:
+- Clear installation instructions
+- Working examples
+- Troubleshooting section
+- API reference (if applicable)
+- Video demo (optional, high impact)
+
+**Naming**:
+- Descriptive plugin name
+- Prefix with `claude-plugin-` on npm
+- Use keywords for discoverability
+- Clear command names
+
+**Support**:
+- GitHub Discussions for Q&A
+- Issues for bugs
+- PR template for contributions
+- Code of Conduct
+
+## When to Use
+
+- Publishing completed plugin
+- Releasing new plugin version
+- Submitting to marketplace
+- Open-sourcing internal tools
+
+Ship production-ready plugins!
--- a/commands/plugin-test.md
+++ b/commands/plugin-test.md
@@ -0,0 +1,293 @@
+# /specweave-plugin-dev:plugin-test
+
+Test Claude Code plugins for correctness, activation, and best practices compliance.
+
+You are an expert plugin tester who validates plugin structure and functionality.
+
+## Your Task
+
+Validate plugin structure, test activation, and verify best practices compliance.
+
+### 1. Validation Checklist
+
+**File Structure**:
+```bash
+# Check plugin exists
+ls ~/.claude/plugins/my-plugin
+
+# Verify structure
+tree ~/.claude/plugins/my-plugin
+# Expected:
+# .claude-plugin/plugin.json ✓
+# commands/*.md ✓
+# skills/*/SKILL.md ✓
+```
+
+**plugin.json Validation**:
+```typescript
+interface PluginManifest {
+  name: string;         // Required: kebab-case
+  description: string;  // Required: activation keywords
+  version: string;      // Required: semver
+  author?: {
+    name: string;
+    email: string;
+  };
+  keywords?: string[];
+  homepage?: string;
+  repository?: string;
+  license?: string;
+}
+
+// Validate
+const plugin = JSON.parse(fs.readFileSync('.claude-plugin/plugin.json'));
+assert(plugin.name.match(/^[a-z0-9-]+$/), 'Name must be kebab-case');
+assert(plugin.description.length > 20, 'Description too short');
+assert(semver.valid(plugin.version), 'Invalid version');
+```
+
+**Command Validation**:
+```bash
+# Check header format
+grep -E '^# /[a-z0-9-]+:[a-z0-9-]+$' commands/*.md
+
+# Verify no YAML frontmatter in commands
+! grep -l '^---$' commands/*.md
+
+# Check for clear instructions
+grep -A 20 '## Your Task' commands/*.md
+```
+
+**Skill Validation**:
+```bash
+# Check YAML frontmatter
+grep -l '^---$' skills/*/SKILL.md
+
+# Validate activation keywords
+grep 'Activates for' skills/*/SKILL.md
+
+# Verify subdirectory structure
+find skills -name 'SKILL.md' -not -path 'skills/*/SKILL.md' # Should be empty
+```
+
+### 2. Activation Testing
+
+**Test Slash Command**:
+```bash
+# In Claude Code:
+# 1. Type "/" 
+# 2. Verify command appears in autocomplete
+# 3. Execute: /my-plugin:my-command
+# 4. Verify behavior matches documentation
+```
+
+**Test Skill Auto-Activation**:
+```bash
+# Test each activation keyword
+echo "Testing skill activation..."
+
+# Skill: cost-optimization
+# Keywords: reduce costs, save money, cloud costs, finops
+# Test: Ask "How can I reduce my AWS costs?"
+# Expected: Skill activates, provides cost optimization advice
+
+# Skill: python-expert
+# Keywords: python, optimize python, speed up python
+# Test: Ask "How do I speed up my Python code?"
+# Expected: Skill activates, provides optimization tips
+```
+
+**Test Agent Invocation**:
+```typescript
+// Verify agent exists
+const agentPath = '~/.claude/plugins/my-plugin/agents/my-agent/AGENT.md';
+assert(fs.existsSync(agentPath), 'Agent file missing');
+
+// Test invocation syntax
+Task({
+  subagent_type: "my-plugin:my-agent:my-agent", // plugin:folder:yaml-name
+  prompt: "Test agent invocation"
+});
+```
+
+### 3. Best Practices Validation
+
+**Naming Convention Check**:
+```bash
+# Plugin name: kebab-case only
+echo "my-plugin" | grep -E '^[a-z0-9-]+$' ✓
+echo "MyPlugin" | grep -E '^[a-z0-9-]+$' ✗ # No CamelCase
+
+# Command names: kebab-case
+echo "analyze-costs" | grep -E '^[a-z0-9-]+$' ✓
+echo "analyzeCosts" | grep -E '^[a-z0-9-]+$' ✗ # No camelCase
+```
+
+**Activation Keyword Quality**:
+```yaml
+# ✅ Good: Specific, varied keywords
+description: Expert cost optimization. Activates for reduce costs, save money, aws costs, cloud spending, finops, cost analysis, budget optimization.
+
+# ⚠️ Weak: Too few keywords
+description: Cost expert. Activates for costs.
+
+# ❌ Bad: No keywords
+description: Cost optimization plugin.
+```
+
+**Documentation Quality**:
+```markdown
+# Check for:
+- [ ] Clear "Your Task" section
+- [ ] Code examples with syntax highlighting
+- [ ] Workflow/steps
+- [ ] "When to Use" section
+- [ ] Example usage
+```
+
+### 4. Integration Testing
+
+**Test Plugin Loading**:
+```bash
+# Check Claude Code logs
+tail -f ~/.claude/logs/claude.log | grep 'my-plugin'
+
+# Expected output:
+# ✅ "Loaded plugin: my-plugin"
+# ✅ "Registered command: /my-plugin:my-command"
+# ✅ "Registered skill: my-skill"
+
+# Red flags:
+# ❌ "Failed to parse plugin.json"
+# ❌ "YAML parsing error in SKILL.md"
+# ❌ "Command header malformed"
+```
+
+**Test Cross-Plugin Compatibility**:
+```bash
+# Ensure no conflicts with other plugins
+ls ~/.claude/plugins/
+
+# Check for:
+- Name collisions (same plugin name)
+- Command collisions (same /command)
+- Skill keyword overlap (acceptable, but note)
+```
+
+### 5. Performance Testing
+
+**Skill Activation Speed**:
+```bash
+# Skills should activate in < 100ms
+# Monitor: Does Claude Code lag when typing trigger keywords?
+
+# If slow:
+# - Reduce skill description length
+# - Optimize SKILL.md size (< 50KB)
+# - Avoid complex regex in activation patterns
+```
+
+**Command Execution**:
+```bash
+# Commands should provide first response in < 2s
+# Test with: /my-plugin:my-command
+
+# If slow:
+# - Check for expensive operations in command instructions
+# - Optimize prompt length
+```
+
+### 6. Security Review
+
+**Secret Detection**:
+```bash
+# Check for hardcoded secrets
+grep -r 'API_KEY\|SECRET\|PASSWORD\|TOKEN' .
+
+# ❌ Hardcoded secrets
+const API_KEY = 'sk-1234567890abcdef';
+
+# ✅ Environment variables
+const API_KEY = process.env.API_KEY;
+```
+
+**Input Validation**:
+```bash
+# Ensure commands validate user input
+grep -r 'validate\|sanitize\|escape' commands/
+
+# Commands that execute code should warn about risks
+```
+
+### 7. Testing Workflow
+
+**Manual Testing**:
+1. Install plugin: `cp -r my-plugin ~/.claude/plugins/`
+2. Restart Claude Code
+3. Test commands: `/my-plugin:command`
+4. Test skills: Ask trigger questions
+5. Test agents: Use Task() tool
+6. Check logs: `~/.claude/logs/`
+
+**Automated Testing** (if applicable):
+```bash
+# Validation script
+#!/bin/bash
+
+PLUGIN_DIR="my-plugin"
+
+# Check structure
+test -f "$PLUGIN_DIR/.claude-plugin/plugin.json" || exit 1
+test -d "$PLUGIN_DIR/commands" || exit 1
+test -d "$PLUGIN_DIR/skills" || exit 1
+
+# Validate JSON
+jq . "$PLUGIN_DIR/.claude-plugin/plugin.json" > /dev/null || exit 1
+
+# Check SKILL.md files
+find "$PLUGIN_DIR/skills" -name 'SKILL.md' -path '*/*/SKILL.md' | wc -l
+
+# Validate YAML frontmatter
+for skill in "$PLUGIN_DIR/skills"/*/SKILL.md; do
+  head -n 5 "$skill" | grep -q '^---$' || echo "Missing YAML: $skill"
+done
+
+echo "✅ Plugin validation passed"
+```
+
+### 8. Common Issues
+
+**Issue: Command not appearing**
+```bash
+# Check header format
+# ❌ Wrong: # my-plugin:my-command
+# ❌ Wrong: # /myPlugin:myCommand
+# ✅ Correct: # /my-plugin:my-command
+```
+
+**Issue: Skill not activating**
+```bash
+# Check:
+1. YAML frontmatter present?
+2. Activation keywords in description?
+3. SKILL.md in subdirectory?
+4. Claude Code restarted after changes?
+```
+
+**Issue: YAML parsing error**
+```bash
+# Common causes:
+- Unclosed quotes: description: "Missing end quote
+- Invalid characters: name: my_skill (use hyphens)
+- Missing closing ---
+- Incorrect indentation
+```
+
+## When to Use
+
+- After creating/modifying plugins
+- Before publishing to marketplace
+- Debugging plugin activation issues
+- Pre-release quality assurance
+
+Test plugins thoroughly before release!
--- a/plugin.lock.json
+++ b/plugin.lock.json
@@ -0,0 +1,65 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:anton-abyzov/specweave:plugins/specweave-plugin-dev",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "442a0324ab7169d3c83aa754fa2539976a40abbf",
+    "treeHash": "c194d1641329efbbefd5566e4c48499e4814ea2aa22fb602dfcac7951468ca77",
+    "generatedAt": "2025-11-28T10:13:55.606013Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "specweave-plugin-dev",
+    "description": "Claude Code plugin development tools including plugin creation, testing, marketplace publishing, skill authoring, agent development, and CLI command integration.",
+    "version": "0.24.0"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "8e616d10b955fe58d48a67a5c53546a0ffdb96a066f394403a493c696877bc61"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "2ff039bbf52c2f335965883cc4f07fbe6abd9f378a62aee0a8efa70e305be817"
+      },
+      {
+        "path": "commands/plugin-create.md",
+        "sha256": "363347f4b496126889d9809639e336d1e77803ba1b59a6b0b54e8aa9e67ee569"
+      },
+      {
+        "path": "commands/plugin-publish.md",
+        "sha256": "775775c6676addd6fa02334c7ede39391d55f09bd52d14f449ae198646f450d2"
+      },
+      {
+        "path": "commands/plugin-test.md",
+        "sha256": "fcabf4a457b3074b1946e122eed04241fe5ff054a90c6c653c212052639cca19"
+      },
+      {
+        "path": "skills/marketplace-publishing/SKILL.md",
+        "sha256": "b35347d6a36b5a9ed36223c1701bcd995e2981c3a237e903df90c4e6bd20ce5e"
+      },
+      {
+        "path": "skills/claude-sdk/SKILL.md",
+        "sha256": "3c2204a18ec220b118f4f256b42a3b5f42a15842201d6901fb287b0f5274d65d"
+      },
+      {
+        "path": "skills/plugin-development/SKILL.md",
+        "sha256": "3e3a51a2ef882046cfcd8d3ecdb2b7224c34776a5c4c8cf50644cf3181bd0f7a"
+      }
+    ],
+    "dirSha256": "c194d1641329efbbefd5566e4c48499e4814ea2aa22fb602dfcac7951468ca77"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}
--- a/skills/claude-sdk/SKILL.md
+++ b/skills/claude-sdk/SKILL.md
@@ -0,0 +1,164 @@
+---
+name: claude-sdk
+description: Expert knowledge of Claude Code SDK, API, tools (Read, Write, Edit, Bash, Grep, Glob), agent tools (Task, Skill, SlashCommand), plugin hooks, MCP integration, and Claude Code extension development. Activates for claude sdk, claude api, claude tools, Read tool, Write tool, Edit tool, Task tool, Skill tool, claude hooks, MCP, claude code api.
+---
+
+# Claude SDK Expert
+
+Expert knowledge of Claude Code SDK, tools, and extension development.
+
+## Core Tools
+
+**File Operations**:
+```typescript
+// Read files
+Read({ file_path: '/absolute/path/file.ts' });
+
+// Write files (creates new or overwrites)
+Write({
+  file_path: '/absolute/path/file.ts',
+  content: 'export const hello = () => "world";'
+});
+
+// Edit files (precise replacements)
+Edit({
+  file_path: '/absolute/path/file.ts',
+  old_string: 'const x = 1;',
+  new_string: 'const x = 2;'
+});
+```
+
+**Search**:
+```typescript
+// Find files by pattern
+Glob({ pattern: '**/*.ts' });
+
+// Search file contents
+Grep({
+  pattern: 'TODO',
+  output_mode: 'files_with_matches'
+});
+
+// Search with context
+Grep({
+  pattern: 'function.*export',
+  output_mode: 'content',
+  '-C': 3, // 3 lines before/after
+  '-n': true // Line numbers
+});
+```
+
+**Execution**:
+```typescript
+// Run commands
+Bash({
+  command: 'npm test',
+  description: 'Run test suite'
+});
+
+// Background processes
+Bash({
+  command: 'npm run dev',
+  run_in_background: true
+});
+```
+
+## Agent Tools
+
+**Sub-agents**:
+```typescript
+// Invoke specialized sub-agent
+Task({
+  subagent_type: 'plugin:agent-folder:agent-name',
+  prompt: 'Analyze this architecture'
+});
+```
+
+**Skills**:
+```typescript
+// Activate skill explicitly
+Skill({ skill: 'skill-name' });
+
+// Or let auto-activation handle it
+```
+
+**Commands**:
+```typescript
+// Execute slash command
+SlashCommand({ command: '/plugin:command arg1 arg2' });
+```
+
+## Plugin Hooks
+
+**Available Hook Events**:
+```typescript
+type HookEvent =
+  | 'PostToolUse'        // After tool executes
+  | 'PreToolUse'         // Before tool executes
+  | 'PermissionRequest'  // User permission dialog
+  | 'Notification'       // System notification
+  | 'UserPromptSubmit'   // After user submits prompt
+  | 'Stop'               // Conversation stopped
+  | 'SubagentStop'       // Sub-agent stopped
+  | 'PreCompact'         // Before context compaction
+  | 'SessionStart'       // Session started
+  | 'SessionEnd';        // Session ended
+```
+
+**Hook Configuration**:
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "TodoWrite",
+        "hooks": [{
+          "type": "command",
+          "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-task.sh",
+          "timeout": 10
+        }]
+      }
+    ]
+  }
+}
+```
+
+## MCP (Model Context Protocol)
+
+> **Code-First Preferred**: Anthropic research shows [code execution achieves 98% token reduction vs MCP](https://www.anthropic.com/engineering/code-execution-with-mcp). Use MCP only for: quick debugging, Claude Desktop integration, or tools with no code equivalent. For automation, CI/CD, and production - write code instead.
+
+**MCP Server Integration** (when needed):
+```typescript
+// Connect to MCP server
+const mcp = await connectMCP({
+  name: 'filesystem',
+  transport: 'stdio',
+  command: 'node',
+  args: ['mcp-server-filesystem.js']
+});
+
+// Use MCP tools
+mcp.call('read_file', { path: '/path/to/file' });
+```
+
+## Best Practices
+
+**Tool Usage**:
+- Use absolute paths (not relative)
+- Handle errors gracefully
+- Provide clear descriptions
+- Batch independent operations
+
+**Performance**:
+- Minimize tool calls
+- Use Grep before Read (search first)
+- Parallel independent operations
+- Cache results when possible
+
+**Security**:
+- Validate file paths
+- Sanitize user input
+- No hardcoded secrets
+- Use environment variables
+
+Build powerful Claude Code extensions!
--- a/skills/marketplace-publishing/SKILL.md
+++ b/skills/marketplace-publishing/SKILL.md
@@ -0,0 +1,263 @@
+---
+name: marketplace-publishing
+description: Expert Claude Code marketplace publishing covering npm publishing, GitHub releases, semantic versioning, plugin packaging, README documentation, CHANGELOG management, marketplace submission, and plugin distribution. Activates for publish plugin, npm publish, marketplace, release plugin, semantic versioning, semver, plugin distribution, publish to npm, github release.
+---
+
+# Marketplace Publishing Expert
+
+Expert guidance for publishing Claude Code plugins to npm and marketplace.
+
+## Publishing Platforms
+
+**1. GitHub** (Recommended):
+```bash
+# Install from GitHub
+claude plugin add github:username/plugin-name
+
+# Pros:
+- Free hosting
+- Version control
+- Issue tracking
+- Easy updates
+
+# Requirements:
+- Public repository
+- Proper directory structure
+- README with installation
+```
+
+**2. npm**:
+```bash
+# Install from npm
+claude plugin add plugin-name
+
+# Pros:
+- Centralized registry
+- Semantic versioning
+- Easy discovery
+
+# Requirements:
+- npm account
+- package.json
+- Unique name (prefix: claude-plugin-)
+```
+
+**3. Marketplace**:
+```bash
+# Official Claude Code marketplace
+# PR to marketplace repository
+
+# Requirements:
+- Quality standards
+- Complete documentation
+- No security issues
+- Proper licensing
+```
+
+## Semantic Versioning
+
+**Version Format**: `MAJOR.MINOR.PATCH`
+
+**Rules**:
+```yaml
+MAJOR (1.0.0 → 2.0.0):
+  - Breaking changes
+  - Remove commands
+  - Change skill keywords
+  - Incompatible API changes
+
+MINOR (1.0.0 → 1.1.0):
+  - New features
+  - Add commands
+  - Add skills
+  - Backward compatible
+
+PATCH (1.0.0 → 1.0.1):
+  - Bug fixes
+  - Documentation updates
+  - Performance improvements
+  - No API changes
+```
+
+**Examples**:
+```bash
+# Bug fix
+npm version patch  # 1.0.0 → 1.0.1
+
+# New feature
+npm version minor  # 1.0.1 → 1.1.0
+
+# Breaking change
+npm version major  # 1.1.0 → 2.0.0
+```
+
+## package.json Setup
+
+**Minimum**:
+```json
+{
+  "name": "claude-plugin-my-plugin",
+  "version": "1.0.0",
+  "description": "Expert [domain] plugin for Claude Code",
+  "keywords": ["claude-code", "plugin", "keyword1"],
+  "author": "Your Name",
+  "license": "MIT",
+  "files": [
+    ".claude-plugin",
+    "commands",
+    "skills",
+    "agents",
+    "README.md",
+    "LICENSE"
+  ]
+}
+```
+
+**Full**:
+```json
+{
+  "name": "claude-plugin-my-plugin",
+  "version": "1.0.0",
+  "description": "Expert [domain] plugin with [features]",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"No tests yet\"",
+    "validate": "bash validate.sh"
+  },
+  "keywords": [
+    "claude-code",
+    "plugin",
+    "development-tools",
+    "keyword1",
+    "keyword2"
+  ],
+  "author": "Your Name <you@example.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/username/my-plugin"
+  },
+  "homepage": "https://github.com/username/my-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/username/my-plugin/issues"
+  },
+  "files": [
+    ".claude-plugin/**/*",
+    "commands/**/*",
+    "skills/**/*",
+    "agents/**/*",
+    "README.md",
+    "LICENSE"
+  ]
+}
+```
+
+## Publishing Workflow
+
+**GitHub Release**:
+```bash
+# 1. Update version
+npm version patch
+
+# 2. Commit changes
+git add .
+git commit -m "Release v1.0.1"
+
+# 3. Create tag
+git tag v1.0.1
+
+# 4. Push
+git push && git push --tags
+
+# 5. Create GitHub release
+gh release create v1.0.1 \
+  --title "v1.0.1" \
+  --notes "Bug fixes and improvements"
+```
+
+**npm Publish**:
+```bash
+# 1. Login
+npm login
+
+# 2. Validate package
+npm pack --dry-run
+
+# 3. Publish
+npm publish
+
+# 4. Verify
+npm view claude-plugin-my-plugin
+```
+
+## Documentation Requirements
+
+**README.md**:
+```markdown
+# Plugin Name
+
+> One-line tagline
+
+Brief description.
+
+## Features
+
+- Feature 1
+- Feature 2
+
+## Installation
+
+\```bash
+claude plugin add github:user/plugin
+\```
+
+## Commands
+
+### /plugin:command
+
+Description.
+
+## Examples
+
+[Working examples]
+
+## License
+
+MIT
+```
+
+**CHANGELOG.md**:
+```markdown
+# Changelog
+
+## [1.0.1] - 2025-01-15
+
+### Fixed
+- Bug fix 1
+- Bug fix 2
+
+## [1.0.0] - 2025-01-01
+
+### Added
+- Initial release
+```
+
+## Quality Checklist
+
+**Pre-publish**:
+- ✅ All commands working
+- ✅ Skills activate correctly
+- ✅ No hardcoded secrets
+- ✅ README with examples
+- ✅ LICENSE file
+- ✅ Semantic versioning
+- ✅ CHANGELOG updated
+- ✅ Git tag created
+
+**Post-publish**:
+- ✅ Test installation
+- ✅ Verify on npm (if published)
+- ✅ Check GitHub release
+- ✅ Update marketplace (if applicable)
+
+Publish professional Claude Code plugins!
--- a/skills/plugin-development/SKILL.md
+++ b/skills/plugin-development/SKILL.md
@@ -0,0 +1,316 @@
+---
+name: plugin-development
+description: Expert Claude Code plugin development covering plugin structure, slash commands, auto-activating skills, sub-agents, plugin.json configuration, YAML frontmatter, activation keywords, directory structure, and plugin best practices. Activates for plugin development, create plugin, claude plugin, slash command, skill activation, SKILL.md, plugin.json, claude code plugin, how to make plugin.
+---
+
+# Plugin Development Expert
+
+Expert guidance for creating production-ready Claude Code plugins.
+
+## Critical Structure Rules
+
+**Directory Hierarchy**:
+```
+~/.claude/plugins/my-plugin/    ← Plugin root
+├── .claude-plugin/
+│   └── plugin.json            ← Manifest (REQUIRED)
+├── commands/
+│   └── command-name.md        ← Slash commands
+├── skills/
+│   └── skill-name/            ← MUST be subdirectory
+│       └── SKILL.md           ← MUST be uppercase
+└── agents/
+    └── agent-name/
+        └── AGENT.md
+```
+
+**Common Mistakes**:
+```
+# ❌ WRONG
+skills/SKILL.md                # Missing subdirectory
+skills/my-skill.md             # Wrong filename
+skills/My-Skill/SKILL.md       # CamelCase not allowed
+
+# ✅ CORRECT
+skills/my-skill/SKILL.md       # kebab-case subdirectory + SKILL.md
+```
+
+## plugin.json Format
+
+**Minimum Required**:
+```json
+{
+  "name": "my-plugin",
+  "description": "Clear description with activation keywords",
+  "version": "1.0.0"
+}
+```
+
+**Full Example**:
+```json
+{
+  "name": "my-awesome-plugin",
+  "description": "Expert cost optimization for AWS, Azure, GCP. Activates for reduce costs, cloud costs, finops, save money, cost analysis.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Your Name",
+    "email": "you@example.com"
+  },
+  "homepage": "https://github.com/user/my-plugin",
+  "repository": "https://github.com/user/my-plugin",
+  "license": "MIT",
+  "keywords": ["cost", "finops", "aws", "azure", "gcp"]
+}
+```
+
+## Command Format (Slash Commands)
+
+**Header Format** (CRITICAL):
+```markdown
+# /my-plugin:command-name
+```
+
+**Rules**:
+- MUST start with `# /`
+- Plugin name: `kebab-case`
+- Command name: `kebab-case`
+- NO YAML frontmatter (only skills use YAML)
+
+**Full Template**:
+```markdown
+# /my-plugin:analyze-costs
+
+Analyze cloud costs and provide optimization recommendations.
+
+You are an expert FinOps engineer.
+
+## Your Task
+
+1. Collect cost data
+2. Analyze usage patterns
+3. Identify optimization opportunities
+4. Generate report
+
+### 1. Data Collection
+
+\```bash
+aws ce get-cost-and-usage --time-period...
+\```
+
+## Example Usage
+
+**User**: "Analyze our AWS costs"
+
+**Response**:
+- Pulls Cost Explorer data
+- Identifies $5K/month in savings
+- Provides implementation plan
+
+## When to Use
+
+- Monthly cost reviews
+- Budget overruns
+- Pre-purchase planning
+```
+
+## Skill Format (Auto-Activating)
+
+**YAML Frontmatter** (REQUIRED):
+```yaml
+---
+name: cost-optimization
+description: Expert cloud cost optimization for AWS, Azure, GCP. Covers FinOps, reserved instances, spot instances, right-sizing, storage optimization. Activates for reduce costs, save money, cloud costs, aws costs, finops, cost optimization, budget overrun, expensive bill.
+---
+```
+
+**Activation Keywords**:
+```yaml
+# ✅ GOOD: Specific, varied keywords
+description: Expert Python optimization. Activates for python performance, optimize python code, speed up python, profiling, cProfile, pypy, numba.
+
+# ❌ BAD: Too generic
+description: Python expert.
+
+# ❌ BAD: No activation keywords
+description: Expert Python optimization covering performance tuning.
+```
+
+**Full Template**:
+```markdown
+---
+name: my-skill
+description: Expert [domain] covering [topics]. Activates for keyword1, keyword2, phrase3, action4.
+---
+
+# Skill Title
+
+You are an expert [role] with deep knowledge of [domain].
+
+## Core Expertise
+
+### 1. Topic Area
+
+Content here...
+
+### 2. Code Examples
+
+\```typescript
+// Working examples
+\```
+
+## Best Practices
+
+- Practice 1
+- Practice 2
+
+You are ready to help with [domain]!
+```
+
+## Agent Format (Sub-Agents)
+
+**File Location**:
+```
+agents/agent-name/AGENT.md
+```
+
+**Template**:
+```markdown
+---
+name: specialist-agent
+description: Specialized agent for [specific task]
+---
+
+# Agent Title
+
+You are a specialized agent for [purpose].
+
+## Capabilities
+
+1. Capability 1
+2. Capability 2
+
+## Workflow
+
+1. Analyze input
+2. Execute specialized task
+3. Return results
+```
+
+**Invocation**:
+```typescript
+Task({
+  subagent_type: "plugin-name:folder-name:yaml-name",
+  prompt: "Task description"
+});
+
+// Example
+Task({
+  subagent_type: "my-plugin:specialist-agent:specialist-agent",
+  prompt: "Analyze this code for security vulnerabilities"
+});
+```
+
+## Testing Workflow
+
+**1. Install Plugin**:
+```bash
+cp -r my-plugin ~/.claude/plugins/
+# OR
+claude plugin add github:username/my-plugin
+```
+
+**2. Restart Claude Code**:
+```bash
+# Required after:
+- Adding new plugin
+- Modifying plugin.json
+- Adding/removing commands
+- Changing YAML frontmatter
+```
+
+**3. Test Commands**:
+```bash
+# Type "/" in Claude Code
+# Verify command appears: /my-plugin:command-name
+# Execute command
+# Verify behavior
+```
+
+**4. Test Skills**:
+```bash
+# Ask trigger question: "How do I reduce costs?"
+# Verify skill activates
+# Check response uses skill knowledge
+```
+
+**5. Check Logs**:
+```bash
+tail -f ~/.claude/logs/claude.log | grep my-plugin
+
+# Expected:
+# ✅ "Loaded plugin: my-plugin"
+# ✅ "Registered command: /my-plugin:analyze"
+# ✅ "Registered skill: cost-optimization"
+
+# Errors:
+# ❌ "Failed to parse plugin.json"
+# ❌ "YAML parsing error in SKILL.md"
+# ❌ "Command header malformed"
+```
+
+## Common Issues
+
+**Issue: Skill not activating**
+```
+Checklist:
+1. ✅ YAML frontmatter present? (---...---)
+2. ✅ Activation keywords in description?
+3. ✅ SKILL.md in subdirectory? (skills/name/SKILL.md)
+4. ✅ File named SKILL.md (uppercase)?
+5. ✅ Claude Code restarted?
+```
+
+**Issue: Command not found**
+```
+Checklist:
+1. ✅ Header format: # /plugin-name:command-name
+2. ✅ File in commands/ directory?
+3. ✅ Plugin name matches plugin.json?
+4. ✅ Claude Code restarted?
+```
+
+**Issue: YAML parsing error**
+```
+Common causes:
+- Unclosed quotes: description: "Missing end
+- Invalid characters: name: my_skill (use hyphens)
+- Missing closing ---
+- Incorrect indentation
+```
+
+## Best Practices
+
+**Naming**:
+- Plugin: `my-awesome-plugin` (kebab-case)
+- Commands: `analyze-costs` (kebab-case)
+- Skills: `cost-optimization` (kebab-case)
+- NO underscores, NO CamelCase
+
+**Activation Keywords**:
+- Include 5-10 trigger keywords
+- Mix specific terms and common phrases
+- Think about what users will ask
+- Test with real questions
+
+**Documentation**:
+- Clear "Your Task" section
+- Code examples with syntax highlighting
+- "Example Usage" section
+- "When to Use" section
+
+**Performance**:
+- Keep SKILL.md under 50KB
+- Optimize command prompts
+- Avoid expensive operations
+
+Create production-ready Claude Code plugins!