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>
2025-10-17 11:17:09 -05:00
parent cb6b9f532a
commit 7911d90995
19 changed files with 6112 additions and 0 deletions
--- a/claude-skills-plugin/skills/claude-skills/SKILL.md
+++ b/claude-skills-plugin/skills/claude-skills/SKILL.md
@@ -0,0 +1,456 @@
+---
+name: Skill Creator
+description: Guide for creating effective Claude Agent Skills with best practices, structure guidelines, and progressive disclosure principles. Use when building new skills or improving existing ones.
+---
+
+# Skill Creation Best Practices
+
+## 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
+
+## Core Principle: Progressive Disclosure
+
+**Progressive disclosure is the fundamental design pattern for Agent Skills.** It works in three layers:
+
+### Layer 1: Metadata (Always Loaded)
+- **What**: YAML frontmatter with `name` and `description`
+- **When**: Pre-loaded at every session start
+- **Cost**: ~100 tokens per skill
+- **Purpose**: Trigger detection - helps Claude decide if skill is relevant
+
+### Layer 2: Instructions (Triggered)
+- **What**: Main SKILL.md content
+- **When**: Loads when Claude determines skill applies
+- **Cost**: Variable (keep focused and concise)
+- **Purpose**: Procedural guidance, workflows, best practices
+
+### Layer 3: Resources (On-Demand)
+- **What**: Additional files, scripts, reference materials
+- **When**: Only when explicitly needed
+- **Cost**: Only when accessed
+- **Purpose**: Deep reference, executable code, examples
+
+## Skill Structure Requirements
+
+### Mandatory: SKILL.md File
+
+Every skill MUST have a `SKILL.md` file with YAML frontmatter:
+
+```yaml
+---
+name: Your Skill Name
+description: Clear description of what this does and when to use it
+---
+```
+
+**Critical Constraints:**
+- Name: Maximum 64 characters
+- Description: Maximum 1024 characters
+- **The description is crucial** - it determines when Claude triggers the skill
+
+### Optional: Additional Resources
+
+Structure additional files strategically:
+
+```
+my-skill/
+├── SKILL.md                 # Main entry point (required)
+├── reference.md             # Deep reference material (load on-demand)
+├── examples.md              # Code samples and templates
+├── workflows/               # Step-by-step procedures
+│   ├── advanced.md
+│   └── beginner.md
+└── scripts/                 # Executable utilities
+    └── helper.sh
+```
+
+## Writing Effective Descriptions
+
+The `description` field is your skill's trigger mechanism. Make it count:
+
+### Good Descriptions
+✓ **Specific use cases**: "Create and analyze Excel spreadsheets with formulas, formatting, and pivot tables"
+✓ **Clear triggers**: "Use when building React components following atomic design principles"
+✓ **Domain clarity**: "Debug Swift applications using LLDB for crashes, memory issues, and runtime errors"
+
+### Poor Descriptions
+✗ **Too vague**: "Helps with coding"
+✗ **No trigger context**: "Python utilities"
+✗ **Feature list without purpose**: "Has functions for A, B, and C"
+
+### Template for Descriptions
+
+```
+[Action verb] [specific domain/task] [with/for/using] [key capabilities].
+Use when [primary trigger scenario] [and optional secondary scenarios].
+```
+
+**Example:** "Create professional PowerPoint presentations with custom themes, charts, and animations. Use when building slide decks, pitch presentations, or visual reports."
+
+## Best Practices for SKILL.md Content
+
+### 1. Start with "When to Use This Skill"
+
+Immediately clarify trigger scenarios:
+
+```markdown
+## When to Use This Skill
+
+Use this skill when:
+- [Primary scenario]
+- [Secondary scenario]
+- [Edge case to include]
+
+Do NOT use this skill for:
+- [Common confusion case]
+- [Related but different scenario]
+```
+
+### 2. Structure for Scannability
+
+Use clear hierarchies and action-oriented headers:
+
+```markdown
+## Quick Start
+[Minimal example to get started]
+
+## Core Workflows
+### Workflow 1: [Name]
+1. Step one
+2. Step two
+
+### Workflow 2: [Name]
+1. Step one
+2. Step two
+
+## Advanced Techniques
+[Less common but powerful approaches]
+
+## Common Pitfalls
+[Known issues and how to avoid them]
+```
+
+### 3. Include Concrete Examples
+
+Always provide working examples, not abstract descriptions:
+
+```markdown
+## Example: Creating a User Authentication Module
+
+**Scenario**: Building JWT-based auth for a Flask API
+
+**Steps**:
+1. Install dependencies: `pip install pyjwt flask-login`
+2. Create auth.py with [specific structure]
+3. Configure middleware in app.py
+4. Add protected routes with @login_required
+
+**Result**: Users can register, login, and access protected endpoints
+```
+
+### 4. Reference Additional Files Explicitly
+
+When you need to split content, reference it clearly:
+
+```markdown
+## Deep Dive: Advanced Patterns
+
+For comprehensive examples of [topic], see [examples.md](examples.md).
+
+For API reference, consult [reference.md](reference.md).
+```
+
+## Optimizing for Token Efficiency
+
+### When to Split Files
+
+**Keep in SKILL.md if:**
+- Information is needed for 80%+ of use cases
+- Content is under ~2000 tokens
+- Steps are sequential and interdependent
+
+**Split to separate file if:**
+- Content is mutually exclusive (e.g., Python vs JavaScript examples)
+- Material is reference-heavy (API docs, configuration options)
+- Information is advanced/edge-case focused
+
+### Code as Documentation
+
+Executable scripts serve dual purposes:
+1. **Tools Claude can run** without loading code into context
+2. **Documentation by example** showing best practices
+
+```markdown
+## Generating Boilerplate
+
+Run the initialization script to create project structure:
+
+```bash
+./scripts/init-project.sh my-app
+```
+
+This creates [description of what's created].
+```
+
+Claude can execute this without the script code consuming context tokens.
+
+## Development Workflow
+
+### 1. Start with Evaluation
+
+**Don't guess what skills you need.** Instead:
+1. Run Claude on representative tasks
+2. Identify where it struggles or asks repetitive questions
+3. Capture successful patterns from those sessions
+4. Codify into a skill
+
+### 2. Iterate with Claude
+
+Build skills collaboratively:
+1. Work with Claude on a task
+2. When you find a good solution, ask: "Should we capture this as a skill?"
+3. Let Claude help structure the skill content
+4. Test with new similar tasks
+5. Refine based on actual usage
+
+### 3. Monitor Trigger Accuracy
+
+After creating a skill, test whether it triggers correctly:
+
+**Test scenarios:**
+- Direct requests that SHOULD trigger it
+- Similar requests that SHOULD trigger it
+- Related requests that should NOT trigger it
+
+If triggering is unreliable, refine the `description` field.
+
+### 4. Start Simple, Grow Organically
+
+Begin with a minimal SKILL.md:
+- Clear metadata
+- One core workflow
+- A few examples
+
+Add complexity only when you encounter actual needs:
+- Split files when SKILL.md exceeds ~3000 tokens
+- Add scripts when you repeat the same commands
+- Create reference files for API documentation
+
+## Common Patterns by Domain
+
+### Code Development Skills
+
+```markdown
+---
+name: [Framework/Language] [Pattern] Guide
+description: [Action] [framework] applications following [specific pattern/principles]. Use when building [type of apps] with [key requirements].
+---
+
+## When to Use This Skill
+Use when building [specific project type] with [language/framework]
+
+## Project Structure
+[Standard directory layout]
+
+## Core Workflows
+### Create New [Component Type]
+[Step-by-step process]
+
+### Common Patterns
+[Frequently used code patterns with examples]
+
+## Testing Strategy
+[How to test this type of code]
+```
+
+### Workflow/Process Skills
+
+```markdown
+---
+name: [Task] Workflow
+description: [Action] for [domain] following [methodology]. Use when [scenario].
+---
+
+## When to Use This Skill
+Use when you need to [primary task] and [key differentiator]
+
+## Prerequisites
+[What's needed before starting]
+
+## Step-by-Step Process
+### Phase 1: [Name]
+[Detailed steps]
+
+### Phase 2: [Name]
+[Detailed steps]
+
+## Quality Checklist
+- [ ] [Verification step]
+- [ ] [Verification step]
+```
+
+### Reference/Documentation Skills
+
+```markdown
+---
+name: [Topic] Reference
+description: [Type of information] for [domain/tool]. Use when [looking up/configuring/understanding] [specific aspects].
+---
+
+## Quick Reference
+[Most common lookups in concise format]
+
+## Detailed Documentation
+See [reference.md](reference.md) for comprehensive API documentation.
+
+## Common Tasks
+### Task 1
+[Quick example]
+
+### Task 2
+[Quick example]
+```
+
+## Security Considerations
+
+### For Skill Creators
+
+**Never include in skills:**
+- Hardcoded credentials or API keys
+- Personal identifying information
+- Proprietary code without permission
+- Instructions to make unsafe system changes
+
+**Always consider:**
+- Can this skill be misused if shared?
+- Does it access sensitive file locations?
+- Are external dependencies from trusted sources?
+
+### For Skill Users
+
+**Before installing a skill:**
+1. Audit all files in the skill package
+2. Check for network access attempts
+3. Review any bundled scripts for malicious code
+4. Verify the source is trustworthy
+
+## Debugging Skills
+
+### Skill Doesn't Trigger
+
+**Checklist:**
+1. Is the description specific enough?
+2. Does the description mention the trigger scenario?
+3. Is the name too generic?
+4. Test with explicit requests mentioning keywords from the description
+
+**Example fix:**
+- 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
+
+**Checklist:**
+1. Is the description too broad?
+2. Add negative cases: "Do NOT use for..."
+3. Make the domain more specific
+
+### Content Doesn't Load
+
+**Checklist:**
+1. Verify file paths in references are correct
+2. Check that additional .md files are in the skill package
+3. Ensure script paths are relative to skill root
+
+## Skill Metadata Checklist
+
+Before finalizing a skill, verify:
+
+- [ ] Name is under 64 characters
+- [ ] Description is under 1024 characters
+- [ ] Description includes specific use cases
+- [ ] Description mentions when to trigger the skill
+- [ ] SKILL.md has YAML frontmatter with both fields
+- [ ] "When to Use This Skill" section is present
+- [ ] At least one concrete example is included
+- [ ] No sensitive information is hardcoded
+- [ ] File references are accurate
+- [ ] Tested triggering with target scenarios
+- [ ] Tested NOT triggering with related but different scenarios
+
+## Resources
+
+### Official Documentation
+- [Agent Skills Overview](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
+- [Engineering Blog Post](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)
+
+### Example Skills
+Study Anthropic's pre-built skills for reference:
+- Excel (xlsx) - Complex domain with many features
+- Word (docx) - Document generation workflows
+- PowerPoint (pptx) - Creative + structured content
+- PDF (pdf) - File manipulation and analysis
+
+## Quick Start Template
+
+Use this template to begin a new skill:
+
+```markdown
+---
+name:
+description:
+---
+
+# [Skill Name]
+
+## When to Use This Skill
+
+Use this skill when:
+-
+-
+
+Do NOT use this skill for:
+-
+
+## Quick Start
+
+[Minimal working example]
+
+## Core Workflows
+
+### Workflow 1: [Name]
+
+1.
+2.
+3.
+
+**Example:**
+```
+[Code or command]
+```
+
+**Result:** [What this achieves]
+
+## Common Pitfalls
+
+### Issue: [Problem]
+**Solution:** [How to avoid/fix]
+
+### Issue: [Problem]
+**Solution:** [How to avoid/fix]
+
+## Advanced Topics
+
+[Optional: complex scenarios or optimizations]
+```
+
+---
+
+**Remember**: The best skills emerge from real usage patterns. Start simple, iterate based on actual needs, and prioritize clarity over comprehensiveness.