Initial commit

2025-11-29 17:57:04 +08:00
commit e6ff08128c
9 changed files with 1791 additions and 0 deletions
--- 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!