claude-mpm 5.4.48__py3-none-any.whl → 5.6.34__py3-none-any.whl

claude_mpm/skills/bundled/main/skill-creator/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: skill-creator
+description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
+license: Complete terms in LICENSE.txt
+progressive_disclosure:
+  entry_point:
+    summary: "Create modular skills that extend Claude with specialized knowledge, workflows, and tools through structured components"
+    when_to_use: "When users want to create or update skills with specialized domain knowledge, workflows, or tool integrations. Focus on progressive disclosure for skills >150 lines."
+    quick_start: "1. Understand skill with concrete examples 2. Plan reusable components (scripts/references/assets) 3. Initialize with init_skill.py 4. Edit SKILL.md and resources 5. Package and validate 6. Iterate based on usage"
+  references:
+    - skill-structure.md
+    - creation-workflow.md
+    - progressive-disclosure.md
+    - best-practices.md
+    - examples.md
+---
+
+# Skill Creator
+
+## Overview
+
+Create effective skills that extend Claude's capabilities through specialized knowledge, workflows, and tools. Skills are modular packages that transform Claude from a general-purpose agent into a specialized agent with procedural knowledge for specific domains.
+
+**This skill exemplifies its own teachings** by using progressive disclosure to keep the entry point lean while providing deep detail in reference files.
+
+## When to Use This Skill
+
+Activate when:
+- Creating a new skill from scratch
+- Updating or refactoring an existing skill
+- Adding progressive disclosure to monolithic skills
+- Understanding skill structure and best practices
+- Planning skill components (scripts, references, assets)
+- Packaging skills for distribution
+
+## Core Principles
+
+1. **Example-Driven Design**: Start with concrete usage examples, not abstract concepts
+2. **Progressive Disclosure**: Keep entry point <200 lines (optimal: 140-160), detailed content in references
+3. **Reusable Components**: Extract scripts for repeated code, references for knowledge, assets for templates
+4. **Imperative Voice**: Use verb-first instructions throughout (not second person)
+5. **Purpose-Built Resources**: Each component should solve specific repetitive needs
+
+## What Skills Provide
+
+**Four Core Capabilities:**
+1. **Specialized workflows** - Multi-step procedures for specific domains
+2. **Tool integrations** - Instructions for working with file formats or APIs
+3. **Domain expertise** - Company-specific knowledge, schemas, business logic
+4. **Bundled resources** - Scripts, references, and assets for complex tasks
+
+**Three-Level Loading System:**
+1. Metadata (name + description) - Always in context (~100 words)
+2. SKILL.md body - When skill triggers (<200 lines, optimal: 140-160)
+3. Bundled resources - As needed by Claude (unlimited)
+
+## Quick Start
+
+### Six-Step Creation Process
+
+**Step 1: Understand with Concrete Examples**
+Gather 3-5 realistic usage examples. Ask: "What would users say to trigger this skill?" and "What tasks should it accomplish?" → [Complete guide](./references/creation-workflow.md#step-1-understanding-the-skill-with-concrete-examples)
+
+**Step 2: Plan Reusable Components**
+Analyze examples to identify: scripts (repeated code), references (domain knowledge), assets (templates). → [Planning guide](./references/creation-workflow.md#step-2-planning-the-reusable-skill-contents)
+
+**Step 3: Initialize Skill**
+Run `scripts/init_skill.py <skill-name> --path <output-directory>` to generate template structure. → [Initialization details](./references/creation-workflow.md#step-3-initializing-the-skill)
+
+**Step 4: Edit Skill**
+Implement scripts/references/assets, then update SKILL.md using imperative voice. Apply progressive disclosure if >150 lines. → [Editing guide](./references/creation-workflow.md#step-4-edit-the-skill)
+
+**Step 5: Package and Validate**
+Run `scripts/package_skill.py <path/to/skill-folder>` to validate and create distributable zip. → [Packaging guide](./references/creation-workflow.md#step-5-packaging-a-skill)
+
+**Step 6: Iterate**
+Use on real tasks, notice struggles, update skill accordingly. → [Iteration guide](./references/creation-workflow.md#step-6-iterate)
+
+## Skill Anatomy
+
+```
+skill-name/
+├── SKILL.md (required)           # Entry point with frontmatter + markdown
+├── scripts/ (optional)           # Executable code (Python/Bash)
+├── references/ (optional)        # Documentation loaded as needed
+└── assets/ (optional)            # Templates, images, files for output
+```
+
+**Component Guidelines:**
+- **Scripts**: When same code is repeatedly rewritten or deterministic execution needed
+- **References**: For detailed specs, workflows, schemas, API docs (150-500 lines each)
+- **Assets**: For templates, boilerplate, images, fonts used in outputs
+- **Entry Point**: Core workflow, navigation, reminders (140-160 lines optimal)
+
+→ [Complete structure guide](./references/skill-structure.md)
+
+## Progressive Disclosure Pattern
+
+**When to apply:** Skills >150 lines total
+
+**Implementation:**
+1. Add `progressive_disclosure` frontmatter with summary, when_to_use, quick_start
+2. Reduce entry point to 140-160 lines (core workflow + navigation)
+3. Create 3-5 reference files (150-500 lines each)
+4. Organize by topic: structure, workflow, best practices, examples
+5. Add navigation section linking all references
+
+**Benefits:**
+- Entry loads only essential content
+- Deep detail available when needed
+- Better organization and maintainability
+- 20-30% reduction in entry point size
+
+→ [Complete progressive disclosure guide](./references/progressive-disclosure.md)
+
+**Meta-example:** This skill-creator demonstrates progressive disclosure:
+- Entry: 150 lines (28% reduction from 209)
+- References: 5 files with complete implementation details
+- Recently optimized: mcp-builder (160 lines), testing-anti-patterns (140 lines)
+
+## Navigation
+
+### Core Concepts
+- **[🏗️ Skill Structure](./references/skill-structure.md)** - Anatomy, components (scripts/references/assets), progressive disclosure architecture. Load when planning skill layout or understanding resource types.
+
+### Step-by-Step Process
+- **[🔄 Creation Workflow](./references/creation-workflow.md)** - Complete 6-step process from examples to iteration. Load when creating new skill or following structured workflow.
+
+### Design Patterns
+- **[📊 Progressive Disclosure](./references/progressive-disclosure.md)** - Three-level loading, implementation guide, anti-patterns, examples. Load when refactoring skills >150 lines or optimizing context usage.
+
+### Quality Standards
+- **[✅ Best Practices](./references/best-practices.md)** - Writing style, metadata quality, content organization, anti-patterns. Load when writing/reviewing skill content or ensuring quality.
+
+### Real-World Examples
+- **[📚 Examples](./references/examples.md)** - Complete skill examples: mcp-builder, testing-anti-patterns, pdf-editor, brand-guidelines, database-builder, frontend-builder. Load when starting new skill or seeking patterns.
+
+## Key Reminders
+
+- **Start with examples** - 3-5 concrete usage scenarios before designing
+- **Use init script** - `scripts/init_skill.py` creates proper structure automatically
+- **Imperative voice** - "To accomplish X, do Y" (not "You should do X")
+- **Progressive disclosure** - Entry <200 lines, details in references (for skills >150 lines)
+- **Avoid duplication** - Information lives in ONE place (entry summary, reference detail)
+- **Component clarity** - Scripts for code, references for knowledge, assets for templates
+- **Validate before sharing** - `scripts/package_skill.py` validates and packages
+- **Iterate continuously** - Use on real tasks, update based on struggles
+
+## Red Flags - STOP
+
+If you catch yourself:
+- "Let me write all the details in SKILL.md" → Move to references (progressive disclosure)
+- "I'll use second person" → Switch to imperative voice
+- "Same information in entry and reference" → Delete duplication
+- Using generic description → Be specific about activation conditions
+- Leaving example files from init script → Delete unused resources
+- Skipping validation → Always run package_skill.py before sharing
+- Creating skill without examples → Gather concrete usage scenarios first
+- Entry point >200 lines → Apply progressive disclosure pattern
+
+**ALL of these mean: STOP. Review principles and references.**
+
+## Integration with Other Skills
+
+**Meta-Skills:**
+- **skill-creator** (this skill) - Creates other skills, demonstrates its own patterns
+
+**Development Skills:**
+- **mcp-builder** - Example of progressive disclosure implementation
+- **testing-anti-patterns** - Example of ultra-lean entry point (140 lines)
+
+**Workflow Skills:**
+- **documentation** - Writing clear, structured content
+- **verification-before-completion** - Testing skills before packaging
+
+## Real-World Impact
+
+From skill optimization experience:
+- Progressive disclosure: 20-30% reduction in entry point size
+- mcp-builder: 209 → 160 lines (23% reduction, 6 references)
+- testing-anti-patterns: → 140 lines (ultra-lean with 4 references)
+- skill-creator: 209 → 150 lines (28% reduction, 5 references)
+- Context efficiency: Load only needed references (saves 50-80% context)
+- Maintainability: Update specific references without touching entry point
+- Clarity: Better organization improves discoverability and comprehension
+
+---
+
+**Remember:** Skills are modular packages that transform Claude into a specialized agent. Apply progressive disclosure for skills >150 lines. This skill demonstrates the pattern it teaches.

claude_mpm/skills/bundled/main/skill-creator/references/best-practices.md

@@ -0,0 +1,500 @@
+# Skill Creation Best Practices
+
+## Writing Style and Voice
+
+### Imperative Form (MANDATORY)
+
+All skill content MUST use imperative/infinitive form (verb-first instructions), not second person.
+
+**✅ Correct Examples:**
+- "To accomplish X, do Y"
+- "Follow these steps to complete the task"
+- "Load the reference file when needed"
+- "Execute the script with these parameters"
+- "Consider these factors before proceeding"
+
+**❌ Incorrect Examples:**
+- "You should do X"
+- "If you need to do X"
+- "You can find this in..."
+- "Your task is to..."
+- "You will need to..."
+
+**Rationale:**
+- Maintains consistency across all skills
+- Optimizes for AI comprehension
+- Removes ambiguity about audience
+- Creates professional, instructional tone
+- Easier to scan and parse
+
+### Voice and Tone Guidelines
+
+**Objective and Instructional:**
+- Focus on clear procedures and workflows
+- State facts and requirements directly
+- Avoid conversational filler
+- Be specific and actionable
+
+**Active Voice:**
+- "Execute the script" not "The script should be executed"
+- "Load the reference" not "The reference can be loaded"
+- "Validate the input" not "Input should be validated"
+
+**Present Tense:**
+- "The skill provides..." not "The skill will provide..."
+- "Claude loads..." not "Claude will load..."
+- "Scripts execute..." not "Scripts will execute..."
+
+### Documentation Style
+
+**Concise and Scannable:**
+- Use bullet points for lists
+- Keep paragraphs short (2-4 sentences)
+- Use headers to organize content
+- Highlight key terms in **bold**
+- Use code blocks for examples
+
+**Example-Driven:**
+- Show concrete examples
+- Demonstrate patterns in practice
+- Provide before/after comparisons
+- Include realistic scenarios
+
+## Metadata Quality
+
+### Name Field
+
+The `name:` field in YAML frontmatter should be:
+
+**Format:** kebab-case (lowercase with hyphens)
+
+**Examples:**
+- ✅ `skill-creator`
+- ✅ `mcp-builder`
+- ✅ `testing-anti-patterns`
+- ❌ `Skill Creator`
+- ❌ `skill_creator`
+- ❌ `skillCreator`
+
+### Description Field
+
+The `description:` field determines when Claude activates the skill. Write descriptions that:
+
+**Be Specific About Purpose:**
+- Clearly state what the skill does
+- Mention key capabilities
+- Include constraints or limitations
+
+**Use Third Person:**
+- "This skill should be used when..." ✅
+- "Use this skill when..." ❌
+- "The skill provides..." ✅
+- "Provides..." ❌
+
+**Include Activation Conditions:**
+- What user requests trigger the skill?
+- What keywords or scenarios activate it?
+- When should it NOT be used?
+
+**Examples:**
+
+✅ **Good:**
+```yaml
+description: Create high-quality MCP servers that enable LLMs to effectively interact with external services. Use when building MCP integrations for APIs or services in Python (FastMCP) or Node/TypeScript (MCP SDK).
+```
+
+❌ **Too Vague:**
+```yaml
+description: Helps with MCP servers.
+```
+
+❌ **Wrong Voice:**
+```yaml
+description: Use this when you need to build MCP servers.
+```
+
+✅ **Good:**
+```yaml
+description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
+```
+
+## Content Organization
+
+### Entry Point Structure
+
+For skills using progressive disclosure, organize the entry point with these sections:
+
+1. **Overview** (2-3 sentences)
+   - What the skill provides
+   - Key capabilities
+   - Primary value proposition
+
+2. **When to Use This Skill** (5-10 bullet points)
+   - Clear activation scenarios
+   - Specific trigger conditions
+   - Related keywords
+
+3. **The Iron Law** (Optional, if applicable)
+   - Non-negotiable principles
+   - Core constraints
+   - Fundamental requirements
+
+4. **Core Principles** (3-5 brief principles)
+   - Foundational guidelines
+   - Key philosophies
+   - Essential approaches
+
+5. **Quick Start** (5-10 steps)
+   - High-level workflow
+   - Phase-based organization
+   - Links to detailed references
+
+6. **Navigation** (Annotated list)
+   - All reference files
+   - Clear descriptions
+   - When to load each
+
+7. **Key Reminders** (5-10 bullets)
+   - Critical points
+   - Common pitfalls
+   - Essential practices
+
+8. **Red Flags - STOP** (5-10 warning signs)
+   - Anti-patterns to avoid
+   - Warning indicators
+   - Stop conditions
+
+9. **Integration with Other Skills** (Optional)
+   - Related skills
+   - Prerequisites
+   - Complementary skills
+
+10. **Real-World Impact** (Optional)
+    - Metrics and outcomes
+    - Evidence of effectiveness
+    - Success stories
+
+### Reference File Structure
+
+Each reference file should have:
+
+**Clear Purpose Statement:**
+```markdown
+# Reference Topic Name
+
+## Purpose
+
+Brief description of what this reference covers and when to use it.
+```
+
+**Logical Organization:**
+- Clear section hierarchy
+- Progressive complexity (simple → advanced)
+- Self-contained content
+- Cross-references where helpful
+
+**Appropriate Depth:**
+- 150-500 lines per file
+- Combine if <150 lines
+- Split if >500 lines
+
+## Resource Organization
+
+### Scripts Best Practices
+
+**When to Create Scripts:**
+- Same code repeatedly rewritten
+- Deterministic execution required
+- Complex operations benefit from testing
+- Performance optimization matters
+
+**Script Quality:**
+- Include usage documentation
+- Handle errors gracefully
+- Support common parameters
+- Add helpful error messages
+- Make executable (`chmod +x`)
+
+**Documentation in SKILL.md:**
+```markdown
+Execute `scripts/rotate_pdf.py <input.pdf> <output.pdf> <degrees>` to rotate PDFs.
+
+Parameters:
+- input.pdf: Source PDF file
+- output.pdf: Destination file path
+- degrees: Rotation angle (90, 180, 270)
+```
+
+### References Best Practices
+
+**Content That Belongs in References:**
+- Detailed specifications
+- API documentation
+- Database schemas
+- Step-by-step workflows
+- Best practice details
+- Examples and templates
+- Domain knowledge
+
+**Organization:**
+- One topic per file
+- Descriptive filenames
+- 150-500 lines each
+- Clear navigation from entry point
+
+**Avoid Duplication:**
+- Information lives in ONE place
+- Entry point has summary
+- Reference has detail
+- Never copy-paste between them
+
+**Large Files (>10k words):**
+Include grep patterns in SKILL.md:
+```markdown
+Search `references/api_docs.md` for specific endpoints:
+- "POST /users" - User creation
+- "GET /users/:id" - User retrieval
+- "PUT /users/:id" - User updates
+```
+
+### Assets Best Practices
+
+**Content That Belongs in Assets:**
+- Templates for output
+- Images and icons
+- Fonts and typography
+- Boilerplate code
+- Sample documents
+- Binary resources
+
+**Organization:**
+- Group by type or purpose
+- Descriptive directory names
+- Include README if structure is complex
+
+**Documentation in SKILL.md:**
+```markdown
+Copy `assets/frontend-template/` as starting point for new web applications.
+
+The template includes:
+- index.html - Main HTML structure
+- styles.css - Base styling
+- app.js - JavaScript framework setup
+```
+
+## Quality Standards
+
+### Completeness Checklist
+
+Before considering a skill complete:
+
+- [ ] YAML frontmatter includes required fields (name, description)
+- [ ] Description clearly states purpose and activation conditions
+- [ ] All planned scripts implemented and documented
+- [ ] All reference files created with clear purpose
+- [ ] All assets included and referenced
+- [ ] Entry point uses imperative voice throughout
+- [ ] Navigation section links to all references
+- [ ] No content duplication between entry and references
+- [ ] Examples provided for complex workflows
+- [ ] Red flags section warns about common mistakes
+- [ ] Integration with other skills documented
+
+### Progressive Disclosure Checklist
+
+For skills using progressive disclosure:
+
+- [ ] Progressive disclosure frontmatter added
+- [ ] Entry point reduced to <200 lines (optimal: 140-160)
+- [ ] 3-5 reference files created
+- [ ] Each reference 150-500 lines
+- [ ] Clear navigation with descriptions
+- [ ] No duplicated content
+- [ ] Descriptive reference filenames
+- [ ] References organized by logical topics
+
+### Validation and Testing
+
+**Automated Validation:**
+Use packaging script to validate:
+```bash
+scripts/package_skill.py <path/to/skill-folder>
+```
+
+Checks:
+- YAML frontmatter format
+- Required fields present
+- File structure correct
+- References exist
+
+**Manual Testing:**
+1. Use the skill on realistic tasks
+2. Note any confusion or missing information
+3. Iterate based on feedback
+4. Repeat until smooth execution
+
+## Common Anti-Patterns
+
+### ❌ Anti-Pattern 1: Overly Detailed Entry Point
+
+**Problem:** Entry point becomes monolithic reference manual
+
+**Example:**
+```markdown
+# My Skill
+
+## Step 1: Do This
+[300 lines of detailed instructions]
+
+## Step 2: Do That
+[400 lines of detailed instructions]
+```
+
+**Fix:** Move details to references
+```markdown
+# My Skill
+
+## Quick Start
+1. First phase - See [workflow.md](./references/workflow.md) for details
+2. Second phase - See [implementation.md](./references/implementation.md)
+```
+
+### ❌ Anti-Pattern 2: Unclear Activation Conditions
+
+**Problem:** Claude doesn't know when to use the skill
+
+**Example:**
+```yaml
+description: Helps with stuff
+```
+
+**Fix:** Specific activation conditions
+```yaml
+description: Creates database migration scripts. Use when user requests schema changes, table creation, or data migration for PostgreSQL or MySQL databases.
+```
+
+### ❌ Anti-Pattern 3: Second-Person Voice
+
+**Problem:** Violates imperative voice requirement
+
+**Example:**
+```markdown
+You should first load the reference file, then you can start implementing.
+```
+
+**Fix:** Imperative voice
+```markdown
+Load the reference file before implementing.
+```
+
+### ❌ Anti-Pattern 4: Duplicated Content
+
+**Problem:** Same information in multiple places
+
+**Example:**
+```markdown
+SKILL.md: "The API requires authentication via OAuth 2.0..."
+references/api.md: "The API requires authentication via OAuth 2.0..."
+```
+
+**Fix:** Summary in entry, detail in reference
+```markdown
+SKILL.md: "API uses OAuth 2.0 - see references/api.md for details"
+references/api.md: [Complete OAuth 2.0 implementation guide]
+```
+
+### ❌ Anti-Pattern 5: Missing Navigation
+
+**Problem:** References exist but aren't mentioned in entry point
+
+**Fix:** Explicit navigation section
+```markdown
+## Navigation
+
+- **[API Reference](./references/api.md)** - Complete API documentation
+- **[Examples](./references/examples.md)** - Sample implementations
+```
+
+### ❌ Anti-Pattern 6: Unused Resources
+
+**Problem:** Example files from init script left in skill
+
+**Fix:** Delete unused directories and files
+```bash
+rm -rf scripts/ references/ assets/  # If not needed
+```
+
+## Naming Conventions
+
+### Skill Names
+- kebab-case
+- Descriptive and specific
+- Avoid generic terms
+- Examples: `pdf-editor`, `brand-guidelines`, `mcp-builder`
+
+### Reference Filenames
+- kebab-case
+- Indicate content clearly
+- Group related content
+- Examples: `workflow.md`, `best-practices.md`, `api-reference.md`
+
+### Script Names
+- snake_case for Python
+- kebab-case for Bash
+- Clear purpose
+- Examples: `rotate_pdf.py`, `init-skill.sh`
+
+### Asset Names
+- Descriptive
+- Include type/purpose
+- Examples: `logo.png`, `template.html`, `boilerplate/`
+
+## Maintenance Best Practices
+
+### Version Control
+- Track skills in git
+- Commit after each iteration
+- Tag major versions
+- Include changelog
+
+### Documentation Updates
+- Update as skill evolves
+- Keep examples current
+- Remove outdated information
+- Test documented workflows
+
+### User Feedback
+- Collect usage feedback
+- Track common issues
+- Iterate based on patterns
+- Improve clarity continuously
+
+## Meta-Skill Considerations
+
+For skills that teach skill creation (like this one):
+
+**Demonstrate Your Own Teachings:**
+- Apply patterns you recommend
+- Use structure you advocate
+- Follow guidelines you establish
+- Be the example
+
+**Reference Recent Work:**
+- Cite recently optimized skills
+- Show before/after examples
+- Demonstrate real improvements
+- Prove effectiveness
+
+**Stay Current:**
+- Update as patterns evolve
+- Incorporate new best practices
+- Refine based on experience
+- Lead by example
+
+**This skill-creator skill exemplifies progressive disclosure by:**
+- Entry point <200 lines
+- 5 well-organized references
+- Clear navigation
+- No content duplication
+- Imperative voice throughout
+- Recent examples (mcp-builder, testing-anti-patterns)