zhongwei/gh-anton-abyzov-specweave-plugins-specweave-plugin-dev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 17:57:04 +08:00
commit e6ff08128c
9 changed files with 1791 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
.claude-plugin/plugin.json Normal file
View File

@@ -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"
]
}

3
README.md Normal file
View File

@@ -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.

333
commands/plugin-create.md Normal file
View File

@@ -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!

339
commands/plugin-publish.md Normal file
View File

@@ -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!

293
commands/plugin-test.md Normal file
View File

@@ -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!

65
plugin.lock.json Normal file
View File

@@ -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": []
}
}

164
skills/claude-sdk/SKILL.md Normal file
View File

@@ -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!

263
skills/marketplace-publishing/SKILL.md Normal file
View File

@@ -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!

316
skills/plugin-development/SKILL.md Normal file
View File

@@ -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!