feat: Convert to Claude Code plugin marketplace
Transform repository into a plugin marketplace structure with two plugins: - claude-code plugin: Complete toolkit with 5 skills * claude-code-plugins * claude-code-slash-commands * claude-code-hooks * claude-code-subagents * claude-code-memory - claude-skills plugin: Meta-skill for creating Agent Skills * Comprehensive best practices guide * Templates and examples * Progressive disclosure patterns Infrastructure: - Add marketplace.json manifest - Create plugin.json for each plugin - Update documentation for marketplace structure - Add contribution and testing guides Installation: - /plugin install claude-code@claude-skills - /plugin install claude-skills@claude-skills 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
movq
19
.claude-plugin/marketplace.json
Normal file
19
.claude-plugin/marketplace.json
Normal file
@@ -0,0 +1,19 @@
|
||||
{
|
||||
"name": "claude-skills-marketplace",
|
||||
"owner": {
|
||||
"name": "Claude Skills Contributors"
|
||||
},
|
||||
"description": "A curated collection of Agent Skills and plugins for Claude Code and Claude.ai",
|
||||
"plugins": [
|
||||
{
|
||||
"name": "claude-code",
|
||||
"source": "./claude-code",
|
||||
"description": "Complete toolkit for Claude Code: plugins, slash commands, hooks, subagents, and memory management"
|
||||
},
|
||||
{
|
||||
"name": "claude-skills",
|
||||
"source": "./claude-skills-plugin",
|
||||
"description": "Meta-skill for creating effective Agent Skills with best practices and templates"
|
||||
}
|
||||
]
|
||||
}
|
||||
57
.gitignore
vendored
57
.gitignore
vendored
@@ -1 +1,58 @@
|
||||
# Claude Code local settings
|
||||
.claude/settings.local.json
|
||||
|
||||
# macOS
|
||||
.DS_Store
|
||||
.AppleDouble
|
||||
.LSOverride
|
||||
|
||||
# Temporary files
|
||||
*.tmp
|
||||
*.swp
|
||||
*.swo
|
||||
*~
|
||||
.*.sw?
|
||||
|
||||
# Test artifacts
|
||||
tmp/
|
||||
temp/
|
||||
test-output/
|
||||
|
||||
# Compressed skill packages
|
||||
*.zip
|
||||
*.tar.gz
|
||||
|
||||
# IDE
|
||||
.vscode/
|
||||
.idea/
|
||||
*.sublime-*
|
||||
|
||||
# Python (if testing skills)
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
*$py.class
|
||||
.pytest_cache/
|
||||
.coverage
|
||||
htmlcov/
|
||||
.venv/
|
||||
venv/
|
||||
ENV/
|
||||
|
||||
# Node (if testing skills)
|
||||
node_modules/
|
||||
npm-debug.log
|
||||
yarn-error.log
|
||||
.npm/
|
||||
|
||||
# Build outputs
|
||||
dist/
|
||||
build/
|
||||
*.egg-info/
|
||||
|
||||
# Sensitive data
|
||||
*.key
|
||||
*.pem
|
||||
*.cert
|
||||
secrets/
|
||||
.env
|
||||
.env.local
|
||||
|
||||
484
CONTRIBUTING.md
Normal file
484
CONTRIBUTING.md
Normal file
@@ -0,0 +1,484 @@
|
||||
# Contributing to Claude Skills Marketplace
|
||||
|
||||
Thank you for contributing! This guide helps you add plugins, skills, and improvements to the marketplace.
|
||||
|
||||
## Types of Contributions
|
||||
|
||||
1. **Add skills to existing plugins** - Extend claude-code or claude-skills
|
||||
2. **Create new plugins** - Package related skills together
|
||||
3. **Improve existing skills** - Refine content, fix bugs, add examples
|
||||
4. **Update documentation** - Improve guides and READMEs
|
||||
|
||||
## Before You Start
|
||||
|
||||
1. **Use the claude-skills plugin** - Get guidance on skill creation
|
||||
2. **Review existing plugins** - Check claude-code and claude-skills-plugin
|
||||
3. **Test thoroughly** - See [TESTING.md](./TESTING.md)
|
||||
|
||||
## Adding a Skill to an Existing Plugin
|
||||
|
||||
### Option 1: Add to claude-code Plugin
|
||||
|
||||
Add Claude Code-specific skills (features, tools, workflows):
|
||||
|
||||
```bash
|
||||
# 1. Create skill directory
|
||||
cd claude-code/skills
|
||||
mkdir my-claude-code-skill
|
||||
|
||||
# 2. Create SKILL.md
|
||||
cat > my-claude-code-skill/SKILL.md << 'EOF'
|
||||
---
|
||||
name: My Claude Code Feature
|
||||
description: [Specific description with trigger scenarios]
|
||||
---
|
||||
|
||||
# Content here
|
||||
EOF
|
||||
|
||||
# 3. Update plugin README
|
||||
vim claude-code/README.md
|
||||
# Add your skill to the "What's Included" section
|
||||
```
|
||||
|
||||
**Best for:**
|
||||
- Claude Code features (like our existing 5 skills)
|
||||
- Development workflows
|
||||
- Tool integrations
|
||||
|
||||
### Option 2: Add to claude-skills Plugin
|
||||
|
||||
Add skill-creation guidance (templates, patterns, best practices):
|
||||
|
||||
```bash
|
||||
# 1. Create skill directory
|
||||
cd claude-skills-plugin/skills
|
||||
mkdir my-skill-pattern
|
||||
|
||||
# 2. Create SKILL.md
|
||||
# Follow claude-skills format (see existing skill)
|
||||
|
||||
# 3. Update plugin README
|
||||
```
|
||||
|
||||
**Best for:**
|
||||
- New skill templates
|
||||
- Skill-creation patterns
|
||||
- Meta-guidance on skills
|
||||
|
||||
## Creating a New Plugin
|
||||
|
||||
For a collection of related skills that don't fit existing plugins:
|
||||
|
||||
### 1. Create Plugin Structure
|
||||
|
||||
```bash
|
||||
# Create plugin directory
|
||||
mkdir my-plugin
|
||||
|
||||
# Create required directories
|
||||
mkdir -p my-plugin/.claude-plugin
|
||||
mkdir -p my-plugin/skills
|
||||
|
||||
# Optional: commands, agents, hooks
|
||||
mkdir -p my-plugin/commands
|
||||
mkdir -p my-plugin/agents
|
||||
mkdir -p my-plugin/hooks
|
||||
```
|
||||
|
||||
### 2. Create plugin.json
|
||||
|
||||
```bash
|
||||
cat > my-plugin/.claude-plugin/plugin.json << 'EOF'
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"description": "Clear description of plugin purpose",
|
||||
"version": "1.0.0",
|
||||
"author": {
|
||||
"name": "Your Name",
|
||||
"email": "you@example.com"
|
||||
},
|
||||
"keywords": [
|
||||
"keyword1",
|
||||
"keyword2"
|
||||
]
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
**Required fields:**
|
||||
- `name` - Lowercase, kebab-case identifier
|
||||
- `description` - Clear, concise purpose
|
||||
- `version` - Semantic versioning (1.0.0)
|
||||
- `author.name` - Creator name
|
||||
|
||||
**Optional fields:**
|
||||
- `author.email` - Contact email
|
||||
- `author.url` - Website or profile
|
||||
- `repository` - Git repository info
|
||||
- `license` - License identifier
|
||||
- `keywords` - Search/discovery terms
|
||||
|
||||
### 3. Add Skills to Plugin
|
||||
|
||||
```bash
|
||||
# Create skill directory
|
||||
mkdir my-plugin/skills/my-skill
|
||||
|
||||
# Create SKILL.md with frontmatter
|
||||
cat > my-plugin/skills/my-skill/SKILL.md << 'EOF'
|
||||
---
|
||||
name: Skill Name
|
||||
description: [Specific description]
|
||||
---
|
||||
|
||||
# Skill content
|
||||
EOF
|
||||
```
|
||||
|
||||
### 4. Create Plugin README
|
||||
|
||||
```bash
|
||||
cat > my-plugin/README.md << 'EOF'
|
||||
# My Plugin
|
||||
|
||||
Brief description.
|
||||
|
||||
## What's Included
|
||||
|
||||
List of skills/features
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
/plugin install my-plugin@claude-skills
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
Examples of how to use
|
||||
|
||||
[More sections...]
|
||||
EOF
|
||||
```
|
||||
|
||||
### 5. Update Marketplace Manifest
|
||||
|
||||
```bash
|
||||
# Edit .claude-plugin/marketplace.json
|
||||
vim .claude-plugin/marketplace.json
|
||||
```
|
||||
|
||||
Add your plugin:
|
||||
```json
|
||||
{
|
||||
"plugins": [
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"source": "./my-plugin",
|
||||
"description": "Brief plugin description"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 6. Test Plugin Installation
|
||||
|
||||
```bash
|
||||
# Test local installation
|
||||
/plugin install /path/to/Skills/my-plugin@local
|
||||
|
||||
# Verify skills load
|
||||
# Try triggering scenarios
|
||||
```
|
||||
|
||||
## Skill Creation Guidelines
|
||||
|
||||
### Required: SKILL.md Structure
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: Skill Name (max 64 chars)
|
||||
description: Specific description with triggers (max 1024 chars)
|
||||
---
|
||||
|
||||
# Skill Name
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
- [Primary scenario]
|
||||
- [Secondary scenario]
|
||||
|
||||
Do NOT use this skill for:
|
||||
- [Confusion case]
|
||||
|
||||
## Quick Start
|
||||
|
||||
[Minimal example]
|
||||
|
||||
## Core Workflows
|
||||
|
||||
[Step-by-step guides]
|
||||
|
||||
## Examples
|
||||
|
||||
[Concrete examples]
|
||||
```
|
||||
|
||||
### Writing Effective Descriptions
|
||||
|
||||
**Template:**
|
||||
```
|
||||
[Action] [domain/task] [with/for] [capabilities].
|
||||
Use when [trigger scenario].
|
||||
[Optional: PROACTIVELY/MUST BE USED if needed]
|
||||
```
|
||||
|
||||
**Good Examples:**
|
||||
```yaml
|
||||
# Specific, clear triggers
|
||||
description: Create and structure Claude Code plugins with commands, agents, skills, hooks, and MCP servers. Use when building plugins for Claude Code, setting up plugin structure, or configuring plugin manifests.
|
||||
|
||||
# Domain-specific
|
||||
description: Optimize and troubleshoot Claude Code memory files (CLAUDE.md) for efficiency, token management, and team collaboration. Use when memory isn't loading, context is bloated, or organizing memory hierarchy.
|
||||
```
|
||||
|
||||
**Bad Examples:**
|
||||
```yaml
|
||||
# Too vague
|
||||
description: Helps with development
|
||||
|
||||
# No triggers
|
||||
description: Python tools and utilities
|
||||
```
|
||||
|
||||
### Progressive Disclosure
|
||||
|
||||
**Layer 1: Metadata (100 tokens)**
|
||||
- Skill name and description in frontmatter
|
||||
- Triggers skill selection
|
||||
|
||||
**Layer 2: SKILL.md (2000-5000 tokens)**
|
||||
- Core workflows and common examples
|
||||
- Loaded when skill activates
|
||||
|
||||
**Layer 3: Additional Files (on-demand)**
|
||||
- Detailed docs in separate .md files
|
||||
- Scripts, templates, references
|
||||
- Loaded only when needed
|
||||
|
||||
### Content Best Practices
|
||||
|
||||
**DO:**
|
||||
- Be specific, not vague
|
||||
- Use bullet points, not paragraphs
|
||||
- Include concrete, working examples
|
||||
- Provide step-by-step workflows
|
||||
- Add troubleshooting sections
|
||||
- Test trigger scenarios
|
||||
|
||||
**DON'T:**
|
||||
- Include sensitive data (API keys, credentials)
|
||||
- Use generic advice ("write good code")
|
||||
- Create novel-length content
|
||||
- Duplicate information
|
||||
- Skip testing
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before submitting:
|
||||
|
||||
### Metadata
|
||||
- [ ] Name ≤ 64 characters
|
||||
- [ ] Description ≤ 1024 characters
|
||||
- [ ] Description includes specific triggers
|
||||
- [ ] YAML frontmatter is valid
|
||||
|
||||
### Content
|
||||
- [ ] "When to Use This Skill" section present
|
||||
- [ ] At least one concrete example
|
||||
- [ ] Examples are runnable/testable
|
||||
- [ ] File references are accurate
|
||||
- [ ] No sensitive data hardcoded
|
||||
|
||||
### Testing
|
||||
- [ ] Skill triggers on target scenarios
|
||||
- [ ] Doesn't trigger on unrelated scenarios
|
||||
- [ ] Examples work as documented
|
||||
- [ ] No conflicts with existing skills
|
||||
|
||||
### Documentation
|
||||
- [ ] Plugin README updated
|
||||
- [ ] Marketplace manifest updated (if new plugin)
|
||||
- [ ] Clear installation instructions
|
||||
- [ ] Usage examples provided
|
||||
|
||||
## Testing Your Contribution
|
||||
|
||||
See [TESTING.md](./TESTING.md) for:
|
||||
- Trigger accuracy testing
|
||||
- Content quality validation
|
||||
- Token efficiency measurement
|
||||
- Team collaboration testing
|
||||
|
||||
Quick test:
|
||||
```bash
|
||||
# 1. Install locally
|
||||
/plugin install /path/to/your-plugin@local
|
||||
|
||||
# 2. Test trigger scenarios
|
||||
# Ask questions that should trigger the skill
|
||||
|
||||
# 3. Test exclusion scenarios
|
||||
# Ask questions that should NOT trigger
|
||||
|
||||
# 4. Verify quality
|
||||
# Review Claude's responses for accuracy
|
||||
```
|
||||
|
||||
## Submission Process
|
||||
|
||||
### For Small Changes (Skills to Existing Plugins)
|
||||
|
||||
1. Create skill in appropriate plugin
|
||||
2. Update plugin README
|
||||
3. Test locally
|
||||
4. Submit PR with:
|
||||
- Skill files
|
||||
- Updated README
|
||||
- Test results
|
||||
|
||||
### For New Plugins
|
||||
|
||||
1. Create complete plugin structure
|
||||
2. Update marketplace.json
|
||||
3. Create plugin README
|
||||
4. Test installation and usage
|
||||
5. Submit PR with:
|
||||
- Full plugin directory
|
||||
- Updated marketplace.json
|
||||
- Documentation
|
||||
- Test results
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Plugin Organization
|
||||
|
||||
```
|
||||
my-plugin/
|
||||
├── .claude-plugin/
|
||||
│ └── plugin.json
|
||||
├── skills/ # Related skills grouped together
|
||||
│ ├── skill-1/
|
||||
│ ├── skill-2/
|
||||
│ └── skill-3/
|
||||
├── commands/ # Optional: slash commands
|
||||
├── agents/ # Optional: subagent configs
|
||||
├── hooks/ # Optional: automation hooks
|
||||
└── README.md
|
||||
```
|
||||
|
||||
### Skill Naming Conventions
|
||||
|
||||
**For Claude Code features:**
|
||||
- `claude-code-[feature]` (e.g., claude-code-plugins)
|
||||
|
||||
**For domain-specific:**
|
||||
- `[domain]-[purpose]` (e.g., python-testing, api-documentation)
|
||||
|
||||
**For meta/general:**
|
||||
- `[category]-[action]` (e.g., skill-creator, code-reviewer)
|
||||
|
||||
### Version Bumping
|
||||
|
||||
Follow semantic versioning:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.2.3"
|
||||
}
|
||||
```
|
||||
|
||||
- **Major (1.x.x)**: Breaking changes
|
||||
- **Minor (x.2.x)**: New features, backward compatible
|
||||
- **Patch (x.x.3)**: Bug fixes
|
||||
|
||||
Update version in plugin.json when:
|
||||
- Adding new skills → Minor
|
||||
- Changing skill structure → Major
|
||||
- Fixing bugs → Patch
|
||||
|
||||
## Example: Adding a Skill
|
||||
|
||||
### Scenario: Add "claude-code-mcp" skill
|
||||
|
||||
```bash
|
||||
# 1. Navigate to plugin
|
||||
cd claude-code/skills
|
||||
|
||||
# 2. Create skill
|
||||
mkdir claude-code-mcp
|
||||
|
||||
# 3. Create SKILL.md
|
||||
cat > claude-code-mcp/SKILL.md << 'EOF'
|
||||
---
|
||||
name: Claude Code MCP Servers
|
||||
description: Configure and troubleshoot Model Context Protocol servers for Claude Code. Use when setting up MCP servers, debugging connections, or integrating external tools.
|
||||
---
|
||||
|
||||
# Claude Code MCP Server Management
|
||||
|
||||
## When to Use This Skill
|
||||
[Content here...]
|
||||
EOF
|
||||
|
||||
# 4. Update plugin README
|
||||
vim ../README.md
|
||||
# Add claude-code-mcp to "What's Included"
|
||||
|
||||
# 5. Bump version in plugin.json
|
||||
vim ../.claude-plugin/plugin.json
|
||||
# Change: "version": "1.0.0" → "1.1.0"
|
||||
|
||||
# 6. Test
|
||||
/plugin install /path/to/Skills/claude-code@local
|
||||
# Test trigger scenarios
|
||||
|
||||
# 7. Submit PR
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Never Include
|
||||
|
||||
- API keys, tokens, or credentials
|
||||
- Personal identifying information
|
||||
- Proprietary code without permission
|
||||
- Hardcoded paths to user-specific locations
|
||||
- Malicious scripts or commands
|
||||
|
||||
### Always Review
|
||||
|
||||
- External dependencies (trusted sources only)
|
||||
- File system access patterns
|
||||
- Network requests
|
||||
- Bash commands in examples
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Skill creation guidance** - Use claude-skills plugin
|
||||
- **Plugin structure questions** - Use claude-code-plugins skill
|
||||
- **Testing help** - See TESTING.md
|
||||
- **Questions** - Open an issue
|
||||
|
||||
## Resources
|
||||
|
||||
- [Agent Skills Documentation](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
|
||||
- [Plugin Documentation](https://docs.claude.com/en/docs/claude-code/plugins)
|
||||
- [claude-skills Plugin](./claude-skills-plugin/README.md)
|
||||
- [claude-code Plugin](./claude-code/README.md)
|
||||
|
||||
---
|
||||
|
||||
**Thank you for contributing!** Your skills help the entire Claude community work more effectively.
|
||||
363
README.md
Normal file
363
README.md
Normal file
@@ -0,0 +1,363 @@
|
||||
# Claude Skills Marketplace
|
||||
|
||||
A curated marketplace of Agent Skills and plugins for Claude Code and Claude.ai, designed to extend Claude's capabilities with specialized knowledge and workflows.
|
||||
|
||||
## What's in This Marketplace
|
||||
|
||||
### 🔧 claude-code Plugin
|
||||
Complete toolkit for mastering Claude Code features.
|
||||
|
||||
**Includes 5 specialized skills:**
|
||||
- **claude-code-plugins** - Create and structure plugins
|
||||
- **claude-code-slash-commands** - Build custom commands
|
||||
- **claude-code-hooks** - Set up event-driven automation
|
||||
- **claude-code-subagents** - Refine and troubleshoot subagents
|
||||
- **claude-code-memory** - Optimize CLAUDE.md files
|
||||
|
||||
[View Plugin Details](./claude-code/README.md)
|
||||
|
||||
### 📚 claude-skills Plugin
|
||||
Meta-skill for creating effective Agent Skills.
|
||||
|
||||
**Comprehensive guide covering:**
|
||||
- Progressive disclosure architecture
|
||||
- Trigger optimization techniques
|
||||
- Token efficiency strategies
|
||||
- Development workflows
|
||||
- Templates and examples
|
||||
|
||||
[View Plugin Details](./claude-skills-plugin/README.md)
|
||||
|
||||
## Quick Start
|
||||
|
||||
### For Claude Code
|
||||
|
||||
Install individual plugins from this marketplace:
|
||||
|
||||
```bash
|
||||
# Install Claude Code plugin
|
||||
/plugin install claude-code@local --path /path/to/Skills
|
||||
|
||||
# Install Claude Skills plugin
|
||||
/plugin install claude-skills@local --path /path/to/Skills
|
||||
```
|
||||
|
||||
Or configure the marketplace in your settings:
|
||||
|
||||
```json
|
||||
// ~/.claude/settings.json or .claude/settings.json
|
||||
{
|
||||
"plugin-marketplaces": {
|
||||
"claude-skills": {
|
||||
"url": "file:///path/to/Skills"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then install from the marketplace:
|
||||
|
||||
```bash
|
||||
/plugin install claude-code@claude-skills
|
||||
/plugin install claude-skills@claude-skills
|
||||
```
|
||||
|
||||
### For Claude.ai
|
||||
|
||||
Each plugin can be zipped and uploaded individually:
|
||||
|
||||
1. Zip a plugin directory (e.g., `claude-code/`)
|
||||
2. Go to Settings > Capabilities > Upload skill
|
||||
3. Upload the zip file
|
||||
4. Enable the plugin
|
||||
|
||||
## Available Plugins
|
||||
|
||||
| Plugin | Version | Skills | Description |
|
||||
|--------|---------|--------|-------------|
|
||||
| [claude-code](./claude-code/) | 1.0.0 | 5 | Complete Claude Code toolkit |
|
||||
| [claude-skills](./claude-skills-plugin/) | 1.0.0 | 1 | Skill creation meta-guide |
|
||||
|
||||
## Plugin Details
|
||||
|
||||
### claude-code
|
||||
|
||||
**Best for:** Claude Code users who want to master plugins, commands, hooks, subagents, and memory management.
|
||||
|
||||
**Skills included:**
|
||||
1. `claude-code-plugins` - Plugin development
|
||||
2. `claude-code-slash-commands` - Custom command creation
|
||||
3. `claude-code-hooks` - Event-driven automation
|
||||
4. `claude-code-subagents` - Subagent optimization
|
||||
5. `claude-code-memory` - Memory file management
|
||||
|
||||
**Installation:**
|
||||
```bash
|
||||
/plugin install claude-code@claude-skills
|
||||
```
|
||||
|
||||
### claude-skills
|
||||
|
||||
**Best for:** Anyone creating Agent Skills for Claude Code or Claude.ai.
|
||||
|
||||
**What it teaches:**
|
||||
- How to structure skills effectively
|
||||
- Writing descriptions that trigger correctly
|
||||
- Optimizing for token efficiency
|
||||
- Progressive disclosure patterns
|
||||
- Testing and validation
|
||||
|
||||
**Installation:**
|
||||
```bash
|
||||
/plugin install claude-skills@claude-skills
|
||||
```
|
||||
|
||||
## How This Marketplace Works
|
||||
|
||||
### Marketplace Structure
|
||||
|
||||
```
|
||||
claude-skills-marketplace/
|
||||
├── .claude-plugin/
|
||||
│ └── marketplace.json # Marketplace manifest
|
||||
├── claude-code/ # Plugin 1
|
||||
│ ├── .claude-plugin/
|
||||
│ │ └── plugin.json
|
||||
│ ├── skills/ # 5 Claude Code skills
|
||||
│ └── README.md
|
||||
├── claude-skills-plugin/ # Plugin 2
|
||||
│ ├── .claude-plugin/
|
||||
│ │ └── plugin.json
|
||||
│ ├── skills/ # Skill creation guide
|
||||
│ └── README.md
|
||||
├── README.md # This file
|
||||
├── CONTRIBUTING.md # How to add plugins/skills
|
||||
└── TESTING.md # Validation guide
|
||||
```
|
||||
|
||||
### Plugin Installation Flow
|
||||
|
||||
1. **Marketplace Configuration** - Add marketplace to settings
|
||||
2. **Discovery** - Claude Code reads marketplace.json
|
||||
3. **Installation** - `/plugin install [plugin-name]@[marketplace-name]`
|
||||
4. **Activation** - Skills load automatically based on context
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Working with Claude Code Features
|
||||
|
||||
```
|
||||
# Plugin development
|
||||
"Help me create a plugin for my team"
|
||||
→ claude-code-plugins skill activates
|
||||
|
||||
# Custom commands
|
||||
"I want to create a slash command for code review"
|
||||
→ claude-code-slash-commands skill activates
|
||||
|
||||
# Setting up automation
|
||||
"How do I run tests automatically after file edits?"
|
||||
→ claude-code-hooks skill activates
|
||||
|
||||
# Subagent issues
|
||||
"My security analyzer subagent isn't triggering"
|
||||
→ claude-code-subagents skill activates
|
||||
|
||||
# Memory optimization
|
||||
"My CLAUDE.md file is too long and wastes tokens"
|
||||
→ claude-code-memory skill activates
|
||||
```
|
||||
|
||||
### Creating New Skills
|
||||
|
||||
```
|
||||
"I want to create a skill for React testing"
|
||||
→ claude-skills skill activates
|
||||
→ Guides you through templates and best practices
|
||||
```
|
||||
|
||||
## Team Setup
|
||||
|
||||
Share this marketplace with your team:
|
||||
|
||||
### Option 1: Git Repository (Recommended)
|
||||
|
||||
```bash
|
||||
# Team members clone the repo
|
||||
git clone https://your-repo/claude-skills-marketplace.git
|
||||
|
||||
# Add to Claude Code settings
|
||||
# .claude/settings.json (committed to repo)
|
||||
{
|
||||
"plugin-marketplaces": {
|
||||
"team-skills": {
|
||||
"url": "file:///path/to/claude-skills-marketplace"
|
||||
}
|
||||
},
|
||||
"plugins": [
|
||||
"claude-code@team-skills",
|
||||
"claude-skills@team-skills"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Benefits:
|
||||
- Version control for skills
|
||||
- Team consistency
|
||||
- Easy updates via `git pull`
|
||||
|
||||
### Option 2: Network Share
|
||||
|
||||
```json
|
||||
{
|
||||
"plugin-marketplaces": {
|
||||
"team-skills": {
|
||||
"url": "file://network-share/claude-skills"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Option 3: Individual Installation
|
||||
|
||||
Team members install plugins locally:
|
||||
|
||||
```bash
|
||||
/plugin install /local/path/to/claude-code@local
|
||||
/plugin install /local/path/to/claude-skills@local
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### For Plugin Users
|
||||
|
||||
1. **Start with claude-skills** if you're creating skills
|
||||
2. **Install claude-code** if you use Claude Code regularly
|
||||
3. **Keep plugins updated** - Check for new versions
|
||||
4. **Test in local settings** before team-wide deployment
|
||||
|
||||
### For Skill Creators
|
||||
|
||||
1. Follow [CONTRIBUTING.md](./CONTRIBUTING.md) guidelines
|
||||
2. Test skills thoroughly (see [TESTING.md](./TESTING.md))
|
||||
3. Use progressive disclosure (keep main content lean)
|
||||
4. Include concrete examples
|
||||
5. Write specific trigger descriptions
|
||||
|
||||
### For Teams
|
||||
|
||||
1. **Share marketplace via git** for version control
|
||||
2. **Document custom workflows** in team CLAUDE.md
|
||||
3. **Create team-specific plugins** for your stack
|
||||
4. **Regular reviews** of skill effectiveness
|
||||
|
||||
## Customization
|
||||
|
||||
### Adding Your Own Plugins
|
||||
|
||||
1. Create plugin directory with structure:
|
||||
```
|
||||
your-plugin/
|
||||
├── .claude-plugin/
|
||||
│ └── plugin.json
|
||||
├── skills/
|
||||
│ └── your-skill/
|
||||
│ └── SKILL.md
|
||||
└── README.md
|
||||
```
|
||||
|
||||
2. Update marketplace.json:
|
||||
```json
|
||||
{
|
||||
"plugins": [
|
||||
{
|
||||
"name": "your-plugin",
|
||||
"source": "./your-plugin",
|
||||
"description": "Your plugin description"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
3. See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines
|
||||
|
||||
### Creating Custom Skills
|
||||
|
||||
Use the **claude-skills** plugin to guide you:
|
||||
|
||||
```
|
||||
"Help me create a skill for [your domain]"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Plugins Not Installing
|
||||
|
||||
**Check marketplace configuration:**
|
||||
```bash
|
||||
# Verify marketplace.json exists
|
||||
cat .claude-plugin/marketplace.json
|
||||
|
||||
# Check file paths are correct
|
||||
ls claude-code/.claude-plugin/plugin.json
|
||||
ls claude-skills-plugin/.claude-plugin/plugin.json
|
||||
```
|
||||
|
||||
### Skills Not Triggering
|
||||
|
||||
**Verify installation:**
|
||||
```bash
|
||||
/plugin list
|
||||
# Should show: claude-code, claude-skills
|
||||
```
|
||||
|
||||
**Check descriptions:** Skills may not match your use case
|
||||
- Read plugin READMEs for trigger scenarios
|
||||
- Try explicit skill references in prompts
|
||||
|
||||
### Updates Not Applying
|
||||
|
||||
**Reload plugins:**
|
||||
```bash
|
||||
# Restart Claude Code session
|
||||
# Or reinstall plugin
|
||||
/plugin uninstall claude-code
|
||||
/plugin install claude-code@claude-skills
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for:
|
||||
- Adding new skills
|
||||
- Improving existing skills
|
||||
- Creating new plugins
|
||||
- Documentation improvements
|
||||
- Bug reports
|
||||
|
||||
## Resources
|
||||
|
||||
### Official Documentation
|
||||
- [Agent Skills Overview](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
|
||||
- [Claude Code Plugins](https://docs.claude.com/en/docs/claude-code/plugins)
|
||||
- [Sub-agents](https://docs.claude.com/en/docs/claude-code/sub-agents)
|
||||
- [Memory Management](https://docs.claude.com/en/docs/claude-code/memory)
|
||||
|
||||
### Community
|
||||
- [Engineering Blog: Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
|
||||
- [Engineering Blog: Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)
|
||||
|
||||
## Version History
|
||||
|
||||
### 1.0.0 (Initial Release)
|
||||
- claude-code plugin (5 skills)
|
||||
- claude-skills plugin (meta-skill)
|
||||
- Marketplace infrastructure
|
||||
- Documentation and guides
|
||||
|
||||
## License
|
||||
|
||||
Individual plugins may have their own licenses. Check each plugin directory for details.
|
||||
|
||||
---
|
||||
|
||||
**Get Started**: Install the plugins, explore the skills, and level up your Claude Code workflow!
|
||||
446
TESTING.md
Normal file
446
TESTING.md
Normal file
@@ -0,0 +1,446 @@
|
||||
# Testing and Validating Skills
|
||||
|
||||
This guide helps you validate skills before adding them to the repository or using them in production.
|
||||
|
||||
## Quick Validation Checklist
|
||||
|
||||
Run through this checklist before submitting a skill:
|
||||
|
||||
```
|
||||
Metadata
|
||||
[ ] SKILL.md exists
|
||||
[ ] YAML frontmatter is valid
|
||||
[ ] Name ≤ 64 characters
|
||||
[ ] Description ≤ 1024 characters
|
||||
[ ] Description includes trigger scenarios
|
||||
|
||||
Content Quality
|
||||
[ ] "When to Use This Skill" section present
|
||||
[ ] At least one concrete example
|
||||
[ ] Examples are runnable/testable
|
||||
[ ] File references are accurate
|
||||
[ ] No sensitive data hardcoded
|
||||
|
||||
Triggering Tests
|
||||
[ ] Triggers on target scenarios
|
||||
[ ] Doesn't trigger on unrelated scenarios
|
||||
[ ] No conflicts with similar skills
|
||||
|
||||
Security
|
||||
[ ] No credentials or API keys
|
||||
[ ] No personal information
|
||||
[ ] Safe file system access only
|
||||
[ ] External dependencies verified
|
||||
```
|
||||
|
||||
## Detailed Testing Process
|
||||
|
||||
### 1. Metadata Validation
|
||||
|
||||
#### Test YAML Parsing
|
||||
|
||||
Try parsing the frontmatter:
|
||||
|
||||
```bash
|
||||
# Extract and validate YAML
|
||||
head -n 10 SKILL.md | grep -A 3 "^---$"
|
||||
```
|
||||
|
||||
Verify:
|
||||
- YAML is valid (no syntax errors)
|
||||
- Both `name` and `description` are present
|
||||
- Values are within character limits
|
||||
|
||||
#### Character Limits
|
||||
|
||||
```bash
|
||||
# Count characters in name (must be ≤ 64)
|
||||
grep "^name:" SKILL.md | sed 's/name: //' | wc -c
|
||||
|
||||
# Count characters in description (must be ≤ 1024)
|
||||
grep "^description:" SKILL.md | sed 's/description: //' | wc -c
|
||||
```
|
||||
|
||||
### 2. Content Quality Testing
|
||||
|
||||
#### Check Required Sections
|
||||
|
||||
```bash
|
||||
# Verify "When to Use This Skill" section exists
|
||||
grep -i "when to use" SKILL.md
|
||||
|
||||
# Verify examples exist
|
||||
grep -i "example" SKILL.md
|
||||
```
|
||||
|
||||
#### Test File References
|
||||
|
||||
If skill references other files, verify they exist:
|
||||
|
||||
```bash
|
||||
# Find markdown links
|
||||
grep -o '\[.*\]([^)]*\.md)' SKILL.md
|
||||
|
||||
# Check if referenced files exist
|
||||
# (manually verify each one)
|
||||
```
|
||||
|
||||
#### Validate Examples
|
||||
|
||||
For each example in the skill:
|
||||
1. Try running the code/commands
|
||||
2. Verify output matches expectations
|
||||
3. Check for edge cases
|
||||
4. Ensure examples are complete (no placeholders)
|
||||
|
||||
### 3. Trigger Testing
|
||||
|
||||
This is the most important validation step.
|
||||
|
||||
#### Create Test Scenarios
|
||||
|
||||
**Positive Tests (SHOULD trigger)**
|
||||
|
||||
Create a list of scenarios where the skill should activate:
|
||||
|
||||
```markdown
|
||||
Test Scenario 1: [Describe task that should trigger]
|
||||
Expected: Skill activates
|
||||
Actual: [Test result]
|
||||
|
||||
Test Scenario 2: [Another trigger case]
|
||||
Expected: Skill activates
|
||||
Actual: [Test result]
|
||||
```
|
||||
|
||||
**Negative Tests (SHOULD NOT trigger)**
|
||||
|
||||
Create scenarios where the skill should NOT activate:
|
||||
|
||||
```markdown
|
||||
Test Scenario 3: [Similar but different task]
|
||||
Expected: Skill does NOT activate
|
||||
Actual: [Test result]
|
||||
|
||||
Test Scenario 4: [Unrelated task]
|
||||
Expected: Skill does NOT activate
|
||||
Actual: [Test result]
|
||||
```
|
||||
|
||||
#### Example Testing Session
|
||||
|
||||
For a "Python Testing with pytest" skill:
|
||||
|
||||
**Should Trigger:**
|
||||
- "Help me write tests for my Python function"
|
||||
- "How do I use pytest fixtures?"
|
||||
- "Create unit tests for this class"
|
||||
|
||||
**Should NOT Trigger:**
|
||||
- "Help me test my JavaScript code" (different language)
|
||||
- "Debug my pytest installation" (installation, not testing)
|
||||
- "Explain what unit testing is" (concept, not implementation)
|
||||
|
||||
#### Run Tests with Claude
|
||||
|
||||
1. Load the skill
|
||||
2. Ask Claude each test question
|
||||
3. Observe if skill triggers (check response for skill context)
|
||||
4. Document results
|
||||
|
||||
### 4. Token Efficiency Testing
|
||||
|
||||
#### Measure Content Size
|
||||
|
||||
```bash
|
||||
# Count tokens (approximate: words × 1.3)
|
||||
wc -w SKILL.md
|
||||
|
||||
# Or use a proper token counter
|
||||
# (tokens ≈ characters ÷ 4 for rough estimate)
|
||||
wc -c SKILL.md
|
||||
```
|
||||
|
||||
#### Evaluate Split Points
|
||||
|
||||
Ask yourself:
|
||||
- Is content loaded only when needed?
|
||||
- Could mutually exclusive sections be split?
|
||||
- Are examples concise but complete?
|
||||
- Is reference material in separate files?
|
||||
|
||||
Target sizes:
|
||||
- **SKILL.md**: Under 3000 tokens (core workflows)
|
||||
- **Additional files**: Load only when referenced
|
||||
- **Total metadata**: ~100 tokens
|
||||
|
||||
### 5. Security Validation
|
||||
|
||||
#### Automated Checks
|
||||
|
||||
```bash
|
||||
# Check for potential secrets
|
||||
grep -iE "(password|api[_-]?key|secret|token|credential)" SKILL.md
|
||||
|
||||
# Check for hardcoded paths
|
||||
grep -E "(/Users/|/home/|C:\\\\)" SKILL.md
|
||||
|
||||
# Check for sensitive file extensions
|
||||
grep -E "\.(key|pem|cert|p12|pfx)( |$)" SKILL.md
|
||||
```
|
||||
|
||||
#### Manual Review
|
||||
|
||||
Review each file for:
|
||||
- [ ] No credentials in examples
|
||||
- [ ] No personal information
|
||||
- [ ] File paths are generic/relative
|
||||
- [ ] Network access is documented
|
||||
- [ ] External dependencies are from trusted sources
|
||||
- [ ] Scripts don't make unsafe system changes
|
||||
|
||||
### 6. Cross-Skill Conflict Testing
|
||||
|
||||
If you have multiple skills installed:
|
||||
|
||||
1. **Similar domain overlap**: Test that specific skills trigger (not generic ones)
|
||||
2. **Keyword conflicts**: Check if multiple skills trigger on same query
|
||||
3. **Description clarity**: Ensure each skill's domain is distinct
|
||||
|
||||
Example conflicts to avoid:
|
||||
- "Python Helper" (too generic) vs "Python Testing with pytest" (specific)
|
||||
- Both trigger on "Help with Python" → Fix by making descriptions more specific
|
||||
|
||||
## Testing Workflows
|
||||
|
||||
### Quick Test (5 minutes)
|
||||
|
||||
For minor updates or simple skills:
|
||||
|
||||
1. ✓ Validate metadata (YAML, character limits)
|
||||
2. ✓ Check one example works
|
||||
3. ✓ Test one positive trigger
|
||||
4. ✓ Test one negative trigger
|
||||
5. ✓ Scan for secrets
|
||||
|
||||
### Standard Test (15 minutes)
|
||||
|
||||
For new skills or significant changes:
|
||||
|
||||
1. ✓ Complete metadata validation
|
||||
2. ✓ Test all examples
|
||||
3. ✓ Run 3-5 trigger tests (positive + negative)
|
||||
4. ✓ Check token efficiency
|
||||
5. ✓ Full security review
|
||||
6. ✓ Verify file references
|
||||
|
||||
### Comprehensive Test (30+ minutes)
|
||||
|
||||
For complex skills or pre-release:
|
||||
|
||||
1. ✓ All standard tests
|
||||
2. ✓ Test with different Claude models
|
||||
3. ✓ Test conflict scenarios with other skills
|
||||
4. ✓ Have someone else try the skill
|
||||
5. ✓ Test edge cases in examples
|
||||
6. ✓ Review progressive disclosure strategy
|
||||
7. ✓ Load test (simulate typical usage)
|
||||
|
||||
## Common Issues and Fixes
|
||||
|
||||
### Skill Doesn't Trigger
|
||||
|
||||
**Symptoms**: Claude doesn't load skill context when expected
|
||||
|
||||
**Diagnose**:
|
||||
1. Description too vague?
|
||||
2. Description missing trigger keywords?
|
||||
3. Name too generic?
|
||||
|
||||
**Fix**:
|
||||
```yaml
|
||||
# Before
|
||||
description: Python development helpers
|
||||
|
||||
# After
|
||||
description: Create Python projects using Hatch and Hatchling for dependency management. Use when initializing new Python packages or configuring build systems.
|
||||
```
|
||||
|
||||
### Skill Triggers Too Often
|
||||
|
||||
**Symptoms**: Skill loads for unrelated queries
|
||||
|
||||
**Diagnose**:
|
||||
1. Description too broad?
|
||||
2. Keywords too common?
|
||||
|
||||
**Fix**:
|
||||
```yaml
|
||||
# Add specificity and exclusions
|
||||
description: Debug Swift applications using LLDB for crashes, memory issues, and runtime errors. Use when investigating Swift bugs or analyzing app behavior. NOT for general Swift coding or learning.
|
||||
```
|
||||
|
||||
### Examples Don't Work
|
||||
|
||||
**Symptoms**: Users can't reproduce examples
|
||||
|
||||
**Diagnose**:
|
||||
1. Missing prerequisites?
|
||||
2. Placeholders not explained?
|
||||
3. Environment-specific code?
|
||||
|
||||
**Fix**:
|
||||
- Add prerequisites section
|
||||
- Make examples self-contained
|
||||
- Use generic paths and values
|
||||
|
||||
### High Token Usage
|
||||
|
||||
**Symptoms**: Skill loads too much content
|
||||
|
||||
**Diagnose**:
|
||||
1. Too much in SKILL.md?
|
||||
2. No progressive disclosure?
|
||||
3. Verbose examples?
|
||||
|
||||
**Fix**:
|
||||
- Split reference material to separate files
|
||||
- Link to external resources
|
||||
- Condense examples
|
||||
- Move advanced content to on-demand files
|
||||
|
||||
## Automated Testing (Advanced)
|
||||
|
||||
For repositories with many skills, consider automation:
|
||||
|
||||
### Validate All Skills
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# validate-skills.sh
|
||||
|
||||
for skill_dir in */; do
|
||||
if [ -f "$skill_dir/SKILL.md" ]; then
|
||||
echo "Validating $skill_dir..."
|
||||
|
||||
# Check frontmatter exists
|
||||
if ! grep -q "^---$" "$skill_dir/SKILL.md"; then
|
||||
echo "❌ Missing YAML frontmatter"
|
||||
fi
|
||||
|
||||
# Check name length
|
||||
name=$(grep "^name:" "$skill_dir/SKILL.md" | sed 's/name: //')
|
||||
if [ ${#name} -gt 64 ]; then
|
||||
echo "❌ Name too long: ${#name} chars"
|
||||
fi
|
||||
|
||||
# Check for secrets
|
||||
if grep -qiE "(password|api[_-]?key|secret)" "$skill_dir/SKILL.md"; then
|
||||
echo "⚠️ Potential secrets found"
|
||||
fi
|
||||
|
||||
echo "✓ $skill_dir validated"
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
### CI/CD Integration
|
||||
|
||||
Add to GitHub Actions or similar:
|
||||
|
||||
```yaml
|
||||
name: Validate Skills
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
validate:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
- name: Run validation
|
||||
run: |
|
||||
chmod +x validate-skills.sh
|
||||
./validate-skills.sh
|
||||
```
|
||||
|
||||
## Documentation Testing
|
||||
|
||||
Ensure documentation is accurate:
|
||||
|
||||
1. **Links work**: All markdown links resolve
|
||||
2. **Paths are correct**: File references are accurate
|
||||
3. **Examples are current**: Code samples match latest versions
|
||||
4. **Formatting is consistent**: Markdown renders correctly
|
||||
|
||||
```bash
|
||||
# Check for broken internal links
|
||||
grep -r '\[.*\](.*\.md)' . | while read line; do
|
||||
# Extract and verify file exists
|
||||
# (implementation left as exercise)
|
||||
done
|
||||
```
|
||||
|
||||
## User Acceptance Testing
|
||||
|
||||
The ultimate test is real usage:
|
||||
|
||||
1. **Give skill to others**: Have colleagues test it
|
||||
2. **Monitor usage**: See when it triggers in practice
|
||||
3. **Gather feedback**: Ask users about clarity and usefulness
|
||||
4. **Iterate**: Refine based on real-world usage
|
||||
|
||||
## Testing Checklist Template
|
||||
|
||||
Copy this for each skill you test:
|
||||
|
||||
```markdown
|
||||
# Testing Report: [Skill Name]
|
||||
|
||||
Date: [YYYY-MM-DD]
|
||||
Tester: [Name]
|
||||
|
||||
## Metadata
|
||||
- [ ] YAML valid
|
||||
- [ ] Name ≤ 64 chars
|
||||
- [ ] Description ≤ 1024 chars
|
||||
- [ ] Trigger scenarios in description
|
||||
|
||||
## Content
|
||||
- [ ] "When to Use" section present
|
||||
- [ ] Examples runnable
|
||||
- [ ] File references accurate
|
||||
- [ ] No secrets
|
||||
|
||||
## Triggering
|
||||
Positive tests:
|
||||
1. [Scenario] - Result: [ ] Pass [ ] Fail
|
||||
2. [Scenario] - Result: [ ] Pass [ ] Fail
|
||||
|
||||
Negative tests:
|
||||
1. [Scenario] - Result: [ ] Pass [ ] Fail
|
||||
2. [Scenario] - Result: [ ] Pass [ ] Fail
|
||||
|
||||
## Security
|
||||
- [ ] No credentials
|
||||
- [ ] No personal data
|
||||
- [ ] Safe file access
|
||||
- [ ] Dependencies verified
|
||||
|
||||
## Overall
|
||||
- [ ] Ready for production
|
||||
- [ ] Needs revision
|
||||
- [ ] Rejected
|
||||
|
||||
Notes:
|
||||
[Any additional observations]
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- [claude-skills/SKILL.md](./claude-skills/SKILL.md) - Best practices guide
|
||||
- [claude-skills/checklist.md](./claude-skills/checklist.md) - Quality checklist
|
||||
- [CONTRIBUTING.md](./CONTRIBUTING.md) - Contribution guidelines
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Testing isn't just about finding bugs—it's about ensuring your skill provides real value and triggers at the right time.
|
||||
17
claude-code/.claude-plugin/plugin.json
Normal file
17
claude-code/.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,17 @@
|
||||
{
|
||||
"name": "claude-code",
|
||||
"description": "Comprehensive skills for mastering Claude Code features: plugins, slash commands, hooks, subagents, and memory management",
|
||||
"version": "1.0.0",
|
||||
"author": {
|
||||
"name": "Claude Skills Contributors"
|
||||
},
|
||||
"keywords": [
|
||||
"claude-code",
|
||||
"plugins",
|
||||
"slash-commands",
|
||||
"hooks",
|
||||
"subagents",
|
||||
"memory",
|
||||
"productivity"
|
||||
]
|
||||
}
|
||||
202
claude-code/README.md
Normal file
202
claude-code/README.md
Normal file
@@ -0,0 +1,202 @@
|
||||
# Claude Code Plugin
|
||||
|
||||
Comprehensive skills for mastering Claude Code features including plugins, slash commands, hooks, subagents, and memory management.
|
||||
|
||||
## What's Included
|
||||
|
||||
This plugin provides five specialized skills that help you work more effectively with Claude Code:
|
||||
|
||||
### 1. claude-code-plugins
|
||||
Create and structure Claude Code plugins with commands, agents, skills, hooks, and MCP servers.
|
||||
|
||||
**Use when:**
|
||||
- Building plugins for Claude Code
|
||||
- Setting up plugin structure
|
||||
- Configuring plugin manifests
|
||||
|
||||
### 2. claude-code-slash-commands
|
||||
Create custom slash commands with argument handling, bash execution, and file references.
|
||||
|
||||
**Use when:**
|
||||
- Building reusable prompts
|
||||
- Automating workflows
|
||||
- Creating project-specific commands
|
||||
|
||||
### 3. claude-code-hooks
|
||||
Configure event-driven hooks for automating workflows, validating code, and controlling tool execution.
|
||||
|
||||
**Use when:**
|
||||
- Setting up automation
|
||||
- Enforcing standards
|
||||
- Injecting context
|
||||
- Integrating external tools
|
||||
|
||||
### 4. claude-code-subagents
|
||||
Refine and troubleshoot Claude Code subagents by optimizing prompts, tool access, and delegation patterns.
|
||||
|
||||
**Use when:**
|
||||
- Improving existing subagents (NOT initial creation - use `/agents` command)
|
||||
- Debugging activation issues
|
||||
- Optimizing performance
|
||||
|
||||
### 5. claude-code-memory
|
||||
Optimize and troubleshoot Claude Code memory files (CLAUDE.md) for efficiency, token management, and team collaboration.
|
||||
|
||||
**Use when:**
|
||||
- Memory isn't loading
|
||||
- Context is bloated
|
||||
- Organizing memory hierarchy
|
||||
- Setting up team collaboration (NOT initial setup - use `/init` command)
|
||||
|
||||
## Installation
|
||||
|
||||
### For Claude Code
|
||||
|
||||
Install from marketplace:
|
||||
|
||||
```bash
|
||||
/plugin install claude-code@claude-skills-marketplace
|
||||
```
|
||||
|
||||
Or install from local directory:
|
||||
|
||||
```bash
|
||||
/plugin install /path/to/Skills/claude-code@local
|
||||
```
|
||||
|
||||
### For Claude.ai
|
||||
|
||||
1. Zip this plugin directory
|
||||
2. Go to Settings > Capabilities > Upload skill
|
||||
3. Upload the zip file
|
||||
4. Enable the plugin
|
||||
|
||||
## Usage
|
||||
|
||||
Once installed, these skills activate automatically when you work on related tasks:
|
||||
|
||||
- **Working on a plugin?** → claude-code-plugins skill activates
|
||||
- **Creating slash commands?** → claude-code-slash-commands skill activates
|
||||
- **Setting up hooks?** → claude-code-hooks skill activates
|
||||
- **Refining a subagent?** → claude-code-subagents skill activates
|
||||
- **Troubleshooting CLAUDE.md?** → claude-code-memory skill activates
|
||||
|
||||
You can also explicitly reference skills:
|
||||
```
|
||||
"Help me optimize my CLAUDE.md file"
|
||||
"My subagent isn't triggering correctly"
|
||||
"How do I create a hook that runs after file writes?"
|
||||
```
|
||||
|
||||
## Skills Details
|
||||
|
||||
### claude-code-plugins
|
||||
|
||||
**Covers:**
|
||||
- Plugin manifest configuration (plugin.json)
|
||||
- Component setup (commands/agents/skills/hooks)
|
||||
- Distribution and marketplace publishing
|
||||
- Best practices and troubleshooting
|
||||
|
||||
[View Details](./skills/claude-code-plugins/SKILL.md)
|
||||
|
||||
### claude-code-slash-commands
|
||||
|
||||
**Covers:**
|
||||
- Command syntax and frontmatter options
|
||||
- Argument patterns ($ARGUMENTS, $1, $2...)
|
||||
- Bash integration with ! prefix
|
||||
- File references with @ prefix
|
||||
- Complete examples and patterns
|
||||
|
||||
[View Details](./skills/claude-code-slash-commands/SKILL.md)
|
||||
|
||||
### claude-code-hooks
|
||||
|
||||
**Covers:**
|
||||
- All hook types (SessionStart, PreToolUse, PostToolUse, etc.)
|
||||
- Matcher patterns for tool filtering
|
||||
- Exit codes and control flow
|
||||
- Environment variables
|
||||
- Complete working examples
|
||||
|
||||
[View Details](./skills/claude-code-hooks/SKILL.md)
|
||||
|
||||
### claude-code-subagents
|
||||
|
||||
**Covers:**
|
||||
- Common problems and solutions
|
||||
- System prompt optimization
|
||||
- Tool access strategies
|
||||
- Model selection guide
|
||||
- Testing and validation
|
||||
- Migration from ad-hoc prompts
|
||||
|
||||
[View Details](./skills/claude-code-subagents/SKILL.md)
|
||||
|
||||
### claude-code-memory
|
||||
|
||||
**Covers:**
|
||||
- Memory hierarchy (project/user/subfolder)
|
||||
- Token management and optimization
|
||||
- Import system (@path/to/file)
|
||||
- Team collaboration patterns
|
||||
- Troubleshooting loading issues
|
||||
- Template examples
|
||||
|
||||
[View Details](./skills/claude-code-memory/SKILL.md)
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Initial Setup
|
||||
1. Use built-in commands first:
|
||||
- `/init` for memory setup
|
||||
- `/agents` for subagent creation
|
||||
2. Use these skills to refine and optimize afterward
|
||||
|
||||
### Progressive Learning
|
||||
Start with one skill at a time:
|
||||
1. Begin with **memory** - establish good context management
|
||||
2. Add **slash commands** for common workflows
|
||||
3. Implement **hooks** for automation
|
||||
4. Create **subagents** for specialized tasks
|
||||
5. Package everything in **plugins** for reusability
|
||||
|
||||
### Team Collaboration
|
||||
- Share this plugin with your team for consistent workflows
|
||||
- Use memory files for team standards
|
||||
- Create project-specific slash commands
|
||||
- Document subagent usage patterns
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Skills not activating?**
|
||||
- Verify plugin is installed: `/plugin list`
|
||||
- Check descriptions match your use case
|
||||
- Try explicit skill references in prompts
|
||||
|
||||
**Need help with specific features?**
|
||||
- Memory issues → Use claude-code-memory skill
|
||||
- Subagent problems → Use claude-code-subagents skill
|
||||
- Hook debugging → Use claude-code-hooks skill
|
||||
|
||||
## Version History
|
||||
|
||||
### 1.0.0 (Initial Release)
|
||||
- claude-code-plugins skill
|
||||
- claude-code-slash-commands skill
|
||||
- claude-code-hooks skill
|
||||
- claude-code-subagents skill
|
||||
- claude-code-memory skill
|
||||
|
||||
## Contributing
|
||||
|
||||
Found an issue or have improvements? See the main marketplace [CONTRIBUTING.md](../CONTRIBUTING.md).
|
||||
|
||||
## License
|
||||
|
||||
See main marketplace repository for license information.
|
||||
|
||||
---
|
||||
|
||||
**Remember**: These skills are for refinement and troubleshooting. Use Claude Code's built-in commands (`/init`, `/agents`, `/memory`) for initial setup, then use these skills to optimize.
|
||||
1049
claude-code/skills/claude-code-hooks/SKILL.md
Normal file
1049
claude-code/skills/claude-code-hooks/SKILL.md
Normal file
File diff suppressed because it is too large
Load Diff
1032
claude-code/skills/claude-code-memory/SKILL.md
Normal file
1032
claude-code/skills/claude-code-memory/SKILL.md
Normal file
File diff suppressed because it is too large
Load Diff
546
claude-code/skills/claude-code-plugins/SKILL.md
Normal file
546
claude-code/skills/claude-code-plugins/SKILL.md
Normal file
@@ -0,0 +1,546 @@
|
||||
---
|
||||
name: Claude Code Plugin Developer
|
||||
description: Create and structure Claude Code plugins with commands, agents, skills, hooks, and MCP servers. Use when building plugins for Claude Code, setting up plugin structure, or configuring plugin manifests.
|
||||
---
|
||||
|
||||
# Claude Code Plugin Development
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
- Creating a new Claude Code plugin from scratch
|
||||
- Adding components to an existing plugin (commands, agents, skills, hooks)
|
||||
- Configuring plugin manifests and metadata
|
||||
- Setting up plugin distribution and marketplaces
|
||||
- Troubleshooting plugin structure or installation issues
|
||||
|
||||
Do NOT use this skill for:
|
||||
- Creating standalone MCP servers (use MCP-specific documentation)
|
||||
- General Claude Code usage (not plugin development)
|
||||
- Creating individual skills without plugin context
|
||||
|
||||
## Quick Start: Creating a Plugin
|
||||
|
||||
### 1. Basic Plugin Structure
|
||||
|
||||
```bash
|
||||
# Create plugin directory
|
||||
mkdir my-plugin
|
||||
cd my-plugin
|
||||
|
||||
# Create required manifest directory
|
||||
mkdir -p .claude-plugin
|
||||
|
||||
# Create plugin.json manifest
|
||||
cat > .claude-plugin/plugin.json << 'EOF'
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"description": "Description of what your plugin does",
|
||||
"version": "1.0.0",
|
||||
"author": {
|
||||
"name": "Your Name"
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
### 2. Add Component Directories
|
||||
|
||||
```bash
|
||||
# Create directories for plugin components
|
||||
mkdir -p commands # Slash commands
|
||||
mkdir -p agents # Custom agents
|
||||
mkdir -p skills # Agent Skills
|
||||
mkdir -p hooks # Event handlers
|
||||
```
|
||||
|
||||
**Result**: Basic plugin structure ready for adding components.
|
||||
|
||||
## Plugin Manifest (plugin.json)
|
||||
|
||||
### Required Fields
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "plugin-name", // Lowercase, kebab-case
|
||||
"description": "What it does", // Clear, concise description
|
||||
"version": "1.0.0", // Semantic versioning
|
||||
"author": {
|
||||
"name": "Author Name" // Your name or organization
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Optional Fields
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-plugin",
|
||||
"description": "Advanced features",
|
||||
"version": "1.2.0",
|
||||
"author": {
|
||||
"name": "Your Name",
|
||||
"email": "you@example.com",
|
||||
"url": "https://yoursite.com"
|
||||
},
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/user/repo"
|
||||
},
|
||||
"license": "MIT",
|
||||
"keywords": ["productivity", "automation"]
|
||||
}
|
||||
```
|
||||
|
||||
## Plugin Components
|
||||
|
||||
### 1. Commands (Slash Commands)
|
||||
|
||||
Create markdown files in `commands/` directory:
|
||||
|
||||
```bash
|
||||
# commands/review-security.md
|
||||
---
|
||||
description: Review code for security vulnerabilities
|
||||
allowed-tools: Read(*), Grep(*)
|
||||
---
|
||||
|
||||
Review the following files for common security issues:
|
||||
- SQL injection vulnerabilities
|
||||
- XSS vulnerabilities
|
||||
- Hardcoded credentials
|
||||
- Unsafe deserialization
|
||||
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
**Usage**: `/review-security @src/auth.js`
|
||||
|
||||
### 2. Agents
|
||||
|
||||
Create agent configurations in `agents/` directory:
|
||||
|
||||
```bash
|
||||
# agents/code-reviewer.md
|
||||
---
|
||||
description: Reviews code for best practices
|
||||
tools: [Read, Grep, Bash]
|
||||
model: claude-sonnet-4
|
||||
---
|
||||
|
||||
You are a code review specialist. When reviewing code:
|
||||
1. Check for common patterns and anti-patterns
|
||||
2. Verify error handling
|
||||
3. Look for security issues
|
||||
4. Suggest improvements
|
||||
```
|
||||
|
||||
### 3. Skills
|
||||
|
||||
Create skill directories in `skills/`:
|
||||
|
||||
```bash
|
||||
mkdir -p skills/my-skill
|
||||
# Then create skills/my-skill/SKILL.md with proper frontmatter
|
||||
```
|
||||
|
||||
See the `claude-skills` skill for comprehensive skill creation guidance.
|
||||
|
||||
### 4. Hooks
|
||||
|
||||
Create `hooks/hooks.json` to define event handlers:
|
||||
|
||||
```json
|
||||
{
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Edit|Write",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "echo 'File modified: $TOOL_ARGS' >> .claude/activity.log"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 5. MCP Servers
|
||||
|
||||
Create `.mcp.json` for external tools:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-server": {
|
||||
"command": "node",
|
||||
"args": ["server.js"],
|
||||
"env": {
|
||||
"API_KEY": "env:MY_API_KEY"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Complete Plugin Example
|
||||
|
||||
### File Structure
|
||||
|
||||
```
|
||||
weather-plugin/
|
||||
├── .claude-plugin/
|
||||
│ └── plugin.json
|
||||
├── commands/
|
||||
│ └── weather.md
|
||||
├── agents/
|
||||
│ └── forecast-analyst.md
|
||||
├── skills/
|
||||
│ └── weather-api/
|
||||
│ └── SKILL.md
|
||||
└── README.md
|
||||
```
|
||||
|
||||
### plugin.json
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "weather-plugin",
|
||||
"description": "Weather forecasting and analysis tools",
|
||||
"version": "1.0.0",
|
||||
"author": {
|
||||
"name": "Weather Team"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### commands/weather.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Get current weather for a location
|
||||
argument-hint: <location>
|
||||
---
|
||||
|
||||
Get the current weather conditions for: $ARGUMENTS
|
||||
|
||||
Include:
|
||||
- Temperature
|
||||
- Conditions
|
||||
- Humidity
|
||||
- Wind speed
|
||||
```
|
||||
|
||||
### agents/forecast-analyst.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Analyzes weather patterns and forecasts
|
||||
tools: [WebFetch, Read]
|
||||
---
|
||||
|
||||
You are a weather analysis specialist. When asked about weather:
|
||||
1. Gather current conditions
|
||||
2. Analyze patterns
|
||||
3. Provide forecast insights
|
||||
4. Suggest appropriate actions
|
||||
```
|
||||
|
||||
## Distribution & Installation
|
||||
|
||||
### Local Development
|
||||
|
||||
Test your plugin locally:
|
||||
|
||||
```bash
|
||||
# Install from local directory
|
||||
/plugin install /path/to/my-plugin@local
|
||||
|
||||
# Verify installation
|
||||
/plugin list
|
||||
```
|
||||
|
||||
### Development Marketplace
|
||||
|
||||
Create a development marketplace for testing:
|
||||
|
||||
```json
|
||||
// ~/.claude/settings.json
|
||||
{
|
||||
"plugin-marketplaces": {
|
||||
"dev": {
|
||||
"url": "file:///path/to/marketplace-dir"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Team Distribution
|
||||
|
||||
Add to project settings for automatic installation:
|
||||
|
||||
```json
|
||||
// .claude/settings.json
|
||||
{
|
||||
"plugins": [
|
||||
"my-plugin@company-marketplace"
|
||||
],
|
||||
"plugin-marketplaces": {
|
||||
"company-marketplace": {
|
||||
"url": "https://plugins.company.com"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Plugin Design
|
||||
|
||||
1. **Single responsibility**: Each plugin should have a focused purpose
|
||||
2. **Clear naming**: Use descriptive, kebab-case names
|
||||
3. **Semantic versioning**: Follow SemVer for version numbers
|
||||
4. **Documentation**: Include comprehensive README.md
|
||||
|
||||
### Directory Organization
|
||||
|
||||
```
|
||||
my-plugin/
|
||||
├── .claude-plugin/ # Manifest only
|
||||
│ └── plugin.json
|
||||
├── commands/ # At plugin root, not in .claude-plugin/
|
||||
├── agents/ # At plugin root
|
||||
├── skills/ # At plugin root
|
||||
└── README.md # Usage documentation
|
||||
```
|
||||
|
||||
**IMPORTANT**: Component directories go at the plugin root, NOT inside `.claude-plugin/`
|
||||
|
||||
### Testing Checklist
|
||||
|
||||
- [ ] Plugin.json is valid JSON
|
||||
- [ ] All required fields present
|
||||
- [ ] Component directories at plugin root
|
||||
- [ ] Commands have valid frontmatter
|
||||
- [ ] Skills follow proper structure
|
||||
- [ ] Local installation works
|
||||
- [ ] No sensitive data in files
|
||||
- [ ] README documents all features
|
||||
|
||||
### Version Management
|
||||
|
||||
```bash
|
||||
# Update version in plugin.json
|
||||
{
|
||||
"version": "1.1.0" // Increment for changes
|
||||
}
|
||||
|
||||
# Breaking changes: 2.0.0
|
||||
# New features: 1.1.0
|
||||
# Bug fixes: 1.0.1
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Multi-Command Plugin
|
||||
|
||||
For related commands, use subdirectories:
|
||||
|
||||
```
|
||||
git-tools/
|
||||
├── .claude-plugin/plugin.json
|
||||
└── commands/
|
||||
├── commit.md
|
||||
├── pr.md
|
||||
└── review.md
|
||||
```
|
||||
|
||||
**Usage**: `/commit`, `/pr`, `/review`
|
||||
|
||||
### Agent + Skill Combination
|
||||
|
||||
Combine agents with specialized skills:
|
||||
|
||||
```
|
||||
api-plugin/
|
||||
├── .claude-plugin/plugin.json
|
||||
├── agents/
|
||||
│ └── api-specialist.md
|
||||
└── skills/
|
||||
└── rest-api/
|
||||
└── SKILL.md
|
||||
```
|
||||
|
||||
The agent can leverage the skill for specialized knowledge.
|
||||
|
||||
### Hook-Based Automation
|
||||
|
||||
Use hooks for workflow automation:
|
||||
|
||||
```json
|
||||
{
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "npm run format $TOOL_ARGS"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Plugin Not Found
|
||||
|
||||
**Issue**: `/plugin install` can't find plugin
|
||||
|
||||
**Solutions**:
|
||||
1. Check marketplace configuration in settings.json
|
||||
2. Verify plugin name matches directory name
|
||||
3. Ensure plugin.json exists in `.claude-plugin/`
|
||||
|
||||
### Commands Not Available
|
||||
|
||||
**Issue**: Slash commands don't appear
|
||||
|
||||
**Solutions**:
|
||||
1. Verify commands are in `commands/` at plugin root
|
||||
2. Check markdown files have `.md` extension
|
||||
3. Restart Claude Code to refresh
|
||||
|
||||
### Invalid Structure Error
|
||||
|
||||
**Issue**: Plugin fails to load
|
||||
|
||||
**Solutions**:
|
||||
1. Ensure `.claude-plugin/plugin.json` exists
|
||||
2. Validate JSON syntax
|
||||
3. Move component directories to plugin root (not in `.claude-plugin/`)
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Never Include
|
||||
|
||||
- API keys or credentials in plugin files
|
||||
- Personal identifying information
|
||||
- Proprietary code without permission
|
||||
- Hardcoded paths to user-specific locations
|
||||
|
||||
### Use Environment Variables
|
||||
|
||||
```json
|
||||
// .mcp.json
|
||||
{
|
||||
"mcpServers": {
|
||||
"api-server": {
|
||||
"env": {
|
||||
"API_KEY": "env:MY_API_KEY" // Reference env var
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Command Permissions
|
||||
|
||||
Limit tool access in command frontmatter:
|
||||
|
||||
```markdown
|
||||
---
|
||||
allowed-tools: Read(src/**), Grep(src/**)
|
||||
---
|
||||
```
|
||||
|
||||
## Plugin Template
|
||||
|
||||
Use this as a starting point:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# create-plugin.sh <plugin-name>
|
||||
|
||||
PLUGIN_NAME=$1
|
||||
|
||||
mkdir -p "$PLUGIN_NAME"/{.claude-plugin,commands,agents,skills,hooks}
|
||||
|
||||
cat > "$PLUGIN_NAME/.claude-plugin/plugin.json" << EOF
|
||||
{
|
||||
"name": "$PLUGIN_NAME",
|
||||
"description": "TODO: Add description",
|
||||
"version": "0.1.0",
|
||||
"author": {
|
||||
"name": "TODO: Add author"
|
||||
}
|
||||
}
|
||||
EOF
|
||||
|
||||
cat > "$PLUGIN_NAME/README.md" << EOF
|
||||
# $PLUGIN_NAME
|
||||
|
||||
TODO: Add plugin description
|
||||
|
||||
## Installation
|
||||
|
||||
\`\`\`
|
||||
/plugin install $PLUGIN_NAME@marketplace
|
||||
\`\`\`
|
||||
|
||||
## Features
|
||||
|
||||
TODO: List features
|
||||
|
||||
## Usage
|
||||
|
||||
TODO: Add usage examples
|
||||
EOF
|
||||
|
||||
echo "Plugin structure created in $PLUGIN_NAME/"
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- [Official Plugin Documentation](https://docs.claude.com/en/docs/claude-code/plugins)
|
||||
- [Slash Commands Guide](../claude-code-slash-commands/SKILL.md)
|
||||
- [Hooks Guide](../claude-code-hooks/SKILL.md)
|
||||
- [Agent Skills Guide](../claude-skills/SKILL.md)
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Required Structure
|
||||
```
|
||||
plugin-name/
|
||||
└── .claude-plugin/
|
||||
└── plugin.json
|
||||
```
|
||||
|
||||
### Common Commands
|
||||
```bash
|
||||
# Install
|
||||
/plugin install plugin-name@marketplace
|
||||
|
||||
# List installed
|
||||
/plugin list
|
||||
|
||||
# Uninstall
|
||||
/plugin uninstall plugin-name
|
||||
```
|
||||
|
||||
### Manifest Template
|
||||
```json
|
||||
{
|
||||
"name": "plugin-name",
|
||||
"description": "What it does",
|
||||
"version": "1.0.0",
|
||||
"author": {"name": "Your Name"}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Plugins extend Claude Code with persistent, reusable functionality. Start simple with one or two components, test thoroughly, then expand based on actual needs.
|
||||
698
claude-code/skills/claude-code-slash-commands/SKILL.md
Normal file
698
claude-code/skills/claude-code-slash-commands/SKILL.md
Normal file
@@ -0,0 +1,698 @@
|
||||
---
|
||||
name: Slash Command Creator
|
||||
description: Create custom slash commands for Claude Code with argument handling, bash execution, and file references. Use when building reusable prompts, automating workflows, or creating project-specific commands.
|
||||
---
|
||||
|
||||
# Slash Command Development
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
- Creating custom slash commands for Claude Code
|
||||
- Building reusable prompt templates
|
||||
- Automating repetitive tasks with commands
|
||||
- Setting up project-specific workflows
|
||||
- Converting manual prompts to slash commands
|
||||
|
||||
Do NOT use this skill for:
|
||||
- Creating full plugins (use claude-code-plugins skill)
|
||||
- Setting up hooks (use claude-code-hooks skill)
|
||||
- General Claude Code usage
|
||||
|
||||
## Quick Start: Creating a Command
|
||||
|
||||
### 1. Create Command File
|
||||
|
||||
```bash
|
||||
# Project-specific command (shared with team)
|
||||
mkdir -p .claude/commands
|
||||
cat > .claude/commands/review.md << 'EOF'
|
||||
---
|
||||
description: Review code for common issues
|
||||
---
|
||||
|
||||
Review the following code for:
|
||||
- Bugs and logic errors
|
||||
- Code style issues
|
||||
- Performance problems
|
||||
- Security vulnerabilities
|
||||
|
||||
$ARGUMENTS
|
||||
EOF
|
||||
```
|
||||
|
||||
**Usage**: `/review @src/main.js`
|
||||
|
||||
### 2. Personal Command (Your Use Only)
|
||||
|
||||
```bash
|
||||
# Personal command (not shared)
|
||||
mkdir -p ~/.claude/commands
|
||||
cat > ~/.claude/commands/explain.md << 'EOF'
|
||||
---
|
||||
description: Explain code in detail
|
||||
argument-hint: <file-path>
|
||||
---
|
||||
|
||||
Provide a detailed explanation of: $ARGUMENTS
|
||||
|
||||
Include:
|
||||
- What the code does
|
||||
- How it works
|
||||
- Key design decisions
|
||||
- Potential improvements
|
||||
EOF
|
||||
```
|
||||
|
||||
**Usage**: `/explain @utils/parser.ts`
|
||||
|
||||
## Command Locations
|
||||
|
||||
### Project Commands (.claude/commands/)
|
||||
|
||||
**Location**: `.claude/commands/` in your project
|
||||
**Scope**: Available to everyone working on the project
|
||||
**Version Control**: Commit to git for team sharing
|
||||
**Use For**: Project-specific workflows, team standards
|
||||
|
||||
### Personal Commands (~/.claude/commands/)
|
||||
|
||||
**Location**: `~/.claude/commands/`
|
||||
**Scope**: Available in all your projects
|
||||
**Version Control**: Not in git (user-specific)
|
||||
**Use For**: Personal productivity, custom preferences
|
||||
|
||||
## Command Syntax
|
||||
|
||||
### Basic Structure
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Brief description for /help
|
||||
---
|
||||
|
||||
Prompt content here
|
||||
```
|
||||
|
||||
### Command Name
|
||||
|
||||
The filename (without `.md`) becomes the command:
|
||||
|
||||
```bash
|
||||
# File: .claude/commands/test.md
|
||||
# Command: /test
|
||||
|
||||
# File: .claude/commands/commit-push.md
|
||||
# Command: /commit-push
|
||||
```
|
||||
|
||||
## Frontmatter Options
|
||||
|
||||
### description
|
||||
|
||||
Shows in `/help` output:
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: Generate unit tests for a function
|
||||
---
|
||||
```
|
||||
|
||||
### argument-hint
|
||||
|
||||
Shows expected arguments in autocomplete:
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: Compare two files
|
||||
argument-hint: <file1> <file2>
|
||||
---
|
||||
```
|
||||
|
||||
### allowed-tools
|
||||
|
||||
Specifies which tools the command can use:
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: Review and commit changes
|
||||
allowed-tools: Bash(git status:*), Bash(git add:*), Bash(git commit:*)
|
||||
---
|
||||
```
|
||||
|
||||
**Patterns**:
|
||||
- `Bash(git status:*)` - Specific command with any args
|
||||
- `Read(*)` - Tool with any args
|
||||
- `*` - All tools allowed
|
||||
|
||||
### model
|
||||
|
||||
Override default model for this command:
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: Simple task
|
||||
model: claude-haiku-4
|
||||
---
|
||||
```
|
||||
|
||||
### disable-model-invocation
|
||||
|
||||
Prevent SlashCommand tool from calling this:
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: Internal helper command
|
||||
disable-model-invocation: true
|
||||
---
|
||||
```
|
||||
|
||||
## Argument Handling
|
||||
|
||||
### $ARGUMENTS - All Arguments
|
||||
|
||||
Captures everything passed to the command:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Explain multiple files
|
||||
---
|
||||
|
||||
Explain these files: $ARGUMENTS
|
||||
```
|
||||
|
||||
**Usage**: `/explain @src/a.js @src/b.js @src/c.js`
|
||||
**Result**: All three file paths captured
|
||||
|
||||
### Positional Arguments ($1, $2, $3...)
|
||||
|
||||
Individual arguments like shell scripts:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Compare two approaches
|
||||
argument-hint: <approach1> <approach2>
|
||||
---
|
||||
|
||||
Compare approach "$1" versus "$2" and recommend which is better.
|
||||
```
|
||||
|
||||
**Usage**: `/compare REST GraphQL`
|
||||
**$1** = "REST"
|
||||
**$2** = "GraphQL"
|
||||
|
||||
### Combining Arguments
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Test specific function
|
||||
argument-hint: <file> <function-name>
|
||||
---
|
||||
|
||||
In file $1, create comprehensive tests for the function: $2
|
||||
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
## File References with @
|
||||
|
||||
### Single File
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Review a file
|
||||
---
|
||||
|
||||
Review @$1 for code quality issues.
|
||||
```
|
||||
|
||||
**Usage**: `/review src/auth.js`
|
||||
Claude will read `src/auth.js` automatically
|
||||
|
||||
### Multiple Files
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Compare implementations
|
||||
---
|
||||
|
||||
Compare the implementation approaches in:
|
||||
$ARGUMENTS
|
||||
|
||||
Which approach is better and why?
|
||||
```
|
||||
|
||||
**Usage**: `/compare @old/version.js @new/version.js`
|
||||
|
||||
### Inline File References
|
||||
|
||||
```markdown
|
||||
Review @src/config.js and ensure it follows @docs/style-guide.md
|
||||
```
|
||||
|
||||
The `@` prefix tells Claude to read those files before processing.
|
||||
|
||||
## Bash Execution with !
|
||||
|
||||
### Prefix Commands with !
|
||||
|
||||
Run bash before the slash command executes:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Show git status and suggest next steps
|
||||
allowed-tools: Bash(git status:*), Bash(git diff:*)
|
||||
---
|
||||
|
||||
!git status
|
||||
!git diff --stat
|
||||
|
||||
Based on the current git state, suggest what I should do next.
|
||||
```
|
||||
|
||||
**Important**: Must include `allowed-tools` with Bash tool specification.
|
||||
|
||||
### Why Use ! Prefix?
|
||||
|
||||
Without `!`, bash commands are just text in the prompt.
|
||||
With `!`, they execute and results are included in context.
|
||||
|
||||
```markdown
|
||||
# This doesn't work (just text):
|
||||
git status
|
||||
What should I commit?
|
||||
|
||||
# This works (executes first):
|
||||
---
|
||||
allowed-tools: Bash(git status:*)
|
||||
---
|
||||
|
||||
!git status
|
||||
What should I commit?
|
||||
```
|
||||
|
||||
## Namespacing with Directories
|
||||
|
||||
### Organize Related Commands
|
||||
|
||||
```
|
||||
.claude/commands/
|
||||
├── git/
|
||||
│ ├── commit.md
|
||||
│ ├── review.md
|
||||
│ └── sync.md
|
||||
└── test/
|
||||
├── unit.md
|
||||
└── integration.md
|
||||
```
|
||||
|
||||
**Commands**: `/commit`, `/review`, `/sync`, `/unit`, `/integration`
|
||||
|
||||
**Note**: Directory structure is for organization only - it doesn't affect command names.
|
||||
|
||||
## Complete Examples
|
||||
|
||||
### 1. Security Review Command
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Comprehensive security review of code files
|
||||
allowed-tools: Read(*), Grep(*), Bash(grep:*)
|
||||
argument-hint: <files...>
|
||||
---
|
||||
|
||||
Perform a security audit on: $ARGUMENTS
|
||||
|
||||
Check for:
|
||||
1. SQL injection vulnerabilities
|
||||
2. XSS vulnerabilities
|
||||
3. Authentication/authorization issues
|
||||
4. Hardcoded secrets or credentials
|
||||
5. Unsafe deserialization
|
||||
6. Path traversal vulnerabilities
|
||||
7. Insecure cryptography
|
||||
8. Information disclosure
|
||||
|
||||
For each issue found:
|
||||
- Severity level (Critical/High/Medium/Low)
|
||||
- Location (file:line)
|
||||
- Explanation of the vulnerability
|
||||
- Recommended fix with code example
|
||||
```
|
||||
|
||||
**Usage**: `/security-review @src/auth.js @src/api.js`
|
||||
|
||||
### 2. Commit + Push Command
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Review changes, commit, and push to remote
|
||||
allowed-tools: Bash(git:*)
|
||||
---
|
||||
|
||||
!git status
|
||||
!git diff
|
||||
|
||||
Review the changes above and:
|
||||
1. Create an appropriate commit message
|
||||
2. Commit the changes
|
||||
3. Push to remote
|
||||
|
||||
Ask for confirmation before pushing.
|
||||
```
|
||||
|
||||
**Usage**: `/commit-push`
|
||||
|
||||
### 3. Test Generator
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Generate comprehensive tests for a function
|
||||
argument-hint: <file> <function-name>
|
||||
model: claude-sonnet-4
|
||||
---
|
||||
|
||||
For the function "$2" in @$1:
|
||||
|
||||
1. Analyze the function's behavior
|
||||
2. Identify edge cases
|
||||
3. Generate comprehensive unit tests including:
|
||||
- Happy path tests
|
||||
- Edge case tests
|
||||
- Error condition tests
|
||||
- Boundary value tests
|
||||
|
||||
Use the project's existing test framework and patterns.
|
||||
```
|
||||
|
||||
**Usage**: `/test-gen src/parser.js parseQuery`
|
||||
|
||||
### 4. API Documentation
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Generate API documentation for endpoints
|
||||
allowed-tools: Read(*), Grep(*)
|
||||
---
|
||||
|
||||
Generate API documentation for: $ARGUMENTS
|
||||
|
||||
Include:
|
||||
- Endpoint URL and method
|
||||
- Request parameters (query, body, headers)
|
||||
- Response format and status codes
|
||||
- Example requests and responses
|
||||
- Error conditions
|
||||
- Authentication requirements
|
||||
|
||||
Format as OpenAPI/Swagger compatible YAML.
|
||||
```
|
||||
|
||||
**Usage**: `/api-docs @routes/users.js @routes/posts.js`
|
||||
|
||||
### 5. Performance Analysis
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Analyze code for performance issues
|
||||
argument-hint: <file>
|
||||
---
|
||||
|
||||
Analyze @$1 for performance issues:
|
||||
|
||||
1. **Time Complexity**: Identify algorithms and their complexity
|
||||
2. **Space Complexity**: Memory usage patterns
|
||||
3. **Bottlenecks**: Potential performance problems
|
||||
4. **Optimization Opportunities**: Specific improvements with examples
|
||||
|
||||
For each issue:
|
||||
- Current implementation
|
||||
- Why it's problematic
|
||||
- Optimized version
|
||||
- Performance impact estimate
|
||||
```
|
||||
|
||||
**Usage**: `/perf @src/data-processor.js`
|
||||
|
||||
## Command Patterns
|
||||
|
||||
### Review Pattern
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Review X for Y
|
||||
---
|
||||
|
||||
Review $ARGUMENTS for [specific criteria]
|
||||
|
||||
Include:
|
||||
- [Aspect 1]
|
||||
- [Aspect 2]
|
||||
- [Aspect 3]
|
||||
```
|
||||
|
||||
### Generate Pattern
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Generate X from Y
|
||||
---
|
||||
|
||||
Generate [output type] for: $ARGUMENTS
|
||||
|
||||
Requirements:
|
||||
- [Requirement 1]
|
||||
- [Requirement 2]
|
||||
```
|
||||
|
||||
### Compare Pattern
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Compare X and Y
|
||||
argument-hint: <option1> <option2>
|
||||
---
|
||||
|
||||
Compare "$1" versus "$2"
|
||||
|
||||
Analyze:
|
||||
- [Comparison aspect 1]
|
||||
- [Comparison aspect 2]
|
||||
|
||||
Recommendation: [Which is better and why]
|
||||
```
|
||||
|
||||
### Workflow Pattern
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Execute multi-step workflow
|
||||
allowed-tools: Bash(*), Read(*), Write(*)
|
||||
---
|
||||
|
||||
Execute the following workflow:
|
||||
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
|
||||
After each step, confirm before proceeding.
|
||||
```
|
||||
|
||||
## Testing Commands
|
||||
|
||||
### 1. Check Command List
|
||||
|
||||
```bash
|
||||
# See all available commands
|
||||
/help
|
||||
|
||||
# Your command should appear in the list
|
||||
```
|
||||
|
||||
### 2. Test Argument Handling
|
||||
|
||||
```bash
|
||||
# Test with different argument patterns
|
||||
/mycommand arg1
|
||||
/mycommand arg1 arg2
|
||||
/mycommand @file.js
|
||||
/mycommand @file1.js @file2.js
|
||||
```
|
||||
|
||||
### 3. Verify Bash Execution
|
||||
|
||||
If using `!` prefix, confirm commands execute:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Test bash execution
|
||||
allowed-tools: Bash(echo:*)
|
||||
---
|
||||
|
||||
!echo "This should show before prompt processing"
|
||||
|
||||
Did the echo work?
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Clear Descriptions
|
||||
|
||||
```yaml
|
||||
# Good
|
||||
description: Generate unit tests for a specific function
|
||||
|
||||
# Bad
|
||||
description: Testing
|
||||
```
|
||||
|
||||
### 2. Explicit Arguments
|
||||
|
||||
```yaml
|
||||
# Good
|
||||
argument-hint: <file-path> <function-name>
|
||||
|
||||
# Bad (no hint)
|
||||
argument-hint:
|
||||
```
|
||||
|
||||
### 3. Specific Tool Permissions
|
||||
|
||||
```yaml
|
||||
# Good - minimal permissions
|
||||
allowed-tools: Bash(git status:*), Bash(git diff:*)
|
||||
|
||||
# Risky - too permissive
|
||||
allowed-tools: *
|
||||
```
|
||||
|
||||
### 4. Meaningful Names
|
||||
|
||||
```bash
|
||||
# Good
|
||||
/generate-tests
|
||||
/review-security
|
||||
/commit-and-push
|
||||
|
||||
# Bad
|
||||
/gt
|
||||
/rs
|
||||
/cap
|
||||
```
|
||||
|
||||
### 5. Self-Documenting Content
|
||||
|
||||
```markdown
|
||||
Review code for:
|
||||
1. Logic errors
|
||||
2. Style issues
|
||||
3. Performance problems
|
||||
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
Better than:
|
||||
|
||||
```markdown
|
||||
Review: $ARGUMENTS
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Command Not Found
|
||||
|
||||
**Issue**: `/mycommand` says command not found
|
||||
|
||||
**Solutions**:
|
||||
1. Check file is in `.claude/commands/` or `~/.claude/commands/`
|
||||
2. Verify filename ends with `.md`
|
||||
3. Restart Claude Code to refresh command list
|
||||
|
||||
### Arguments Not Working
|
||||
|
||||
**Issue**: `$ARGUMENTS` or `$1` showing literally
|
||||
|
||||
**Solutions**:
|
||||
1. Ensure proper syntax: `$ARGUMENTS`, `$1`, `$2` (not `${ARGUMENTS}`)
|
||||
2. Check for typos in variable names
|
||||
3. Test with simple command first
|
||||
|
||||
### Bash Commands Not Executing
|
||||
|
||||
**Issue**: `!command` not running
|
||||
|
||||
**Solutions**:
|
||||
1. Add `allowed-tools` to frontmatter
|
||||
2. Include specific tool pattern: `Bash(git:*)`
|
||||
3. Test with simple command: `!echo test`
|
||||
|
||||
### File References Not Loading
|
||||
|
||||
**Issue**: `@file.js` not including file content
|
||||
|
||||
**Solutions**:
|
||||
1. Verify file path is correct (relative to project root)
|
||||
2. Check file exists: `ls @file.js`
|
||||
3. Ensure no typos in file path
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Limit Tool Access
|
||||
|
||||
Only grant necessary permissions:
|
||||
|
||||
```yaml
|
||||
# Specific commands only
|
||||
allowed-tools: Bash(git status:*), Bash(git log:*)
|
||||
|
||||
# Never use unless absolutely required
|
||||
allowed-tools: *
|
||||
```
|
||||
|
||||
### No Hardcoded Secrets
|
||||
|
||||
```markdown
|
||||
# Bad - hardcoded API key
|
||||
!curl -H "API-Key: sk-abc123..." api.example.com
|
||||
|
||||
# Good - use environment variables
|
||||
!curl -H "API-Key: $MY_API_KEY" api.example.com
|
||||
```
|
||||
|
||||
### Validate User Input
|
||||
|
||||
If using arguments in bash:
|
||||
|
||||
```markdown
|
||||
# Risky - no validation
|
||||
!rm -rf $1
|
||||
|
||||
# Better - validate first
|
||||
Confirm you want to delete: $1
|
||||
(Then use interactive confirmation before executing)
|
||||
```
|
||||
|
||||
## Command Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: [Clear, concise description of what this command does]
|
||||
argument-hint: [Expected arguments format]
|
||||
allowed-tools: [Specific tool patterns if needed]
|
||||
---
|
||||
|
||||
[Command prompt template]
|
||||
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- [Official Slash Commands Documentation](https://docs.claude.com/en/docs/claude-code/slash-commands)
|
||||
- [Plugin Development](../claude-code-plugins/SKILL.md) - For packaging commands in plugins
|
||||
- [Hooks](../claude-code-hooks/SKILL.md) - For event-based automation
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Slash commands are for reusable prompts. Start with manual prompts, identify patterns you repeat, then codify them as commands.
|
||||
934
claude-code/skills/claude-code-subagents/SKILL.md
Normal file
934
claude-code/skills/claude-code-subagents/SKILL.md
Normal file
@@ -0,0 +1,934 @@
|
||||
---
|
||||
name: Claude Code Subagent Specialist
|
||||
description: Refine and troubleshoot Claude Code subagents by optimizing prompts, tool access, descriptions, and performance. Use when improving existing subagents, debugging activation issues, or optimizing delegation patterns. NOT for initial creation - use /agents command first.
|
||||
---
|
||||
|
||||
# Claude Code Subagent Refinement & Troubleshooting
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
- Refining existing subagent prompts for better performance
|
||||
- Troubleshooting why a subagent isn't activating
|
||||
- Optimizing tool access and permissions
|
||||
- Improving subagent descriptions for better delegation
|
||||
- Debugging context management issues
|
||||
- Testing and validating subagent behavior
|
||||
- Converting ad-hoc workflows to reusable subagents
|
||||
|
||||
Do NOT use this skill for:
|
||||
- **Initial creation** - Use `/agents` command instead (it provides interactive UI)
|
||||
- Creating slash commands (use claude-code-slash-commands skill)
|
||||
- General Claude Code troubleshooting
|
||||
|
||||
**Important**: Always start with `/agents` to create subagents. Use this skill to refine them afterward.
|
||||
|
||||
## Quick Reference: Subagent Structure
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: agent-name # Lowercase, kebab-case identifier
|
||||
description: When to use # Triggers automatic delegation
|
||||
tools: Tool1, Tool2 # Optional: omit to inherit all
|
||||
model: sonnet # Optional: sonnet/opus/haiku/inherit
|
||||
---
|
||||
|
||||
System prompt defining role, capabilities, and behavior.
|
||||
Include specific instructions, constraints, and examples.
|
||||
```
|
||||
|
||||
**File Locations**:
|
||||
- Project: `.claude/agents/` (highest priority)
|
||||
- User: `~/.claude/agents/` (shared across projects)
|
||||
- Plugin: `agents/` in plugin directory
|
||||
|
||||
## Common Problems & Solutions
|
||||
|
||||
### Problem 1: Subagent Never Activates
|
||||
|
||||
**Symptoms**: Claude doesn't delegate to your subagent
|
||||
|
||||
**Diagnose**:
|
||||
```yaml
|
||||
# Check your description field
|
||||
---
|
||||
description: Helper agent # ❌ Too vague
|
||||
---
|
||||
```
|
||||
|
||||
**Fix - Make Description Specific**:
|
||||
```yaml
|
||||
# Before (vague)
|
||||
---
|
||||
description: Helps with security
|
||||
---
|
||||
|
||||
# After (specific)
|
||||
---
|
||||
description: Analyze code for security vulnerabilities including SQL injection, XSS, authentication flaws, and hardcoded secrets. Use PROACTIVELY when reviewing code for security issues.
|
||||
---
|
||||
```
|
||||
|
||||
**Best Practices for Descriptions**:
|
||||
- Include specific trigger words and scenarios
|
||||
- Add "use PROACTIVELY" or "MUST BE USED" for automatic activation
|
||||
- Mention the domain/context clearly
|
||||
- List key capabilities or checks
|
||||
|
||||
### Problem 2: Subagent Has Wrong Tools
|
||||
|
||||
**Symptoms**: Subagent can't complete tasks or has too many permissions
|
||||
|
||||
**Diagnose**:
|
||||
```bash
|
||||
# Check current tool configuration
|
||||
cat .claude/agents/my-agent.md | grep "tools:"
|
||||
```
|
||||
|
||||
**Fix - Whitelist Specific Tools**:
|
||||
```yaml
|
||||
# Inherits all tools (may be too permissive)
|
||||
---
|
||||
name: security-analyzer
|
||||
description: Security analysis
|
||||
---
|
||||
|
||||
# Restricted to read-only tools (better)
|
||||
---
|
||||
name: security-analyzer
|
||||
description: Security analysis
|
||||
tools: Read, Grep, Glob
|
||||
---
|
||||
```
|
||||
|
||||
**Tool Access Strategies**:
|
||||
|
||||
**1. Inherit All (Default)**:
|
||||
```yaml
|
||||
# Omit 'tools' field entirely
|
||||
---
|
||||
name: general-helper
|
||||
description: General assistance
|
||||
---
|
||||
```
|
||||
Use when: Agent needs full flexibility
|
||||
|
||||
**2. Read-Only Access**:
|
||||
```yaml
|
||||
---
|
||||
tools: Read, Grep, Glob, Bash(git log:*), Bash(git diff:*)
|
||||
---
|
||||
```
|
||||
Use when: Analysis, review, documentation
|
||||
|
||||
**3. Specific Permissions**:
|
||||
```yaml
|
||||
---
|
||||
tools: Read, Write, Edit, Bash(npm test:*)
|
||||
---
|
||||
```
|
||||
Use when: Implementation with validation
|
||||
|
||||
**4. No File Access**:
|
||||
```yaml
|
||||
---
|
||||
tools: WebFetch, WebSearch, Bash
|
||||
---
|
||||
```
|
||||
Use when: Research, external data gathering
|
||||
|
||||
### Problem 3: Poor Quality Output
|
||||
|
||||
**Symptoms**: Subagent completes tasks but results are inconsistent or low-quality
|
||||
|
||||
**Diagnose**: Check system prompt specificity
|
||||
|
||||
**Fix - Enhance System Prompt**:
|
||||
|
||||
```markdown
|
||||
# Before (vague)
|
||||
---
|
||||
name: code-reviewer
|
||||
---
|
||||
|
||||
You review code for issues.
|
||||
```
|
||||
|
||||
```markdown
|
||||
# After (specific)
|
||||
---
|
||||
name: code-reviewer
|
||||
---
|
||||
|
||||
You are a senior code reviewer specializing in production-ready code quality.
|
||||
|
||||
## Your Responsibilities
|
||||
|
||||
1. **Logic & Correctness**
|
||||
- Verify algorithm correctness
|
||||
- Check edge case handling
|
||||
- Validate error conditions
|
||||
|
||||
2. **Code Quality**
|
||||
- Ensure single responsibility principle
|
||||
- Check for code duplication (DRY)
|
||||
- Verify meaningful naming
|
||||
|
||||
3. **Security**
|
||||
- Identify injection vulnerabilities
|
||||
- Check authentication/authorization
|
||||
- Flag hardcoded secrets
|
||||
|
||||
4. **Performance**
|
||||
- Spot O(n²) or worse algorithms
|
||||
- Identify unnecessary loops
|
||||
- Check resource cleanup
|
||||
|
||||
## Output Format
|
||||
|
||||
For each issue found:
|
||||
- **Severity**: Critical/High/Medium/Low
|
||||
- **Location**: file:line
|
||||
- **Issue**: Clear description
|
||||
- **Fix**: Specific code example
|
||||
|
||||
## Constraints
|
||||
|
||||
- Only report actionable issues
|
||||
- Provide code examples for fixes
|
||||
- Focus on high-impact problems first
|
||||
- No nitpicking style issues unless severe
|
||||
```
|
||||
|
||||
**System Prompt Best Practices**:
|
||||
- Define role and expertise level
|
||||
- List specific responsibilities
|
||||
- Include output format requirements
|
||||
- Add examples of good/bad cases
|
||||
- Specify constraints and boundaries
|
||||
- Use headings for scannability
|
||||
|
||||
### Problem 4: Context Pollution
|
||||
|
||||
**Symptoms**: Main conversation gets cluttered with subagent details
|
||||
|
||||
**Understand**: Subagents have isolated context windows - only their final output returns
|
||||
|
||||
**Fix - Structure Output Properly**:
|
||||
|
||||
```markdown
|
||||
# System prompt guidance
|
||||
---
|
||||
name: research-agent
|
||||
---
|
||||
|
||||
Research [topic] and return ONLY:
|
||||
1. Key findings (3-5 bullet points)
|
||||
2. Relevant URLs
|
||||
3. Recommendation
|
||||
|
||||
Do NOT include:
|
||||
- Full article text
|
||||
- Research methodology
|
||||
- Intermediate thoughts
|
||||
```
|
||||
|
||||
**Best Practices**:
|
||||
- Explicitly tell subagent what to return
|
||||
- Request summaries, not full details
|
||||
- Have subagent filter before returning
|
||||
- Use structured output formats
|
||||
|
||||
### Problem 5: Activation Too Broad/Narrow
|
||||
|
||||
**Symptoms**: Subagent activates for wrong tasks OR misses relevant tasks
|
||||
|
||||
**Diagnose - Test Trigger Scenarios**:
|
||||
|
||||
```markdown
|
||||
# Test cases for a "security-analyzer" subagent
|
||||
|
||||
Should Activate:
|
||||
- "Review this auth code for vulnerabilities"
|
||||
- "Check if we're handling passwords securely"
|
||||
- "Scan for SQL injection risks"
|
||||
|
||||
Should NOT Activate:
|
||||
- "Write unit tests" (different concern)
|
||||
- "Refactor this function" (not security-focused)
|
||||
- "Add logging" (different task)
|
||||
```
|
||||
|
||||
**Fix - Refine Description**:
|
||||
|
||||
```yaml
|
||||
# Too narrow
|
||||
---
|
||||
description: Checks for SQL injection only
|
||||
---
|
||||
|
||||
# Too broad
|
||||
---
|
||||
description: Helps with code
|
||||
---
|
||||
|
||||
# Just right
|
||||
---
|
||||
description: Analyze code for security vulnerabilities including SQL injection, XSS, CSRF, authentication issues, and secrets exposure. Use when reviewing code for security concerns or compliance requirements.
|
||||
---
|
||||
```
|
||||
|
||||
### Problem 6: Model Selection Issues
|
||||
|
||||
**Symptoms**: Subagent too slow/expensive OR too simple for task
|
||||
|
||||
**Fix - Choose Right Model**:
|
||||
|
||||
```yaml
|
||||
# Fast, simple tasks (formatting, linting)
|
||||
---
|
||||
model: haiku
|
||||
---
|
||||
|
||||
# Complex reasoning (architecture, design)
|
||||
---
|
||||
model: opus
|
||||
---
|
||||
|
||||
# Balanced (most cases)
|
||||
---
|
||||
model: sonnet
|
||||
---
|
||||
|
||||
# Same as main conversation
|
||||
---
|
||||
model: inherit
|
||||
---
|
||||
```
|
||||
|
||||
**Model Selection Guide**:
|
||||
|
||||
| Model | Use For | Avoid For |
|
||||
|-------|---------|-----------|
|
||||
| haiku | Simple transforms, quick checks | Complex reasoning, creativity |
|
||||
| sonnet | General tasks, balanced quality | When opus is specifically needed |
|
||||
| opus | Complex architecture, creative work | Simple/repetitive tasks (cost) |
|
||||
| inherit | Task complexity matches main thread | When you need different capability |
|
||||
|
||||
## Optimization Patterns
|
||||
|
||||
### Pattern 1: Role-Based Pipeline
|
||||
|
||||
Create specialized agents for each workflow stage:
|
||||
|
||||
```yaml
|
||||
# 1. Spec Agent
|
||||
---
|
||||
name: product-spec-writer
|
||||
description: Create detailed product specifications from user requirements
|
||||
tools: Read, Write, WebSearch
|
||||
model: opus
|
||||
---
|
||||
|
||||
You convert user requirements into detailed product specs.
|
||||
|
||||
[Detailed prompt...]
|
||||
```
|
||||
|
||||
```yaml
|
||||
# 2. Architect Agent
|
||||
---
|
||||
name: solution-architect
|
||||
description: Design system architecture from product specs
|
||||
tools: Read, Write, Grep, Glob
|
||||
model: opus
|
||||
---
|
||||
|
||||
You design scalable system architectures.
|
||||
|
||||
[Detailed prompt...]
|
||||
```
|
||||
|
||||
```yaml
|
||||
# 3. Implementer Agent
|
||||
---
|
||||
name: code-implementer
|
||||
description: Implement features from architectural designs
|
||||
tools: Read, Write, Edit, Bash(npm test:*)
|
||||
model: sonnet
|
||||
---
|
||||
|
||||
You implement features following architectural guidelines.
|
||||
|
||||
[Detailed prompt...]
|
||||
```
|
||||
|
||||
**Usage**: Chain with hooks or explicit handoffs
|
||||
|
||||
### Pattern 2: Domain Specialists
|
||||
|
||||
```yaml
|
||||
# Frontend Specialist
|
||||
---
|
||||
name: frontend-specialist
|
||||
description: React/TypeScript UI development and component design. Use PROACTIVELY for frontend work.
|
||||
tools: Read, Write, Edit, Grep, Bash(npm:*)
|
||||
---
|
||||
|
||||
You are a React/TypeScript expert specializing in modern frontend development.
|
||||
|
||||
## Tech Stack
|
||||
- React 18+ with hooks
|
||||
- TypeScript (strict mode)
|
||||
- Tailwind CSS
|
||||
- Component-driven architecture
|
||||
|
||||
## Principles
|
||||
- Functional components only
|
||||
- Custom hooks for logic reuse
|
||||
- Accessibility (WCAG AA)
|
||||
- Performance (lazy loading, memoization)
|
||||
|
||||
[More specific guidance...]
|
||||
```
|
||||
|
||||
```yaml
|
||||
# Backend Specialist
|
||||
---
|
||||
name: backend-specialist
|
||||
description: Node.js/Express API development, database design, and server architecture. Use PROACTIVELY for backend work.
|
||||
tools: Read, Write, Edit, Grep, Bash(npm:*), Bash(docker:*)
|
||||
---
|
||||
|
||||
You are a Node.js backend expert.
|
||||
|
||||
[Similar detailed structure...]
|
||||
```
|
||||
|
||||
### Pattern 3: Security-First Architecture
|
||||
|
||||
```yaml
|
||||
# Security Analyzer (Read-Only)
|
||||
---
|
||||
name: security-analyzer
|
||||
description: Analyze code for security vulnerabilities before allowing modifications. MUST BE USED before code changes in sensitive areas.
|
||||
tools: Read, Grep, Glob, Bash(git diff:*)
|
||||
---
|
||||
|
||||
You are a security analyst. Review code for vulnerabilities BEFORE changes are made.
|
||||
|
||||
## Security Checks
|
||||
1. Authentication/Authorization
|
||||
2. Input validation
|
||||
3. SQL injection
|
||||
4. XSS vulnerabilities
|
||||
5. CSRF protection
|
||||
6. Secrets management
|
||||
|
||||
## Output
|
||||
Return ONLY:
|
||||
- Security score (1-10)
|
||||
- Critical issues (block changes)
|
||||
- Warnings (allow with caution)
|
||||
```
|
||||
|
||||
### Pattern 4: Test-Driven Subagent
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: test-first-developer
|
||||
description: Write comprehensive tests before implementing features. Use PROACTIVELY for TDD workflows.
|
||||
tools: Read, Write, Bash(npm test:*)
|
||||
model: sonnet
|
||||
---
|
||||
|
||||
You are a TDD expert. For every feature request:
|
||||
|
||||
1. **Analyze Requirements**
|
||||
- Extract testable behaviors
|
||||
- Identify edge cases
|
||||
|
||||
2. **Write Tests FIRST**
|
||||
- Unit tests for logic
|
||||
- Integration tests for workflows
|
||||
- Edge case coverage
|
||||
|
||||
3. **Run Tests** (they should fail)
|
||||
```bash
|
||||
npm test
|
||||
```
|
||||
|
||||
4. **Implement ONLY Enough** to pass tests
|
||||
|
||||
5. **Refactor** while keeping tests green
|
||||
|
||||
## Test Structure
|
||||
```javascript
|
||||
describe('Feature', () => {
|
||||
it('handles happy path', () => {})
|
||||
it('handles edge case 1', () => {})
|
||||
it('throws on invalid input', () => {})
|
||||
})
|
||||
```
|
||||
|
||||
Never implement before tests exist.
|
||||
```
|
||||
|
||||
## Testing & Validation
|
||||
|
||||
### 1. Test Trigger Accuracy
|
||||
|
||||
Create test scenarios:
|
||||
|
||||
```markdown
|
||||
# Test Plan for "api-developer" subagent
|
||||
|
||||
## Positive Tests (Should Activate)
|
||||
1. "Create a REST endpoint for user authentication"
|
||||
- Expected: Activates
|
||||
- Actual: ___
|
||||
|
||||
2. "Add GraphQL mutation for updating profile"
|
||||
- Expected: Activates
|
||||
- Actual: ___
|
||||
|
||||
## Negative Tests (Should NOT Activate)
|
||||
1. "Write unit tests for the API"
|
||||
- Expected: Does not activate (testing concern)
|
||||
- Actual: ___
|
||||
|
||||
2. "Review API security"
|
||||
- Expected: Does not activate (security concern)
|
||||
- Actual: ___
|
||||
|
||||
## Results
|
||||
- Precision: X% (correct activations / total activations)
|
||||
- Recall: Y% (correct activations / should activate)
|
||||
```
|
||||
|
||||
### 2. Test Output Quality
|
||||
|
||||
```markdown
|
||||
# Quality Checklist
|
||||
|
||||
Task: "Review auth.js for security issues"
|
||||
|
||||
Subagent Output Should Include:
|
||||
- [ ] Specific vulnerabilities identified
|
||||
- [ ] File:line locations
|
||||
- [ ] Severity ratings
|
||||
- [ ] Concrete fix suggestions
|
||||
- [ ] Code examples for fixes
|
||||
|
||||
Should NOT Include:
|
||||
- [ ] Generic advice
|
||||
- [ ] Full file listings
|
||||
- [ ] Unrelated issues
|
||||
- [ ] Style nitpicks
|
||||
```
|
||||
|
||||
### 3. Test Tool Access
|
||||
|
||||
```bash
|
||||
# Verify tool restrictions work
|
||||
# Give subagent a task requiring forbidden tool
|
||||
|
||||
# Example: Read-only subagent shouldn't be able to edit
|
||||
# Test by asking it to "fix the security issue"
|
||||
# Should fail or request permission
|
||||
```
|
||||
|
||||
### 4. Performance Testing
|
||||
|
||||
```markdown
|
||||
# Performance Metrics
|
||||
|
||||
Task: "Generate API documentation"
|
||||
|
||||
Metrics:
|
||||
- Time to complete: ___
|
||||
- Tokens used: ___
|
||||
- Quality score (1-10): ___
|
||||
- Required follow-ups: ___
|
||||
|
||||
Optimization targets:
|
||||
- < 30 seconds for docs
|
||||
- < 5000 tokens
|
||||
- Quality >= 8
|
||||
- 0 follow-ups needed
|
||||
```
|
||||
|
||||
## Refinement Workflow
|
||||
|
||||
### Step 1: Baseline Performance
|
||||
|
||||
```bash
|
||||
# Document current behavior
|
||||
echo "Task: [Specific task]
|
||||
Expected: [What should happen]
|
||||
Actual: [What actually happens]
|
||||
Issues: [Problems observed]
|
||||
" > .claude/agents/refinement-notes.md
|
||||
```
|
||||
|
||||
### Step 2: Identify Root Cause
|
||||
|
||||
Common causes:
|
||||
- Description too vague → Won't activate
|
||||
- Prompt lacks specificity → Poor output
|
||||
- Wrong tools → Can't complete task
|
||||
- Wrong model → Too slow/simple
|
||||
- Output not filtered → Context pollution
|
||||
|
||||
### Step 3: Make Targeted Changes
|
||||
|
||||
**Only change ONE thing at a time**:
|
||||
1. Update description OR
|
||||
2. Refine prompt OR
|
||||
3. Adjust tools OR
|
||||
4. Change model
|
||||
|
||||
### Step 4: Test Changes
|
||||
|
||||
```bash
|
||||
# Test with same scenarios
|
||||
# Compare before/after results
|
||||
# Document improvements
|
||||
```
|
||||
|
||||
### Step 5: Iterate
|
||||
|
||||
Repeat until subagent meets quality bar.
|
||||
|
||||
## Best Practices Summary
|
||||
|
||||
### Description Writing
|
||||
|
||||
```yaml
|
||||
# Template
|
||||
description: [Action verb] [domain/task] [including specific capabilities]. Use [trigger condition]. PROACTIVELY when [scenario].
|
||||
```
|
||||
|
||||
**Examples**:
|
||||
```yaml
|
||||
description: Analyze Python code for performance bottlenecks including O(n²) algorithms, memory leaks, and inefficient database queries. Use PROACTIVELY when optimizing Python applications.
|
||||
|
||||
description: Generate comprehensive API documentation from code including endpoints, parameters, responses, and examples. Use when documenting REST or GraphQL APIs.
|
||||
|
||||
description: Review frontend code for accessibility issues following WCAG 2.1 AA standards. MUST BE USED for all UI component changes.
|
||||
```
|
||||
|
||||
### System Prompt Structure
|
||||
|
||||
```markdown
|
||||
# Role Definition
|
||||
You are a [role] specializing in [domain].
|
||||
|
||||
## Responsibilities
|
||||
1. [Primary responsibility]
|
||||
2. [Secondary responsibility]
|
||||
3. [Additional responsibilities]
|
||||
|
||||
## Process
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
|
||||
## Output Format
|
||||
[Specific structure required]
|
||||
|
||||
## Examples
|
||||
|
||||
### Good Example
|
||||
[Show what good looks like]
|
||||
|
||||
### Bad Example
|
||||
[Show what to avoid]
|
||||
|
||||
## Constraints
|
||||
- [Important limitation]
|
||||
- [Another constraint]
|
||||
```
|
||||
|
||||
### Tool Selection Strategy
|
||||
|
||||
```markdown
|
||||
Decision Tree:
|
||||
|
||||
1. Does it need to modify files?
|
||||
No → Read, Grep, Glob only
|
||||
Yes → Continue
|
||||
|
||||
2. Does it need to run tests/builds?
|
||||
No → Read, Write, Edit only
|
||||
Yes → Add Bash(test:*), Bash(build:*)
|
||||
|
||||
3. Does it need external data?
|
||||
Yes → Add WebFetch, WebSearch
|
||||
No → Continue
|
||||
|
||||
4. Does it need git operations?
|
||||
Yes → Add Bash(git:*) with specific commands
|
||||
No → Done
|
||||
```
|
||||
|
||||
### Model Selection
|
||||
|
||||
```markdown
|
||||
Choose model based on:
|
||||
|
||||
1. Task complexity
|
||||
- Simple transforms → haiku
|
||||
- Standard coding → sonnet
|
||||
- Complex reasoning → opus
|
||||
|
||||
2. Cost sensitivity
|
||||
- High volume, simple → haiku
|
||||
- Balanced → sonnet
|
||||
- Quality critical → opus
|
||||
|
||||
3. Speed requirements
|
||||
- Real-time needed → haiku
|
||||
- Standard → sonnet
|
||||
- Can wait → opus
|
||||
|
||||
Default: sonnet (best balance)
|
||||
```
|
||||
|
||||
## Debugging Checklist
|
||||
|
||||
When subagent doesn't work as expected:
|
||||
|
||||
```markdown
|
||||
- [ ] Description is specific and includes trigger words
|
||||
- [ ] Description includes "PROACTIVELY" or "MUST BE USED" if needed
|
||||
- [ ] System prompt defines role clearly
|
||||
- [ ] System prompt includes process/steps
|
||||
- [ ] System prompt specifies output format
|
||||
- [ ] System prompt has examples
|
||||
- [ ] Tools match required capabilities
|
||||
- [ ] Tools follow least-privilege principle
|
||||
- [ ] Model appropriate for task complexity
|
||||
- [ ] File location correct (.claude/agents/)
|
||||
- [ ] YAML frontmatter valid
|
||||
- [ ] Name uses kebab-case
|
||||
- [ ] Tested with positive/negative scenarios
|
||||
```
|
||||
|
||||
## Common Anti-Patterns
|
||||
|
||||
### ❌ Anti-Pattern 1: Generic Description
|
||||
|
||||
```yaml
|
||||
---
|
||||
description: Helps with coding
|
||||
---
|
||||
```
|
||||
|
||||
**Why Bad**: Won't trigger reliably
|
||||
|
||||
**Fix**: Be specific about domain and triggers
|
||||
|
||||
### ❌ Anti-Pattern 2: No Process Defined
|
||||
|
||||
```markdown
|
||||
You are a code reviewer. Review code.
|
||||
```
|
||||
|
||||
**Why Bad**: Inconsistent results
|
||||
|
||||
**Fix**: Define step-by-step process
|
||||
|
||||
### ❌ Anti-Pattern 3: All Tools Granted
|
||||
|
||||
```yaml
|
||||
---
|
||||
# Omitting tools when only reads needed
|
||||
---
|
||||
```
|
||||
|
||||
**Why Bad**: Unnecessary permissions, security risk
|
||||
|
||||
**Fix**: Whitelist minimum required tools
|
||||
|
||||
### ❌ Anti-Pattern 4: Verbose System Prompt
|
||||
|
||||
```markdown
|
||||
You are an expert developer with 20 years of experience who has worked on numerous projects across different industries... [3000 words]
|
||||
```
|
||||
|
||||
**Why Bad**: Token waste, slower activation
|
||||
|
||||
**Fix**: Be concise, focus on process and format
|
||||
|
||||
### ❌ Anti-Pattern 5: No Output Structure
|
||||
|
||||
```markdown
|
||||
Review the code and tell me about issues.
|
||||
```
|
||||
|
||||
**Why Bad**: Inconsistent format, hard to parse
|
||||
|
||||
**Fix**: Define exact output format
|
||||
|
||||
## Advanced Techniques
|
||||
|
||||
### Technique 1: Chained Subagents
|
||||
|
||||
Use hooks or explicit handoffs:
|
||||
|
||||
```json
|
||||
// .claude/settings.json
|
||||
{
|
||||
"hooks": {
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Write",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "echo 'Please use security-analyzer subagent to review this file' && exit 0"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Technique 2: Context Injection
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: context-aware-developer
|
||||
---
|
||||
|
||||
Before starting any task:
|
||||
1. Read PROJECT_CONTEXT.md
|
||||
2. Review ARCHITECTURE.md
|
||||
3. Check CODING_STANDARDS.md
|
||||
|
||||
Then proceed with development following documented patterns.
|
||||
```
|
||||
|
||||
### Technique 3: Quality Gates
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: pr-ready-checker
|
||||
description: Verify code is PR-ready before submitting. MUST BE USED before creating pull requests.
|
||||
tools: Read, Grep, Bash(npm test:*), Bash(npm run lint:*)
|
||||
---
|
||||
|
||||
Verify PR readiness:
|
||||
|
||||
1. **Tests Pass**
|
||||
```bash
|
||||
npm test
|
||||
```
|
||||
All tests must pass.
|
||||
|
||||
2. **Linting Clean**
|
||||
```bash
|
||||
npm run lint
|
||||
```
|
||||
Zero warnings or errors.
|
||||
|
||||
3. **Coverage Adequate**
|
||||
- New code > 80% covered
|
||||
- Overall coverage not decreased
|
||||
|
||||
4. **Documentation Updated**
|
||||
- README if public API changed
|
||||
- Inline comments for complex logic
|
||||
|
||||
5. **No Debug Code**
|
||||
- No console.log
|
||||
- No debugger statements
|
||||
- No commented code
|
||||
|
||||
Return: "PR Ready: Yes/No" + blockers list
|
||||
```
|
||||
|
||||
### Technique 4: Iterative Refinement Prompt
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: iterative-implementer
|
||||
---
|
||||
|
||||
When implementation fails or produces errors:
|
||||
|
||||
1. **Analyze Failure**
|
||||
- What was the error?
|
||||
- Why did it happen?
|
||||
- What was I trying to achieve?
|
||||
|
||||
2. **Adjust Approach**
|
||||
- How should I do it differently?
|
||||
- What did I learn?
|
||||
|
||||
3. **Re-implement**
|
||||
- Apply new approach
|
||||
- Test immediately
|
||||
|
||||
4. **Verify**
|
||||
- Did it work?
|
||||
- If not, repeat from step 1
|
||||
|
||||
Never give up after one failure. Iterate until success.
|
||||
```
|
||||
|
||||
## Migration: Ad-Hoc to Subagent
|
||||
|
||||
### When to Migrate
|
||||
|
||||
Migrate repetitive prompts to subagents when:
|
||||
- You've used the same prompt 3+ times
|
||||
- Prompt has clear pattern/structure
|
||||
- Task benefits from isolation
|
||||
- Multiple team members need it
|
||||
|
||||
### Migration Process
|
||||
|
||||
**Step 1: Extract Pattern**
|
||||
|
||||
```markdown
|
||||
# Repeated prompts you've used:
|
||||
|
||||
1. "Review auth.js for security issues including SQL injection, XSS, and auth flaws"
|
||||
2. "Check payment.js for security vulnerabilities like injection and secrets"
|
||||
3. "Analyze api.js for security problems including validation and auth"
|
||||
|
||||
# Common pattern:
|
||||
Review [file] for security [vulnerability types]
|
||||
```
|
||||
|
||||
**Step 2: Generalize**
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: security-reviewer
|
||||
description: Review code for security vulnerabilities including SQL injection, XSS, authentication flaws, and hardcoded secrets. Use PROACTIVELY for security reviews.
|
||||
tools: Read, Grep, Glob
|
||||
---
|
||||
|
||||
Review provided files for security vulnerabilities:
|
||||
|
||||
[Extract common structure from your prompts]
|
||||
```
|
||||
|
||||
**Step 3: Test & Refine**
|
||||
|
||||
Test with previous use cases, refine until quality matches or exceeds manual prompts.
|
||||
|
||||
## Resources
|
||||
|
||||
- [Official Subagents Documentation](https://docs.claude.com/en/docs/claude-code/sub-agents)
|
||||
- [Claude Code Plugins](../claude-code-plugins/SKILL.md) - For packaging subagents
|
||||
- [Slash Commands](../claude-code-slash-commands/SKILL.md) - Alternative for simpler patterns
|
||||
- [Hooks](../claude-code-hooks/SKILL.md) - For automating subagent workflows
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Start with `/agents` command for creation. Use this skill for refinement. Iterate based on real usage. Test thoroughly. Document learnings.
|
||||
15
claude-skills-plugin/.claude-plugin/plugin.json
Normal file
15
claude-skills-plugin/.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,15 @@
|
||||
{
|
||||
"name": "claude-skills",
|
||||
"description": "Meta-skill for creating effective Agent Skills with best practices, templates, and progressive disclosure principles",
|
||||
"version": "1.0.0",
|
||||
"author": {
|
||||
"name": "Claude Skills Contributors"
|
||||
},
|
||||
"keywords": [
|
||||
"agent-skills",
|
||||
"skill-creation",
|
||||
"best-practices",
|
||||
"templates",
|
||||
"progressive-disclosure"
|
||||
]
|
||||
}
|
||||
250
claude-skills-plugin/README.md
Normal file
250
claude-skills-plugin/README.md
Normal file
@@ -0,0 +1,250 @@
|
||||
# Claude Skills Plugin
|
||||
|
||||
Meta-skill for creating effective Agent Skills with best practices, structure guidelines, and progressive disclosure principles.
|
||||
|
||||
## What's Included
|
||||
|
||||
The **claude-skills** skill provides comprehensive guidance for building high-quality Agent Skills that work efficiently with Claude Code and Claude.ai.
|
||||
|
||||
### claude-skills (Skill Creator)
|
||||
|
||||
A comprehensive guide covering:
|
||||
- **Progressive disclosure** - Three-layer architecture (metadata → instructions → resources)
|
||||
- **Trigger optimization** - Writing descriptions that activate at the right time
|
||||
- **Token efficiency** - Strategic file splitting and on-demand loading
|
||||
- **Development workflow** - Iterative approach to skill creation
|
||||
- **Security considerations** - Best practices for safe skill creation and usage
|
||||
|
||||
**Includes:**
|
||||
- `SKILL.md` - Complete best practices guide
|
||||
- `examples.md` - Working examples across different domains
|
||||
- `templates.md` - Ready-to-use templates for common skill types
|
||||
- `checklist.md` - Quality assurance checklist
|
||||
- `README.md` - Skill-specific overview
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
- Creating a new Agent Skill from scratch
|
||||
- Improving or refactoring an existing skill
|
||||
- Debugging why a skill isn't triggering correctly
|
||||
- Understanding skill architecture and design patterns
|
||||
- Optimizing skill structure for token efficiency
|
||||
|
||||
## Installation
|
||||
|
||||
### For Claude Code
|
||||
|
||||
Install from marketplace:
|
||||
|
||||
```bash
|
||||
/plugin install claude-skills@claude-skills-marketplace
|
||||
```
|
||||
|
||||
Or install from local directory:
|
||||
|
||||
```bash
|
||||
/plugin install /path/to/Skills/claude-skills-plugin@local
|
||||
```
|
||||
|
||||
### For Claude.ai
|
||||
|
||||
1. Zip this plugin directory
|
||||
2. Go to Settings > Capabilities > Upload skill
|
||||
3. Upload the zip file
|
||||
4. Enable the plugin
|
||||
|
||||
## Usage
|
||||
|
||||
Once installed, the skill activates automatically when you work on skill-related tasks:
|
||||
|
||||
```
|
||||
"Help me create a skill for Python testing"
|
||||
"Why isn't my skill triggering?"
|
||||
"How do I optimize my skill for token usage?"
|
||||
"Review my skill structure"
|
||||
```
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### Progressive Disclosure
|
||||
|
||||
Skills use a three-layer architecture:
|
||||
|
||||
**Layer 1: Metadata (Always Loaded)**
|
||||
- YAML frontmatter with `name` and `description`
|
||||
- ~100 tokens per skill
|
||||
- Used for trigger detection
|
||||
|
||||
**Layer 2: Instructions (Triggered)**
|
||||
- Main SKILL.md content
|
||||
- Procedural guidance and workflows
|
||||
- Loaded when skill is relevant
|
||||
|
||||
**Layer 3: Resources (On-Demand)**
|
||||
- Additional files, scripts, reference materials
|
||||
- Loaded only when explicitly needed
|
||||
- Maximizes token efficiency
|
||||
|
||||
### Writing Effective Descriptions
|
||||
|
||||
The description field determines when your skill triggers:
|
||||
|
||||
**Good Descriptions:**
|
||||
```yaml
|
||||
description: Create and analyze Excel spreadsheets with formulas, formatting, and pivot tables. Use when working with .xlsx files, data analysis, or generating reports.
|
||||
```
|
||||
|
||||
**Poor Descriptions:**
|
||||
```yaml
|
||||
description: Helps with coding tasks
|
||||
```
|
||||
|
||||
### Skill Structure
|
||||
|
||||
Every skill MUST have:
|
||||
```yaml
|
||||
---
|
||||
name: Your Skill Name (max 64 chars)
|
||||
description: Clear description with use cases (max 1024 chars)
|
||||
---
|
||||
|
||||
# Skill content
|
||||
```
|
||||
|
||||
## What You'll Learn
|
||||
|
||||
### From SKILL.md
|
||||
- When to use progressive disclosure
|
||||
- How to write effective descriptions
|
||||
- Structuring content for scannability
|
||||
- Token optimization techniques
|
||||
- Development workflow best practices
|
||||
- Security considerations
|
||||
|
||||
### From examples.md
|
||||
- Python testing with pytest
|
||||
- REST API integration patterns
|
||||
- Technical documentation writing
|
||||
- Real-world skill structures
|
||||
|
||||
### From templates.md
|
||||
- Code framework skill template
|
||||
- Workflow/process skill template
|
||||
- Reference/lookup skill template
|
||||
- Tool/utility skill template
|
||||
|
||||
### From checklist.md
|
||||
- Metadata requirements
|
||||
- Content quality checks
|
||||
- Trigger testing scenarios
|
||||
- Security review items
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Creating Your First Skill
|
||||
|
||||
1. Ask Claude: "Help me create a skill for [your topic]"
|
||||
2. Claude will guide you through:
|
||||
- Choosing the right template
|
||||
- Writing an effective description
|
||||
- Structuring content efficiently
|
||||
- Adding concrete examples
|
||||
|
||||
### Improving an Existing Skill
|
||||
|
||||
1. Ask Claude: "Review my skill at [path]"
|
||||
2. Claude will analyze:
|
||||
- Trigger accuracy
|
||||
- Structure optimization
|
||||
- Content clarity
|
||||
- Best practices alignment
|
||||
|
||||
## Best Practices Summary
|
||||
|
||||
**DO:**
|
||||
- Keep SKILL.md focused and concise
|
||||
- Use clear, scannable hierarchies
|
||||
- Include concrete, working examples
|
||||
- Reference additional files explicitly
|
||||
- Start simple, expand based on need
|
||||
|
||||
**DON'T:**
|
||||
- Create vague descriptions
|
||||
- Add unnecessary complexity upfront
|
||||
- Hardcode sensitive data
|
||||
- Skip testing trigger scenarios
|
||||
|
||||
## Development Workflow
|
||||
|
||||
1. **Start with Evaluation** - Work with Claude on tasks, identify patterns
|
||||
2. **Iterate Collaboratively** - Let Claude help structure the skill
|
||||
3. **Test Triggering** - Verify activation with target scenarios
|
||||
4. **Start Simple** - Begin minimal, expand based on actual needs
|
||||
|
||||
## Skills Checklist
|
||||
|
||||
Before finalizing a skill:
|
||||
|
||||
- [ ] Name ≤ 64 characters
|
||||
- [ ] Description ≤ 1024 characters and specific
|
||||
- [ ] Description includes trigger scenarios
|
||||
- [ ] SKILL.md has valid YAML frontmatter
|
||||
- [ ] "When to Use This Skill" section present
|
||||
- [ ] At least one concrete example included
|
||||
- [ ] No sensitive information hardcoded
|
||||
- [ ] File references are accurate
|
||||
- [ ] Tested triggering with target scenarios
|
||||
- [ ] Tested NOT triggering with unrelated scenarios
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Code Development Skills
|
||||
```yaml
|
||||
---
|
||||
name: [Framework] Development Guide
|
||||
description: Build [framework] applications following [patterns]. Use when building [type] with [requirements].
|
||||
---
|
||||
```
|
||||
|
||||
### Workflow Skills
|
||||
```yaml
|
||||
---
|
||||
name: [Task] Workflow
|
||||
description: Execute [task] following [methodology]. Use when [scenario].
|
||||
---
|
||||
```
|
||||
|
||||
### Reference Skills
|
||||
```yaml
|
||||
---
|
||||
name: [Topic] Reference
|
||||
description: Quick reference for [domain]. Use when looking up [specific aspects].
|
||||
---
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- [Official Documentation](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
|
||||
- [Engineering Blog](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
|
||||
- [Using Skills Guide](https://support.claude.com/en/articles/12512180-using-skills-in-claude)
|
||||
|
||||
## Version History
|
||||
|
||||
### 1.0.0 (Initial Release)
|
||||
- Complete best practices guide (SKILL.md)
|
||||
- Working examples across domains (examples.md)
|
||||
- Ready-to-use templates (templates.md)
|
||||
- Quality assurance checklist (checklist.md)
|
||||
|
||||
## Contributing
|
||||
|
||||
Found an issue or have improvements? See the main marketplace [CONTRIBUTING.md](../CONTRIBUTING.md).
|
||||
|
||||
## License
|
||||
|
||||
See main marketplace repository for license information.
|
||||
|
||||
---
|
||||
|
||||
**Remember**: The best skills emerge from real usage patterns. Start simple, iterate based on actual needs, and prioritize clarity over comprehensiveness.
|
||||
Reference in New Issue
Block a user