zhongwei/gh-anton-abyzov-specweave-plugins-specweave-plugin-dev

Files

Zhongwei Li e6ff08128c Initial commit

2025-11-29 17:57:04 +08:00

6.8 KiB

Raw Blame History

name, description

name	description
plugin-development	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:

{
  "name": "my-plugin",
  "description": "Clear description with activation keywords",
  "version": "1.0.0"
}

Full Example:

{
  "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):

# /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:

# /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):

---
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:

# ✅ 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:

---
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:

---
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:

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:

cp -r my-plugin ~/.claude/plugins/
# OR
claude plugin add github:username/my-plugin

2. Restart Claude Code:

# Required after:
- Adding new plugin
- Modifying plugin.json
- Adding/removing commands
- Changing YAML frontmatter

3. Test Commands:

# Type "/" in Claude Code
# Verify command appears: /my-plugin:command-name
# Execute command
# Verify behavior

4. Test Skills:

# Ask trigger question: "How do I reduce costs?"
# Verify skill activates
# Check response uses skill knowledge

5. Check Logs:

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