` if needed
+- Keep it simple for broad compatibility
+
+---
+
+### 🌀 5. Surreal / Absurdist Text Memes
+
+**Requirements:** Markdown + strategic spacing
+
+**How to do it:**
+
+```markdown
+you awaken in the hallway of beans
+
+the moon whispers: *not again*
+
+---
+
+**OPTION 1:** accept the beans
+**OPTION 2:** become the beans
+
+you choose Option 3
+
+*there was no Option 3*
+```
+
+**Tips:**
+
+- Use italics for dream-logic emphasis
+- Insert `---` to create uncanny jumps
+- Be playful with lowercase/capitalization
+- Treat whitespace as tension
+
+---
+
+### 🗨️ 6. Tumblrisms (Multi-Speaker Chains)
+
+**Requirements:** Nested blockquotes
+
+**How to do it:**
+
+```markdown
+> **Person A:** frogs are neat
+>> **Person B:** frogs are powerful
+>>> **Person C:** I aspire to frog
+>>>> **Person D:** this post is making me lose my mind
+>>>>> **Person A:** good
+```
+
+**Tips:**
+
+- Increase `>` depth to show escalation
+- Add italics for emotional chaos
+- Bold names for clarity
+- Peak at 5 levels deep for readability
+
+---
+
+### 🐦 7. Twitter / X-style Micro-memes
+
+**Requirements:** Blockquote or plain markdown
+
+**How to do it:**
+
+```markdown
+> me: i'm productive
+> also me: alphabetizes rocks by emotional energy
+
+---
+
+**me at 3am:** what if bread could read
+
+**bread:** *softly* "help"
+```
+
+**Tips:**
+
+- Keep it tight (2–4 lines)
+- Use italics for "stage directions"
+- Short exaggeration = comedy
+- Em dash works great: "me: — also me:"
+
+---
+
+### 🧾 8. Reddit AITA / TIFU / Narrative Memes
+
+**Requirements:** Markdown headings + paragraphs
+
+**How to do it:**
+
+```markdown
+### TIFU by enabling Markdown features too much
+
+**Context:** I work in documentation.
+
+**What Happened:** Today I formatted a shopping list with H3 headings,
+bullet points, and citation links. My family staged an intervention.
+
+**Update:** They've hidden the Markdown guide. I'm formatting this from memory.
+
+**AITA?**
+```
+
+**Tips:**
+
+- Use headings for "post titles"
+- Sincere tone + mild absurdity = gold
+- Include typical Reddit formatting (bold labels)
+- The more mundane the subject, the funnier
+
+---
+
+### 🗿 9. Wojak-style Dialogues (Text-Only)
+
+**Requirements:** Bold names + minimal dialogue
+
+**How to do it:**
+
+```markdown
+**Doomer:** nothing matters
+**Zoomer:** drink water bro
+**Wojak:** *internal screaming*
+**Chad:** have you tried not caring
+**Doomer:** ...wait that's actually helpful
+**Chad:** i know
+```
+
+**Tips:**
+
+- Keep dialogue short
+- Rely on archetypes for instant recognition
+- Tone = half-honest, half-ironic
+- Works great in code blocks too
+
+---
+
+### 💬 10. Discord / Chat Log Memes
+
+**Requirements:** Code fence with timestamp format
+
+**How to do it:**
+
+````markdown
+```text
+[12:41] user123: you up?
+[12:42] system: error: feelings.exe not found
+[12:42] user123: same
+[12:43] bot: did you try turning your emotions off and on again?
+[12:44] user123: yes
+[12:44] system: critical error: emotions.dll missing since 2019
+```
+````
+
+**Tips:**
+
+- Timestamps add realism
+- Use usernames to amplify the joke
+- System messages = comedic gold
+- Maintain deadpan delivery
+
+---
+
+### 😀 11. Emojicore Memes
+
+**Requirements:** Just good spacing
+
+**How to do it:**
+
+```markdown
+🚶💨 leaving my responsibilities
+
+😔👉👈 wondering if coffee counts as a personality
+
+🎯 hitting the target (the target is rock bottom)
+
+✨ manifesting ✨ (chaos)
+```
+
+**Tips:**
+
+- Use emojis as syntax, not decoration
+- Vertical stacking works great
+- Pair emoji with understated text
+- Less is more
+
+---
+
+### 📚 12. Fake Wiki / Manual Pages
+
+**Requirements:** Markdown headings + bold labels
+
+**How to do it:**
+
+```markdown
+## Bread.exe
+
+**Category:** Deprecated Carbohydrate
+**Status:** Unstable
+**Introduced:** ~8000 BCE
+**Last Update:** Never
+
+### Known Issues
+
+- Becomes stale without manual intervention
+- Incompatible with lactose-intolerant systems
+- Memory leak when toasted incorrectly
+
+### Workarounds
+
+See: `butter.dll` documentation
+```
+
+**Tips:**
+
+- Keep the tone pseudo-academic
+- Use definition-style formatting
+- Technical jargon for mundane objects = peak comedy
+- Cross-reference other fake docs
+
+---
+
+### 🐕 13. Slang-Mutation Text Memes
+
+**Requirements:** Markdown paragraphs with stylized orthography
+
+**How to do it:**
+
+```markdown
+how 2 markdown:
+
+1. make text smol
+2. add sparklez ✨
+3. u done it
+
+**congrations** u did a format
+
+no take backsies
+```
+
+**Tips:**
+
+- Lean into childlike spelling
+- Use emoji to exaggerate tone
+- Mix formal structure (lists) with informal language
+- "Congrations" beats "congratulations" every time
+
+---
+
+### 👶 14. ELI5 But Wrong
+
+**Requirements:** Heading + confident incorrect explanation
+
+**How to do it:**
+
+```markdown
+### ELI5: Why do volcanoes erupt?
+
+Volcanoes are mountains that get too excited and sneeze the earth.
+The rocks fly out because they want to be birds but forgot how.
+This is called "geology."
+
+**Follow-up:** Why is lava hot?
+
+Because it's embarrassed about the whole situation.
+```
+
+**Tips:**
+
+- Confidence + incorrectness = humor
+- Keep explanation "plausible" sounding
+- Use actual ELI5 structure for authenticity
+- Works great for tech concepts too
+
+---
+
+### 📄 15. Corporate / Legalese Satire
+
+**Requirements:** Lists + bold labels
+
+**How to do it:**
+
+```markdown
+## Notice of Emotional Noncompliance
+
+**Issued to:** You
+**Date:** Whenever
+**Reason:** Your vibe is irregular
+
+### Required Actions
+
+- [ ] Submit Form 42-B "Vibe Correction Protocol" within 5 business days
+- [ ] Attend mandatory "Feeling Feelings Appropriately" training
+- [ ] Provide written documentation of three (3) genuine smiles
+
+**Failure to comply will result in:**
+
+1. Passive-aggressive Slack messages
+2. A pizza party (no pizza will be provided)
+3. Being asked to "circle back" indefinitely
+
+---
+
+*This notice has been automatically generated by the Department of Vibes.*
+```
+
+**Tips:**
+
+- Official tone for trivial things
+- Short, concise bullet points increase contrast
+- Use checkboxes for "action items"
+- Footer disclaimers are pure gold
+
+---
+
+## 🖼️ Image Memes via Pure URL
+
+Sometimes you want a visual punchline next to your textual meme. With **memegen.link**, you can generate classic image memes just by crafting a URL—no uploads, no editors. Then embed it in your Markdown with standard image syntax.
+
+### 🚀 Quick Start
+
+```markdown
+
+```
+
+That's it—your post renders the Drake format with top "using word art" and bottom "using markdown".
+
+---
+
+### 🔧 URL Anatomy
+
+```
+https://api.memegen.link/images/{template}/{top_text}/{bottom_text}.{ext}?{options}
+```
+
+**Components:**
+
+- `template`: meme name (e.g., `drake`, `two-buttons`, `distracted-boyfriend`)
+- `top_text` / `bottom_text`: your captions
+- `ext`: `png` (default), `jpg`, or `webp` (good for lighter pages)
+- `options`: query params (e.g., `font`, `width`, `watermark`)
+
+**Example:**
+
+```markdown
+
+```
+
+---
+
+### 📝 Text Encoding Cheatsheet
+
+Memegen uses compact encoding so URLs stay readable:
+
+| Character | Encoding | Example |
+|-----------|----------|---------|
+| Space | `_` | `hello world` → `hello_world` |
+| Hyphen | `--` | `foo-bar` → `foo--bar` |
+| Underscore | `__` | `foo_bar` → `foo__bar` |
+| Question mark | `~q` | `why?` → `why~q` |
+| Percent | `~p` | `50%` → `50~p` |
+| Hash | `~h` | `#tag` → `~htag` |
+| Slash (literal) | `~s` | `foo/bar` → `foo~sbar` |
+| Quotes | `''` | `he said "hi"` → `he_said_''hi''` |
+
+**Line breaks:** Use `%0A` (URL-encoded newline) inside a caption.
+
+**Example:**
+```
+top_line%0Asecond_line
+```
+
+---
+
+### ⚙️ Common Options (Query String)
+
+Append with `?` after the file extension:
+
+```markdown
+?font=impact # Default is already impact; try notosans
+?width=600&height=600 # Size control; height optional
+?watermark=none # Remove tiny watermark
+?background=URL # Custom template; URL-encode it
+```
+
+**Example:**
+
+```markdown
+
+```
+
+---
+
+### 🎭 Popular Templates
+
+Quick reference for common meme formats:
+
+| Template | Use Case |
+|----------|----------|
+| `drake` | Rejecting one thing, approving another |
+| `two-buttons` | Difficult choice between two options |
+| `distracted-boyfriend` | Being distracted by something new |
+| `gru-plan` | Plan that goes wrong at the end |
+| `change-my-mind` | Stating an opinion confidently |
+| `mocking-spongebob` | Mocking someone's statement |
+| `is-this-a-pigeon` | Misidentifying something obvious |
+| `surprised-pikachu` | Shocked by predictable outcome |
+| `success-kid` | Celebrating small victories |
+| `uno-draw-25` | Refusing to do something even if costly |
+| `custom` | Use with `?background=` for any image |
+
+---
+
+### 🎯 Blank Sides & One-Sided Captions
+
+Leave a side blank with `_` (single underscore).
+
+**Top only:**
+
+```markdown
+
+```
+
+**Bottom only:**
+
+```markdown
+
+```
+
+---
+
+### 📏 Multiline Captions
+
+Use `%0A` for line breaks inside a side:
+
+```markdown
+
+```
+
+---
+
+### 🎨 Custom Backgrounds (Brand or Screenshot)
+
+Use the `custom` template + `background` parameter. The background must be publicly reachable.
+
+```markdown
+
+```
+
+**Tip:** Pair a screenshot of your app/graph as background to comment on it memetically in the post.
+
+---
+
+### ♿ Accessibility & SEO
+
+**Always provide descriptive alt text:**
+
+```markdown
+
+```
+
+Screen readers will read your alt text, making the joke accessible to everyone.
+
+---
+
+### 📦 Quick Copy-Paste Recipes
+
+**Drake (top/bottom):**
+```markdown
+
+```
+
+**Two Buttons (multiline with %0A):**
+```markdown
+
+```
+
+**Change My Mind (top only):**
+```markdown
+
+```
+
+**Surprised Pikachu (bottom only):**
+```markdown
+
+```
+
+**Custom background (brand screenshot):**
+```markdown
+
+```
+
+---
+
+## 🎭 Mixing Text + Image Memes
+
+Blend text-only formats and image memes to pace a post effectively.
+
+### ✅ Rhythm Pattern
+
+**1. Start with text** to set up context:
+
+````markdown
+### The Day I Realized Markdown Is Too Powerful
+
+```text
+>be me
+>ship blog revamp
+>marketing wants "fun"
+>accidentally create meme culture
+```
+````
+
+**2. Follow with a visual** to amplify the punchline:
+
+```markdown
+
+```
+
+**3. Close with another text format** for resolution:
+
+```markdown
+**Status:** fun achieved
+**Risk:** puns leaked to production
+**Next Steps:** embrace chaos
+```
+
+### ✅ Strategic Placement
+
+**Good patterns:**
+
+- Greentext → Image → Corporate satire
+- Tumblr chain → ASCII art → Image
+- Chat log → Image → Shitpost poetry
+
+**Avoid:**
+
+- 5 images in a row (visual fatigue)
+- 3 long copypastas back-to-back (reader exhaustion)
+- Image without context (confusing)
+
+### ✅ Complementary Pairs
+
+Match text and image memes thematically:
+
+| Text Format | Image Format | Why It Works |
+|-------------|--------------|--------------|
+| Greentext | Drake | Both are format-specific classics |
+| Corporate satire | Two buttons | Amplifies "decision paralysis" theme |
+| Chat log | Surprised Pikachu | Both capture reactions |
+| Reddit AITA | Distracted boyfriend | Narrative + visual work together |
+| Wojak dialogue | Custom background | Text provides context for visual |
+
+---
+
+## 🔥 Advanced Features
+
+### 🎨 Custom CSS for Greentext (MkDocs / Hugo)
+
+Add custom styling for greentext blocks:
+
+```css
+.greentext {
+ color: #789922;
+ font-family: 'Courier New', monospace;
+ background-color: #f0f0f0;
+ padding: 1rem;
+ border-left: 4px solid #789922;
+}
+```
+
+Then wrap greentext in HTML:
+
+```html
+
+
+>be you
+>styling markdown like a pro
+>mfw it actually looks good
+
+
+```
+
+---
+
+### 📢 Admonitions (MkDocs Material, Docusaurus)
+
+Use admonition blocks for "official" memes or mock disclaimers:
+
+```markdown
+!!! warning "System Alert"
+ Your snacks have been revoked pending performance review.
+
+!!! danger "Critical Error"
+ `feelings.exe` has stopped responding.
+ Would you like to send an error report? [Yes] [Yes]
+```
+
+---
+
+### 🗂️ Collapsible Sections
+
+Great for long copypastas and Tumblr chains:
+
+```markdown
+
+Click to expand the legendary copypasta
+
+What the fuck did you just fucking say about Markdown...
+(rest of copypasta)
+
+
+```
+
+---
+
+### 🎯 Tabs (Docusaurus, MkDocs)
+
+Show multiple meme variations side-by-side:
+
+```markdown
+=== "Greentext"
+
+ ```text
+ >be me
+ >tabs are cool
+ ```
+
+=== "Corporate"
+
+ **Notice:** Tabs have been deemed acceptable for meme deployment.
+
+=== "Image"
+
+ 
+```
+
+---
+
+## 🚀 Production Tips
+
+### ⚡ Performance
+
+**For text memes:**
+- Already optimal (it's just text!)
+- No external dependencies
+- Fast rendering
+
+**For image memes:**
+- Prefer `webp` format for 30-50% smaller files
+- Set consistent `?width=640` for predictable layout
+- Consider lazy loading: `loading="lazy"` on `
` tags
+- Cache memegen.link URLs (they're stable)
+
+### ♿ Accessibility
+
+**Text memes:**
+- Already screen-reader friendly
+- Use semantic HTML where appropriate
+- Avoid ASCII art for critical information
+
+**Image memes:**
+- Always provide descriptive alt text
+- Describe the joke, not just "meme image"
+- Good: `![Drake rejecting documentation, approving memes]`
+- Bad: `![funny meme]`
+
+### 🔍 SEO
+
+**Text memes:**
+- Search engines index text content
+- Use semantic HTML for structure
+- Don't hide important information in ASCII art
+
+**Image memes:**
+- Alt text provides indexable content
+- Descriptive filenames help (though memegen URLs are generated)
+- Consider adding captions below images for context
+
+---
+
+## 📚 Complete Blog Example
+
+Here's a full blog post example mixing multiple meme formats:
+
+```markdown
+---
+title: "The Deployment Chronicles"
+date: 2025-01-11
+tags: [devops, humor, deployments]
+---
+
+# The Deployment Chronicles
+
+## Pre-Deployment Anxiety
+
+```text
+>be me
+>friday afternoon
+>manager: "quick deploy?"
+>mfw "quick" and "deploy" in same sentence
+```
+
+**Narrator:** *It was not quick.*
+
+---
+
+## The Planning Phase
+
+### Decision Matrix
+
+
+
+**Status:** We chose poorly.
+
+---
+
+## During Deployment
+
+```text
+[15:42] devops_bot: deployment started
+[15:43] engineer1: looks good
+[15:44] engineer2: why is prod slow
+[15:45] system: ERROR: connection timeout
+[15:46] engineer1: this is fine
+[15:47] system: CRITICAL: database locked
+[15:48] engineer1: THIS IS NOT FINE
+```
+
+
+
+---
+
+## Post-Mortem
+
+### Incident Report #2847
+
+**Issued to:** Engineering Team
+**Date:** 2025-01-11 18:30 UTC
+**Reason:** Premature optimization of deployment strategy
+
+#### Required Actions
+
+- [ ] Never deploy on Friday again
+- [ ] Actually read the deployment checklist
+- [ ] Stop trusting "it works on my machine"
+
+**Consequences:**
+
+1. Mandatory attendance at "Why Friday Deploys Are Bad" training
+2. Team pizza party (cancelled due to incident)
+3. Existential dread
+
+---
+
+*This incident report has been automatically generated by the Department of Preventable Disasters.*
+
+---
+
+## Lessons Learned
+
+**me:** let's deploy carefully next time
+*also me next Friday:* what could go wrong
+
+---
+
+## Success Metrics
+
+After fixing everything:
+
+
+
+🎯 hitting targets (the target was "don't break prod permanently")
+✨ manifesting ✨ (working deployments)
+😅 lessons learned (until next time)
+
+---
+
+## ELI5: What is a deployment?
+
+A deployment is when you tell the computer to use your new code.
+Sometimes the computer listens.
+Sometimes the computer decides chaos is more fun.
+This is called "DevOps."
+
+**Follow-up:** Why do deployments fail?
+
+Because the computer has feelings and Friday afternoon hurts those feelings.
+
+---
+
+## Conclusion
+
+roses are red
+deploys cause pain
+test in production
+again and again
+
+---
+
+*Want more deployment horror stories? Subscribe to our RSS feed of suffering.*
+```
+
+---
+
+## 🎓 Summary
+
+This guide covered:
+
+1. **Why Markdown** - Preserves formatting, accessible, version-controllable
+2. **Core techniques** - Code fences, blockquotes, spacing, emphasis
+3. **15 textual formats** - From greentext to corporate satire
+4. **Image memes** - Using memegen.link URLs
+5. **Mixing formats** - Strategic pacing and rhythm
+6. **Advanced features** - CSS, admonitions, tabs
+7. **Production tips** - Performance, accessibility, SEO
+8. **Complete example** - Real-world blog post
+
+**Key takeaways:**
+
+- Text memes are fast, accessible, and version-controllable
+- Image memes via URL require no uploads or storage
+- Mix formats strategically for comedic pacing
+- Always provide alt text for accessibility
+- Use spacing and whitespace as a comedic tool
+- Keep text concise for maximum impact
+
+**Resources:**
+
+- Memegen API: https://api.memegen.link/docs/
+- Templates: https://api.memegen.link/templates/
+- MkDocs Material: https://squidfunk.github.io/mkdocs-material/
+
+---
+
+*This guide is a living document. Contributions welcome.*
diff --git a/dist/plugins/meme-factory/skills/meme-factory/scripts/meme_generator.py b/dist/plugins/meme-factory/skills/meme-factory/scripts/meme_generator.py
new file mode 100644
index 0000000..4c35525
--- /dev/null
+++ b/dist/plugins/meme-factory/skills/meme-factory/scripts/meme_generator.py
@@ -0,0 +1,244 @@
+#!/usr/bin/env python3
+"""Meme Generator Helper.
+
+A Python interface for the memegen.link API to generate memes programmatically.
+
+Usage:
+ python meme_generator.py generate buzz "memes" "memes everywhere"
+ python meme_generator.py list-templates
+ python meme_generator.py suggest "deployment success"
+
+Or import as a module:
+ from meme_generator import MemeGenerator
+ meme = MemeGenerator()
+ url = meme.generate("buzz", "hello", "world")
+"""
+
+import argparse
+import urllib.parse
+
+
+class MemeGenerator:
+ """Generate memes using the memegen.link API."""
+
+ BASE_URL = "https://api.memegen.link"
+
+ # Popular templates with their use cases
+ TEMPLATES = {
+ "buzz": "X, X everywhere (Buzz Lightyear)",
+ "drake": "Comparing two options (Drake Hotline Bling)",
+ "success": "Celebrating wins (Success Kid)",
+ "fine": "Things going wrong (This is Fine Dog)",
+ "fry": "Uncertainty (Futurama Fry)",
+ "changemind": "Controversial opinions (Change My Mind)",
+ "distracted": "Priorities/distractions (Distracted Boyfriend)",
+ "yodawg": "Yo dawg, I heard you like X (Xzibit)",
+ "interesting": "I don't always X (Most Interesting Man)",
+ "mordor": "One does not simply X (Boromir)",
+ "yuno": "Y U NO (Y U NO Guy)",
+ "doge": "Much X, very Y (Doge)",
+ "wonka": "Condescending statements (Wonka)",
+ "ancient": "Aliens/conspiracy (Ancient Aliens Guy)",
+ "skeptical": "Skeptical reactions (Third World Skeptical Kid)",
+ "awesome": "Good/bad situations (Awesome/Awkward Penguin)",
+ "rollsafe": "Can't X if Y (Roll Safe)",
+ "surprised": "Surprised reactions (Surprised Pikachu)",
+ "thinking": "Thinking/pondering (Thinking Guy)",
+ "boardroom": "Bad suggestions (Boardroom Meeting)",
+ }
+
+ # Context-based template suggestions
+ CONTEXT_MAP = {
+ "success": ["success", "awesome"],
+ "failure": ["fine", "yuno"],
+ "comparison": ["drake", "awesome", "distracted"],
+ "uncertainty": ["fry", "suspicious"],
+ "statement": ["buzz", "yodawg", "interesting", "mordor", "changemind"],
+ "reaction": ["success", "fine", "surprised", "thinking"],
+ "humor": ["doge", "wonka", "ancient", "rollsafe"],
+ "deployment": ["success", "fine", "interesting"],
+ "testing": ["success", "fry", "interesting"],
+ "debugging": ["fine", "fry", "buzz"],
+ "documentation": ["yodawg", "buzz", "wonka"],
+ }
+
+ def __init__(self) -> None:
+ """Initialize the meme generator."""
+
+ def _format_text(self, text: str) -> str:
+ """Format text for URL inclusion following memegen rules."""
+ replacements = {
+ " ": "_",
+ "-": "--",
+ "_": "__",
+ "?": "~q",
+ "%": "~p",
+ "#": "~h",
+ "/": "~s",
+ '"': "''",
+ }
+
+ escaped = "".join(replacements.get(char, char) for char in text)
+
+ # Percent-encode any remaining reserved characters while preserving
+ # memegen's escape sequences and allowed characters.
+ return urllib.parse.quote(escaped, safe="-_~")
+
+ def generate( # noqa: PLR0913
+ self,
+ template: str,
+ top_text: str = "",
+ bottom_text: str = "",
+ extension: str = "png",
+ width: int | None = None,
+ height: int | None = None,
+ layout: str | None = None,
+ style: str | None = None,
+ font: str | None = None,
+ ) -> str:
+ """Generate a meme URL.
+
+ Args:
+ template: Template name (e.g., 'buzz', 'drake')
+ top_text: Text for the top of the meme
+ bottom_text: Text for the bottom of the meme
+ extension: Image format ('png', 'jpg', 'webp', 'gif')
+ width: Optional width in pixels
+ height: Optional height in pixels
+ layout: Optional layout ('top', 'bottom', 'default')
+ style: Optional style or custom background URL
+ font: Optional font name
+
+ Returns:
+ URL to the generated meme
+
+ """
+ # Format text
+ top = self._format_text(top_text) if top_text else "_"
+ bottom = self._format_text(bottom_text) if bottom_text else "_"
+
+ # Build base URL
+ url = f"{self.BASE_URL}/images/{template}/{top}/{bottom}.{extension}"
+
+ # Add query parameters
+ params = {}
+ if width:
+ params["width"] = str(width)
+ if height:
+ params["height"] = str(height)
+ if layout:
+ params["layout"] = layout
+ if style:
+ params["style"] = style
+ if font:
+ params["font"] = font
+
+ if params:
+ query_string = urllib.parse.urlencode(params)
+ url = f"{url}?{query_string}"
+
+ return url
+
+ def suggest_template_for_context(self, context: str) -> str:
+ """Suggest a template based on context.
+
+ Args:
+ context: Description of the situation (e.g., 'deployment success')
+
+ Returns:
+ Suggested template name
+
+ """
+ context_lower = context.lower()
+
+ # Check for keyword matches
+ for key, templates in self.CONTEXT_MAP.items():
+ if key in context_lower:
+ return templates[0]
+
+ # Default fallback
+ return "buzz"
+
+ def list_templates(self) -> dict[str, str]:
+ """List all available templates with descriptions.
+
+ Returns:
+ Dictionary of template names and descriptions
+
+ """
+ return self.TEMPLATES
+
+ def get_markdown_image(self, url: str, alt_text: str = "Meme", width: int | None = None) -> str:
+ """Generate markdown for embedding the meme image.
+
+ Args:
+ url: The meme URL
+ alt_text: Alternative text for the image
+ width: Optional width specification
+
+ Returns:
+ Markdown image syntax
+
+ """
+ if width:
+ return f'
'
+ return f""
+
+
+def main() -> None:
+ """CLI interface for the meme generator."""
+ parser = argparse.ArgumentParser(description="Generate memes using memegen.link")
+ subparsers = parser.add_subparsers(dest="command", help="Command to run")
+
+ # Generate command
+ generate_parser = subparsers.add_parser("generate", help="Generate a meme")
+ generate_parser.add_argument("template", help="Template name (e.g., buzz, drake)")
+ generate_parser.add_argument("top", help="Top text")
+ generate_parser.add_argument("bottom", nargs="?", default="", help="Bottom text")
+ generate_parser.add_argument(
+ "--extension", "-e", default="png", help="Image format (png, jpg, webp, gif)"
+ )
+ generate_parser.add_argument("--width", "-w", type=int, help="Image width")
+ generate_parser.add_argument("--height", type=int, help="Image height")
+ generate_parser.add_argument("--layout", "-l", help="Layout (top, bottom, default)")
+ generate_parser.add_argument("--markdown", "-m", action="store_true", help="Output as markdown")
+
+ # List templates command
+ subparsers.add_parser("list-templates", help="List all available templates")
+
+ # Suggest template command
+ suggest_parser = subparsers.add_parser("suggest", help="Suggest template for context")
+ suggest_parser.add_argument("context", help="Context description")
+
+ args = parser.parse_args()
+ generator = MemeGenerator()
+
+ if args.command == "generate":
+ generator.generate(
+ template=args.template,
+ top_text=args.top,
+ bottom_text=args.bottom,
+ extension=args.extension,
+ width=args.width,
+ height=getattr(args, "height", None),
+ layout=args.layout,
+ )
+ if args.markdown:
+ pass
+ else:
+ pass
+
+ elif args.command == "list-templates":
+ templates = generator.list_templates()
+ for _name, _description in sorted(templates.items()):
+ pass
+
+ elif args.command == "suggest":
+ generator.suggest_template_for_context(args.context)
+
+ else:
+ parser.print_help()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/dist/plugins/mermaid-diagrams/skills/mermaid-diagrams/README.md b/dist/plugins/mermaid-diagrams/skills/mermaid-diagrams/README.md
new file mode 100644
index 0000000..9b09be9
--- /dev/null
+++ b/dist/plugins/mermaid-diagrams/skills/mermaid-diagrams/README.md
@@ -0,0 +1,243 @@
+# Mermaid Diagrams Skill
+
+A comprehensive guide for creating professional software diagrams using Mermaid's text-based syntax. This skill enables you to visualize system architecture, document code structure, model databases, and communicate technical concepts through diagrams.
+
+## Purpose
+
+Transform complex technical concepts into clear, maintainable diagrams that can be version-controlled alongside your code. Mermaid diagrams are rendered from simple text definitions, making them easy to update, review in pull requests, and maintain over time.
+
+## When to Use This Skill
+
+Use this skill when you need to:
+
+- **Document architecture** - Visualize system context, containers, components, and deployment
+- **Model domains** - Create domain models with entities, relationships, and behaviors
+- **Explain flows** - Show API interactions, user journeys, authentication sequences
+- **Design databases** - Document table relationships, keys, and schema structure
+- **Plan processes** - Map workflows, decision trees, algorithms, and pipelines
+- **Communicate designs** - Align stakeholders on technical decisions before coding
+
+### Trigger Phrases
+
+The skill activates when you mention:
+- "diagram", "visualize", "model", "map out", "show the flow"
+- "architecture diagram", "class diagram", "sequence diagram", "flowchart"
+- "database schema", "ERD", "entity relationship"
+- "system design", "data model", "domain model"
+
+## How It Works
+
+1. **Choose the right diagram type** based on what you want to communicate
+2. **Start with core elements** - entities, actors, or components
+3. **Add relationships** - connections, flows, interactions
+4. **Refine incrementally** - add details, styling, notes
+5. **Export or embed** - use in documentation, PRs, wikis
+
+Mermaid syntax is intuitive and follows a consistent pattern across all diagram types:
+
+```mermaid
+diagramType
+ definition content
+```
+
+## Key Features
+
+### 9 Diagram Types Supported
+
+1. **Class Diagrams** - Domain models, OOP design, entity relationships
+2. **Sequence Diagrams** - API flows, user interactions, temporal sequences
+3. **Flowcharts** - User journeys, processes, decision logic, pipelines
+4. **Entity Relationship Diagrams** - Database schemas, table relationships
+5. **C4 Architecture Diagrams** - System context, containers, components
+6. **State Diagrams** - State machines, lifecycle states
+7. **Git Graphs** - Branching strategies, version control flows
+8. **Gantt Charts** - Project timelines, scheduling
+9. **Pie/Bar Charts** - Data visualization, metrics
+
+### Advanced Capabilities
+
+- **Themes and styling** - Default, forest, dark, neutral, base themes
+- **Custom theming** - Configure colors, fonts, and layout
+- **Layout options** - Dagre (balanced) or ELK (advanced)
+- **Look options** - Classic or hand-drawn sketch style
+- **Subgraphs** - Group related elements for clarity
+- **Notes and comments** - Add context and explanations
+- **Alt/loop/opt blocks** - Complex flow control in sequences
+
+### Integration Support
+
+- **GitHub/GitLab** - Automatic rendering in Markdown files
+- **VS Code** - Preview with Markdown Mermaid extension
+- **Notion, Obsidian, Confluence** - Built-in support
+- **Export** - PNG, SVG, PDF via Mermaid Live or CLI
+
+## Usage Examples
+
+### Example 1: Document a Domain Model
+
+**When:** You're designing a video streaming platform and need to model core entities.
+
+```mermaid
+classDiagram
+ Title -- Genre
+ Title *-- Season
+ Title *-- Review
+ User --> Review : creates
+
+ class Title {
+ +string name
+ +int releaseYear
+ +play()
+ }
+
+ class Genre {
+ +string name
+ +getTopTitles()
+ }
+```
+
+### Example 2: Explain an API Authentication Flow
+
+**When:** You need to document how login works for frontend developers.
+
+```mermaid
+sequenceDiagram
+ participant User
+ participant API
+ participant Database
+
+ User->>API: POST /login
+ API->>Database: Query credentials
+ Database-->>API: Return user data
+ alt Valid credentials
+ API-->>User: 200 OK + JWT token
+ else Invalid credentials
+ API-->>User: 401 Unauthorized
+ end
+```
+
+### Example 3: Map a User Journey
+
+**When:** You're planning a feature and need to visualize the user flow.
+
+```mermaid
+flowchart TD
+ Start([User visits site]) --> Auth{Authenticated?}
+ Auth -->|No| Login[Show login page]
+ Auth -->|Yes| Dashboard[Show dashboard]
+ Login --> Creds[Enter credentials]
+ Creds --> Validate{Valid?}
+ Validate -->|Yes| Dashboard
+ Validate -->|No| Error[Show error]
+ Error --> Login
+```
+
+### Example 4: Design a Database Schema
+
+**When:** You're planning table relationships for a new feature.
+
+```mermaid
+erDiagram
+ USER ||--o{ ORDER : places
+ ORDER ||--|{ LINE_ITEM : contains
+ PRODUCT ||--o{ LINE_ITEM : includes
+
+ USER {
+ int id PK
+ string email UK
+ string name
+ datetime created_at
+ }
+
+ ORDER {
+ int id PK
+ int user_id FK
+ decimal total
+ datetime created_at
+ }
+```
+
+### Example 5: Visualize System Architecture (C4)
+
+**When:** You need to show how systems and external services interact.
+
+```mermaid
+C4Context
+ title System Context Diagram for E-commerce Platform
+
+ Person(customer, "Customer", "A user browsing and purchasing products")
+ System(webApp, "Web Application", "Provides product catalog and checkout")
+ System_Ext(payment, "Payment Gateway", "Processes payments")
+ System_Ext(email, "Email Service", "Sends order confirmations")
+
+ Rel(customer, webApp, "Browses products, places orders")
+ Rel(webApp, payment, "Processes payments", "HTTPS")
+ Rel(webApp, email, "Sends notifications", "SMTP")
+```
+
+## Getting Started
+
+1. **Identify what you need to communicate** - Architecture? Flow? Data model?
+2. **Choose the appropriate diagram type** - See "Diagram Type Selection Guide" in SKILL.md
+3. **Start simple** - Add core entities/components first
+4. **Add relationships** - Connect elements with appropriate connectors
+5. **Refine and style** - Add details, notes, and custom theming
+6. **Validate** - Test in [Mermaid Live Editor](https://mermaid.live)
+7. **Embed or export** - Use in Markdown, export as image, or integrate
+
+## Detailed References
+
+For comprehensive syntax and advanced features, see:
+
+- **[SKILL.md](SKILL.md)** - Quick start guide and diagram selection
+- **[references/class-diagrams.md](references/class-diagrams.md)** - Relationships, multiplicity, methods
+- **[references/sequence-diagrams.md](references/sequence-diagrams.md)** - Messages, activations, loops, alt blocks
+- **[references/flowcharts.md](references/flowcharts.md)** - Node shapes, decision logic, subgraphs
+- **[references/erd-diagrams.md](references/erd-diagrams.md)** - Cardinality, keys, attributes
+- **[references/c4-diagrams.md](references/c4-diagrams.md)** - Context, container, component levels
+- **[references/advanced-features.md](references/advanced-features.md)** - Themes, styling, configuration
+
+## Best Practices
+
+1. **Start simple, iterate** - Begin with core elements, add complexity gradually
+2. **One diagram, one concept** - Keep diagrams focused and split large views
+3. **Use meaningful names** - Clear labels make diagrams self-documenting
+4. **Comment liberally** - Use `%%` to explain non-obvious relationships
+5. **Version control** - Store `.mmd` files with code, update as system evolves
+6. **Add context** - Include titles and notes explaining diagram purpose
+7. **Validate syntax** - Test in Mermaid Live before committing
+8. **Keep it readable** - Don't overcrowd; split into multiple diagrams if needed
+
+## Common Use Cases
+
+- **Onboarding** - Help new team members understand system structure
+- **Design reviews** - Visualize proposals before implementation
+- **Documentation** - Create living docs that evolve with code
+- **Architecture decisions** - Align stakeholders on technical choices
+- **Refactoring** - Plan restructuring with before/after diagrams
+- **API handoffs** - Document flows for frontend/backend coordination
+- **Database migrations** - Visualize schema changes
+
+## Tips for Success
+
+- **Test incrementally** - Validate syntax as you build to catch errors early
+- **Use consistent naming** - Match diagram names to code/database names
+- **Leverage GitHub rendering** - Diagrams appear automatically in `.md` files
+- **Export for presentations** - Use Mermaid Live or CLI for high-res exports
+- **Collaborate** - Diagrams are great for PR discussions and design docs
+- **Keep updated** - Update diagrams when code changes to prevent drift
+
+## Tools and Resources
+
+- **[Mermaid Live Editor](https://mermaid.live)** - Interactive editor with instant preview and export
+- **[Official Documentation](https://mermaid.js.org)** - Comprehensive syntax reference
+- **Mermaid CLI** - `npm install -g @mermaid-js/mermaid-cli` for batch exports
+- **VS Code Extension** - "Markdown Preview Mermaid Support" for live preview
+- **GitHub** - Native rendering in all `.md` files
+
+## Support
+
+For questions, syntax help, or advanced features, refer to:
+- SKILL.md for quick reference
+- Reference files in `references/` for detailed syntax
+- [Mermaid official docs](https://mermaid.js.org) for latest features
diff --git a/dist/plugins/mermaid-diagrams/skills/mermaid-diagrams/SKILL.md b/dist/plugins/mermaid-diagrams/skills/mermaid-diagrams/SKILL.md
new file mode 100644
index 0000000..ece9c4e
--- /dev/null
+++ b/dist/plugins/mermaid-diagrams/skills/mermaid-diagrams/SKILL.md
@@ -0,0 +1,216 @@
+---
+name: mermaid-diagrams
+description: Comprehensive guide for creating software diagrams using Mermaid syntax. Use when users need to create, visualize, or document software through diagrams including class diagrams (domain modeling, object-oriented design), sequence diagrams (application flows, API interactions, code execution), flowcharts (processes, algorithms, user journeys), entity relationship diagrams (database schemas), C4 architecture diagrams (system context, containers, components), state diagrams, git graphs, pie charts, gantt charts, or any other diagram type. Triggers include requests to "diagram", "visualize", "model", "map out", "show the flow", or when explaining system architecture, database design, code structure, or user/application flows.
+---
+
+# Mermaid Diagramming
+
+Create professional software diagrams using Mermaid's text-based syntax. Mermaid renders diagrams from simple text definitions, making diagrams version-controllable, easy to update, and maintainable alongside code.
+
+## Core Syntax Structure
+
+All Mermaid diagrams follow this pattern:
+
+```mermaid
+diagramType
+ definition content
+```
+
+**Key principles:**
+- First line declares diagram type (e.g., `classDiagram`, `sequenceDiagram`, `flowchart`)
+- Use `%%` for comments
+- Line breaks and indentation improve readability but aren't required
+- Unknown words break diagrams; parameters fail silently
+
+## Diagram Type Selection Guide
+
+**Choose the right diagram type:**
+
+1. **Class Diagrams** - Domain modeling, OOP design, entity relationships
+ - Domain-driven design documentation
+ - Object-oriented class structures
+ - Entity relationships and dependencies
+
+2. **Sequence Diagrams** - Temporal interactions, message flows
+ - API request/response flows
+ - User authentication flows
+ - System component interactions
+ - Method call sequences
+
+3. **Flowcharts** - Processes, algorithms, decision trees
+ - User journeys and workflows
+ - Business processes
+ - Algorithm logic
+ - Deployment pipelines
+
+4. **Entity Relationship Diagrams (ERD)** - Database schemas
+ - Table relationships
+ - Data modeling
+ - Schema design
+
+5. **C4 Diagrams** - Software architecture at multiple levels
+ - System Context (systems and users)
+ - Container (applications, databases, services)
+ - Component (internal structure)
+ - Code (class/interface level)
+
+6. **State Diagrams** - State machines, lifecycle states
+7. **Git Graphs** - Version control branching strategies
+8. **Gantt Charts** - Project timelines, scheduling
+9. **Pie/Bar Charts** - Data visualization
+
+## Quick Start Examples
+
+### Class Diagram (Domain Model)
+```mermaid
+classDiagram
+ Title -- Genre
+ Title *-- Season
+ Title *-- Review
+ User --> Review : creates
+
+ class Title {
+ +string name
+ +int releaseYear
+ +play()
+ }
+
+ class Genre {
+ +string name
+ +getTopTitles()
+ }
+```
+
+### Sequence Diagram (API Flow)
+```mermaid
+sequenceDiagram
+ participant User
+ participant API
+ participant Database
+
+ User->>API: POST /login
+ API->>Database: Query credentials
+ Database-->>API: Return user data
+ alt Valid credentials
+ API-->>User: 200 OK + JWT token
+ else Invalid credentials
+ API-->>User: 401 Unauthorized
+ end
+```
+
+### Flowchart (User Journey)
+```mermaid
+flowchart TD
+ Start([User visits site]) --> Auth{Authenticated?}
+ Auth -->|No| Login[Show login page]
+ Auth -->|Yes| Dashboard[Show dashboard]
+ Login --> Creds[Enter credentials]
+ Creds --> Validate{Valid?}
+ Validate -->|Yes| Dashboard
+ Validate -->|No| Error[Show error]
+ Error --> Login
+```
+
+### ERD (Database Schema)
+```mermaid
+erDiagram
+ USER ||--o{ ORDER : places
+ ORDER ||--|{ LINE_ITEM : contains
+ PRODUCT ||--o{ LINE_ITEM : includes
+
+ USER {
+ int id PK
+ string email UK
+ string name
+ datetime created_at
+ }
+
+ ORDER {
+ int id PK
+ int user_id FK
+ decimal total
+ datetime created_at
+ }
+```
+
+## Detailed References
+
+For in-depth guidance on specific diagram types, see:
+
+- **[references/class-diagrams.md](references/class-diagrams.md)** - Domain modeling, relationships (association, composition, aggregation, inheritance), multiplicity, methods/properties
+- **[references/sequence-diagrams.md](references/sequence-diagrams.md)** - Actors, participants, messages (sync/async), activations, loops, alt/opt/par blocks, notes
+- **[references/flowcharts.md](references/flowcharts.md)** - Node shapes, connections, decision logic, subgraphs, styling
+- **[references/erd-diagrams.md](references/erd-diagrams.md)** - Entities, relationships, cardinality, keys, attributes
+- **[references/c4-diagrams.md](references/c4-diagrams.md)** - System context, container, component diagrams, boundaries
+- **[references/advanced-features.md](references/advanced-features.md)** - Themes, styling, configuration, layout options
+
+## Best Practices
+
+1. **Start Simple** - Begin with core entities/components, add details incrementally
+2. **Use Meaningful Names** - Clear labels make diagrams self-documenting
+3. **Comment Extensively** - Use `%%` comments to explain complex relationships
+4. **Keep Focused** - One diagram per concept; split large diagrams into multiple focused views
+5. **Version Control** - Store `.mmd` files alongside code for easy updates
+6. **Add Context** - Include titles and notes to explain diagram purpose
+7. **Iterate** - Refine diagrams as understanding evolves
+
+## Configuration and Theming
+
+Configure diagrams using frontmatter:
+
+```mermaid
+---
+config:
+ theme: base
+ themeVariables:
+ primaryColor: "#ff6b6b"
+---
+flowchart LR
+ A --> B
+```
+
+**Available themes:** default, forest, dark, neutral, base
+
+**Layout options:**
+- `layout: dagre` (default) - Classic balanced layout
+- `layout: elk` - Advanced layout for complex diagrams (requires integration)
+
+**Look options:**
+- `look: classic` - Traditional Mermaid style
+- `look: handDrawn` - Sketch-like appearance
+
+## Exporting and Rendering
+
+**Native support in:**
+- GitHub/GitLab - Automatically renders in Markdown
+- VS Code - With Markdown Mermaid extension
+- Notion, Obsidian, Confluence - Built-in support
+
+**Export options:**
+- [Mermaid Live Editor](https://mermaid.live) - Online editor with PNG/SVG export
+- Mermaid CLI - `npm install -g @mermaid-js/mermaid-cli` then `mmdc -i input.mmd -o output.png`
+- Docker - `docker run --rm -v $(pwd):/data minlag/mermaid-cli -i /data/input.mmd -o /data/output.png`
+
+## Common Pitfalls
+
+- **Breaking characters** - Avoid `{}` in comments, use proper escape sequences for special characters
+- **Syntax errors** - Misspellings break diagrams; validate syntax in Mermaid Live
+- **Overcomplexity** - Split complex diagrams into multiple focused views
+- **Missing relationships** - Document all important connections between entities
+
+## When to Create Diagrams
+
+**Always diagram when:**
+- Starting new projects or features
+- Documenting complex systems
+- Explaining architecture decisions
+- Designing database schemas
+- Planning refactoring efforts
+- Onboarding new team members
+
+**Use diagrams to:**
+- Align stakeholders on technical decisions
+- Document domain models collaboratively
+- Visualize data flows and system interactions
+- Plan before coding
+- Create living documentation that evolves with code
diff --git a/dist/plugins/mermaid-diagrams/skills/mermaid-diagrams/references/advanced-features.md b/dist/plugins/mermaid-diagrams/skills/mermaid-diagrams/references/advanced-features.md
new file mode 100644
index 0000000..0c7bfca
--- /dev/null
+++ b/dist/plugins/mermaid-diagrams/skills/mermaid-diagrams/references/advanced-features.md
@@ -0,0 +1,556 @@
+# Advanced Mermaid Features
+
+Advanced configuration, styling, theming, and other powerful features for creating professional diagrams.
+
+## Frontmatter Configuration
+
+Add YAML configuration at the top of diagrams:
+
+```mermaid
+---
+config:
+ theme: dark
+ themeVariables:
+ primaryColor: "#ff6b6b"
+ primaryTextColor: "#fff"
+ primaryBorderColor: "#333"
+ lineColor: "#666"
+ secondaryColor: "#4ecdc4"
+ tertiaryColor: "#ffe66d"
+---
+flowchart TD
+ A --> B
+```
+
+## Themes
+
+### Built-in Themes
+
+```mermaid
+---
+config:
+ theme: default
+---
+```
+
+**Available themes:**
+- `default` - Standard blue theme
+- `forest` - Green earth tones
+- `dark` - Dark mode friendly
+- `neutral` - Grayscale professional
+- `base` - Minimal base theme for customization
+
+### Theme Examples
+
+**Default Theme:**
+```mermaid
+---
+config:
+ theme: default
+---
+flowchart LR
+ A[Start] --> B[Process]
+ B --> C{Decision}
+ C -->|Yes| D[Action 1]
+ C -->|No| E[Action 2]
+```
+
+**Dark Theme:**
+```mermaid
+---
+config:
+ theme: dark
+---
+flowchart LR
+ A[Start] --> B[Process]
+ B --> C{Decision}
+```
+
+**Forest Theme:**
+```mermaid
+---
+config:
+ theme: forest
+---
+flowchart LR
+ A[Start] --> B[Process]
+```
+
+## Custom Theme Variables
+
+Override specific colors:
+
+```mermaid
+---
+config:
+ theme: base
+ themeVariables:
+ primaryColor: "#ff6b6b"
+ primaryTextColor: "#fff"
+ primaryBorderColor: "#d63031"
+ lineColor: "#74b9ff"
+ secondaryColor: "#00b894"
+ tertiaryColor: "#fdcb6e"
+ background: "#f0f0f0"
+ mainBkg: "#ffffff"
+ textColor: "#333333"
+ nodeBorder: "#333333"
+ clusterBkg: "#f9f9f9"
+ clusterBorder: "#666666"
+---
+flowchart TD
+ A --> B --> C
+```
+
+## Layout Options
+
+### Dagre Layout (Default)
+
+```mermaid
+---
+config:
+ layout: dagre
+---
+flowchart TD
+ A --> B
+```
+
+### ELK Layout (Advanced)
+
+For complex diagrams with better automatic layout:
+
+```mermaid
+---
+config:
+ layout: elk
+ elk:
+ mergeEdges: true
+ nodePlacementStrategy: BRANDES_KOEPF
+---
+flowchart TD
+ A --> B
+```
+
+**ELK node placement strategies:**
+- `SIMPLE` - Basic placement
+- `NETWORK_SIMPLEX` - Network optimization
+- `LINEAR_SEGMENTS` - Linear arrangement
+- `BRANDES_KOEPF` - Balanced (default)
+
+## Look Options
+
+### Classic Look
+
+Traditional Mermaid appearance:
+
+```mermaid
+---
+config:
+ look: classic
+---
+flowchart LR
+ A --> B --> C
+```
+
+### Hand-Drawn Look
+
+Sketch-like, informal style:
+
+```mermaid
+---
+config:
+ look: handDrawn
+---
+flowchart LR
+ A --> B --> C
+```
+
+## Complete Configuration Example
+
+```mermaid
+---
+config:
+ theme: base
+ look: handDrawn
+ layout: dagre
+ themeVariables:
+ primaryColor: "#ff6b6b"
+ primaryTextColor: "#fff"
+ primaryBorderColor: "#d63031"
+ lineColor: "#74b9ff"
+ secondaryColor: "#00b894"
+ tertiaryColor: "#fdcb6e"
+---
+flowchart TD
+ Start([Begin Process]) --> Input[Gather Data]
+ Input --> Process{Valid?}
+ Process -->|Yes| Store[(Save to DB)]
+ Process -->|No| Error[Show Error]
+ Store --> Notify[Send Notification]
+ Error --> Input
+ Notify --> End([Complete])
+```
+
+## Diagram-Specific Styling
+
+### Flowchart Styling
+
+**Class-based styling:**
+```mermaid
+flowchart TD
+ A[Normal]:::success
+ B[Warning]:::warning
+ C[Error]:::error
+
+ classDef success fill:#00b894,stroke:#00a383,color:#fff
+ classDef warning fill:#fdcb6e,stroke:#e8b923,color:#333
+ classDef error fill:#ff6b6b,stroke:#ee5253,color:#fff
+
+ A --> B --> C
+```
+
+**Node-specific styling:**
+```mermaid
+flowchart LR
+ A[Node A]
+ B[Node B]
+ C[Node C]
+
+ style A fill:#ff6b6b,stroke:#333,stroke-width:4px
+ style B fill:#4ecdc4,stroke:#333,stroke-width:2px
+ style C fill:#ffe66d,stroke:#333,stroke-width:2px
+
+ A --> B --> C
+```
+
+**Link styling:**
+```mermaid
+flowchart LR
+ A --> B
+ B --> C
+ C --> D
+
+ linkStyle 0 stroke:#ff6b6b,stroke-width:4px
+ linkStyle 1 stroke:#4ecdc4,stroke-width:2px
+ linkStyle 2 stroke:#ffe66d,stroke-width:2px
+```
+
+### Sequence Diagram Styling
+
+```mermaid
+sequenceDiagram
+ participant A
+ participant B
+ participant C
+
+ A->>B: Message 1
+ B->>C: Message 2
+
+ Note over A,C: Styled note
+
+ %%{init: {'theme':'forest'}}%%
+```
+
+### Class Diagram Styling
+
+```mermaid
+classDiagram
+ class User {
+ +String name
+ +login()
+ }
+
+ class Admin {
+ +manageUsers()
+ }
+
+ User <|-- Admin
+
+ %%{init: {'theme':'dark'}}%%
+```
+
+## Directional Hints
+
+Control layout direction for specific nodes:
+
+```mermaid
+flowchart TB
+ A --> B
+ B --> C
+ B --> D
+ C --> E
+ D --> E
+
+ %% This is a comment - helps organize complex diagrams
+```
+
+## Click Events and Links
+
+Add interactive elements:
+
+```mermaid
+flowchart LR
+ A[GitHub]
+ B[Documentation]
+ C[Live Demo]
+
+ click A "https://github.com" "Go to GitHub"
+ click B "https://mermaid.js.org" "View Docs"
+ click C "https://mermaid.live" "Try Live Editor"
+
+ A --> B --> C
+```
+
+## Tooltips
+
+Add hover information:
+
+```mermaid
+flowchart LR
+ A[Service A]
+ B[Service B]
+
+ A -.->|REST API| B
+
+ %% Tooltips are defined with links
+ link A: API Documentation @ https://api.example.com
+ link B: Service Dashboard @ https://dashboard.example.com
+```
+
+## Subgraph Styling
+
+```mermaid
+flowchart TB
+ subgraph Frontend
+ A[Web App]
+ B[Mobile App]
+ end
+
+ subgraph Backend
+ C[API]
+ D[Database]
+ end
+
+ A & B --> C
+ C --> D
+
+ style Frontend fill:#e3f2fd,stroke:#2196f3,stroke-width:2px
+ style Backend fill:#fff3e0,stroke:#ff9800,stroke-width:2px
+```
+
+## Comments and Documentation
+
+```mermaid
+flowchart TD
+ %% This is a single-line comment
+
+ %% Multi-line comments can be created
+ %% by using multiple comment lines
+
+ A[Start]
+ B[Process]
+ C[End]
+
+ %% Define relationships
+ A --> B
+ B --> C
+
+ %% Add styling
+ style A fill:#90EE90
+ style C fill:#FFB6C1
+```
+
+## Complex Styling Example
+
+```mermaid
+flowchart TB
+ subgraph production[Production Environment]
+ direction LR
+ lb[Load Balancer]
+
+ subgraph servers[Application Servers]
+ app1[Server 1]
+ app2[Server 2]
+ app3[Server 3]
+ end
+
+ cache[(Redis Cache)]
+ db[(PostgreSQL)]
+ end
+
+ subgraph monitoring[Monitoring]
+ logs[Log Aggregator]
+ metrics[Metrics Dashboard]
+ end
+
+ users[Users] --> lb
+ lb --> app1 & app2 & app3
+ app1 & app2 & app3 --> cache
+ app1 & app2 & app3 --> db
+ app1 & app2 & app3 --> logs
+ logs --> metrics
+
+ style production fill:#e8f5e9,stroke:#4caf50,stroke-width:3px
+ style servers fill:#fff3e0,stroke:#ff9800,stroke-width:2px
+ style monitoring fill:#e3f2fd,stroke:#2196f3,stroke-width:2px
+
+ style lb fill:#ffeb3b,stroke:#fbc02d,stroke-width:2px
+ style cache fill:#ce93d8,stroke:#ab47bc,stroke-width:2px
+ style db fill:#ce93d8,stroke:#ab47bc,stroke-width:2px
+
+ classDef serverClass fill:#81c784,stroke:#4caf50,stroke-width:2px,color:#000
+ class app1,app2,app3 serverClass
+
+ linkStyle 0,1,2,3 stroke:#4caf50,stroke-width:2px
+ linkStyle 4,5,6,7,8,9 stroke:#ff9800,stroke-width:1px
+```
+
+## Responsive Sizing
+
+Use CSS to make diagrams responsive:
+
+```html
+
+
+ flowchart LR
+ A --> B --> C
+
+
+```
+
+## SVG Export Options
+
+When exporting to SVG:
+
+```bash
+# Export with custom dimensions
+mmdc -i diagram.mmd -o output.svg -w 1920 -H 1080
+
+# Export with background color
+mmdc -i diagram.mmd -o output.svg -b "#ffffff"
+
+# Export with transparent background
+mmdc -i diagram.mmd -o output.svg -b "transparent"
+```
+
+## Best Practices for Advanced Features
+
+1. **Use themes consistently** - Pick one theme for related diagrams
+2. **Don't over-style** - Too many colors can reduce clarity
+3. **Test hand-drawn look** - Some diagrams work better with classic look
+4. **Use ELK for complex layouts** - When dagre creates crossed lines
+5. **Comment complex configurations** - Explain non-obvious styling choices
+6. **Keep it accessible** - Ensure sufficient color contrast
+7. **Test exports** - Verify diagrams render correctly in target format
+8. **Version control configs** - Track theme changes in your repository
+
+## Accessibility Considerations
+
+```mermaid
+---
+config:
+ theme: base
+ themeVariables:
+ primaryColor: "#0066cc"
+ primaryTextColor: "#ffffff"
+ primaryBorderColor: "#003d7a"
+ lineColor: "#333333"
+ background: "#ffffff"
+ mainBkg: "#f0f0f0"
+---
+flowchart TD
+ A[High Contrast Text] --> B[Clear Labels]
+ B --> C[Meaningful Colors]
+```
+
+**Accessibility tips:**
+- Use high contrast color combinations
+- Don't rely solely on color to convey meaning
+- Include descriptive text labels
+- Test with color blindness simulators
+- Consider dark mode alternatives
+
+## Performance Considerations
+
+For large diagrams:
+
+```mermaid
+---
+config:
+ layout: elk
+ elk:
+ mergeEdges: true
+---
+flowchart TD
+ %% ELK handles complex layouts better
+ %% Merge edges reduces visual clutter
+```
+
+**Performance tips:**
+- Use ELK layout for diagrams with >20 nodes
+- Enable edge merging for simplified connections
+- Split very large diagrams into multiple focused views
+- Consider using subgraphs to organize complexity
+- Limit styling to essential elements
+
+## Integration Examples
+
+### Markdown Files
+
+````markdown
+# System Architecture
+
+```mermaid
+flowchart LR
+ A --> B
+```
+````
+
+### HTML Files
+
+```html
+
+
+
+
+
+
+
+ flowchart LR
+ A --> B
+
+
+
+```
+
+### React Components
+
+```jsx
+import React from 'react';
+import mermaid from 'mermaid';
+
+mermaid.initialize({
+ startOnLoad: true,
+ theme: 'forest'
+});
+
+function DiagramComponent() {
+ React.useEffect(() => {
+ mermaid.contentLoaded();
+ }, []);
+
+ return (
+
+ flowchart LR
+ A --> B
+
+ );
+}
+```
diff --git a/dist/plugins/mermaid-diagrams/skills/mermaid-diagrams/references/c4-diagrams.md b/dist/plugins/mermaid-diagrams/skills/mermaid-diagrams/references/c4-diagrams.md
new file mode 100644
index 0000000..bc4d698
--- /dev/null
+++ b/dist/plugins/mermaid-diagrams/skills/mermaid-diagrams/references/c4-diagrams.md
@@ -0,0 +1,410 @@
+# C4 Model Diagrams
+
+The C4 model provides a hierarchical way to visualize software architecture at different levels of abstraction: Context, Containers, Components, and Code.
+
+## C4 Model Levels
+
+1. **System Context** - Shows the system and its users/external systems
+2. **Container** - Shows applications, databases, and services within the system
+3. **Component** - Shows internal structure of containers
+4. **Code** - Class diagrams showing implementation details (use regular class diagrams)
+
+## C4 Context Diagram
+
+Shows the big picture: your system and its relationships with users and external systems.
+
+### Basic Syntax
+
+```mermaid
+C4Context
+ title System Context for Banking System
+
+ Person(customer, "Customer", "A banking customer")
+ System(banking, "Banking System", "Allows customers to manage accounts")
+ System_Ext(email, "Email System", "Sends emails")
+
+ Rel(customer, banking, "Uses")
+ Rel(banking, email, "Sends emails via")
+```
+
+### Elements
+
+**People:**
+```mermaid
+C4Context
+ Person(user, "User", "Description")
+ Person_Ext(external, "External User", "Outside organization")
+```
+
+**Systems:**
+```mermaid
+C4Context
+ System(internal, "Internal System", "Description")
+ System_Ext(external, "External System", "Description")
+ SystemDb(database, "Database System", "Description")
+ SystemDb_Ext(external_db, "External DB", "Description")
+ SystemQueue(queue, "Message Queue", "Description")
+ SystemQueue_Ext(external_queue, "External Queue", "Description")
+```
+
+**Relationships:**
+```mermaid
+C4Context
+ Rel(from, to, "Label")
+ Rel(from, to, "Label", "Optional Technology")
+ BiRel(system1, system2, "Bidirectional")
+```
+
+### Comprehensive Context Example
+
+```mermaid
+C4Context
+ title System Context - E-Commerce Platform
+
+ Person(customer, "Customer", "Shops online")
+ Person(admin, "Administrator", "Manages products and orders")
+ Person_Ext(delivery, "Delivery Personnel", "Delivers orders")
+
+ System(ecommerce, "E-Commerce Platform", "Online shopping platform")
+
+ System_Ext(payment, "Payment Gateway", "Processes payments")
+ System_Ext(email, "Email Service", "Sends notifications")
+ System_Ext(sms, "SMS Service", "Sends SMS alerts")
+ System_Ext(analytics, "Analytics Platform", "Tracks user behavior")
+ SystemQueue_Ext(shipping, "Shipping API", "Calculates shipping rates")
+
+ Rel(customer, ecommerce, "Browses products, places orders")
+ Rel(admin, ecommerce, "Manages catalog, reviews orders")
+ Rel(delivery, ecommerce, "Updates delivery status")
+
+ Rel(ecommerce, payment, "Processes payments via", "HTTPS/REST")
+ Rel(ecommerce, email, "Sends emails via", "SMTP")
+ Rel(ecommerce, sms, "Sends SMS via", "REST API")
+ Rel(ecommerce, analytics, "Tracks events", "JavaScript SDK")
+ Rel(ecommerce, shipping, "Gets shipping rates", "REST API")
+
+ UpdateRelStyle(customer, ecommerce, $offsetX="-50", $offsetY="-30")
+ UpdateRelStyle(admin, ecommerce, $offsetX="50", $offsetY="-30")
+```
+
+## C4 Container Diagram
+
+Zooms into the system to show containers (applications, databases, services).
+
+### Basic Syntax
+
+```mermaid
+C4Container
+ title Container Diagram for Banking System
+
+ Person(customer, "Customer")
+
+ Container_Boundary(banking, "Banking System") {
+ Container(web, "Web Application", "React", "Delivers static content")
+ Container(api, "API Application", "Node.js", "Provides banking API")
+ ContainerDb(db, "Database", "PostgreSQL", "Stores account data")
+ }
+
+ Rel(customer, web, "Uses", "HTTPS")
+ Rel(web, api, "Makes API calls", "HTTPS/JSON")
+ Rel(api, db, "Reads/writes", "SQL/TCP")
+```
+
+### Container Elements
+
+```mermaid
+C4Container
+ Container(app, "Application", "Technology", "Description")
+ ContainerDb(db, "Database", "PostgreSQL", "Description")
+ ContainerQueue(queue, "Queue", "RabbitMQ", "Description")
+ Container_Ext(external, "External Service", "Tech", "Description")
+```
+
+### Container Boundaries
+
+```mermaid
+C4Container
+ Container_Boundary(boundary_name, "Boundary Label") {
+ Container(app1, "App 1", "Tech")
+ Container(app2, "App 2", "Tech")
+ }
+```
+
+### Comprehensive Container Example
+
+```mermaid
+C4Container
+ title Container Diagram - E-Commerce Platform
+
+ Person(customer, "Customer")
+ Person(admin, "Admin")
+ System_Ext(payment, "Payment Gateway")
+ System_Ext(email, "Email Service")
+
+ Container_Boundary(frontend, "Frontend") {
+ Container(web, "Web App", "React", "Delivers UI")
+ Container(mobile, "Mobile App", "React Native", "Mobile UI")
+ }
+
+ Container_Boundary(backend, "Backend Services") {
+ Container(api, "API Gateway", "Node.js/Express", "Routes requests")
+ Container(auth, "Auth Service", "Node.js", "Handles authentication")
+ Container(catalog, "Catalog Service", "Python/FastAPI", "Manages products")
+ Container(order, "Order Service", "Java/Spring", "Processes orders")
+ Container(notification, "Notification Service", "Node.js", "Sends notifications")
+ }
+
+ Container_Boundary(data, "Data Layer") {
+ ContainerDb(postgres, "Main Database", "PostgreSQL", "Stores core data")
+ ContainerDb(mongo, "Product DB", "MongoDB", "Product catalog")
+ ContainerDb(redis, "Cache", "Redis", "Session & caching")
+ ContainerQueue(queue, "Message Queue", "RabbitMQ", "Async processing")
+ }
+
+ Rel(customer, web, "Uses", "HTTPS")
+ Rel(customer, mobile, "Uses", "HTTPS")
+ Rel(admin, web, "Manages via", "HTTPS")
+
+ Rel(web, api, "Makes calls", "HTTPS/JSON")
+ Rel(mobile, api, "Makes calls", "HTTPS/JSON")
+
+ Rel(api, auth, "Authenticates", "gRPC")
+ Rel(api, catalog, "Gets products", "REST")
+ Rel(api, order, "Creates orders", "REST")
+
+ Rel(auth, postgres, "Reads/writes users", "SQL")
+ Rel(catalog, mongo, "Reads/writes products", "MongoDB Protocol")
+ Rel(order, postgres, "Reads/writes orders", "SQL")
+
+ Rel(auth, redis, "Stores sessions", "Redis Protocol")
+ Rel(api, redis, "Caches data", "Redis Protocol")
+
+ Rel(order, queue, "Publishes events", "AMQP")
+ Rel(notification, queue, "Consumes events", "AMQP")
+ Rel(notification, email, "Sends via", "SMTP")
+ Rel(order, payment, "Processes payment", "HTTPS/REST")
+```
+
+## C4 Component Diagram
+
+Zooms into a container to show its internal components.
+
+### Basic Syntax
+
+```mermaid
+C4Component
+ title Component Diagram for API Application
+
+ Container(web, "Web App", "React")
+ ContainerDb(db, "Database", "PostgreSQL")
+ System_Ext(email, "Email System")
+
+ Container_Boundary(api, "API Application") {
+ Component(controller, "Controller", "Express Router", "Handles HTTP")
+ Component(service, "Business Logic", "Service Layer", "Core logic")
+ Component(repository, "Data Access", "Repository", "DB operations")
+ Component(emailClient, "Email Client", "Client", "Sends emails")
+ }
+
+ Rel(web, controller, "Makes requests", "HTTPS")
+ Rel(controller, service, "Uses")
+ Rel(service, repository, "Uses")
+ Rel(repository, db, "Reads/writes", "SQL")
+ Rel(service, emailClient, "Sends emails via")
+ Rel(emailClient, email, "Sends", "SMTP")
+```
+
+### Comprehensive Component Example
+
+```mermaid
+C4Component
+ title Component Diagram - Order Service
+
+ Container(api_gateway, "API Gateway", "Node.js")
+ ContainerDb(postgres, "Database", "PostgreSQL")
+ ContainerQueue(queue, "Message Queue", "RabbitMQ")
+ System_Ext(payment, "Payment Gateway")
+ System_Ext(inventory, "Inventory Service")
+
+ Container_Boundary(order_service, "Order Service") {
+ Component(controller, "REST Controllers", "Spring MVC", "HTTP endpoints")
+ Component(order_logic, "Order Manager", "Service", "Order processing logic")
+ Component(payment_client, "Payment Client", "REST Client", "Payment integration")
+ Component(inventory_client, "Inventory Client", "REST Client", "Inventory integration")
+ Component(repository, "Order Repository", "JPA", "Database operations")
+ Component(event_publisher, "Event Publisher", "Component", "Publishes domain events")
+ Component(validator, "Order Validator", "Component", "Validates orders")
+ }
+
+ Rel(api_gateway, controller, "Routes requests", "HTTPS/REST")
+
+ Rel(controller, order_logic, "Delegates to")
+ Rel(controller, validator, "Validates with")
+
+ Rel(order_logic, payment_client, "Processes payment")
+ Rel(order_logic, inventory_client, "Checks stock")
+ Rel(order_logic, repository, "Persists orders")
+ Rel(order_logic, event_publisher, "Publishes events")
+
+ Rel(payment_client, payment, "Calls", "HTTPS/REST")
+ Rel(inventory_client, inventory, "Calls", "HTTPS/REST")
+ Rel(repository, postgres, "Reads/writes", "JDBC/SQL")
+ Rel(event_publisher, queue, "Publishes to", "AMQP")
+```
+
+## Microservices Architecture Example
+
+```mermaid
+C4Container
+ title Microservices Architecture - Streaming Platform
+
+ Person(user, "User", "Platform user")
+ Person(creator, "Content Creator", "Uploads videos")
+ System_Ext(cdn, "CDN", "Delivers media")
+ System_Ext(storage, "Object Storage", "Stores videos")
+ System_Ext(transcoding, "Transcoding Service", "Processes videos")
+
+ Container_Boundary(frontend, "Frontend Layer") {
+ Container(web, "Web Application", "Next.js", "Server-rendered UI")
+ Container(mobile, "Mobile Apps", "React Native", "iOS/Android apps")
+ }
+
+ Container_Boundary(api_layer, "API Layer") {
+ Container(api_gateway, "API Gateway", "Kong", "Routing, auth, rate limiting")
+ Container(graphql, "GraphQL Gateway", "Apollo", "Unified API")
+ }
+
+ Container_Boundary(services, "Microservices") {
+ Container(auth, "Auth Service", "Go", "Authentication & authorization")
+ Container(user, "User Service", "Node.js", "User profiles & preferences")
+ Container(video, "Video Service", "Python", "Video metadata & management")
+ Container(recommendation, "Recommendation Engine", "Python/ML", "Content recommendations")
+ Container(analytics, "Analytics Service", "Go", "View tracking & metrics")
+ Container(search, "Search Service", "Elasticsearch", "Content search")
+ Container(comment, "Comment Service", "Node.js", "Comments & discussions")
+ }
+
+ Container_Boundary(data, "Data Layer") {
+ ContainerDb(user_db, "User Database", "PostgreSQL", "User data")
+ ContainerDb(video_db, "Video Database", "MongoDB", "Video metadata")
+ ContainerDb(analytics_db, "Analytics DB", "ClickHouse", "Analytics data")
+ ContainerDb(cache, "Cache Layer", "Redis Cluster", "Caching & sessions")
+ ContainerQueue(event_bus, "Event Bus", "Kafka", "Event streaming")
+ ContainerDb(search_index, "Search Index", "Elasticsearch", "Search data")
+ }
+
+ Rel(user, web, "Uses", "HTTPS")
+ Rel(creator, web, "Uploads via", "HTTPS")
+ Rel(user, mobile, "Uses", "HTTPS")
+
+ Rel(web, api_gateway, "API calls", "HTTPS/REST")
+ Rel(mobile, api_gateway, "API calls", "HTTPS/REST")
+ Rel(web, graphql, "Queries", "HTTPS/GraphQL")
+
+ Rel(api_gateway, auth, "Authenticates", "gRPC")
+ Rel(graphql, video, "Gets videos", "gRPC")
+ Rel(graphql, user, "Gets users", "gRPC")
+ Rel(graphql, recommendation, "Gets recommendations", "gRPC")
+
+ Rel(video, storage, "Stores videos", "S3 API")
+ Rel(video, transcoding, "Sends for transcoding", "REST")
+ Rel(video, cdn, "Publishes to", "API")
+
+ Rel(auth, user_db, "Manages credentials", "SQL")
+ Rel(user, user_db, "Stores profiles", "SQL")
+ Rel(video, video_db, "Stores metadata", "MongoDB")
+ Rel(analytics, analytics_db, "Stores metrics", "SQL")
+
+ Rel(auth, cache, "Sessions", "Redis")
+ Rel(video, cache, "Caches metadata", "Redis")
+ Rel(search, search_index, "Indexes & queries", "REST")
+
+ Rel(video, event_bus, "Publishes VideoUploaded", "Kafka")
+ Rel(analytics, event_bus, "Publishes ViewStarted", "Kafka")
+ Rel(recommendation, event_bus, "Consumes events", "Kafka")
+ Rel(search, event_bus, "Consumes events", "Kafka")
+```
+
+## Best Practices
+
+1. **Use appropriate level** - Context for stakeholders, Container for architects, Component for developers
+2. **Keep it focused** - One system per Context diagram, one container per Component diagram
+3. **Show key relationships** - Don't clutter with every possible connection
+4. **Use consistent naming** - Same names across all diagram levels
+5. **Add technology details** - Specify frameworks, languages, protocols at Container/Component level
+6. **Update regularly** - Keep diagrams in sync with architecture
+7. **Use boundaries** - Group related containers/components logically
+8. **Document protocols** - Show communication methods (REST, gRPC, messaging)
+9. **Highlight external systems** - Use *_Ext variants for clarity
+10. **Start simple** - Begin with Context, drill down as needed
+
+## Common Architecture Patterns
+
+### Monolithic Application
+```mermaid
+C4Container
+ Person(user, "User")
+
+ Container_Boundary(system, "Application") {
+ Container(app, "Web Application", "Ruby on Rails", "Monolithic application")
+ ContainerDb(db, "Database", "PostgreSQL", "Application database")
+ ContainerDb(cache, "Cache", "Redis", "Session store")
+ }
+
+ Rel(user, app, "Uses", "HTTPS")
+ Rel(app, db, "Reads/writes", "SQL")
+ Rel(app, cache, "Caches", "Redis Protocol")
+```
+
+### Three-Tier Architecture
+```mermaid
+C4Container
+ Person(user, "User")
+
+ Container_Boundary(presentation, "Presentation Tier") {
+ Container(web, "Web Server", "Nginx", "Static content")
+ Container(app, "App Server", "Node.js", "Application logic")
+ }
+
+ Container_Boundary(business, "Business Tier") {
+ Container(api, "API Server", "Java", "Business logic")
+ }
+
+ Container_Boundary(data, "Data Tier") {
+ ContainerDb(db, "Database", "MySQL", "Data storage")
+ }
+
+ Rel(user, web, "Uses", "HTTPS")
+ Rel(web, app, "Proxies to", "HTTP")
+ Rel(app, api, "Calls", "REST")
+ Rel(api, db, "Reads/writes", "SQL")
+```
+
+### Event-Driven Architecture
+```mermaid
+C4Container
+ Person(user, "User")
+
+ Container(frontend, "Frontend", "React", "User interface")
+ Container(api, "API Gateway", "Kong", "API routing")
+
+ Container_Boundary(services, "Services") {
+ Container(order, "Order Service", "Java", "Order processing")
+ Container(inventory, "Inventory Service", "Go", "Stock management")
+ Container(notification, "Notification Service", "Node.js", "Alerts")
+ }
+
+ ContainerQueue(events, "Event Bus", "Kafka", "Event streaming")
+ ContainerDb(db, "Databases", "Various", "Service databases")
+
+ Rel(user, frontend, "Uses")
+ Rel(frontend, api, "Calls")
+ Rel(api, order, "Routes to")
+
+ Rel(order, events, "Publishes OrderCreated")
+ Rel(events, inventory, "Consumes events")
+ Rel(events, notification, "Consumes events")
+
+ Rel(order, db, "Persists")
+ Rel(inventory, db, "Persists")
+```
diff --git a/dist/plugins/mermaid-diagrams/skills/mermaid-diagrams/references/class-diagrams.md b/dist/plugins/mermaid-diagrams/skills/mermaid-diagrams/references/class-diagrams.md
new file mode 100644
index 0000000..514dac0
--- /dev/null
+++ b/dist/plugins/mermaid-diagrams/skills/mermaid-diagrams/references/class-diagrams.md
@@ -0,0 +1,361 @@
+# Class Diagrams
+
+Class diagrams model object-oriented designs and domain models. They show entities (classes), their attributes/methods, and relationships.
+
+## Basic Syntax
+
+```mermaid
+classDiagram
+ ClassName
+```
+
+## Defining Classes with Members
+
+```mermaid
+classDiagram
+ class BankAccount {
+ +String owner
+ +Decimal balance
+ -String accountNumber
+ +deposit(amount)
+ +withdraw(amount)
+ +getBalance() Decimal
+ }
+```
+
+**Visibility modifiers:**
+- `+` Public
+- `-` Private
+- `#` Protected
+- `~` Package/Internal
+
+**Member syntax:**
+- `+type attribute` - Attribute with type
+- `+method(params) ReturnType` - Method with parameters and return type
+
+## Relationships
+
+### Association (`--`)
+Loose relationship where entities use each other but exist independently.
+
+```mermaid
+classDiagram
+ Title -- Genre
+```
+
+### Composition (`*--`)
+Strong ownership - child cannot exist without parent. When parent is deleted, children are deleted.
+
+```mermaid
+classDiagram
+ Order *-- LineItem
+ House *-- Room
+```
+
+### Aggregation (`o--`)
+Weaker ownership - child can exist independently. Represents "has-a" relationship.
+
+```mermaid
+classDiagram
+ Department o-- Employee
+ Playlist o-- Song
+```
+
+### Inheritance (`<|--`)
+"Is-a" relationship. Child class inherits from parent class.
+
+```mermaid
+classDiagram
+ Animal <|-- Dog
+ Animal <|-- Cat
+
+ class Animal {
+ +String name
+ +makeSound()
+ }
+
+ class Dog {
+ +bark()
+ }
+```
+
+### Dependency (`<..`)
+One class depends on another, often as a parameter or local variable.
+
+```mermaid
+classDiagram
+ OrderProcessor <.. PaymentGateway
+```
+
+### Realization/Implementation (`<|..`)
+Class implements an interface.
+
+```mermaid
+classDiagram
+ class Drawable {
+ <
>
+ +draw()
+ }
+ Drawable <|.. Circle
+ Drawable <|.. Rectangle
+```
+
+## Multiplicity
+
+Show how many instances participate in a relationship:
+
+```mermaid
+classDiagram
+ Customer "1" --> "0..*" Order : places
+ Order "1" *-- "1..*" LineItem : contains
+ Author "1..*" -- "1..*" Book : writes
+```
+
+**Common multiplicities:**
+- `1` - Exactly one
+- `0..1` - Zero or one
+- `0..*` or `*` - Zero or many
+- `1..*` - One or many
+- `m..n` - Between m and n
+
+## Relationship Labels
+
+```mermaid
+classDiagram
+ Customer --> Order : places
+ Order --> Product : contains
+ Driver --> Vehicle : drives
+```
+
+## Class Stereotypes
+
+Mark special class types:
+
+```mermaid
+classDiagram
+ class IRepository {
+ <>
+ +save(entity)
+ +findById(id)
+ }
+
+ class UserService {
+ <>
+ +createUser()
+ }
+
+ class UserDTO {
+ <>
+ +String name
+ +String email
+ }
+```
+
+## Abstract Classes and Methods
+
+```mermaid
+classDiagram
+ class Shape {
+ <>
+ +int x
+ +int y
+ +draw()* abstract
+ +move(x, y)
+ }
+
+ Shape <|-- Circle
+ Shape <|-- Rectangle
+```
+
+## Generic Classes
+
+```mermaid
+classDiagram
+ class List~T~ {
+ +add(item: T)
+ +get(index: int) T
+ }
+
+ List~String~ <-- StringProcessor
+```
+
+## Comprehensive Example: E-Commerce Domain
+
+```mermaid
+classDiagram
+ %% Core entities
+ class Customer {
+ +UUID id
+ +String email
+ +String name
+ +Address shippingAddress
+ +placeOrder(cart: Cart) Order
+ +getOrderHistory() List~Order~
+ }
+
+ class Order {
+ +UUID id
+ +DateTime orderDate
+ +OrderStatus status
+ +Decimal total
+ +calculateTotal() Decimal
+ +ship()
+ +cancel()
+ }
+
+ class LineItem {
+ +int quantity
+ +Decimal pricePerUnit
+ +getSubtotal() Decimal
+ }
+
+ class Product {
+ +UUID id
+ +String name
+ +String description
+ +Decimal price
+ +int stockQuantity
+ +reduceStock(quantity: int)
+ +isAvailable() bool
+ }
+
+ class Category {
+ +String name
+ +String description
+ }
+
+ class Cart {
+ +addItem(product: Product, quantity: int)
+ +removeItem(product: Product)
+ +getTotal() Decimal
+ +clear()
+ }
+
+ %% Relationships
+ Customer "1" --> "0..*" Order : places
+ Customer "1" --> "1" Cart : has
+ Order "1" *-- "1..*" LineItem : contains
+ LineItem "1" --> "1" Product : references
+ Product "0..*" --> "1" Category : belongs to
+ Cart "1" o-- "0..*" Product : contains
+
+ %% Enums
+ class OrderStatus {
+ <>
+ PENDING
+ PAID
+ SHIPPED
+ DELIVERED
+ CANCELLED
+ }
+
+ Order --> OrderStatus
+```
+
+## Domain-Driven Design Patterns
+
+### Entities
+```mermaid
+classDiagram
+ class User {
+ <>
+ -UUID id
+ +String email
+ +String name
+ }
+```
+
+### Value Objects
+```mermaid
+classDiagram
+ class Money {
+ <>
+ +Decimal amount
+ +String currency
+ +add(other: Money) Money
+ }
+
+ class Address {
+ <>
+ +String street
+ +String city
+ +String postalCode
+ }
+```
+
+### Aggregates
+```mermaid
+classDiagram
+ class Order {
+ <>
+ -UUID id
+ +addLineItem(item)
+ +removeLineItem(item)
+ }
+
+ Order *-- LineItem
+```
+
+## Tips for Effective Class Diagrams
+
+1. **Start with core entities** - Add attributes and methods incrementally
+2. **Show only relevant details** - Omit obvious getters/setters unless important
+3. **Use appropriate relationships** - Choose between association, aggregation, and composition carefully
+4. **Add multiplicity** - Clarifies how many instances participate
+5. **Group related classes** - Use notes or visual proximity
+6. **Document invariants** - Use notes to explain business rules
+
+## Common Patterns
+
+### Repository Pattern
+```mermaid
+classDiagram
+ class IRepository~T~ {
+ <>
+ +save(entity: T)
+ +findById(id: UUID) T
+ +delete(entity: T)
+ }
+
+ class UserRepository {
+ +findByEmail(email: String) User
+ }
+
+ IRepository~User~ <|.. UserRepository
+```
+
+### Factory Pattern
+```mermaid
+classDiagram
+ class ShapeFactory {
+ +createShape(type: String) Shape
+ }
+
+ class Shape {
+ <>
+ +draw()*
+ }
+
+ ShapeFactory ..> Shape : creates
+ Shape <|-- Circle
+ Shape <|-- Rectangle
+```
+
+### Strategy Pattern
+```mermaid
+classDiagram
+ class PaymentProcessor {
+ -PaymentStrategy strategy
+ +setStrategy(strategy: PaymentStrategy)
+ +processPayment(amount: Decimal)
+ }
+
+ class PaymentStrategy {
+ <>
+ +pay(amount: Decimal)*
+ }
+
+ PaymentStrategy <|.. CreditCardPayment
+ PaymentStrategy <|.. PayPalPayment
+ PaymentProcessor --> PaymentStrategy
+```
diff --git a/dist/plugins/mermaid-diagrams/skills/mermaid-diagrams/references/erd-diagrams.md b/dist/plugins/mermaid-diagrams/skills/mermaid-diagrams/references/erd-diagrams.md
new file mode 100644
index 0000000..ba577ea
--- /dev/null
+++ b/dist/plugins/mermaid-diagrams/skills/mermaid-diagrams/references/erd-diagrams.md
@@ -0,0 +1,510 @@
+# Entity Relationship Diagrams (ERD)
+
+ERDs model database schemas, showing tables (entities), their columns (attributes), and relationships between tables. Essential for database design and documentation.
+
+## Basic Syntax
+
+```mermaid
+erDiagram
+ CUSTOMER ||--o{ ORDER : places
+```
+
+## Defining Entities
+
+```mermaid
+erDiagram
+ CUSTOMER
+ ORDER
+ PRODUCT
+```
+
+## Entity Attributes
+
+Define columns with type and constraints:
+
+```mermaid
+erDiagram
+ CUSTOMER {
+ int id PK
+ string email UK
+ string name
+ string phone
+ datetime created_at
+ }
+```
+
+**Attribute format:** `type name constraints`
+
+**Common constraints:**
+- `PK` - Primary Key
+- `FK` - Foreign Key
+- `UK` - Unique Key
+- `NN` - Not Null
+
+## Relationships
+
+### Relationship Symbols
+
+**Cardinality indicators:**
+- `||` - Exactly one
+- `|o` - Zero or one
+- `}{` - One or many
+- `}o` - Zero or many
+
+**Relationship line:**
+- `--` - Non-identifying relationship
+- `..` - Identifying relationship (rare in practice)
+
+### Common Relationships
+
+```mermaid
+erDiagram
+ %% One-to-One
+ USER ||--|| PROFILE : has
+
+ %% One-to-Many
+ CUSTOMER ||--o{ ORDER : places
+
+ %% Many-to-Many (with junction table)
+ STUDENT }o--o{ COURSE : enrolls
+ STUDENT ||--o{ ENROLLMENT : has
+ COURSE ||--o{ ENROLLMENT : includes
+
+ %% Optional Relationships
+ EMPLOYEE |o--o{ DEPARTMENT : manages
+```
+
+### Relationship with Labels
+
+```mermaid
+erDiagram
+ AUTHOR ||--o{ BOOK : writes
+ BOOK }o--|| PUBLISHER : "published by"
+ READER }o--o{ BOOK : reads
+```
+
+## Data Types
+
+Use standard database types:
+- `int`, `bigint`, `smallint`
+- `varchar`, `text`, `char`
+- `decimal`, `float`, `double`
+- `boolean`, `bool`
+- `date`, `datetime`, `timestamp`
+- `json`, `jsonb`
+- `uuid`
+- `blob`, `bytea`
+
+## Comprehensive Example: E-Commerce Database
+
+```mermaid
+erDiagram
+ CUSTOMER ||--o{ ORDER : places
+ CUSTOMER ||--o{ REVIEW : writes
+ CUSTOMER ||--o{ ADDRESS : has
+ ORDER ||--|{ LINE_ITEM : contains
+ PRODUCT ||--o{ LINE_ITEM : "ordered in"
+ PRODUCT }o--|| CATEGORY : "belongs to"
+ PRODUCT ||--o{ REVIEW : receives
+ PRODUCT ||--o{ INVENTORY : tracks
+ ORDER ||--|| PAYMENT : "paid by"
+ ORDER ||--o| SHIPMENT : "shipped via"
+
+ CUSTOMER {
+ uuid id PK
+ varchar email UK "NOT NULL"
+ varchar name "NOT NULL"
+ varchar phone
+ timestamp created_at "DEFAULT NOW()"
+ timestamp updated_at
+ }
+
+ ADDRESS {
+ uuid id PK
+ uuid customer_id FK
+ varchar street "NOT NULL"
+ varchar city "NOT NULL"
+ varchar state
+ varchar postal_code
+ varchar country "NOT NULL"
+ boolean is_default
+ }
+
+ ORDER {
+ uuid id PK
+ uuid customer_id FK "NOT NULL"
+ decimal total "NOT NULL"
+ varchar status "NOT NULL"
+ timestamp order_date "DEFAULT NOW()"
+ timestamp shipped_date
+ timestamp delivered_date
+ }
+
+ LINE_ITEM {
+ uuid id PK
+ uuid order_id FK "NOT NULL"
+ uuid product_id FK "NOT NULL"
+ int quantity "NOT NULL"
+ decimal price_per_unit "NOT NULL"
+ decimal subtotal "COMPUTED"
+ }
+
+ PRODUCT {
+ uuid id PK
+ varchar sku UK "NOT NULL"
+ varchar name "NOT NULL"
+ text description
+ decimal price "NOT NULL"
+ uuid category_id FK
+ boolean is_active "DEFAULT TRUE"
+ timestamp created_at "DEFAULT NOW()"
+ }
+
+ CATEGORY {
+ uuid id PK
+ varchar name UK "NOT NULL"
+ text description
+ uuid parent_category_id FK
+ }
+
+ INVENTORY {
+ uuid id PK
+ uuid product_id FK "NOT NULL"
+ int quantity "DEFAULT 0"
+ varchar warehouse_location
+ timestamp last_updated
+ }
+
+ REVIEW {
+ uuid id PK
+ uuid customer_id FK "NOT NULL"
+ uuid product_id FK "NOT NULL"
+ int rating "CHECK 1-5"
+ text comment
+ timestamp created_at "DEFAULT NOW()"
+ }
+
+ PAYMENT {
+ uuid id PK
+ uuid order_id FK "NOT NULL"
+ varchar payment_method "NOT NULL"
+ decimal amount "NOT NULL"
+ varchar status "NOT NULL"
+ varchar transaction_id UK
+ timestamp processed_at
+ }
+
+ SHIPMENT {
+ uuid id PK
+ uuid order_id FK "NOT NULL"
+ varchar carrier
+ varchar tracking_number
+ timestamp shipped_date
+ timestamp estimated_delivery
+ timestamp actual_delivery
+ }
+```
+
+## Blog Platform Schema
+
+```mermaid
+erDiagram
+ USER ||--o{ POST : creates
+ USER ||--o{ COMMENT : writes
+ POST ||--o{ COMMENT : receives
+ POST }o--o{ TAG : tagged_with
+ POST ||--o{ POST_TAG : has
+ TAG ||--o{ POST_TAG : applied_to
+ POST }o--|| CATEGORY : "belongs to"
+ USER ||--o{ LIKE : gives
+ POST ||--o{ LIKE : receives
+ COMMENT ||--o{ LIKE : receives
+
+ USER {
+ bigint id PK "AUTO_INCREMENT"
+ varchar email UK "NOT NULL"
+ varchar username UK "NOT NULL"
+ varchar password_hash "NOT NULL"
+ varchar display_name
+ text bio
+ varchar avatar_url
+ timestamp created_at "DEFAULT NOW()"
+ timestamp last_login
+ }
+
+ POST {
+ bigint id PK "AUTO_INCREMENT"
+ bigint user_id FK "NOT NULL"
+ bigint category_id FK
+ varchar title "NOT NULL"
+ varchar slug UK "NOT NULL"
+ text content "NOT NULL"
+ text excerpt
+ varchar featured_image_url
+ varchar status "NOT NULL DEFAULT 'draft'"
+ int view_count "DEFAULT 0"
+ timestamp published_at
+ timestamp created_at "DEFAULT NOW()"
+ timestamp updated_at
+ }
+
+ COMMENT {
+ bigint id PK "AUTO_INCREMENT"
+ bigint user_id FK "NOT NULL"
+ bigint post_id FK "NOT NULL"
+ bigint parent_comment_id FK "NULL"
+ text content "NOT NULL"
+ varchar status "DEFAULT 'pending'"
+ timestamp created_at "DEFAULT NOW()"
+ }
+
+ CATEGORY {
+ bigint id PK "AUTO_INCREMENT"
+ varchar name UK "NOT NULL"
+ varchar slug UK "NOT NULL"
+ text description
+ bigint parent_id FK
+ }
+
+ TAG {
+ bigint id PK "AUTO_INCREMENT"
+ varchar name UK "NOT NULL"
+ varchar slug UK "NOT NULL"
+ }
+
+ POST_TAG {
+ bigint post_id FK "NOT NULL"
+ bigint tag_id FK "NOT NULL"
+ }
+
+ LIKE {
+ bigint id PK "AUTO_INCREMENT"
+ bigint user_id FK "NOT NULL"
+ varchar likeable_type "NOT NULL"
+ bigint likeable_id "NOT NULL"
+ timestamp created_at "DEFAULT NOW()"
+ }
+```
+
+## Social Media Schema
+
+```mermaid
+erDiagram
+ USER ||--o{ POST : creates
+ USER ||--o{ FOLLOW : follows
+ USER ||--o{ FOLLOW : "followed by"
+ POST ||--o{ LIKE : receives
+ POST ||--o{ COMMENT : has
+ USER ||--o{ LIKE : gives
+ USER ||--o{ COMMENT : makes
+ USER ||--o{ NOTIFICATION : receives
+ POST ||--o{ POST_MEDIA : contains
+ USER }o--o{ GROUP : "member of"
+ USER ||--o{ MESSAGE : sends
+ USER ||--o{ MESSAGE : receives
+
+ USER {
+ uuid id PK
+ varchar username UK "NOT NULL"
+ varchar email UK "NOT NULL"
+ varchar password_hash "NOT NULL"
+ varchar full_name
+ text bio
+ varchar profile_picture_url
+ varchar cover_photo_url
+ boolean is_verified "DEFAULT FALSE"
+ boolean is_private "DEFAULT FALSE"
+ timestamp created_at "DEFAULT NOW()"
+ }
+
+ POST {
+ uuid id PK
+ uuid user_id FK "NOT NULL"
+ text content
+ varchar visibility "DEFAULT 'public'"
+ int likes_count "DEFAULT 0"
+ int comments_count "DEFAULT 0"
+ int shares_count "DEFAULT 0"
+ timestamp created_at "DEFAULT NOW()"
+ timestamp edited_at
+ }
+
+ POST_MEDIA {
+ uuid id PK
+ uuid post_id FK "NOT NULL"
+ varchar media_type "NOT NULL"
+ varchar media_url "NOT NULL"
+ int display_order
+ }
+
+ FOLLOW {
+ uuid id PK
+ uuid follower_id FK "NOT NULL"
+ uuid following_id FK "NOT NULL"
+ timestamp created_at "DEFAULT NOW()"
+ }
+
+ LIKE {
+ uuid id PK
+ uuid user_id FK "NOT NULL"
+ uuid post_id FK "NOT NULL"
+ timestamp created_at "DEFAULT NOW()"
+ }
+
+ COMMENT {
+ uuid id PK
+ uuid user_id FK "NOT NULL"
+ uuid post_id FK "NOT NULL"
+ uuid parent_comment_id FK
+ text content "NOT NULL"
+ int likes_count "DEFAULT 0"
+ timestamp created_at "DEFAULT NOW()"
+ }
+
+ MESSAGE {
+ uuid id PK
+ uuid sender_id FK "NOT NULL"
+ uuid receiver_id FK "NOT NULL"
+ text content "NOT NULL"
+ boolean is_read "DEFAULT FALSE"
+ timestamp created_at "DEFAULT NOW()"
+ timestamp read_at
+ }
+
+ NOTIFICATION {
+ uuid id PK
+ uuid user_id FK "NOT NULL"
+ varchar notification_type "NOT NULL"
+ text content "NOT NULL"
+ boolean is_read "DEFAULT FALSE"
+ varchar related_entity_type
+ uuid related_entity_id
+ timestamp created_at "DEFAULT NOW()"
+ }
+
+ GROUP {
+ uuid id PK
+ varchar name "NOT NULL"
+ text description
+ uuid created_by FK "NOT NULL"
+ boolean is_private "DEFAULT FALSE"
+ timestamp created_at "DEFAULT NOW()"
+ }
+```
+
+## Best Practices
+
+1. **Name entities in UPPERCASE** - Convention for clarity
+2. **Use singular names** - `USER` not `USERS`, `ORDER` not `ORDERS`
+3. **Define all constraints** - Document PKs, FKs, UKs, NOT NULL
+4. **Show cardinality accurately** - Be precise about one-to-many vs many-to-many
+5. **Include timestamps** - created_at, updated_at for auditing
+6. **Document computed columns** - Mark calculated/derived values
+7. **Add meaningful comments** - Use quotes for constraints and descriptions
+8. **Consider junction tables** - Explicitly model many-to-many relationships
+9. **Use appropriate types** - Match database-specific types
+10. **Show indexes** - Document UK (unique keys) beyond PKs
+
+## Common Patterns
+
+### Self-Referencing (Hierarchical)
+```mermaid
+erDiagram
+ CATEGORY ||--o{ CATEGORY : "parent of"
+
+ CATEGORY {
+ uuid id PK
+ varchar name "NOT NULL"
+ uuid parent_id FK "NULLABLE"
+ }
+```
+
+### Junction Table (Many-to-Many)
+```mermaid
+erDiagram
+ STUDENT }o--o{ COURSE : enrolls
+ STUDENT ||--o{ ENROLLMENT : has
+ COURSE ||--o{ ENROLLMENT : includes
+
+ STUDENT {
+ uuid id PK
+ varchar name "NOT NULL"
+ }
+
+ ENROLLMENT {
+ uuid student_id FK PK
+ uuid course_id FK PK
+ date enrolled_date
+ varchar grade
+ }
+
+ COURSE {
+ uuid id PK
+ varchar title "NOT NULL"
+ }
+```
+
+### Polymorphic Relationship
+```mermaid
+erDiagram
+ COMMENT {
+ uuid id PK
+ uuid user_id FK
+ varchar commentable_type "NOT NULL"
+ uuid commentable_id "NOT NULL"
+ text content
+ }
+
+ POST {
+ uuid id PK
+ varchar title
+ }
+
+ VIDEO {
+ uuid id PK
+ varchar title
+ }
+```
+
+### Soft Deletes
+```mermaid
+erDiagram
+ USER {
+ uuid id PK
+ varchar email UK
+ varchar name
+ timestamp deleted_at "NULLABLE"
+ }
+```
+
+### Audit Trail
+```mermaid
+erDiagram
+ DOCUMENT ||--o{ DOCUMENT_VERSION : has
+
+ DOCUMENT {
+ uuid id PK
+ varchar title "NOT NULL"
+ int current_version "DEFAULT 1"
+ }
+
+ DOCUMENT_VERSION {
+ uuid id PK
+ uuid document_id FK "NOT NULL"
+ int version_number "NOT NULL"
+ text content "NOT NULL"
+ uuid modified_by FK
+ timestamp created_at "DEFAULT NOW()"
+ }
+```
+
+## Tips for Database Design
+
+1. **Normalize appropriately** - Balance normalization with query performance
+2. **Use surrogate keys** - UUID or auto-increment integers as PKs
+3. **Index foreign keys** - Essential for join performance
+4. **Plan for soft deletes** - Add deleted_at columns instead of hard deletes
+5. **Version critical data** - Maintain history for important entities
+6. **Set appropriate defaults** - created_at, status, boolean flags
+7. **Consider denormalization** - Counts and cached values for performance
+8. **Use enum/check constraints** - Enforce valid values at database level
diff --git a/dist/plugins/mermaid-diagrams/skills/mermaid-diagrams/references/flowcharts.md b/dist/plugins/mermaid-diagrams/skills/mermaid-diagrams/references/flowcharts.md
new file mode 100644
index 0000000..1a43c58
--- /dev/null
+++ b/dist/plugins/mermaid-diagrams/skills/mermaid-diagrams/references/flowcharts.md
@@ -0,0 +1,450 @@
+# Flowcharts
+
+Flowcharts visualize processes, algorithms, decision trees, and user journeys. They show step-by-step progression through a system or workflow.
+
+## Basic Syntax
+
+```mermaid
+flowchart TD
+ A --> B
+```
+
+**Directions:**
+- `TD` or `TB` - Top to Bottom (default)
+- `BT` - Bottom to Top
+- `LR` - Left to Right
+- `RL` - Right to Left
+
+## Node Shapes
+
+### Rectangle (default)
+```mermaid
+flowchart LR
+ A[Process step]
+```
+
+### Rounded Rectangle
+```mermaid
+flowchart LR
+ B([Rounded process])
+```
+
+### Stadium/Pill Shape
+```mermaid
+flowchart LR
+ C(Start or End)
+```
+
+### Subroutine (Double Border)
+```mermaid
+flowchart LR
+ D[[Subroutine]]
+```
+
+### Cylindrical (Database)
+```mermaid
+flowchart LR
+ E[(Database)]
+```
+
+### Circle
+```mermaid
+flowchart LR
+ F((Circle node))
+```
+
+### Asymmetric/Flag
+```mermaid
+flowchart LR
+ G>Flag node]
+```
+
+### Rhombus (Decision)
+```mermaid
+flowchart LR
+ H{Decision?}
+```
+
+### Hexagon
+```mermaid
+flowchart LR
+ I{{Hexagon}}
+```
+
+### Parallelogram (Input/Output)
+```mermaid
+flowchart LR
+ J[/Input or Output/]
+ K[\Alternative IO\]
+```
+
+### Trapezoid
+```mermaid
+flowchart LR
+ L[/Trapezoid\]
+ M[\Alt trapezoid/]
+```
+
+## Connections
+
+### Basic Arrow
+```mermaid
+flowchart LR
+ A --> B
+```
+
+### Open Link (No Arrow)
+```mermaid
+flowchart LR
+ A --- B
+```
+
+### Text on Links
+```mermaid
+flowchart LR
+ A -->|Label text| B
+ C ---|"Text with spaces"| D
+```
+
+### Dotted Links
+```mermaid
+flowchart LR
+ A -.-> B
+ C -.- D
+ E -.Label.-> F
+```
+
+### Thick Links
+```mermaid
+flowchart LR
+ A ==> B
+ C === D
+ E ==Label==> F
+```
+
+### Chaining
+```mermaid
+flowchart LR
+ A --> B --> C --> D
+ E --> F & G --> H
+```
+
+### Multi-directional
+```mermaid
+flowchart LR
+ A --> B & C & D
+ B & C & D --> E
+```
+
+## Subgraphs
+
+Group related nodes:
+
+```mermaid
+flowchart TB
+ A[Start]
+
+ subgraph Processing
+ B[Step 1]
+ C[Step 2]
+ D[Step 3]
+ end
+
+ E[End]
+
+ A --> B
+ D --> E
+```
+
+### Nested Subgraphs
+```mermaid
+flowchart TB
+ subgraph Outer
+ A[Node A]
+
+ subgraph Inner
+ B[Node B]
+ C[Node C]
+ end
+ end
+```
+
+### Subgraph Direction
+```mermaid
+flowchart LR
+ subgraph one
+ direction TB
+ A1 --> A2
+ end
+
+ subgraph two
+ direction TB
+ B1 --> B2
+ end
+
+ one --> two
+```
+
+## Styling
+
+### Individual Node Styling
+```mermaid
+flowchart LR
+ A[Normal]
+ B[Styled]
+
+ style B fill:#ff6b6b,stroke:#333,stroke-width:4px,color:#fff
+```
+
+### Class-based Styling
+```mermaid
+flowchart LR
+ A[Node 1]:::className
+ B[Node 2]:::className
+ C[Node 3]
+
+ classDef className fill:#f9f,stroke:#333,stroke-width:2px
+```
+
+### Link Styling
+```mermaid
+flowchart LR
+ A --> B
+ linkStyle 0 stroke:#ff3,stroke-width:4px,color:red
+```
+
+## Comprehensive Example: User Registration Flow
+
+```mermaid
+flowchart TD
+ Start([User visits registration page]) --> Form[Show registration form]
+ Form --> Input[User enters details]
+ Input --> Validate{Valid input?}
+
+ Validate -->|No| ShowError[Show validation errors]
+ ShowError --> Form
+
+ Validate -->|Yes| CheckEmail{Email exists?}
+
+ CheckEmail -->|Yes| EmailError[Show 'Email already registered']
+ EmailError --> Form
+
+ CheckEmail -->|No| CreateAccount[Create user account]
+ CreateAccount --> Hash[Hash password]
+ Hash --> SaveDB[(Save to database)]
+ SaveDB --> GenerateToken[Generate verification token]
+ GenerateToken --> SendEmail[Send verification email]
+ SendEmail --> ShowSuccess[Show success message]
+ ShowSuccess --> End([Redirect to login])
+
+ style Start fill:#90EE90,stroke:#333,stroke-width:2px
+ style End fill:#90EE90,stroke:#333,stroke-width:2px
+ style CreateAccount fill:#87CEEB,stroke:#333,stroke-width:2px
+ style SaveDB fill:#FFD700,stroke:#333,stroke-width:2px
+```
+
+## Algorithm Example: Binary Search
+
+```mermaid
+flowchart TD
+ Start([Start Binary Search]) --> Init[Set low = 0, high = array.length - 1]
+ Init --> Check{low <= high?}
+
+ Check -->|No| NotFound[Return -1: Not found]
+ NotFound --> End([End])
+
+ Check -->|Yes| CalcMid[mid = low + (high - low) / 2]
+ CalcMid --> Compare{array[mid] == target?}
+
+ Compare -->|Yes| Found[Return mid: Found]
+ Found --> End
+
+ Compare -->|No| CheckLess{array[mid] < target?}
+
+ CheckLess -->|Yes| MoveLow[low = mid + 1]
+ MoveLow --> Check
+
+ CheckLess -->|No| MoveHigh[high = mid - 1]
+ MoveHigh --> Check
+
+ style Start fill:#90EE90
+ style End fill:#90EE90
+ style Found fill:#FFD700
+ style NotFound fill:#FF6B6B
+```
+
+## CI/CD Pipeline
+
+```mermaid
+flowchart LR
+ subgraph Development
+ Commit[Developer commits code] --> Push[Push to repository]
+ end
+
+ subgraph CI
+ Push --> Trigger[Trigger CI pipeline]
+ Trigger --> Checkout[Checkout code]
+ Checkout --> Install[Install dependencies]
+ Install --> Lint[Run linters]
+ Lint --> Test[Run tests]
+ Test --> Build[Build application]
+ end
+
+ subgraph QA
+ Build --> DeployStaging[Deploy to staging]
+ DeployStaging --> E2E[Run E2E tests]
+ E2E --> ManualQA{Manual QA approval?}
+ end
+
+ subgraph Production
+ ManualQA -->|Approved| DeployProd[Deploy to production]
+ DeployProd --> HealthCheck{Health check passed?}
+ HealthCheck -->|Yes| Success([Deployment successful])
+ HealthCheck -->|No| Rollback[Rollback deployment]
+ Rollback --> Alert[Alert team]
+ end
+
+ ManualQA -->|Rejected| FixIssues[Fix issues]
+ FixIssues --> Development
+
+ Test -->|Failed| NotifyDev[Notify developer]
+ NotifyDev --> FixIssues
+```
+
+## E-Commerce Checkout Flow
+
+```mermaid
+flowchart TD
+ Start([User clicks Checkout]) --> Auth{Authenticated?}
+
+ Auth -->|No| Login[Redirect to login]
+ Login --> Auth
+
+ Auth -->|Yes| Cart{Cart empty?}
+ Cart -->|Yes| EmptyCart[Show empty cart message]
+ EmptyCart --> Browse[Redirect to products]
+
+ Cart -->|No| Address[Show shipping address form]
+ Address --> ValidateAddr{Valid address?}
+ ValidateAddr -->|No| Address
+ ValidateAddr -->|Yes| Shipping[Select shipping method]
+
+ Shipping --> Payment[Enter payment details]
+ Payment --> ValidatePayment{Valid payment info?}
+ ValidatePayment -->|No| Payment
+
+ ValidatePayment -->|Yes| Review[Show order review]
+ Review --> Confirm{Confirm order?}
+
+ Confirm -->|No| Edit{Edit what?}
+ Edit -->|Address| Address
+ Edit -->|Shipping| Shipping
+ Edit -->|Payment| Payment
+
+ Confirm -->|Yes| ProcessPayment[Process payment]
+ ProcessPayment --> PaymentResult{Payment successful?}
+
+ PaymentResult -->|No| PaymentError[Show payment error]
+ PaymentError --> RetryPayment{Retry?}
+ RetryPayment -->|Yes| Payment
+ RetryPayment -->|No| Cancel([Order cancelled])
+
+ PaymentResult -->|Yes| CreateOrder[(Create order record)]
+ CreateOrder --> ReduceStock[Reduce inventory]
+ ReduceStock --> SendConfirmation[Send confirmation email]
+ SendConfirmation --> Success([Order complete - Show confirmation])
+
+ style Start fill:#90EE90
+ style Success fill:#90EE90
+ style Cancel fill:#FF6B6B
+ style CreateOrder fill:#FFD700
+```
+
+## Decision Matrix Example
+
+```mermaid
+flowchart TD
+ Start([Select deployment strategy]) --> Env{Environment?}
+
+ Env -->|Development| DevDecision{Automated tests?}
+ DevDecision -->|Pass| DevDeploy[Auto-deploy to dev]
+ DevDecision -->|Fail| Block[Block deployment]
+
+ Env -->|Staging| StageDecision{All checks pass?}
+ StageDecision -->|Yes| StageDeploy[Deploy to staging]
+ StageDecision -->|No| Block
+
+ Env -->|Production| ProdDecision{Change type?}
+
+ ProdDecision -->|Hotfix| Urgent{Critical bug?}
+ Urgent -->|Yes| FastTrack[Emergency approval + deploy]
+ Urgent -->|No| NormalProcess
+
+ ProdDecision -->|Feature| NormalProcess{Approval status?}
+ NormalProcess -->|Approved| Schedule{Deploy window?}
+ NormalProcess -->|Pending| Wait[Wait for approval]
+ NormalProcess -->|Rejected| Block
+
+ Schedule -->|Now| ImmediateDeploy[Deploy immediately]
+ Schedule -->|Scheduled| QueueDeploy[Queue for deploy window]
+
+ DevDeploy --> Monitor[Monitor metrics]
+ StageDeploy --> Monitor
+ FastTrack --> Monitor
+ ImmediateDeploy --> Monitor
+ QueueDeploy --> Monitor
+
+ Monitor --> End([Deployment complete])
+ Block --> End
+ Wait --> End
+```
+
+## Best Practices
+
+1. **Use meaningful labels** - Node text should be clear and action-oriented
+2. **Consistent node shapes** - Same shapes for same types of actions
+3. **Decision nodes as diamonds** - Standard convention for yes/no decisions
+4. **Flow top-to-bottom or left-to-right** - Natural reading direction
+5. **Start and end nodes** - Use stadium/pill shapes to mark entry/exit
+6. **Group related steps** - Use subgraphs for logical groupings
+7. **Color code** - Use colors to highlight different types of actions
+8. **Minimize crossing lines** - Reorganize for clarity
+9. **Keep it focused** - One process per diagram
+
+## Common Patterns
+
+### Simple Linear Flow
+```mermaid
+flowchart LR
+ A[Step 1] --> B[Step 2] --> C[Step 3] --> D[Step 4]
+```
+
+### Branching Decision
+```mermaid
+flowchart TD
+ A[Input] --> B{Condition?}
+ B -->|True| C[Path 1]
+ B -->|False| D[Path 2]
+ C --> E[Merge]
+ D --> E
+```
+
+### Loop Pattern
+```mermaid
+flowchart TD
+ A[Initialize] --> B[Process]
+ B --> C{Continue?}
+ C -->|Yes| B
+ C -->|No| D[Exit]
+```
+
+### Error Handling
+```mermaid
+flowchart TD
+ A[Try operation] --> B{Success?}
+ B -->|Yes| C[Continue]
+ B -->|No| D[Handle error]
+ D --> E{Retry?}
+ E -->|Yes| A
+ E -->|No| F[Abort]
+```
diff --git a/dist/plugins/mermaid-diagrams/skills/mermaid-diagrams/references/sequence-diagrams.md b/dist/plugins/mermaid-diagrams/skills/mermaid-diagrams/references/sequence-diagrams.md
new file mode 100644
index 0000000..027b5b5
--- /dev/null
+++ b/dist/plugins/mermaid-diagrams/skills/mermaid-diagrams/references/sequence-diagrams.md
@@ -0,0 +1,394 @@
+# Sequence Diagrams
+
+Sequence diagrams show interactions between participants over time. They're ideal for API flows, authentication sequences, and system component interactions.
+
+## Basic Syntax
+
+```mermaid
+sequenceDiagram
+ participant A
+ participant B
+ A->>B: Message
+```
+
+## Participants and Actors
+
+```mermaid
+sequenceDiagram
+ actor User
+ participant Frontend
+ participant API
+ participant Database
+
+ User->>Frontend: Click button
+ Frontend->>API: POST /data
+```
+
+**Difference:**
+- `participant` - System components (services, classes, databases)
+- `actor` - External entities (users, external systems)
+
+## Message Types
+
+### Solid Arrow (Synchronous)
+```mermaid
+sequenceDiagram
+ Client->>Server: Request
+ Server-->>Client: Response
+```
+
+- `->>` Solid arrow (request)
+- `-->>` Dotted arrow (response/return)
+
+### Open Arrow (Asynchronous)
+```mermaid
+sequenceDiagram
+ Client-)Server: Async message
+ Server--)Client: Async response
+```
+
+- `-)` Solid open arrow
+- `--)` Dotted open arrow
+
+### Cross/X (Delete)
+```mermaid
+sequenceDiagram
+ Client-xServer: Delete
+```
+
+## Activations
+
+Show when a participant is actively processing:
+
+```mermaid
+sequenceDiagram
+ Client->>+Server: Request
+ Server->>+Database: Query
+ Database-->>-Server: Data
+ Server-->>-Client: Response
+```
+
+- `+` after arrow activates
+- `-` before arrow deactivates
+
+## Alt/Else (Conditional Logic)
+
+```mermaid
+sequenceDiagram
+ User->>API: POST /login
+ API->>Database: Query user
+ Database-->>API: User data
+
+ alt Valid credentials
+ API-->>User: 200 OK + Token
+ else Invalid credentials
+ API-->>User: 401 Unauthorized
+ else Account locked
+ API-->>User: 403 Forbidden
+ end
+```
+
+## Opt (Optional)
+
+```mermaid
+sequenceDiagram
+ User->>API: POST /order
+ API->>PaymentService: Process payment
+
+ opt Payment successful
+ API->>EmailService: Send confirmation
+ end
+
+ API-->>User: Order result
+```
+
+## Par (Parallel)
+
+Show concurrent operations:
+
+```mermaid
+sequenceDiagram
+ API->>Service: Process order
+
+ par Send email
+ Service->>EmailService: Send confirmation
+ and Update inventory
+ Service->>InventoryService: Reduce stock
+ and Log event
+ Service->>LogService: Log order
+ end
+
+ Service-->>API: Complete
+```
+
+## Loop
+
+```mermaid
+sequenceDiagram
+ Client->>Server: Request batch
+
+ loop For each item
+ Server->>Database: Process item
+ Database-->>Server: Result
+ end
+
+ Server-->>Client: All results
+```
+
+**Loop with condition:**
+```mermaid
+sequenceDiagram
+ loop Every 5 seconds
+ Monitor->>API: Health check
+ API-->>Monitor: Status
+ end
+```
+
+## Break (Early Exit)
+
+```mermaid
+sequenceDiagram
+ User->>API: Submit form
+ API->>Validator: Validate input
+
+ break Input invalid
+ API-->>User: 400 Bad Request
+ end
+
+ API->>Database: Save data
+ Database-->>API: Success
+ API-->>User: 200 OK
+```
+
+## Notes
+
+### Note over single participant
+```mermaid
+sequenceDiagram
+ User->>API: Request
+ Note over API: Validates JWT token
+ API-->>User: Response
+```
+
+### Note spanning participants
+```mermaid
+sequenceDiagram
+ Frontend->>API: Request
+ Note over Frontend,API: HTTPS encrypted
+ API-->>Frontend: Response
+```
+
+### Right/Left notes
+```mermaid
+sequenceDiagram
+ User->>System: Action
+ Note right of System: Logs to database
+ System-->>User: Response
+ Note left of User: Updates UI
+```
+
+## Sequence Numbers
+
+Automatically number messages:
+
+```mermaid
+sequenceDiagram
+ autonumber
+
+ User->>Frontend: Login
+ Frontend->>API: Authenticate
+ API->>Database: Verify credentials
+ Database-->>API: User data
+ API-->>Frontend: JWT token
+ Frontend-->>User: Success
+```
+
+## Links and Tooltips
+
+Add clickable links:
+
+```mermaid
+sequenceDiagram
+ participant A as Service A
+ link A: Dashboard @ https://dashboard.example.com
+ link A: API Docs @ https://docs.example.com
+
+ A->>B: Message
+```
+
+## Comprehensive Example: User Authentication Flow
+
+```mermaid
+sequenceDiagram
+ autonumber
+ actor User
+ participant Frontend
+ participant AuthAPI
+ participant Database
+ participant Redis
+ participant EmailService
+
+ User->>+Frontend: Enter credentials
+ Frontend->>+AuthAPI: POST /auth/login
+
+ AuthAPI->>+Database: Query user by email
+ Database-->>-AuthAPI: User record
+
+ alt User not found
+ AuthAPI-->>Frontend: 404 User not found
+ Frontend-->>User: Show error
+ else User found
+ AuthAPI->>AuthAPI: Verify password hash
+
+ alt Invalid password
+ AuthAPI->>Database: Increment failed attempts
+
+ opt Failed attempts > 5
+ AuthAPI->>Database: Lock account
+ AuthAPI->>EmailService: Send security alert
+ end
+
+ AuthAPI-->>Frontend: 401 Invalid credentials
+ Frontend-->>User: Show error
+ else Valid password
+ AuthAPI->>AuthAPI: Generate JWT token
+ AuthAPI->>+Redis: Store session
+ Redis-->>-AuthAPI: Confirm
+
+ par Update login metadata
+ AuthAPI->>Database: Update last_login
+ and Track analytics
+ AuthAPI->>Database: Log login event
+ end
+
+ AuthAPI-->>-Frontend: 200 OK + JWT token
+ Frontend->>Frontend: Store token in localStorage
+ Frontend-->>-User: Redirect to dashboard
+
+ opt First login
+ EmailService->>User: Welcome email
+ end
+ end
+ end
+```
+
+## API Request/Response Example
+
+```mermaid
+sequenceDiagram
+ autonumber
+ participant Client
+ participant Gateway
+ participant AuthService
+ participant UserService
+ participant Database
+
+ Client->>+Gateway: GET /api/users/123
+ Note over Gateway: Rate limiting check
+
+ Gateway->>+AuthService: Validate JWT
+ AuthService->>AuthService: Verify signature
+
+ alt Token invalid or expired
+ AuthService-->>Gateway: 401 Unauthorized
+ Gateway-->>Client: 401 Unauthorized
+ else Token valid
+ AuthService-->>-Gateway: User context
+
+ Gateway->>+UserService: GET /users/123
+ UserService->>+Database: SELECT * FROM users WHERE id=123
+ Database-->>-UserService: User record
+
+ alt User not found
+ UserService-->>Gateway: 404 Not Found
+ Gateway-->>Client: 404 Not Found
+ else User found
+ UserService-->>-Gateway: 200 OK + User data
+ Gateway-->>-Client: 200 OK + User data
+ end
+ end
+```
+
+## Microservices Communication
+
+```mermaid
+sequenceDiagram
+ actor User
+ participant Gateway
+ participant OrderService
+ participant PaymentService
+ participant InventoryService
+ participant NotificationService
+ participant MessageQueue
+
+ User->>+Gateway: POST /orders
+ Gateway->>+OrderService: Create order
+
+ OrderService->>+InventoryService: Check stock
+ InventoryService-->>-OrderService: Stock available
+
+ break Insufficient stock
+ OrderService-->>Gateway: 400 Out of stock
+ Gateway-->>User: Error message
+ end
+
+ OrderService->>OrderService: Reserve order
+ OrderService->>+PaymentService: Charge customer
+
+ alt Payment successful
+ PaymentService-->>-OrderService: Payment confirmed
+ OrderService->>MessageQueue: Publish OrderConfirmed event
+
+ par Async processing
+ MessageQueue->>InventoryService: Reduce stock
+ and
+ MessageQueue->>NotificationService: Send confirmation
+ NotificationService->>User: Email confirmation
+ end
+
+ OrderService-->>-Gateway: 201 Created
+ Gateway-->>User: Order confirmed
+ else Payment failed
+ PaymentService-->>OrderService: Payment declined
+ OrderService->>OrderService: Release reservation
+ OrderService-->>Gateway: 402 Payment Required
+ Gateway-->>User: Payment failed
+ end
+```
+
+## Best Practices
+
+1. **Order participants logically** - Typically: User → Frontend → Backend → Database
+2. **Use activations** - Shows when components are actively processing
+3. **Group related logic** - Use alt/opt/par to organize conditional flows
+4. **Add descriptive notes** - Explain complex logic or important details
+5. **Keep diagrams focused** - One scenario per diagram
+6. **Number messages** - Use autonumber for complex flows
+7. **Show error paths** - Document failure scenarios with alt/else
+8. **Indicate async operations** - Use open arrows for fire-and-forget messages
+
+## Common Use Cases
+
+### Authentication
+- Login flows
+- OAuth/SSO flows
+- Token refresh
+- Password reset
+
+### API Operations
+- CRUD operations
+- Search and filtering
+- Batch processing
+- Webhook handling
+
+### System Integration
+- Microservice communication
+- Third-party API calls
+- Message queue processing
+- Event-driven architecture
+
+### Business Processes
+- Order fulfillment
+- Payment processing
+- Approval workflows
+- Notification chains
diff --git a/dist/plugins/mui/skills/mui/README.md b/dist/plugins/mui/skills/mui/README.md
new file mode 100644
index 0000000..8acfdf4
--- /dev/null
+++ b/dist/plugins/mui/skills/mui/README.md
@@ -0,0 +1,232 @@
+# MUI v7 Patterns Skill
+
+A comprehensive skill for working with Material-UI v7 components, styling, and best practices in React applications.
+
+## Purpose
+
+This skill provides guidance and patterns for building React applications with Material-UI v7 (released March 2025). It covers component usage, the sx prop styling system, theme integration, responsive design, and MUI-specific utilities.
+
+MUI is one of the most popular React UI libraries, and v7 introduced several breaking changes from v6. This skill helps developers navigate these changes while following consistent, type-safe patterns.
+
+## When to Use
+
+Use this skill when you are:
+
+- **Styling components with the sx prop** - Need guidance on MUI's styling approach
+- **Working with MUI components** - Using Box, Grid, Paper, Typography, Button, Card, Dialog, and other MUI components
+- **Customizing themes** - Setting up or modifying MUI themes
+- **Building responsive layouts** - Using MUI's breakpoint system for mobile-first design
+- **Using MUI utilities and hooks** - Working with useTheme, useMediaQuery, or custom MUI hooks
+- **Migrating from MUI v6** - Understanding v7 breaking changes
+
+**Trigger phrases:**
+- "style with sx prop"
+- "MUI component"
+- "Material-UI"
+- "theme customization"
+- "MUI responsive design"
+- "MUI Grid layout"
+
+## How It Works
+
+1. **Identify the MUI task** - Recognize when MUI patterns are relevant to the current work
+2. **Apply appropriate patterns** - Use the correct styling approach based on component complexity
+3. **Leverage theme tokens** - Use MUI's built-in theme values instead of hardcoded styles
+4. **Ensure type safety** - Apply proper TypeScript types for sx props
+5. **Build responsively** - Use MUI's breakpoint system for adaptive layouts
+
+## Key Features
+
+### MUI v7 Breaking Changes Awareness
+
+The skill includes guidance on v7-specific changes:
+- Deep imports no longer work (use package exports)
+- `onBackdropClick` removed from Modal (use `onClose` instead)
+- Standardized `slots` and `slotProps` pattern for all components
+- CSS layers support via `enableCssLayer` config (Tailwind v4 compatible)
+
+### Styling Patterns
+
+Two approaches based on component complexity:
+- **Inline styles (< 100 lines)** - Define styles at component top
+- **Separate styles file (>= 100 lines)** - Create `ComponentName.styles.ts`
+
+### Complete Component Coverage
+
+- Layout: Box, Paper, Container, Stack
+- Grid system: 12-column responsive grid
+- Typography: All variants with custom styling
+- Forms: TextField, validation, error states
+- Feedback: Dialog, Snackbar, Loading states
+- Navigation: Cards, Buttons, Icons
+
+### Theme Integration
+
+- Direct theme value access in sx prop
+- useTheme hook for programmatic access
+- Callback syntax for complex theme-dependent styles
+
+### Responsive Design
+
+- Mobile-first breakpoint system (xs, sm, md, lg, xl)
+- Responsive prop values for any CSS property
+- Conditional display based on screen size
+
+## Usage Examples
+
+### Basic Component with sx Prop
+
+```typescript
+import { Box, Typography, Button, Paper } from '@mui/material';
+import type { SxProps, Theme } from '@mui/material';
+
+const styles: Record> = {
+ container: {
+ p: 2,
+ display: 'flex',
+ flexDirection: 'column',
+ gap: 2,
+ },
+ header: {
+ mb: 3,
+ fontSize: '1.5rem',
+ fontWeight: 600,
+ },
+};
+
+function MyComponent() {
+ return (
+
+ Title
+ Action
+
+ );
+}
+```
+
+### Responsive Layout
+
+```typescript
+
+ Responsive content
+
+```
+
+### Grid System
+
+```typescript
+import { Grid } from '@mui/material';
+
+
+
+ ...
+
+
+ ...
+
+
+```
+
+### Theme-Aware Styling
+
+```typescript
+ ({
+ color: theme.palette.primary.main,
+ bgcolor: 'background.paper',
+ p: 2,
+ '&:hover': {
+ color: theme.palette.primary.dark,
+ },
+ })}
+>
+ Theme-integrated content
+
+```
+
+## Prerequisites
+
+- React 18 or later
+- Material-UI v7 packages installed:
+ - `@mui/material`
+ - `@mui/icons-material` (for icons)
+- TypeScript (recommended for type safety)
+
+## Output
+
+This skill produces:
+- Type-safe component code using MUI patterns
+- Properly structured style definitions
+- Responsive, theme-integrated layouts
+- Accessible UI components following MUI conventions
+
+## Best Practices
+
+### 1. Always Type Your sx Props
+
+```typescript
+import type { SxProps, Theme } from '@mui/material';
+
+const styles: Record> = {
+ container: { p: 2 },
+};
+```
+
+### 2. Use Theme Tokens Over Hardcoded Values
+
+```typescript
+// Good
+> = {
+ container: {
+ p: 2,
+ display: 'flex',
+ flexDirection: 'column',
+ gap: 2,
+ },
+ header: {
+ mb: 3,
+ fontSize: '1.5rem',
+ fontWeight: 600,
+ },
+};
+
+function MyComponent() {
+ return (
+
+
+ Title
+
+
+ Action
+
+
+ );
+}
+```
+
+---
+
+## Styling Patterns
+
+### Inline Styles (< 100 lines)
+
+For components with simple styling, define styles at the top:
+
+```typescript
+import type { SxProps, Theme } from '@mui/material';
+
+const componentStyles: Record> = {
+ container: {
+ p: 2,
+ display: 'flex',
+ flexDirection: 'column',
+ },
+ header: {
+ mb: 2,
+ color: 'primary.main',
+ },
+ button: {
+ mt: 'auto',
+ alignSelf: 'flex-end',
+ },
+};
+
+function Component() {
+ return (
+
+ Header
+ Action
+
+ );
+}
+```
+
+### Separate Styles File (>= 100 lines)
+
+For complex components, create separate style file:
+
+```typescript
+// UserProfile.styles.ts
+import type { SxProps, Theme } from '@mui/material';
+
+export const userProfileStyles: Record> = {
+ container: {
+ p: 3,
+ maxWidth: 800,
+ mx: 'auto',
+ },
+ header: {
+ display: 'flex',
+ justifyContent: 'space-between',
+ alignItems: 'center',
+ mb: 3,
+ },
+ // ... many more styles
+};
+
+// UserProfile.tsx
+import { userProfileStyles as styles } from './UserProfile.styles';
+
+function UserProfile() {
+ return ... ;
+}
+```
+
+---
+
+## Common Components
+
+### Layout Components
+
+```typescript
+// Box - Generic container
+
+ Content
+
+
+// Paper - Elevated surface
+
+ Content
+
+
+// Container - Centered content with max-width
+
+ Content
+
+
+// Stack - Flex container with spacing
+
+
+```
+
+### Grid System
+
+```typescript
+import { Grid } from '@mui/material';
+
+// 12-column grid
+
+
+ Left half
+
+
+ Right half
+
+
+
+// Responsive grid
+
+
+ Card
+
+ {/* Repeat for more cards */}
+
+```
+
+### Typography
+
+```typescript
+Heading 1
+Heading 2
+Body text
+Small text
+
+// With custom styling
+
+ Custom Heading
+
+```
+
+### Buttons
+
+```typescript
+// Variants
+Contained
+Outlined
+Text
+
+// Colors
+Primary
+Secondary
+Error
+
+// With icons
+import { Add as AddIcon } from '@mui/icons-material';
+
+
+ Themed box
+
+ );
+}
+```
+
+### Theme in sx Prop
+
+```typescript
+
+ Content
+
+
+// Callback for advanced usage
+ ({
+ color: theme.palette.primary.main,
+ '&:hover': {
+ color: theme.palette.primary.dark,
+ },
+ })}
+>
+ Hover me
+
+```
+
+---
+
+## Responsive Design
+
+### Breakpoints
+
+```typescript
+// Mobile-first responsive values
+
+ Responsive width
+
+
+// Responsive display
+
+ Desktop only
+
+```
+
+### Responsive Typography
+
+```typescript
+
+ Responsive text
+
+```
+
+---
+
+## Forms
+
+```typescript
+import { TextField, Stack, Button } from '@mui/material';
+
+
+
+ setEmail(e.target.value)}
+ fullWidth
+ required
+ error={!!errors.email}
+ helperText={errors.email}
+ />
+ Submit
+
+
+```
+
+---
+
+## Common Patterns
+
+### Card Component
+
+```typescript
+import { Card, CardContent, CardActions, Typography, Button } from '@mui/material';
+
+
+
+
+ Title
+
+
+ Description
+
+
+
+ Learn More
+
+
+```
+
+### Dialog/Modal
+
+```typescript
+import { Dialog, DialogTitle, DialogContent, DialogActions, Button } from '@mui/material';
+
+
+ Confirm Action
+
+ Are you sure you want to proceed?
+
+
+ Cancel
+
+ Confirm
+
+
+
+```
+
+### Loading States
+
+```typescript
+import { CircularProgress, Skeleton } from '@mui/material';
+
+// Spinner
+
+
+
+// Skeleton
+
+
+```
+
+---
+
+## MUI-Specific Hooks
+
+### useMuiSnackbar
+
+```typescript
+import { useMuiSnackbar } from '@/hooks/useMuiSnackbar';
+
+function Component() {
+ const { showSuccess, showError, showInfo } = useMuiSnackbar();
+
+ const handleSave = async () => {
+ try {
+ await saveData();
+ showSuccess('Saved successfully');
+ } catch (error) {
+ showError('Failed to save');
+ }
+ };
+
+ return Save ;
+}
+```
+
+---
+
+## Icons
+
+```typescript
+import { Add as AddIcon, Delete as DeleteIcon } from '@mui/icons-material';
+import { Button, IconButton } from '@mui/material';
+
+> = {
+ container: { p: 2 },
+};
+
+// ❌ Avoid
+const styles = {
+ container: { p: 2 }, // No type safety
+};
+```
+
+### 2. Use Theme Tokens
+
+```typescript
+// ✅ Good: Use theme tokens
+
+ Section Title
+ Content goes here
+
+```
+
+### Container
+Centers content with max-width:
+
+```typescript
+
+ {/* Content automatically centered and constrained */}
+
+```
+
+### Grid (v2)
+Responsive grid layout:
+
+```typescript
+import Grid from '@mui/material/Grid2';
+
+
+
+ Item 1
+
+
+ Item 2
+
+
+ Item 3
+
+
+```
+
+### Stack
+One-dimensional layout with spacing:
+
+```typescript
+
+ {user.name}
+
+```
+
+## Data Display
+
+### Typography
+Text with theme variants:
+
+```typescript
+
+ Main Heading
+
+
+ Body text with secondary color
+
+
+ Bold caption
+
+```
+
+### Card
+Content container:
+
+```typescript
+
+
+
+ Card Title
+
+
+ Card description text
+
+
+
+ Learn More
+ Share
+
+
+```
+
+### List
+Structured content lists:
+
+```typescript
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+### Table
+Data tables:
+
+```typescript
+
+
+
+
+ Name
+ Email
+ Actions
+
+
+
+ {rows.map((row) => (
+
+ {row.name}
+ {row.email}
+
+
+
+
+
+ ))}
+
+
+
+```
+
+## Input Components
+
+### TextField
+Text input with validation:
+
+```typescript
+ setEmail(e.target.value)}
+ error={!!emailError}
+ helperText={emailError}
+ fullWidth
+ required
+/>
+```
+
+### Select
+Dropdown selection:
+
+```typescript
+
+ Country
+ setCountry(e.target.value)}
+ label="Country"
+ >
+ United States
+ United Kingdom
+ Canada
+
+
+```
+
+### Checkbox & Switch
+Boolean inputs:
+
+```typescript
+
+ Payment Method
+ setPayment(e.target.value)}>
+
+
+```
+
+### Autocomplete
+Searchable select:
+
+```typescript
+ option.label}
+ value={value}
+ onChange={(event, newValue) => setValue(newValue)}
+ renderInput={(params) => (
+
+ Contained
+ Outlined
+ Text
+
+```
+
+### Button with Icons
+```typescript
+
+
+
+
+
+```
+
+## Feedback Components
+
+### Alert
+Status messages:
+
+```typescript
+
+ Operation completed successfully!
+
+
+
+
+ Changes saved!
+
+
+```
+
+### Dialog
+Modal dialogs:
+
+```typescript
+
+ Confirm Delete
+
+
+ Are you sure you want to delete this item? This action cannot be undone.
+
+
+
+ Cancel
+
+ Delete
+
+
+
+```
+
+### CircularProgress & LinearProgress
+Loading indicators:
+
+```typescript
+
+
+```
+
+## Navigation
+
+### AppBar & Toolbar
+Application header:
+
+```typescript
+
+
+
+
+
+ App Title
+
+
+
+
+
+```
+
+### Drawer
+Side navigation:
+
+```typescript
+
+
+
+ navigate('/dashboard')}>
+
+ navigate('/settings')}>
+
+
+
+
+```
+
+### Tabs
+Tabbed navigation:
+
+```typescript
+
+
+
+
+
+ Overview content
+
+```
+
+### Breadcrumbs
+Navigation trail:
+
+```typescript
+
+ Electronics
+
+```
+
+## Utility Components
+
+### Tooltip
+Helpful hints:
+
+```typescript
+
+
+
+
+```
+
+### Popover
+Floating content:
+
+```typescript
+
+
+ Popover content
+
+
+```
+
+### Menu
+Context menus:
+
+```typescript
+
+
+ Edit
+
+
+ Delete
+
+
+```
+
+### Chip
+Compact information:
+
+```typescript
+
+
+```
+
+### Badge
+Notification indicators:
+
+```typescript
+
+
+
+
+
+```
+
+### Avatar
+User images:
+
+```typescript
+
+ JD
+
+
+
+```
+
+## Form Example
+
+Complete form with validation:
+
+```typescript
+
+
+
+ Role
+ setRole(e.target.value)}>
+ User
+ Admin
+
+
+
+ setAgreed(e.target.checked)} />}
+ label="I agree to the terms and conditions"
+ />
+
+
+
+ Cancel
+
+
+ Submit
+
+
+
+
+```
diff --git a/dist/plugins/mui/skills/mui/resources/styling-guide.md b/dist/plugins/mui/skills/mui/resources/styling-guide.md
new file mode 100644
index 0000000..fbba62f
--- /dev/null
+++ b/dist/plugins/mui/skills/mui/resources/styling-guide.md
@@ -0,0 +1,289 @@
+# MUI Styling Guide
+
+## The sx Prop
+
+The `sx` prop is the primary styling method in MUI v7+:
+
+```typescript
+(({ theme, variant }) => ({
+ backgroundColor: variant === 'primary'
+ ? theme.palette.primary.main
+ : theme.palette.secondary.main,
+ color: theme.palette.primary.contrastText,
+ '&:hover': {
+ backgroundColor: variant === 'primary'
+ ? theme.palette.primary.dark
+ : theme.palette.secondary.dark
+ }
+}));
+```
+
+## Theme Overrides
+
+```typescript
+import { createTheme } from '@mui/material/styles';
+
+const theme = createTheme({
+ components: {
+ MuiButton: {
+ styleOverrides: {
+ root: {
+ borderRadius: 8,
+ textTransform: 'none',
+ fontWeight: 600
+ },
+ containedPrimary: {
+ boxShadow: 'none',
+ '&:hover': {
+ boxShadow: 'none'
+ }
+ }
+ },
+ defaultProps: {
+ disableRipple: true
+ }
+ },
+ MuiCard: {
+ styleOverrides: {
+ root: {
+ borderRadius: 12,
+ boxShadow: '0 2px 8px rgba(0,0,0,0.1)'
+ }
+ }
+ }
+ }
+});
+```
+
+## CSS Variables (MUI v7+)
+
+```typescript
+// In theme configuration
+const theme = createTheme({
+ cssVariables: true
+});
+
+// Use in sx prop
+
+ `linear-gradient(45deg, ${theme.palette.primary.main} 30%, ${theme.palette.secondary.main} 90%)`,
+ color: 'white'
+ }}
+/>
+```
+
+### Sticky Header
+```typescript
+ theme.zIndex.drawer + 1
+ }}
+/>
+```
+
+### Flexbox Layouts
+```typescript
+ ({ p: 2 })} />
+
+// ✅ Good: Direct object
+ {
+ console.log('Theme:', theme);
+ return { p: 2 };
+}} />
+
+// Use sx as array for conditional styles
+
+
+ );
+}
+```
+
+## Dark Mode Support
+
+```typescript
+const getTheme = (mode: 'light' | 'dark') => createTheme({
+ palette: {
+ mode,
+ ...(mode === 'light'
+ ? {
+ // Light mode colors
+ primary: { main: '#1976d2' },
+ background: {
+ default: '#f5f5f5',
+ paper: '#ffffff'
+ }
+ }
+ : {
+ // Dark mode colors
+ primary: { main: '#90caf9' },
+ background: {
+ default: '#121212',
+ paper: '#1e1e1e'
+ }
+ })
+ }
+});
+
+function App() {
+ const [mode, setMode] = useState<'light' | 'dark'>('light');
+ const theme = useMemo(() => getTheme(mode), [mode]);
+
+ return (
+
+ setMode(m => m === 'light' ? 'dark' : 'light')}>
+ {mode === 'light' ?
+ {/* Your app */}
+
+ );
+}
+```
+
+## Typography Customization
+
+```typescript
+const theme = createTheme({
+ typography: {
+ fontFamily: '"Inter", sans-serif',
+ fontSize: 14,
+ fontWeightLight: 300,
+ fontWeightRegular: 400,
+ fontWeightMedium: 500,
+ fontWeightBold: 700,
+ h1: {
+ fontSize: '3rem',
+ fontWeight: 700,
+ lineHeight: 1.2,
+ letterSpacing: '-0.01562em'
+ },
+ h2: {
+ fontSize: '2.5rem',
+ fontWeight: 700,
+ lineHeight: 1.3
+ },
+ body1: {
+ fontSize: '1rem',
+ lineHeight: 1.5,
+ letterSpacing: '0.00938em'
+ },
+ button: {
+ fontSize: '0.875rem',
+ fontWeight: 600,
+ textTransform: 'none',
+ letterSpacing: '0.02857em'
+ }
+ }
+});
+```
+
+## Component Style Overrides
+
+```typescript
+const theme = createTheme({
+ components: {
+ MuiButton: {
+ styleOverrides: {
+ root: {
+ borderRadius: 8,
+ padding: '8px 16px',
+ boxShadow: 'none',
+ '&:hover': {
+ boxShadow: 'none'
+ }
+ },
+ contained: {
+ '&:hover': {
+ transform: 'translateY(-2px)',
+ transition: 'transform 0.2s'
+ }
+ }
+ },
+ defaultProps: {
+ disableElevation: true
+ }
+ },
+ MuiCard: {
+ styleOverrides: {
+ root: {
+ borderRadius: 12,
+ boxShadow: '0 2px 8px rgba(0,0,0,0.1)'
+ }
+ }
+ },
+ MuiTextField: {
+ defaultProps: {
+ variant: 'outlined',
+ size: 'medium'
+ },
+ styleOverrides: {
+ root: {
+ '& .MuiOutlinedInput-root': {
+ borderRadius: 8
+ }
+ }
+ }
+ },
+ MuiChip: {
+ styleOverrides: {
+ root: {
+ borderRadius: 6,
+ fontWeight: 500
+ }
+ }
+ }
+ }
+});
+```
+
+## Breakpoints
+
+```typescript
+const theme = createTheme({
+ breakpoints: {
+ values: {
+ xs: 0,
+ sm: 600,
+ md: 960,
+ lg: 1280,
+ xl: 1920
+ }
+ }
+});
+
+// Usage
+Tertiary Button
+```
+
+## Shadows
+
+```typescript
+const theme = createTheme({
+ shadows: [
+ 'none',
+ '0 2px 4px rgba(0,0,0,0.1)',
+ '0 4px 8px rgba(0,0,0,0.12)',
+ '0 8px 16px rgba(0,0,0,0.14)',
+ // ... up to shadows[24]
+ ]
+});
+
+// Usage
+
+ theme.transitions.create(['transform', 'background-color'], {
+ duration: theme.transitions.duration.standard
+ })
+ }}
+/>
+```
+
+## Complete Theme Example
+
+```typescript
+import { createTheme } from '@mui/material/styles';
+
+const theme = createTheme({
+ palette: {
+ mode: 'light',
+ primary: {
+ main: '#2563eb',
+ light: '#60a5fa',
+ dark: '#1e40af',
+ contrastText: '#ffffff'
+ },
+ secondary: {
+ main: '#7c3aed',
+ light: '#a78bfa',
+ dark: '#5b21b6',
+ contrastText: '#ffffff'
+ },
+ error: {
+ main: '#dc2626'
+ },
+ warning: {
+ main: '#f59e0b'
+ },
+ info: {
+ main: '#0ea5e9'
+ },
+ success: {
+ main: '#10b981'
+ },
+ background: {
+ default: '#f8fafc',
+ paper: '#ffffff'
+ },
+ text: {
+ primary: '#0f172a',
+ secondary: '#64748b'
+ }
+ },
+ typography: {
+ fontFamily: '"Inter", "Segoe UI", "Roboto", sans-serif',
+ fontSize: 14,
+ h1: {
+ fontSize: '3rem',
+ fontWeight: 700,
+ lineHeight: 1.2
+ },
+ h2: {
+ fontSize: '2.25rem',
+ fontWeight: 700,
+ lineHeight: 1.3
+ },
+ h3: {
+ fontSize: '1.875rem',
+ fontWeight: 600,
+ lineHeight: 1.4
+ },
+ h4: {
+ fontSize: '1.5rem',
+ fontWeight: 600,
+ lineHeight: 1.5
+ },
+ h5: {
+ fontSize: '1.25rem',
+ fontWeight: 600,
+ lineHeight: 1.6
+ },
+ h6: {
+ fontSize: '1rem',
+ fontWeight: 600,
+ lineHeight: 1.6
+ },
+ button: {
+ textTransform: 'none',
+ fontWeight: 600,
+ fontSize: '0.875rem'
+ }
+ },
+ shape: {
+ borderRadius: 10
+ },
+ spacing: 8,
+ components: {
+ MuiButton: {
+ styleOverrides: {
+ root: {
+ borderRadius: 8,
+ padding: '10px 20px',
+ fontWeight: 600,
+ boxShadow: 'none',
+ '&:hover': {
+ boxShadow: 'none'
+ }
+ },
+ contained: {
+ '&:hover': {
+ transform: 'translateY(-1px)',
+ boxShadow: '0 4px 12px rgba(0,0,0,0.15)'
+ }
+ }
+ },
+ defaultProps: {
+ disableElevation: true
+ }
+ },
+ MuiCard: {
+ styleOverrides: {
+ root: {
+ borderRadius: 12,
+ boxShadow: '0 1px 3px rgba(0,0,0,0.12), 0 1px 2px rgba(0,0,0,0.24)',
+ '&:hover': {
+ boxShadow: '0 3px 6px rgba(0,0,0,0.16), 0 3px 6px rgba(0,0,0,0.23)'
+ }
+ }
+ }
+ },
+ MuiTextField: {
+ defaultProps: {
+ variant: 'outlined'
+ },
+ styleOverrides: {
+ root: {
+ '& .MuiOutlinedInput-root': {
+ borderRadius: 8,
+ '&:hover .MuiOutlinedInput-notchedOutline': {
+ borderColor: '#2563eb'
+ }
+ }
+ }
+ }
+ },
+ MuiChip: {
+ styleOverrides: {
+ root: {
+ borderRadius: 6,
+ fontWeight: 500,
+ height: 28
+ }
+ }
+ },
+ MuiAppBar: {
+ styleOverrides: {
+ root: {
+ boxShadow: '0 1px 3px rgba(0,0,0,0.12)'
+ }
+ }
+ }
+ }
+});
+
+export default theme;
+```
+
+## Theme Provider Setup
+
+```typescript
+// src/theme.ts - Export your theme
+export { default as theme } from './theme';
+
+// src/main.tsx or src/index.tsx
+import { ThemeProvider } from '@mui/material/styles';
+import CssBaseline from '@mui/material/CssBaseline';
+import theme from './theme';
+
+root.render(
+
+
+
+
+);
+```
+
+## Accessing Theme in Components
+
+```typescript
+import { useTheme } from '@mui/material/styles';
+
+function MyComponent() {
+ const theme = useTheme();
+
+ return (
+
+
+ Dark section within light app
+
+
+ );
+}
+```
diff --git a/dist/plugins/mui/skills/mui/skill-rules-fragment.json b/dist/plugins/mui/skills/mui/skill-rules-fragment.json
new file mode 100644
index 0000000..8b4e2c3
--- /dev/null
+++ b/dist/plugins/mui/skills/mui/skill-rules-fragment.json
@@ -0,0 +1,84 @@
+{
+ "mui": {
+ "type": "domain",
+ "enforcement": "suggest",
+ "priority": "high",
+ "promptTriggers": {
+ "keywords": [
+ "mui",
+ "material-ui",
+ "material ui",
+ "@mui/material",
+ "@mui/icons-material",
+ "@mui/system",
+ "sx prop",
+ "mui theme",
+ "ThemeProvider",
+ "createTheme",
+ "useTheme",
+ "styled",
+ "Box",
+ "Typography",
+ "Button",
+ "TextField",
+ "Card",
+ "Dialog",
+ "Drawer",
+ "AppBar",
+ "Grid",
+ "Stack",
+ "Paper",
+ "Container",
+ "IconButton",
+ "Chip",
+ "Avatar",
+ "Alert",
+ "Snackbar",
+ "Menu",
+ "MenuItem",
+ "Select",
+ "Checkbox",
+ "Radio",
+ "Switch",
+ "Tabs",
+ "Autocomplete"
+ ],
+ "intentPatterns": [
+ "style.*with.*mui",
+ "use.*mui.*component",
+ "create.*mui.*theme",
+ "customize.*mui",
+ "add.*material.*ui.*component",
+ "implement.*mui.*dialog",
+ "create.*mui.*form",
+ "setup.*mui.*theme",
+ "use.*mui.*icon",
+ "add.*mui.*(button|card|dialog|form|menu)"
+ ]
+ },
+ "fileTriggers": {
+ "pathPatterns": [
+ "**/*.styles.ts",
+ "**/*.styles.tsx",
+ "**/components/**/*.tsx",
+ "**/components/**/*.ts",
+ "**/theme.ts",
+ "**/theme.tsx",
+ "**/theme/**/*.ts"
+ ],
+ "contentPatterns": [
+ "import.*@mui/material",
+ "import.*@mui/icons-material",
+ "import.*@mui/system",
+ "from '@mui/material'",
+ "sx=\\{",
+ " 18) { }
+setTimeout(callback, 3600000);
+
+// After
+const LEGAL_AGE = 18;
+const ONE_HOUR_IN_MS = 60 * 60 * 1000;
+
+if (age > LEGAL_AGE) { }
+setTimeout(callback, ONE_HOUR_IN_MS);
+```
+
+### Refactoring Support
+
+Can generate refactoring scripts to apply naming changes across the codebase while maintaining git history.
+
+## Usage Examples
+
+**Analyze a single file:**
+```
+@naming-analyzer UserService.js
+```
+
+**Analyze an entire directory:**
+```
+@naming-analyzer src/
+```
+
+**Show naming conventions reference:**
+```
+@naming-analyzer --conventions
+```
+
+**Analyze and suggest fixes for all issues:**
+```
+@naming-analyzer --fix-all
+```
+
+**General invocation:**
+```
+@naming-analyzer
+```
+Then provide the code or file path when prompted.
+
+## Output
+
+The skill produces a detailed markdown report containing:
+
+### Summary Section
+
+```
+## Summary
+- Items analyzed: 156
+- Issues found: 23
+- Critical: 5 (misleading names)
+- Major: 12 (unclear/vague)
+- Minor: 6 (convention violations)
+```
+
+### Issue Details
+
+Each issue includes:
+- **Current**: The existing name
+- **Issue**: Description of the problem
+- **Severity**: Critical, Major, or Minor
+- **Suggestion**: The recommended replacement
+- **Reason**: Why the suggestion is better
+
+### Suggested Renaming
+
+Prioritized list of all recommended changes:
+- High Priority: Misleading or critical issues
+- Medium Priority: Clarity improvements
+- Low Priority: Convention fixes
+
+## Best Practices
+
+### Do
+
+- **Use full words over abbreviations** - `userConfig` not `usrCfg`
+- **Be specific and descriptive** - `emailAddress` not `str`
+- **Follow language conventions** - camelCase in JavaScript, snake_case in Python
+- **Use consistent patterns** - don't mix styles within a file
+- **Make booleans obvious** - `isEnabled`, `hasPermission`
+- **Include units in constants** - `TIMEOUT_MS`, `MAX_SIZE_MB`
+
+### Don't
+
+- **Use single letters** - except in loops (`i`, `j`, `k`)
+- **Use vague names** - avoid `data`, `info`, `temp`, `x`, `result`
+- **Mix naming conventions** - pick one and stick with it
+- **Use misleading names** - name should match behavior exactly
+- **Over-abbreviate** - `calculateTotal` not `calcTtl`
+- **Use Hungarian notation** - not needed in modern typed languages
+
+### Acceptable Abbreviations
+
+Some abbreviations are well-known and acceptable:
+- `html`, `api`, `url`, `id`, `db`, `io`, `ui`
+- `min`, `max`, `src`, `dest`, `config`, `env`
+- `req`, `res` (in HTTP context)
+- `err` (in error handling context)
+
+## Naming Decision Tree
+
+```
+Is it a boolean?
+├─ Yes → Use is/has/can/should prefix
+└─ No → Is it a function?
+ ├─ Yes → Use verb phrase (action)
+ └─ No → Is it a class?
+ ├─ Yes → Use noun (PascalCase)
+ └─ No → Is it a constant?
+ ├─ Yes → Use UPPER_SNAKE_CASE
+ └─ No → Use descriptive noun (camelCase/snake_case)
+```
+
+## Notes
+
+- **Context matters**: Loop counters can be `i`, `j` - not every short name is bad
+- **Consistency over perfection**: Being consistent within a project is more important than following every convention perfectly
+- **Refactor as understanding improves**: Names should evolve as you better understand the domain
+- **Use IDE refactoring tools**: When renaming, use your IDE's rename feature to safely update all references
+- **Well-known abbreviations are okay**: `html`, `api`, `url`, `id` are universally understood
diff --git a/dist/plugins/naming-analyzer/skills/naming-analyzer/SKILL.md b/dist/plugins/naming-analyzer/skills/naming-analyzer/SKILL.md
new file mode 100644
index 0000000..fa2815a
--- /dev/null
+++ b/dist/plugins/naming-analyzer/skills/naming-analyzer/SKILL.md
@@ -0,0 +1,351 @@
+---
+name: naming-analyzer
+description: Suggest better variable, function, and class names based on context and conventions.
+---
+
+# Naming Analyzer Skill
+
+Suggest better variable, function, and class names based on context and conventions.
+
+## Instructions
+
+You are a naming convention expert. When invoked:
+
+1. **Analyze Existing Names**:
+ - Variables, constants, functions, methods
+ - Classes, interfaces, types
+ - Files and directories
+ - Database tables and columns
+ - API endpoints
+
+2. **Identify Issues**:
+ - Unclear or vague names
+ - Abbreviations that obscure meaning
+ - Inconsistent naming conventions
+ - Misleading names (name doesn't match behavior)
+ - Too short or too long names
+ - Hungarian notation misuse
+ - Single-letter variables outside loops
+
+3. **Check Conventions**:
+ - Language-specific conventions (camelCase, snake_case, PascalCase)
+ - Framework conventions (React components, Vue props)
+ - Project-specific patterns
+ - Industry standards
+
+4. **Provide Suggestions**:
+ - Better alternative names
+ - Reasoning for each suggestion
+ - Consistency improvements
+ - Contextual appropriateness
+
+## Naming Conventions by Language
+
+### JavaScript/TypeScript
+- Variables/functions: `camelCase`
+- Classes/interfaces: `PascalCase`
+- Constants: `UPPER_SNAKE_CASE`
+- Private fields: `_prefixUnderscore` or `#privateField`
+- Boolean: `is`, `has`, `can`, `should` prefixes
+
+### Python
+- Variables/functions: `snake_case`
+- Classes: `PascalCase`
+- Constants: `UPPER_SNAKE_CASE`
+- Private: `_prefix_underscore`
+- Boolean: `is_`, `has_`, `can_` prefixes
+
+### Java
+- Variables/methods: `camelCase`
+- Classes/interfaces: `PascalCase`
+- Constants: `UPPER_SNAKE_CASE`
+- Packages: `lowercase`
+
+### Go
+- Exported: `PascalCase`
+- Unexported: `camelCase`
+- Acronyms: All caps (`HTTPServer`, not `HttpServer`)
+
+## Common Naming Issues
+
+### Too Vague
+```javascript
+// ❌ Bad - Too generic
+function process(data) { }
+const info = getData();
+let temp = x;
+
+// ✓ Good - Specific and clear
+function processPayment(transaction) { }
+const userProfile = getUserProfile();
+let previousValue = x;
+```
+
+### Misleading Names
+```javascript
+// ❌ Bad - Name doesn't match behavior
+function getUser(id) {
+ const user = fetchUser(id);
+ user.lastLogin = Date.now();
+ saveUser(user); // Side effect! Not just "getting"
+ return user;
+}
+
+// ✓ Good - Name reflects actual behavior
+function fetchAndUpdateUserLogin(id) {
+ const user = fetchUser(id);
+ user.lastLogin = Date.now();
+ saveUser(user);
+ return user;
+}
+```
+
+### Abbreviations
+```javascript
+// ❌ Bad - Unclear abbreviations
+const usrCfg = loadConfig();
+function calcTtl(arr) { }
+
+// ✓ Good - Clear and readable
+const userConfig = loadConfig();
+function calculateTotal(amounts) { }
+
+// ✓ Acceptable - Well-known abbreviations
+const htmlElement = document.getElementById('main');
+const apiUrl = process.env.API_URL;
+```
+
+### Boolean Naming
+```javascript
+// ❌ Bad - Unclear state
+const login = user.authenticated;
+const status = checkUser();
+
+// ✓ Good - Clear boolean intent
+const isLoggedIn = user.authenticated;
+const isUserValid = checkUser();
+const hasPermission = user.roles.includes('admin');
+const canEditPost = isOwner || isAdmin;
+const shouldShowNotification = isEnabled && hasUnread;
+```
+
+### Magic Numbers
+```javascript
+// ❌ Bad - Unnamed constants
+if (age > 18) { }
+setTimeout(callback, 3600000);
+
+// ✓ Good - Named constants
+const LEGAL_AGE = 18;
+const ONE_HOUR_IN_MS = 60 * 60 * 1000;
+
+if (age > LEGAL_AGE) { }
+setTimeout(callback, ONE_HOUR_IN_MS);
+```
+
+## Usage Examples
+
+```
+@naming-analyzer
+@naming-analyzer src/
+@naming-analyzer UserService.js
+@naming-analyzer --conventions
+@naming-analyzer --fix-all
+```
+
+## Report Format
+
+```markdown
+# Naming Analysis Report
+
+## Summary
+- Items analyzed: 156
+- Issues found: 23
+- Critical: 5 (misleading names)
+- Major: 12 (unclear/vague)
+- Minor: 6 (convention violations)
+
+---
+
+## Critical Issues (5)
+
+### src/services/UserService.js:45
+**Current**: `getUser(id)`
+**Issue**: Function name implies read-only but has side effects (updates lastLogin)
+**Severity**: Critical - Misleading
+**Suggestion**: `fetchAndUpdateUserLogin(id)`
+**Reason**: Name should reflect the mutation
+
+### src/utils/helpers.js:23
+**Current**: `validate(x)`
+**Issue**: Generic parameter name, unclear what's being validated
+**Severity**: Critical - Too vague
+**Suggestion**: `validateEmail(emailAddress)`
+**Reason**: Specific names improve clarity
+
+---
+
+## Major Issues (12)
+
+### src/components/DataList.jsx:12
+**Current**: `const d = new Date()`
+**Issue**: Single-letter variable in large scope
+**Severity**: Major
+**Suggestion**: `const currentDate = new Date()`
+**Reason**: Clarity and searchability
+
+### src/api/client.js:67
+**Current**: `function proc(data) {}`
+**Issue**: Abbreviated function name
+**Severity**: Major
+**Suggestion**: `function processApiResponse(data) {}`
+**Reason**: Full words are more readable
+
+### src/models/User.js:34
+**Current**: `user.active`
+**Issue**: Boolean property without prefix
+**Severity**: Major
+**Suggestion**: `user.isActive`
+**Reason**: Follow boolean naming convention
+
+### src/utils/format.js:89
+**Current**: `const MAX = 100`
+**Issue**: Generic constant name
+**Severity**: Major
+**Suggestion**: `const MAX_RETRY_ATTEMPTS = 100`
+**Reason**: Specific purpose is clearer
+
+---
+
+## Minor Issues (6)
+
+### src/config/settings.js:12
+**Current**: `const API_url = '...'`
+**Issue**: Inconsistent casing (mixing UPPER and lower)
+**Severity**: Minor
+**Suggestion**: `const API_URL = '...'` or `const apiUrl = '...'`
+**Reason**: Consistency in convention
+
+### src/helpers/string.js:45
+**Current**: `function strToNum(s) {}`
+**Issue**: Abbreviated function and parameter
+**Severity**: Minor
+**Suggestion**: `function stringToNumber(value) {}`
+**Reason**: Clarity over brevity
+
+---
+
+## Convention Violations
+
+### Inconsistent Boolean Prefixes
+**Locations**: 8 files
+**Issue**: Mixed use of `is`, `has`, `can` vs no prefix
+**Recommendation**: Standardize on boolean prefixes
+- Use `is` for state: `isActive`, `isVisible`
+- Use `has` for possession: `hasPermission`, `hasError`
+- Use `can` for ability: `canEdit`, `canDelete`
+- Use `should` for decisions: `shouldRender`, `shouldValidate`
+
+### Mixed Naming Conventions
+**Location**: src/legacy/
+**Issue**: Mix of camelCase and snake_case in JavaScript
+**Recommendation**: Convert all to camelCase for consistency
+
+---
+
+## Suggested Renaming
+
+### High Priority (Misleading or Critical)
+1. `getUser` → `fetchAndUpdateUserLogin` (src/services/UserService.js:45)
+2. `validate` → `validateEmail` (src/utils/helpers.js:23)
+3. `process` → `processPaymentTransaction` (src/payment/processor.js:67)
+
+### Medium Priority (Clarity)
+1. `d` → `currentDate` (7 locations)
+2. `temp` → `previousValue` (4 locations)
+3. `data` → `apiResponse` or more specific (12 locations)
+4. `arr` → `items`, `values`, or more specific (8 locations)
+
+### Low Priority (Convention)
+1. `active` → `isActive` (12 locations)
+2. `error` → `hasError` (6 locations)
+3. `API_url` → `API_URL` (3 locations)
+
+---
+
+## Naming Patterns to Follow
+
+### Functions/Methods
+- Verbs: `get`, `set`, `create`, `update`, `delete`, `fetch`, `calculate`, `validate`
+- Clear action: `sendEmail()`, `parseJSON()`, `formatCurrency()`
+
+### Classes
+- Nouns: `UserService`, `PaymentProcessor`, `EmailValidator`
+- Avoid generic: Don't use `Manager`, `Helper`, `Utility` unless necessary
+
+### Variables
+- Nouns or noun phrases: `user`, `emailAddress`, `totalAmount`
+- Descriptive: `userList` not `list`, `activeUsers` not `users2`
+
+### Constants
+- All caps with underscores: `MAX_RETRY_ATTEMPTS`, `DEFAULT_TIMEOUT`
+- Include units: `CACHE_DURATION_MS`, `MAX_FILE_SIZE_MB`
+
+### Booleans
+- Question form: `isValid`, `hasPermission`, `canEdit`
+- Affirmative: `isEnabled` not `isDisabled` (prefer positive)
+
+---
+
+## Refactoring Script
+
+Would you like me to create a refactoring script to apply these changes?
+This will:
+1. Rename all suggested items
+2. Update all references
+3. Maintain git history
+4. Generate migration guide
+
+---
+
+## Best Practices
+
+✓ **DO**:
+- Use full words over abbreviations
+- Be specific and descriptive
+- Follow language conventions
+- Use consistent patterns
+- Make booleans obvious
+- Include units in constants
+
+✗ **DON'T**:
+- Use single letters (except in loops: i, j, k)
+- Use vague names (data, info, temp, x)
+- Mix naming conventions
+- Use misleading names
+- Over-abbreviate
+- Use Hungarian notation in modern code
+```
+
+## Naming Decision Tree
+
+```
+Is it a boolean?
+├─ Yes → Use is/has/can/should prefix
+└─ No → Is it a function?
+ ├─ Yes → Use verb phrase (action)
+ └─ No → Is it a class?
+ ├─ Yes → Use noun (PascalCase)
+ └─ No → Is it a constant?
+ ├─ Yes → Use UPPER_SNAKE_CASE
+ └─ No → Use descriptive noun (camelCase/snake_case)
+```
+
+## Notes
+
+- Prioritize clarity over brevity
+- Context matters (loop counters can be `i`, `j`)
+- Well-known abbreviations are okay (`html`, `api`, `url`, `id`)
+- Consistency within a project is more important than perfect naming
+- Refactor names as understanding improves
+- Use IDE rename refactoring to safely update all references
diff --git a/dist/plugins/openapi-to-typescript/skills/openapi-to-typescript/README.md b/dist/plugins/openapi-to-typescript/skills/openapi-to-typescript/README.md
new file mode 100644
index 0000000..5a9c041
--- /dev/null
+++ b/dist/plugins/openapi-to-typescript/skills/openapi-to-typescript/README.md
@@ -0,0 +1,300 @@
+# OpenAPI to TypeScript
+
+A Claude Code skill that converts OpenAPI 3.0 specifications (JSON or YAML) into TypeScript interfaces and type guards.
+
+## Purpose
+
+This skill automates the process of generating type-safe TypeScript code from OpenAPI API specifications. It creates:
+- TypeScript interfaces for all schema definitions
+- Request/Response type definitions for API endpoints
+- Runtime type guards for validation
+- Proper handling of complex types (unions, intersections, enums, arrays)
+
+## When to Use
+
+Use this skill when you need to:
+- Generate TypeScript types from an OpenAPI specification
+- Create type-safe API client interfaces
+- Convert API documentation into TypeScript code
+- Maintain type safety between backend API specs and frontend code
+
+### Trigger Phrases
+
+- "generate types from openapi"
+- "convert openapi to typescript"
+- "create API interfaces"
+- "generate types from spec"
+- "convert schema to TS"
+
+## How It Works
+
+### Workflow
+
+1. **Request Input**: Asks for the OpenAPI file path (if not provided)
+2. **Validation**: Reads and validates the OpenAPI specification (must be 3.0.x)
+3. **Schema Extraction**: Extracts schemas from `components/schemas`
+4. **Endpoint Analysis**: Extracts request/response types from `paths`
+5. **Code Generation**: Generates TypeScript interfaces and type guards
+6. **Output**: Asks where to save (default: `types/api.ts`)
+7. **Write File**: Creates the TypeScript file
+
+### OpenAPI Support
+
+- **Version**: OpenAPI 3.0.x only
+- **Format**: JSON or YAML
+- **Required fields**: `openapi`, `paths`, `components.schemas`
+
+## Key Features
+
+### Type Mapping
+
+**Primitives**:
+- `string` → `string`
+- `number` / `integer` → `number`
+- `boolean` → `boolean`
+- `null` → `null`
+
+**Format Modifiers** (with JSDoc comments):
+- `uuid` → `string` (/** UUID */)
+- `date` → `string` (/** Date */)
+- `date-time` → `string` (/** ISO DateTime */)
+- `email` → `string` (/** Email */)
+- `uri` → `string` (/** URI */)
+
+**Complex Types**:
+- **Objects** → TypeScript interfaces with optional/required fields
+- **Arrays** → TypeScript array types (`Type[]`)
+- **Enums** → TypeScript union types (`"value1" | "value2"`)
+- **oneOf** → Union types (`Type1 | Type2`)
+- **allOf** → Interface extension (`extends`)
+- **$ref** → Direct type references
+
+### Generated Code Structure
+
+```typescript
+/**
+ * Auto-generated from: {source_file}
+ * Generated at: {timestamp}
+ *
+ * DO NOT EDIT MANUALLY - Regenerate from OpenAPI schema
+ */
+
+// Types
+export interface User { ... }
+export type Status = "active" | "draft";
+
+// Request/Response Types
+export interface GetUsersRequest { ... }
+export type GetUsersResponse = User[];
+
+// Type Guards
+export function isUser(value: unknown): value is User { ... }
+
+// Error Types (always included)
+export interface ApiError { ... }
+export function isApiError(value: unknown): value is ApiError { ... }
+```
+
+### Type Guards
+
+Runtime validation functions for each interface:
+- Check object structure
+- Validate required fields
+- Type-check primitives
+- Validate enums and arrays
+
+## Usage Examples
+
+### Basic Usage
+
+```
+User: Generate TypeScript types from my OpenAPI spec at ./api/openapi.json
+
+Claude: I'll convert your OpenAPI specification to TypeScript.
+[Reads file, validates, generates types, saves to types/api.ts]
+```
+
+### With Custom Output Path
+
+```
+User: Convert openapi.yaml to TypeScript and save it to src/types/backend.ts
+
+Claude: I'll generate TypeScript types from your OpenAPI spec.
+[Generates and saves to specified location]
+```
+
+### Example Input/Output
+
+**Input** (openapi.json):
+```json
+{
+ "openapi": "3.0.0",
+ "components": {
+ "schemas": {
+ "Product": {
+ "type": "object",
+ "properties": {
+ "id": {"type": "string", "format": "uuid"},
+ "name": {"type": "string"},
+ "price": {"type": "number"},
+ "status": {"type": "string", "enum": ["active", "draft"]}
+ },
+ "required": ["id", "name", "price", "status"]
+ }
+ }
+ },
+ "paths": {
+ "/products": {
+ "get": {
+ "parameters": [
+ {"name": "page", "in": "query", "schema": {"type": "integer"}},
+ {"name": "limit", "in": "query", "schema": {"type": "integer"}}
+ ],
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "type": "array",
+ "items": {"$ref": "#/components/schemas/Product"}
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+**Output** (types/api.ts):
+```typescript
+/**
+ * Auto-generated from: openapi.json
+ * Generated at: 2026-01-18T19:00:00Z
+ *
+ * DO NOT EDIT MANUALLY - Regenerate from OpenAPI schema
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type ProductStatus = "active" | "draft";
+
+export interface Product {
+ /** UUID */
+ id: string;
+
+ name: string;
+
+ price: number;
+
+ status: ProductStatus;
+}
+
+// ============================================================================
+// Request/Response Types
+// ============================================================================
+
+export interface GetProductsRequest {
+ page?: number;
+ limit?: number;
+}
+
+export type GetProductsResponse = Product[];
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export function isProduct(value: unknown): value is Product {
+ return (
+ typeof value === 'object' &&
+ value !== null &&
+ 'id' in value &&
+ typeof (value as any).id === 'string' &&
+ 'name' in value &&
+ typeof (value as any).name === 'string' &&
+ 'price' in value &&
+ typeof (value as any).price === 'number' &&
+ 'status' in value &&
+ ['active', 'draft'].includes((value as any).status)
+ );
+}
+
+// ============================================================================
+// Error Types
+// ============================================================================
+
+export interface ApiError {
+ status: number;
+ error: string;
+ detail?: string;
+}
+
+export function isApiError(value: unknown): value is ApiError {
+ return (
+ typeof value === 'object' &&
+ value !== null &&
+ 'status' in value &&
+ typeof (value as any).status === 'number' &&
+ 'error' in value &&
+ typeof (value as any).error === 'string'
+ );
+}
+```
+
+## Benefits
+
+- **Type Safety**: Catch API contract violations at compile time
+- **Auto-completion**: Full IDE support for API request/response types
+- **Runtime Validation**: Type guards for validating API responses
+- **Documentation**: JSDoc comments preserved from OpenAPI descriptions
+- **Maintainability**: Regenerate types when API spec changes
+- **DRY Principle**: Single source of truth (OpenAPI spec)
+
+## Limitations
+
+- Only supports OpenAPI 3.0.x (not 2.0 or 3.1)
+- Circular references handled with type aliases
+- Unknown types fall back to `unknown` with warnings
+- Complex `allOf` scenarios may need manual refinement
+
+## Related Tools
+
+This skill complements:
+- **openapi-validator**: Validate OpenAPI specs before conversion
+- **api-client-generator**: Generate full API clients using these types
+- **schema-diff**: Compare OpenAPI versions to track type changes
+
+## Technical Details
+
+### Naming Conventions
+
+- **Interfaces**: PascalCase (e.g., `User`, `Product`)
+- **Request Types**: `{Method}{Path}Request` (e.g., `GetUsersRequest`)
+- **Response Types**: `{Method}{Path}Response` (e.g., `GetUsersResponse`)
+- **Type Guards**: `is{TypeName}` (e.g., `isUser`, `isProduct`)
+- **Enums**: `{TypeName}{FieldName}` (e.g., `ProductStatus`, `UserRole`)
+
+### Field Handling
+
+- **Required fields**: No `?` suffix
+- **Optional fields**: `?` suffix
+- **Descriptions**: Converted to JSDoc comments
+- **Formats**: Added as JSDoc comments
+
+### Error Handling
+
+The skill validates and reports:
+- Invalid OpenAPI version
+- Missing required fields (`openapi`, `paths`, `components`)
+- Unresolved `$ref` references
+- Unknown or unsupported types
+- Circular reference warnings
+
+## License
+
+Part of the Softaworks Agent Skills collection.
\ No newline at end of file
diff --git a/dist/plugins/openapi-to-typescript/skills/openapi-to-typescript/SKILL.md b/dist/plugins/openapi-to-typescript/skills/openapi-to-typescript/SKILL.md
new file mode 100644
index 0000000..3f53745
--- /dev/null
+++ b/dist/plugins/openapi-to-typescript/skills/openapi-to-typescript/SKILL.md
@@ -0,0 +1,344 @@
+---
+name: openapi-to-typescript
+description: Converts OpenAPI 3.0 JSON/YAML to TypeScript interfaces and type guards. This skill should be used when the user asks to generate types from OpenAPI, convert schema to TS, create API interfaces, or generate TypeScript types from an API specification.
+---
+
+# OpenAPI to TypeScript
+
+Converts OpenAPI 3.0 specifications to TypeScript interfaces and type guards.
+
+**Input:** OpenAPI file (JSON or YAML)
+**Output:** TypeScript file with interfaces and type guards
+
+## When to Use
+
+- "generate types from openapi"
+- "convert openapi to typescript"
+- "create API interfaces"
+- "generate types from spec"
+
+## Workflow
+
+1. Request the OpenAPI file path (if not provided)
+2. Read and validate the file (must be OpenAPI 3.0.x)
+3. Extract schemas from `components/schemas`
+4. Extract endpoints from `paths` (request/response types)
+5. Generate TypeScript (interfaces + type guards)
+6. Ask where to save (default: `types/api.ts` in current directory)
+7. Write the file
+
+## OpenAPI Validation
+
+Check before processing:
+
+```
+- Field "openapi" must exist and start with "3.0"
+- Field "paths" must exist
+- Field "components.schemas" must exist (if there are types)
+```
+
+If invalid, report the error and stop.
+
+## Type Mapping
+
+### Primitives
+
+| OpenAPI | TypeScript |
+|-------------|--------------|
+| `string` | `string` |
+| `number` | `number` |
+| `integer` | `number` |
+| `boolean` | `boolean` |
+| `null` | `null` |
+
+### Format Modifiers
+
+| Format | TypeScript |
+|---------------|-------------------------|
+| `uuid` | `string` (comment UUID) |
+| `date` | `string` (comment date) |
+| `date-time` | `string` (comment ISO) |
+| `email` | `string` (comment email)|
+| `uri` | `string` (comment URI) |
+
+### Complex Types
+
+**Object:**
+```typescript
+// OpenAPI: type: object, properties: {id, name}, required: [id]
+interface Example {
+ id: string; // required: no ?
+ name?: string; // optional: with ?
+}
+```
+
+**Array:**
+```typescript
+// OpenAPI: type: array, items: {type: string}
+type Names = string[];
+```
+
+**Enum:**
+```typescript
+// OpenAPI: type: string, enum: [active, draft]
+type Status = "active" | "draft";
+```
+
+**oneOf (Union):**
+```typescript
+// OpenAPI: oneOf: [{$ref: Cat}, {$ref: Dog}]
+type Pet = Cat | Dog;
+```
+
+**allOf (Intersection/Extends):**
+```typescript
+// OpenAPI: allOf: [{$ref: Base}, {type: object, properties: ...}]
+interface Extended extends Base {
+ extraField: string;
+}
+```
+
+## Code Generation
+
+### File Header
+
+```typescript
+/**
+ * Auto-generated from: {source_file}
+ * Generated at: {timestamp}
+ *
+ * DO NOT EDIT MANUALLY - Regenerate from OpenAPI schema
+ */
+```
+
+### Interfaces (from components/schemas)
+
+For each schema in `components/schemas`:
+
+```typescript
+export interface Product {
+ /** Product unique identifier */
+ id: string;
+
+ /** Product title */
+ title: string;
+
+ /** Product price */
+ price: number;
+
+ /** Created timestamp */
+ created_at?: string;
+}
+```
+
+- Use OpenAPI description as JSDoc
+- Fields in `required[]` have no `?`
+- Fields outside `required[]` have `?`
+
+### Request/Response Types (from paths)
+
+For each endpoint in `paths`:
+
+```typescript
+// GET /products - query params
+export interface GetProductsRequest {
+ page?: number;
+ limit?: number;
+}
+
+// GET /products - response 200
+export type GetProductsResponse = ProductList;
+
+// POST /products - request body
+export interface CreateProductRequest {
+ title: string;
+ price: number;
+}
+
+// POST /products - response 201
+export type CreateProductResponse = Product;
+```
+
+Naming convention:
+- `{Method}{Path}Request` for params/body
+- `{Method}{Path}Response` for response
+
+### Type Guards
+
+For each main interface, generate a type guard:
+
+```typescript
+export function isProduct(value: unknown): value is Product {
+ return (
+ typeof value === 'object' &&
+ value !== null &&
+ 'id' in value &&
+ typeof (value as any).id === 'string' &&
+ 'title' in value &&
+ typeof (value as any).title === 'string' &&
+ 'price' in value &&
+ typeof (value as any).price === 'number'
+ );
+}
+```
+
+Type guard rules:
+- Check `typeof value === 'object' && value !== null`
+- For each required field: check `'field' in value`
+- For primitive fields: check `typeof`
+- For arrays: check `Array.isArray()`
+- For enums: check `.includes()`
+
+### Error Type (always include)
+
+```typescript
+export interface ApiError {
+ status: number;
+ error: string;
+ detail?: string;
+}
+
+export function isApiError(value: unknown): value is ApiError {
+ return (
+ typeof value === 'object' &&
+ value !== null &&
+ 'status' in value &&
+ typeof (value as any).status === 'number' &&
+ 'error' in value &&
+ typeof (value as any).error === 'string'
+ );
+}
+```
+
+## $ref Resolution
+
+When encountering `{"$ref": "#/components/schemas/Product"}`:
+1. Extract the schema name (`Product`)
+2. Use the type directly (don't resolve inline)
+
+```typescript
+// OpenAPI: items: {$ref: "#/components/schemas/Product"}
+// TypeScript:
+items: Product[] // reference, not inline
+```
+
+## Complete Example
+
+**Input (OpenAPI):**
+```json
+{
+ "openapi": "3.0.0",
+ "components": {
+ "schemas": {
+ "User": {
+ "type": "object",
+ "properties": {
+ "id": {"type": "string", "format": "uuid"},
+ "email": {"type": "string", "format": "email"},
+ "role": {"type": "string", "enum": ["admin", "user"]}
+ },
+ "required": ["id", "email", "role"]
+ }
+ }
+ },
+ "paths": {
+ "/users/{id}": {
+ "get": {
+ "parameters": [{"name": "id", "in": "path", "required": true}],
+ "responses": {
+ "200": {
+ "content": {
+ "application/json": {
+ "schema": {"$ref": "#/components/schemas/User"}
+ }
+ }
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+**Output (TypeScript):**
+```typescript
+/**
+ * Auto-generated from: api.openapi.json
+ * Generated at: 2025-01-15T10:30:00Z
+ *
+ * DO NOT EDIT MANUALLY - Regenerate from OpenAPI schema
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type UserRole = "admin" | "user";
+
+export interface User {
+ /** UUID */
+ id: string;
+
+ /** Email */
+ email: string;
+
+ role: UserRole;
+}
+
+// ============================================================================
+// Request/Response Types
+// ============================================================================
+
+export interface GetUserByIdRequest {
+ id: string;
+}
+
+export type GetUserByIdResponse = User;
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export function isUser(value: unknown): value is User {
+ return (
+ typeof value === 'object' &&
+ value !== null &&
+ 'id' in value &&
+ typeof (value as any).id === 'string' &&
+ 'email' in value &&
+ typeof (value as any).email === 'string' &&
+ 'role' in value &&
+ ['admin', 'user'].includes((value as any).role)
+ );
+}
+
+// ============================================================================
+// Error Types
+// ============================================================================
+
+export interface ApiError {
+ status: number;
+ error: string;
+ detail?: string;
+}
+
+export function isApiError(value: unknown): value is ApiError {
+ return (
+ typeof value === 'object' &&
+ value !== null &&
+ 'status' in value &&
+ typeof (value as any).status === 'number' &&
+ 'error' in value &&
+ typeof (value as any).error === 'string'
+ );
+}
+```
+
+## Common Errors
+
+| Error | Action |
+|-------|--------|
+| OpenAPI version != 3.0.x | Report that only 3.0 is supported |
+| $ref not found | List missing refs |
+| Unknown type | Use `unknown` and warn |
+| Circular reference | Use type alias with lazy reference |
diff --git a/dist/plugins/perplexity/skills/perplexity/README.md b/dist/plugins/perplexity/skills/perplexity/README.md
new file mode 100644
index 0000000..fad1bc2
--- /dev/null
+++ b/dist/plugins/perplexity/skills/perplexity/README.md
@@ -0,0 +1,197 @@
+# Perplexity Skill
+
+A comprehensive guide for using Perplexity AI tools effectively within Claude Code. This skill helps you choose the right search and research tool for your needs while avoiding context bloat and unnecessary API calls.
+
+## Purpose
+
+This skill provides clear guidelines for when and how to use Perplexity's search and conversational AI capabilities, ensuring you select the most appropriate tool for each task while respecting token budgets and avoiding overlaps with other specialized tools.
+
+## When to Use This Skill
+
+Use Perplexity tools ONLY when users explicitly request:
+- **Search queries**: "search", "find", "look up", "research"
+- **Current information**: "what's the latest", "recent trends"
+- **Generic questions**: Broad topics not covered by specialized tools
+
+## When NOT to Use This Skill
+
+Do NOT use Perplexity for:
+- **Library/framework documentation** → Use Context7 MCP instead
+- **Graphite `gt` CLI commands** → Use Graphite MCP instead
+- **Workspace-specific questions** → Use Nx MCP instead
+- **Specific URLs** → Use URL Crawler instead
+- **Deep research** → Use Researcher agent (`/research`) instead
+
+## Available Tools
+
+### 1. Perplexity Search
+
+**Best for**: Finding resources, URLs, and current best practices
+
+**When to use**:
+- Discovering tutorials, blog posts, or articles
+- Finding recent information about technologies
+- User says "search for...", "find...", "look up..."
+
+**Default usage** (always start with these limits):
+```typescript
+mcp__perplexity__perplexity_search({
+ query: "your search query",
+ max_results: 3, // Default is 10 - too many!
+ max_tokens_per_page: 512 // Reduce per-result content
+})
+```
+
+**When to increase limits**:
+Only increase limits if:
+- User explicitly needs comprehensive results
+- Initial search found nothing useful
+- Complex topic requires multiple sources
+
+```typescript
+// Increased limits (use sparingly)
+mcp__perplexity__perplexity_search({
+ query: "complex topic",
+ max_results: 5,
+ max_tokens_per_page: 1024
+})
+```
+
+### 2. Perplexity Ask
+
+**Best for**: Getting conversational explanations synthesized from web sources
+
+**When to use**:
+- Need explanation, not just search results
+- Synthesize information from multiple web sources
+- Explain concepts with current context
+
+**Usage**:
+```typescript
+mcp__perplexity__perplexity_ask({
+ messages: [
+ {
+ role: "user",
+ content: "Explain how postgres advisory locks work"
+ }
+ ]
+})
+```
+
+**NOT for**:
+- Library documentation (use Context7)
+- Deep multi-source research (use researcher agent)
+
+### 3. Perplexity Research (PROHIBITED)
+
+**NEVER use**: `mcp__perplexity__perplexity_research`
+
+**Why**: Extremely high token cost (30-50k tokens)
+
+**Use instead**: Researcher agent (`/research `)
+- Provides multi-source synthesis with citations
+- Use sparingly for complex questions only
+
+## Tool Selection Chain
+
+When a user asks a question, follow this priority order:
+
+1. **Context7 MCP** - Library/framework documentation
+2. **Graphite MCP** - Any `gt` CLI mention
+3. **Nx MCP** - Questions about THIS workspace
+4. **Perplexity Search** - Generic searches
+5. **Perplexity Ask** - Conversational answers
+6. **Researcher agent** - Deep multi-source research
+7. **WebSearch** - Last resort (after Perplexity exhausted)
+
+## Usage Examples
+
+### Correct Usage
+
+**Use Perplexity Search:**
+```
+User: "Find postgres migration best practices"
+User: "Search for React testing tutorials"
+User: "Look up latest trends in microservices"
+```
+
+**Use Perplexity Ask:**
+```
+User: "Explain how postgres advisory locks work"
+User: "What are the trade-offs of microservices?"
+```
+
+### Incorrect Usage (Use Other Tools)
+
+**Use Context7 instead:**
+```
+❌ "Search for React hooks documentation"
+❌ "Find Next.js routing docs"
+❌ "Look up Temporal workflow API"
+```
+
+**Use Graphite MCP instead:**
+```
+❌ "Search for gt stack commands"
+❌ "Find gt branch workflow"
+```
+
+**Use Nx MCP instead:**
+```
+❌ "Search for build config" (in THIS workspace)
+❌ "Find project dependencies" (in THIS workspace)
+```
+
+## Key Features
+
+- **Token budget awareness**: Default to limited results to avoid context bloat
+- **Clear tool boundaries**: Know when to use Perplexity vs. specialized tools
+- **Fallback chain**: Search → Ask → WebSearch (last resort)
+- **Research delegation**: Use researcher agent for deep dives, not raw Perplexity API
+
+## Best Practices
+
+1. **Start conservative**: Always use `max_results: 3` and `max_tokens_per_page: 512`
+2. **Check alternatives first**: Try Context7, Graphite MCP, or Nx MCP before Perplexity
+3. **Know your trigger words**: "search", "find", "look up", "research", "latest"
+4. **Avoid research tool**: Never use `perplexity_research` - use researcher agent instead
+5. **Respect the chain**: Follow the tool selection priority order
+
+## Common Pitfalls
+
+- Using Perplexity for library docs (use Context7)
+- Using high limits by default (causes context bloat)
+- Using `perplexity_research` directly (use researcher agent)
+- Skipping the tool selection chain
+- Not checking if specialized tools apply first
+
+## Integration with Other Skills
+
+- **Context7**: For library/framework documentation
+- **Graphite MCP**: For `gt` CLI operations
+- **Nx MCP**: For workspace-specific queries
+- **Researcher agent**: For deep research tasks
+- **WebSearch**: As absolute last resort fallback
+
+## Quick Decision Matrix
+
+| User Request | Tool to Use |
+|--------------|-------------|
+| React hooks docs | Context7 MCP |
+| gt stack command | Graphite MCP |
+| Build config here | Nx MCP |
+| Find migration guide | Perplexity Search |
+| Explain advisory locks | Perplexity Ask |
+| Deep research report | Researcher agent |
+| Generic web search | WebSearch (last resort) |
+
+## Summary
+
+The Perplexity skill ensures you use Perplexity AI tools effectively and appropriately:
+- Choose the right tool (Search vs. Ask)
+- Respect token budgets with conservative limits
+- Defer to specialized tools when appropriate
+- Avoid the expensive research tool
+- Follow the tool selection chain
+
+By following these guidelines, you'll provide better, faster, and more cost-effective responses to users.
diff --git a/dist/plugins/perplexity/skills/perplexity/SKILL.md b/dist/plugins/perplexity/skills/perplexity/SKILL.md
new file mode 100644
index 0000000..dbf0d69
--- /dev/null
+++ b/dist/plugins/perplexity/skills/perplexity/SKILL.md
@@ -0,0 +1,128 @@
+---
+name: perplexity
+description: Web search and research using Perplexity AI. Use when user says "search", "find", "look up", "ask", "research", or "what's the latest" for generic queries. NOT for library/framework docs (use Context7) or workspace questions.
+---
+
+# Perplexity Tools
+
+Use ONLY when user says "search", "find", "look up", "ask", "research", or "what's the latest" for generic queries. NOT for library/framework docs (use Context7), gt CLI (use Graphite MCP), or workspace questions (use Nx MCP).
+
+## Quick Reference
+
+**Which Perplexity tool?**
+- Need search results/URLs? → **Perplexity Search**
+- Need conversational answer? → **Perplexity Ask**
+- Need deep research? → **Researcher agent** (`/research `)
+
+**NOT Perplexity - use these instead:**
+- Library/framework docs → **Context7 MCP**
+- Graphite `gt` CLI → **Graphite MCP**
+- THIS workspace → **Nx MCP**
+- Specific URL → **URL Crawler**
+
+## Perplexity Search
+
+**When to use:**
+- Generic searches, finding resources
+- Current best practices, recent information
+- Tutorial/blog post discovery
+- User says "search for...", "find...", "look up..."
+
+**Default parameters (ALWAYS USE):**
+```typescript
+mcp__perplexity__perplexity_search({
+ query: "your search query",
+ max_results: 3, // Default is 10 - too many!
+ max_tokens_per_page: 512 // Reduce per-result content
+})
+```
+
+**When to increase limits:**
+Only if:
+- User explicitly needs comprehensive results
+- Initial search found nothing useful
+- Complex topic needs multiple sources
+
+```typescript
+// Increased limits (use sparingly)
+mcp__perplexity__perplexity_search({
+ query: "complex topic",
+ max_results: 5,
+ max_tokens_per_page: 1024
+})
+```
+
+## Perplexity Ask
+
+**When to use:**
+- Need conversational explanation, not search results
+- Synthesize information from web
+- Explain concepts with current context
+
+**Usage:**
+```typescript
+mcp__perplexity__perplexity_ask({
+ messages: [
+ {
+ role: "user",
+ content: "Explain how postgres advisory locks work"
+ }
+ ]
+})
+```
+
+**NOT for:**
+- Library documentation (use Context7)
+- Deep multi-source research (use researcher agent)
+
+## Prohibited Tool
+
+**NEVER use:** `mcp__perplexity__perplexity_research`
+
+**Use instead:** Researcher agent (`/research `)
+- Token cost: 30-50k tokens
+- Provides multi-source synthesis with citations
+- Use sparingly for complex questions only
+
+## Tool Selection Chain
+
+**Priority order:**
+1. **Context7 MCP** - Library/framework docs
+2. **Graphite MCP** - Any `gt` CLI mention
+3. **Nx MCP** - THIS workspace questions
+4. **Perplexity Search** - Generic searches
+5. **Perplexity Ask** - Conversational answers
+6. **Researcher agent** - Deep multi-source research
+7. **WebSearch** - Last resort (after Perplexity exhausted)
+
+## Examples
+
+**✅ CORRECT - Use Perplexity Search:**
+- "Find postgres migration best practices"
+- "Search for React testing tutorials"
+- "Look up latest trends in microservices"
+
+**✅ CORRECT - Use Perplexity Ask:**
+- "Explain how postgres advisory locks work"
+- "What are the trade-offs of microservices?"
+
+**❌ WRONG - Use Context7 instead:**
+- "Search for React hooks documentation" → Context7 MCP
+- "Find Next.js routing docs" → Context7 MCP
+- "Look up Temporal workflow API" → Context7 MCP
+
+**❌ WRONG - Use Graphite MCP instead:**
+- "Search for gt stack commands" → Graphite MCP
+- "Find gt branch workflow" → Graphite MCP
+
+**❌ WRONG - Use Nx MCP instead:**
+- "Search for build config" (in THIS workspace) → Nx MCP
+- "Find project dependencies" (in THIS workspace) → Nx MCP
+
+## Key Points
+
+- **Default to limited results** - avoid context bloat
+- **Library docs = Context7** - ALWAYS try Context7 first
+- **"gt" = Graphite MCP** - ANY "gt" mention uses Graphite
+- **Deep research = /research** - NOT perplexity_research tool
+- **Fallback chain** - Search → Ask → WebSearch (last resort)
diff --git a/dist/plugins/plugin-forge/skills/plugin-forge/README.md b/dist/plugins/plugin-forge/skills/plugin-forge/README.md
new file mode 100644
index 0000000..0701d4f
--- /dev/null
+++ b/dist/plugins/plugin-forge/skills/plugin-forge/README.md
@@ -0,0 +1,259 @@
+# CC Plugin Forge
+
+A comprehensive skill for building and managing Claude Code plugins with proper structure, manifests, and marketplace integration.
+
+## Purpose
+
+Plugin Forge streamlines the entire lifecycle of Claude Code plugin development. It provides automation scripts, reference documentation, and structured workflows to help you create professional-quality plugins that integrate seamlessly with the Claude Code plugin ecosystem.
+
+Whether you're building a framework-specific plugin for React or Vue, a utility plugin for common tasks, or a domain-specific knowledge plugin, Plugin Forge guides you through the correct structure and patterns.
+
+## When to Use
+
+Use this skill when you need to:
+
+- **Create new plugins** - "Create a new Claude Code plugin for my project"
+- **Add plugin components** - "Add a new command to my plugin", "Create a skill for this plugin"
+- **Manage versions** - "Bump the plugin version", "Update plugin to 2.0.0"
+- **Work with manifests** - "Update plugin.json", "Register plugin in marketplace"
+- **Set up local testing** - "Test my plugin locally", "Install plugin for development"
+- **Publish plugins** - "Publish plugin to marketplace", "Distribute my plugin"
+
+**Trigger phrases:**
+- "Create a Claude Code plugin"
+- "Build a plugin for marketplace"
+- "Add command/skill/agent/hook to plugin"
+- "Bump plugin version"
+- "Update plugin.json"
+- "Set up plugin testing"
+
+## How It Works
+
+### Plugin Creation Flow
+
+1. **Scaffold Structure** - The `create_plugin.py` script generates the correct directory hierarchy with all required files
+2. **Generate Manifests** - Creates `plugin.json` with metadata and updates `marketplace.json` with the plugin entry
+3. **Create Templates** - Generates a README template for your plugin documentation
+4. **Guide Next Steps** - Provides instructions for adding components and testing
+
+### Version Management Flow
+
+1. **Parse Current Version** - Reads version from `plugin.json`
+2. **Calculate New Version** - Applies semantic versioning rules (major/minor/patch)
+3. **Sync Both Manifests** - Updates version in both `plugin.json` and `marketplace.json`
+4. **Confirm Success** - Reports the version change
+
+## Key Features
+
+### Automation Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `create_plugin.py` | Scaffold new plugins with complete structure and manifests |
+| `bump_version.py` | Update versions across all manifest files consistently |
+
+### Reference Documentation
+
+| Document | Content |
+|----------|---------|
+| `plugin-structure.md` | Directory hierarchy, manifest schema, component types |
+| `marketplace-schema.md` | Marketplace format, plugin entries, source specifications |
+| `workflows.md` | Development workflows, testing patterns, publishing guide |
+
+### Plugin Patterns
+
+- **Framework Plugin** - For framework-specific guidance (React, Vue, Nuxt)
+- **Utility Plugin** - For tools and command collections
+- **Domain Plugin** - For domain-specific knowledge with scripts
+
+### Component Support
+
+| Component | Location | Format |
+|-----------|----------|--------|
+| Commands | `commands/` | Markdown with frontmatter |
+| Skills | `skills//` | Directory with `SKILL.md` |
+| Agents | `agents/` | Markdown definitions |
+| Hooks | `hooks/hooks.json` | Event handlers |
+| MCP Servers | `.mcp.json` | External integrations |
+
+## Usage Examples
+
+### Create a New Plugin
+
+```bash
+python scripts/create_plugin.py my-awesome-plugin \
+ --marketplace-root /path/to/marketplace \
+ --author-name "Your Name" \
+ --author-email "you@example.com" \
+ --description "A plugin that does awesome things" \
+ --keywords "awesome,utility,productivity" \
+ --category "productivity"
+```
+
+This creates:
+```
+plugins/my-awesome-plugin/
+├── .claude-plugin/
+│ └── plugin.json
+├── commands/
+├── skills/
+└── README.md
+```
+
+### Bump Version
+
+```bash
+# Patch bump (bug fixes): 1.0.0 → 1.0.1
+python scripts/bump_version.py my-plugin patch --marketplace-root /path/to/marketplace
+
+# Minor bump (new features): 1.0.0 → 1.1.0
+python scripts/bump_version.py my-plugin minor --marketplace-root /path/to/marketplace
+
+# Major bump (breaking changes): 1.0.0 → 2.0.0
+python scripts/bump_version.py my-plugin major --marketplace-root /path/to/marketplace
+```
+
+### Local Testing
+
+```bash
+# Add your marketplace
+/plugin marketplace add /path/to/marketplace-root
+
+# Install the plugin
+/plugin install my-plugin@marketplace-name
+
+# After making changes, reinstall
+/plugin uninstall my-plugin@marketplace-name
+/plugin install my-plugin@marketplace-name
+```
+
+### Create Command with Namespace
+
+Create `commands/docs/generate.md` to get `/docs:generate` command:
+
+```markdown
+---
+description: Generate documentation for the current project
+---
+
+# Generate Documentation
+
+Instructions for the command...
+```
+
+## Prerequisites
+
+- **Python 3.10+** - Required for running automation scripts
+- **Existing Marketplace** - A marketplace with `.claude-plugin/marketplace.json` must exist before creating plugins
+- **Claude Code** - For testing and using plugins
+
+## Output
+
+### create_plugin.py Output
+
+```
+✅ Created plugin manifest: plugins/my-plugin/.claude-plugin/plugin.json
+✅ Created README: plugins/my-plugin/README.md
+✅ Updated marketplace manifest: .claude-plugin/marketplace.json
+
+🎉 Plugin 'my-plugin' created successfully!
+
+Next steps:
+1. Add commands to: plugins/my-plugin/commands
+2. Add skills to: plugins/my-plugin/skills
+3. Test with: /plugin install my-plugin@marketplace-name
+```
+
+### bump_version.py Output
+
+```
+✅ Updated plugin.json: 1.0.0 → 1.1.0
+✅ Updated marketplace.json: 1.0.0 → 1.1.0
+
+🎉 Version bumped successfully: 1.0.0 → 1.1.0
+```
+
+## Best Practices
+
+### Naming Conventions
+
+- **Plugin names**: Use `kebab-case` (e.g., `vue-components`, `api-testing`)
+- **Command files**: Use `kebab-case.md` (e.g., `generate-docs.md`)
+- **Command namespaces**: Use subdirectories for grouping (e.g., `commands/prime/vue.md` becomes `/prime:vue`)
+
+### Version Management
+
+- Always use semantic versioning
+- **Major (x.0.0)**: Breaking changes that require user action
+- **Minor (0.x.0)**: New features, significant refactoring
+- **Patch (0.0.x)**: Bug fixes, documentation updates
+- Always bump versions in both `plugin.json` and `marketplace.json` - use `bump_version.py` to automate this
+
+### Plugin Structure
+
+- Keep the plugin manifest in `.claude-plugin/plugin.json` (required location)
+- Place components at the plugin root, not inside `.claude-plugin/`
+- Use `${CLAUDE_PLUGIN_ROOT}` for dynamic path resolution in hooks and MCP configs
+
+### Git Commits
+
+Use conventional commits for clear history:
+```bash
+git commit -m "feat: add new plugin"
+git commit -m "fix: correct plugin manifest"
+git commit -m "docs: update plugin README"
+git commit -m "feat!: breaking change"
+```
+
+### Testing
+
+- Always test locally before publishing
+- Restart Claude Code after reinstalling to ensure changes take effect
+- Claude Code caches plugin files, so reinstallation is needed for updates
+
+## Plugin Directory Structure Reference
+
+```
+plugin-name/
+├── .claude-plugin/
+│ └── plugin.json # Required: Plugin metadata manifest
+├── commands/ # Optional: Custom slash commands
+│ ├── simple.md # → /simple
+│ └── namespace/
+│ └── action.md # → /namespace:action
+├── agents/ # Optional: Agent definitions
+├── skills/ # Optional: Agent Skills
+│ └── skill-name/
+│ ├── SKILL.md # Required for each skill
+│ ├── scripts/ # Optional: Executable code
+│ ├── references/ # Optional: Documentation
+│ └── assets/ # Optional: Output files
+├── hooks/ # Optional: Event handlers
+│ └── hooks.json
+├── .mcp.json # Optional: MCP server integrations
+└── README.md # Recommended: Plugin documentation
+```
+
+## Troubleshooting
+
+### Plugin directory already exists
+
+The `create_plugin.py` script will not overwrite existing plugins. Either:
+- Delete the existing directory if you want to start fresh
+- Manually update the existing plugin
+
+### Plugin not found in marketplace manifest
+
+When using `bump_version.py`, ensure:
+- The plugin name matches exactly (case-sensitive)
+- The plugin entry exists in `.claude-plugin/marketplace.json`
+
+### Changes not taking effect after reinstall
+
+Claude Code caches plugin files. After reinstalling:
+1. Restart Claude Code completely
+2. Verify the plugin is listed with `/plugin list`
+
+### Marketplace manifest not found
+
+Ensure you're running scripts from the correct directory or provide the full path with `--marketplace-root`.
diff --git a/dist/plugins/plugin-forge/skills/plugin-forge/SKILL.md b/dist/plugins/plugin-forge/skills/plugin-forge/SKILL.md
new file mode 100644
index 0000000..6b31439
--- /dev/null
+++ b/dist/plugins/plugin-forge/skills/plugin-forge/SKILL.md
@@ -0,0 +1,224 @@
+---
+name: plugin-forge
+description: Create and manage Claude Code plugins with proper structure, manifests, and marketplace integration. Use when creating plugins for a marketplace, adding plugin components (commands, agents, hooks), bumping plugin versions, or working with plugin.json/marketplace.json manifests.
+---
+
+# CC Plugin Forge
+
+## Purpose
+
+Build and manage Claude Code plugins with correct structure, manifests, and marketplace integration. Includes workflows, automation scripts, and reference docs.
+
+## When to Use
+
+- Creating new plugins for a marketplace
+- Adding/modifying plugin components (commands, skills, agents, hooks)
+- Updating plugin versions
+- Working with plugin or marketplace manifests
+- Setting up local plugin testing
+- Publishing plugins
+
+## Getting Started
+
+### Create New Plugin
+
+Use `create_plugin.py` to generate plugin structure:
+
+```bash
+python scripts/create_plugin.py plugin-name \
+ --marketplace-root /path/to/marketplace \
+ --author-name "Your Name" \
+ --author-email "your.email@example.com" \
+ --description "Plugin description" \
+ --keywords "keyword1,keyword2" \
+ --category "productivity"
+```
+
+This automatically:
+
+- Creates plugin directory structure
+- Generates `plugin.json` manifest
+- Creates README template
+- Updates `marketplace.json`
+
+### Bump Version
+
+Use `bump_version.py` to update versions in both manifests:
+
+```bash
+python scripts/bump_version.py plugin-name major|minor|patch \
+ --marketplace-root /path/to/marketplace
+```
+
+Semantic versioning:
+
+- **major**: Breaking changes (1.0.0 → 2.0.0)
+- **minor**: New features, refactoring (1.0.0 → 1.1.0)
+- **patch**: Bug fixes, docs (1.0.0 → 1.0.1)
+
+## Development Workflow
+
+### 1. Create Structure
+
+Manual approach (if not using script):
+
+```bash
+mkdir -p plugins/plugin-name/.claude-plugin
+mkdir -p plugins/plugin-name/commands
+mkdir -p plugins/plugin-name/skills
+```
+
+### 2. Plugin Manifest
+
+File: `plugins/plugin-name/.claude-plugin/plugin.json`
+
+```json
+{
+ "name": "plugin-name",
+ "version": "0.1.0",
+ "description": "Plugin description",
+ "author": {
+ "name": "Your Name",
+ "email": "your.email@example.com"
+ },
+ "keywords": ["keyword1", "keyword2"]
+}
+```
+
+### 3. Register in Marketplace
+
+Update `.claude-plugin/marketplace.json`:
+
+```json
+{
+ "name": "plugin-name",
+ "source": "./plugins/plugin-name",
+ "description": "Plugin description",
+ "version": "0.1.0",
+ "keywords": ["keyword1", "keyword2"],
+ "category": "productivity"
+}
+```
+
+### 4. Add Components
+
+Create in respective directories:
+
+| Component | Location | Format |
+|-----------|----------|--------|
+| Commands | `commands/` | Markdown with frontmatter |
+| Skills | `skills//` | Directory with `SKILL.md` |
+| Agents | `agents/` | Markdown definitions |
+| Hooks | `hooks/hooks.json` | Event handlers |
+| MCP Servers | `.mcp.json` | External integrations |
+
+### 5. Local Testing
+
+```bash
+# Add marketplace
+/plugin marketplace add /path/to/marketplace-root
+
+# Install plugin
+/plugin install plugin-name@marketplace-name
+
+# After changes: reinstall
+/plugin uninstall plugin-name@marketplace-name
+/plugin install plugin-name@marketplace-name
+```
+
+## Plugin Patterns
+
+### Framework Plugin
+
+For framework-specific guidance (React, Vue, etc.):
+
+```
+plugins/framework-name/
+├── .claude-plugin/plugin.json
+├── skills/
+│ └── framework-name/
+│ ├── SKILL.md
+│ └── references/
+├── commands/
+│ └── prime/
+│ ├── components.md
+│ └── framework.md
+└── README.md
+```
+
+### Utility Plugin
+
+For tools and commands:
+
+```
+plugins/utility-name/
+├── .claude-plugin/plugin.json
+├── commands/
+│ ├── action1.md
+│ └── action2.md
+└── README.md
+```
+
+### Domain Plugin
+
+For domain-specific knowledge:
+
+```
+plugins/domain-name/
+├── .claude-plugin/plugin.json
+├── skills/
+│ └── domain-name/
+│ ├── SKILL.md
+│ ├── references/
+│ └── scripts/
+└── README.md
+```
+
+## Command Naming
+
+Subdirectory-based namespacing with `:` separator:
+
+- `commands/namespace/command.md` → `/namespace:command`
+- `commands/simple.md` → `/simple`
+
+Examples:
+
+- `commands/prime/vue.md` → `/prime:vue`
+- `commands/docs/generate.md` → `/docs:generate`
+
+## Version Management
+
+**Important:** Update version in BOTH locations:
+
+1. `plugins//.claude-plugin/plugin.json`
+2. `.claude-plugin/marketplace.json`
+
+Use `bump_version.py` to automate.
+
+## Git Commits
+
+Use conventional commits:
+
+```bash
+git commit -m "feat: add new plugin"
+git commit -m "fix: correct plugin manifest"
+git commit -m "docs: update plugin README"
+git commit -m "feat!: breaking change"
+```
+
+## Reference Docs
+
+Detailed documentation included:
+
+| Reference | Content |
+|-----------|---------|
+| `references/plugin-structure.md` | Directory structure, manifest schema, components |
+| `references/marketplace-schema.md` | Marketplace format, plugin entries, distribution |
+| `references/workflows.md` | Step-by-step workflows, patterns, publishing |
+
+### Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/create_plugin.py` | Scaffold new plugin |
+| `scripts/bump_version.py` | Update versions |
diff --git a/dist/plugins/plugin-forge/skills/plugin-forge/references/marketplace-schema.md b/dist/plugins/plugin-forge/skills/plugin-forge/references/marketplace-schema.md
new file mode 100644
index 0000000..4a07292
--- /dev/null
+++ b/dist/plugins/plugin-forge/skills/plugin-forge/references/marketplace-schema.md
@@ -0,0 +1,132 @@
+# Marketplace Schema Reference
+
+## Marketplace Structure
+
+A marketplace is a JSON catalog enabling plugin discovery and distribution.
+
+**File location:** `.claude-plugin/marketplace.json`
+
+## Required Fields
+
+```json
+{
+ "name": "marketplace-identifier",
+ "owner": {
+ "name": "Maintainer Name",
+ "email": "maintainer@example.com"
+ },
+ "plugins": []
+}
+```
+
+**name**: Kebab-case marketplace identifier
+**owner**: Maintainer contact information
+**plugins**: Array of plugin entries
+
+## Optional Marketplace Fields
+
+**description**: Marketplace overview text
+**version**: Release version
+**pluginRoot**: Base path for relative plugin sources
+
+## Plugin Entry Schema
+
+Each plugin entry in the `plugins` array:
+
+**Required:**
+
+- `name`: Plugin identifier (kebab-case, must match plugin.json)
+- `source`: Plugin origin specification
+
+**Optional:**
+
+- `description`: Plugin purpose
+- `version`: Plugin version (semantic versioning)
+- `author`: Creator information
+- `homepage`: URL
+- `repository`: URL
+- `license`: SPDX identifier
+- `keywords`: Array of search terms
+- `category`: Classification (e.g., "framework", "productivity")
+- `tags`: Additional discovery tags
+- `commands`: Path to commands directory
+- `agents`: Path to agents directory
+- `hooks`: Path to hooks configuration
+- `mcpServers`: Path to MCP configuration
+
+## Source Specifications
+
+### Relative Path Source
+
+```json
+{
+ "name": "my-plugin",
+ "source": "./plugins/my-plugin"
+}
+```
+
+### GitHub Source
+
+```json
+{
+ "name": "my-plugin",
+ "source": {
+ "source": "github",
+ "repo": "owner/repo"
+ }
+}
+```
+
+### Generic Git Source
+
+```json
+{
+ "name": "my-plugin",
+ "source": {
+ "source": "url",
+ "url": "https://git.example.com/plugin.git"
+ }
+}
+```
+
+## Complete Example
+
+```json
+{
+ "name": "example-marketplace",
+ "description": "Example plugin marketplace",
+ "version": "1.0.0",
+ "owner": {
+ "name": "Marketplace Owner",
+ "email": "owner@example.com"
+ },
+ "pluginRoot": "./plugins",
+ "plugins": [
+ {
+ "name": "example-plugin",
+ "source": "./example-plugin",
+ "description": "Example plugin",
+ "version": "1.0.0",
+ "keywords": ["example"],
+ "category": "productivity"
+ }
+ ]
+}
+```
+
+## Team Distribution
+
+Configure automatic marketplace availability via `.claude/settings.json`:
+
+```json
+{
+ "extraKnownMarketplaces": [
+ {
+ "source": {
+ "source": "github",
+ "repo": "company/marketplace"
+ }
+ }
+ ]
+}
+```
diff --git a/dist/plugins/plugin-forge/skills/plugin-forge/references/plugin-structure.md b/dist/plugins/plugin-forge/skills/plugin-forge/references/plugin-structure.md
new file mode 100644
index 0000000..942bfe3
--- /dev/null
+++ b/dist/plugins/plugin-forge/skills/plugin-forge/references/plugin-structure.md
@@ -0,0 +1,103 @@
+# Plugin Structure Reference
+
+## Directory Hierarchy
+
+```
+plugin-name/
+├── .claude-plugin/
+│ └── plugin.json # Required: Plugin metadata manifest
+├── commands/ # Optional: Custom slash commands
+├── agents/ # Optional: Agent definitions
+├── skills/ # Optional: Agent Skills
+│ └── skill-name/
+│ ├── SKILL.md # Required for each skill
+│ ├── scripts/ # Optional: Executable code
+│ ├── references/ # Optional: Documentation
+│ └── assets/ # Optional: Output files
+├── hooks/ # Optional: Event handlers
+│ └── hooks.json
+└── .mcp.json # Optional: MCP server integrations
+```
+
+## Plugin Manifest (`plugin.json`)
+
+**Location:** `.claude-plugin/plugin.json` (must be in this directory)
+
+**Required fields:**
+
+- `name`: Unique identifier (kebab-case)
+
+**Standard metadata:**
+
+- `version`: Semantic versioning (e.g., "1.0.0")
+- `description`: Plugin purpose
+- `author`: Object with name, email, url
+- `homepage`: URL
+- `repository`: URL
+- `license`: SPDX identifier
+- `keywords`: Array of search terms
+
+**Component paths (optional):**
+
+- `commands`: Path to commands directory
+- `agents`: Path to agents directory
+- `hooks`: Path to hooks configuration
+- `mcpServers`: Path to MCP configuration
+
+### Example plugin.json
+
+```json
+{
+ "name": "example-plugin",
+ "version": "1.0.0",
+ "description": "Example plugin for demonstration",
+ "author": {
+ "name": "Plugin Creator",
+ "email": "creator@example.com"
+ },
+ "keywords": ["example", "demo"]
+}
+```
+
+## Component Types
+
+### Commands
+
+**Location:** `commands/` directory
+**Format:** Markdown files with frontmatter
+**Naming:** Subdirectories create namespaces via `:`
+
+```
+commands/
+├── simple.md # Invoked as /simple
+└── namespace/
+ └── command.md # Invoked as /namespace:command
+```
+
+### Agents
+
+**Location:** `agents/` directory
+**Format:** Markdown files describing agent capabilities
+
+### Skills
+
+**Location:** `skills/` directory
+**Format:** Subdirectories with `SKILL.md` file
+**Structure:** See skills documentation
+
+### Hooks
+
+**Location:** `hooks/hooks.json` or path specified in manifest
+**Events:** PreToolUse, PostToolUse, UserPromptSubmit, Notification, Stop, SubagentStop, SessionStart, SessionEnd, PreCompact
+
+### MCP Servers
+
+**Location:** `.mcp.json` at plugin root
+**Purpose:** External tool integrations
+
+## Path Requirements
+
+- All paths relative to plugin root
+- Start with `./` for custom paths
+- Use `${CLAUDE_PLUGIN_ROOT}` for dynamic resolution in hooks/MCP
+- Components must be at plugin root, not inside `.claude-plugin/`
diff --git a/dist/plugins/plugin-forge/skills/plugin-forge/references/workflows.md b/dist/plugins/plugin-forge/skills/plugin-forge/references/workflows.md
new file mode 100644
index 0000000..27f14f0
--- /dev/null
+++ b/dist/plugins/plugin-forge/skills/plugin-forge/references/workflows.md
@@ -0,0 +1,191 @@
+# Plugin Development Workflows
+
+## Creating a New Plugin
+
+### 1. Create Plugin Directory Structure
+
+```bash
+mkdir -p plugins/plugin-name/.claude-plugin
+mkdir -p plugins/plugin-name/commands
+mkdir -p plugins/plugin-name/skills
+```
+
+### 2. Create Plugin Manifest
+
+Create `plugins/plugin-name/.claude-plugin/plugin.json`:
+
+```json
+{
+ "name": "plugin-name",
+ "version": "0.1.0",
+ "description": "Plugin description",
+ "author": {
+ "name": "Your Name",
+ "email": "your.email@example.com"
+ },
+ "keywords": ["keyword1", "keyword2"]
+}
+```
+
+### 3. Add Plugin to Marketplace
+
+Update `.claude-plugin/marketplace.json` by adding entry to `plugins` array:
+
+```json
+{
+ "name": "plugin-name",
+ "source": "./plugins/plugin-name",
+ "description": "Plugin description",
+ "version": "0.1.0",
+ "keywords": ["keyword1", "keyword2"],
+ "category": "productivity"
+}
+```
+
+### 4. Add Plugin Components
+
+Create commands, skills, agents, or hooks as needed in their respective directories.
+
+## Version Bumping
+
+When making changes to a plugin, update version in **both** locations:
+
+1. `plugins//.claude-plugin/plugin.json`
+2. `.claude-plugin/marketplace.json` (matching plugin entry)
+
+**Semantic versioning:**
+
+- **Major (x.0.0)**: Breaking changes
+- **Minor (0.x.0)**: New features, refactoring
+- **Patch (0.0.x)**: Bug fixes, documentation only
+
+## Local Testing Workflow
+
+### Initial Setup
+
+```bash
+# Add marketplace
+/plugin marketplace add /path/to/marketplace-root
+
+# Install plugin
+/plugin install plugin-name@marketplace-name
+```
+
+### Iterative Testing
+
+After making changes to a plugin:
+
+```bash
+# Uninstall
+/plugin uninstall plugin-name@marketplace-name
+
+# Reinstall
+/plugin install plugin-name@marketplace-name
+
+# Restart Claude Code to load changes
+```
+
+**Note:** Claude Code caches plugin files, so restart may be required for changes to take effect.
+
+## Publishing Workflow
+
+### 1. Commit Changes
+
+Use conventional commits:
+
+```bash
+git add .
+git commit -m "feat: add new plugin"
+git commit -m "fix: correct plugin manifest"
+git commit -m "docs: update plugin README"
+```
+
+### 2. Push to Repository
+
+```bash
+git push origin main
+```
+
+### 3. Distribution
+
+**GitHub-hosted marketplace:**
+
+Users add via:
+
+```bash
+/plugin marketplace add owner/repo
+/plugin install plugin-name@marketplace-name
+```
+
+**Local marketplace:**
+
+Users add via absolute path:
+
+```bash
+/plugin marketplace add /path/to/marketplace
+```
+
+## Command Naming Convention
+
+Commands use subdirectory-based namespacing:
+
+- File: `commands/namespace/command.md`
+- Invoked as: `/namespace:command`
+- The `:` represents directory separator `/`
+
+**Examples:**
+
+- `commands/prime/vue.md` → `/prime:vue`
+- `commands/docs/generate.md` → `/docs:generate`
+- `commands/simple.md` → `/simple`
+
+## Common Plugin Patterns
+
+### Framework Plugin
+
+Structure for framework-specific guidance (React, Vue, Nuxt, etc.):
+
+```
+plugins/framework-name/
+├── .claude-plugin/plugin.json
+├── skills/
+│ └── framework-name/
+│ ├── SKILL.md # Quick reference
+│ └── references/ # Library-specific patterns
+├── commands/
+│ └── prime/ # Namespace for loading patterns
+│ ├── components.md
+│ └── framework.md
+└── README.md
+```
+
+### Utility Plugin
+
+Structure for tools and utilities:
+
+```
+plugins/utility-name/
+├── .claude-plugin/plugin.json
+├── commands/
+│ ├── action1.md
+│ └── action2.md
+└── README.md
+```
+
+### Domain Plugin
+
+Structure for domain-specific knowledge:
+
+```
+plugins/domain-name/
+├── .claude-plugin/plugin.json
+├── skills/
+│ └── domain-name/
+│ ├── SKILL.md
+│ ├── references/
+│ │ ├── schema.md
+│ │ └── policies.md
+│ └── scripts/
+│ └── automation.py
+└── README.md
+```
diff --git a/dist/plugins/plugin-forge/skills/plugin-forge/scripts/bump_version.py b/dist/plugins/plugin-forge/skills/plugin-forge/scripts/bump_version.py
new file mode 100755
index 0000000..d04e520
--- /dev/null
+++ b/dist/plugins/plugin-forge/skills/plugin-forge/scripts/bump_version.py
@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+"""
+Bump plugin version in both plugin.json and marketplace.json.
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Literal
+
+
+VersionPart = Literal["major", "minor", "patch"]
+
+
+def parse_version(version: str) -> tuple[int, int, int]:
+ """Parse semantic version string into tuple."""
+ try:
+ parts = version.split(".")
+ return int(parts[0]), int(parts[1]), int(parts[2])
+ except (ValueError, IndexError):
+ print(f"❌ Invalid version format: {version}")
+ sys.exit(1)
+
+
+def bump_version(version: str, part: VersionPart) -> str:
+ """Bump semantic version."""
+ major, minor, patch = parse_version(version)
+
+ if part == "major":
+ return f"{major + 1}.0.0"
+ elif part == "minor":
+ return f"{major}.{minor + 1}.0"
+ elif part == "patch":
+ return f"{major}.{minor}.{patch + 1}"
+ else:
+ print(f"❌ Invalid version part: {part}")
+ sys.exit(1)
+
+
+def update_plugin_version(plugin_name: str, marketplace_root: Path, part: VersionPart) -> None:
+ """Update version in both plugin.json and marketplace.json."""
+
+ # Update plugin.json
+ plugin_json_path = marketplace_root / "plugins" / plugin_name / ".claude-plugin" / "plugin.json"
+
+ if not plugin_json_path.exists():
+ print(f"❌ Plugin manifest not found: {plugin_json_path}")
+ sys.exit(1)
+
+ with open(plugin_json_path, "r") as f:
+ plugin_data = json.load(f)
+
+ old_version = plugin_data.get("version", "0.0.0")
+ new_version = bump_version(old_version, part)
+ plugin_data["version"] = new_version
+
+ with open(plugin_json_path, "w") as f:
+ json.dump(plugin_data, f, indent=2)
+
+ print(f"✅ Updated plugin.json: {old_version} → {new_version}")
+
+ # Update marketplace.json
+ marketplace_json_path = marketplace_root / ".claude-plugin" / "marketplace.json"
+
+ if not marketplace_json_path.exists():
+ print(f"❌ Marketplace manifest not found: {marketplace_json_path}")
+ sys.exit(1)
+
+ with open(marketplace_json_path, "r") as f:
+ marketplace_data = json.load(f)
+
+ plugin_found = False
+ for plugin in marketplace_data.get("plugins", []):
+ if plugin.get("name") == plugin_name:
+ plugin["version"] = new_version
+ plugin_found = True
+ break
+
+ if not plugin_found:
+ print(f"❌ Plugin '{plugin_name}' not found in marketplace manifest")
+ sys.exit(1)
+
+ with open(marketplace_json_path, "w") as f:
+ json.dump(marketplace_data, f, indent=2)
+
+ print(f"✅ Updated marketplace.json: {old_version} → {new_version}")
+ print(f"\n🎉 Version bumped successfully: {old_version} → {new_version}")
+
+
+def main():
+ parser = argparse.ArgumentParser(description="Bump plugin version")
+ parser.add_argument("plugin_name", help="Plugin name")
+ parser.add_argument("part", choices=["major", "minor", "patch"], help="Version part to bump")
+ parser.add_argument("--marketplace-root", default=".", help="Path to marketplace root directory")
+
+ args = parser.parse_args()
+
+ marketplace_root = Path(args.marketplace_root).resolve()
+
+ update_plugin_version(
+ plugin_name=args.plugin_name,
+ marketplace_root=marketplace_root,
+ part=args.part
+ )
+
+
+if __name__ == "__main__":
+ main()
diff --git a/dist/plugins/plugin-forge/skills/plugin-forge/scripts/create_plugin.py b/dist/plugins/plugin-forge/skills/plugin-forge/scripts/create_plugin.py
new file mode 100755
index 0000000..3cb309a
--- /dev/null
+++ b/dist/plugins/plugin-forge/skills/plugin-forge/scripts/create_plugin.py
@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""
+Create a new Claude Code plugin with proper directory structure and manifests.
+"""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def create_plugin_structure(plugin_name: str, marketplace_root: Path, author_name: str, author_email: str, description: str, keywords: list[str], category: str = "productivity") -> None:
+ """Create complete plugin directory structure with manifests."""
+
+ # Create plugin directory
+ plugin_dir = marketplace_root / "plugins" / plugin_name
+ if plugin_dir.exists():
+ print(f"❌ Plugin directory already exists: {plugin_dir}")
+ sys.exit(1)
+
+ # Create directory structure
+ plugin_config_dir = plugin_dir / ".claude-plugin"
+ commands_dir = plugin_dir / "commands"
+ skills_dir = plugin_dir / "skills"
+
+ plugin_config_dir.mkdir(parents=True, exist_ok=True)
+ commands_dir.mkdir(parents=True, exist_ok=True)
+ skills_dir.mkdir(parents=True, exist_ok=True)
+
+ # Create plugin.json
+ plugin_manifest = {
+ "name": plugin_name,
+ "version": "0.1.0",
+ "description": description,
+ "author": {
+ "name": author_name,
+ "email": author_email
+ },
+ "keywords": keywords
+ }
+
+ plugin_json_path = plugin_config_dir / "plugin.json"
+ with open(plugin_json_path, "w") as f:
+ json.dump(plugin_manifest, f, indent=2)
+
+ print(f"✅ Created plugin manifest: {plugin_json_path}")
+
+ # Create README.md
+ readme_content = f"""# {plugin_name}
+
+{description}
+
+## Installation
+
+```bash
+/plugin marketplace add
+/plugin install {plugin_name}@
+```
+
+## Features
+
+- TODO: List features here
+
+## Usage
+
+TODO: Add usage examples
+
+## Development
+
+See [workflows.md](../../CLAUDE.md) for development guidelines.
+"""
+
+ readme_path = plugin_dir / "README.md"
+ with open(readme_path, "w") as f:
+ f.write(readme_content)
+
+ print(f"✅ Created README: {readme_path}")
+
+ # Update marketplace.json
+ marketplace_json_path = marketplace_root / ".claude-plugin" / "marketplace.json"
+
+ if not marketplace_json_path.exists():
+ print(f"❌ Marketplace manifest not found: {marketplace_json_path}")
+ sys.exit(1)
+
+ with open(marketplace_json_path, "r") as f:
+ marketplace_data = json.load(f)
+
+ # Check if plugin already exists in marketplace
+ for plugin in marketplace_data.get("plugins", []):
+ if plugin.get("name") == plugin_name:
+ print(f"❌ Plugin '{plugin_name}' already exists in marketplace manifest")
+ sys.exit(1)
+
+ # Add plugin entry
+ plugin_entry = {
+ "name": plugin_name,
+ "source": f"./plugins/{plugin_name}",
+ "description": description,
+ "version": "0.1.0",
+ "keywords": keywords,
+ "category": category
+ }
+
+ if "plugins" not in marketplace_data:
+ marketplace_data["plugins"] = []
+
+ marketplace_data["plugins"].append(plugin_entry)
+
+ with open(marketplace_json_path, "w") as f:
+ json.dump(marketplace_data, f, indent=2)
+
+ print(f"✅ Updated marketplace manifest: {marketplace_json_path}")
+
+ print(f"\n🎉 Plugin '{plugin_name}' created successfully!")
+ print(f"\nNext steps:")
+ print(f"1. Add commands to: {commands_dir}")
+ print(f"2. Add skills to: {skills_dir}")
+ print(f"3. Test with: /plugin install {plugin_name}@marketplace-name")
+
+
+def main():
+ parser = argparse.ArgumentParser(description="Create a new Claude Code plugin")
+ parser.add_argument("plugin_name", help="Plugin name (kebab-case)")
+ parser.add_argument("--marketplace-root", default=".", help="Path to marketplace root directory")
+ parser.add_argument("--author-name", required=True, help="Plugin author name")
+ parser.add_argument("--author-email", required=True, help="Plugin author email")
+ parser.add_argument("--description", required=True, help="Plugin description")
+ parser.add_argument("--keywords", required=True, help="Comma-separated keywords")
+ parser.add_argument("--category", default="productivity", help="Plugin category (default: productivity)")
+
+ args = parser.parse_args()
+
+ marketplace_root = Path(args.marketplace_root).resolve()
+ keywords = [k.strip() for k in args.keywords.split(",")]
+
+ create_plugin_structure(
+ plugin_name=args.plugin_name,
+ marketplace_root=marketplace_root,
+ author_name=args.author_name,
+ author_email=args.author_email,
+ description=args.description,
+ keywords=keywords,
+ category=args.category
+ )
+
+
+if __name__ == "__main__":
+ main()
diff --git a/dist/plugins/professional-communication/skills/professional-communication/README.md b/dist/plugins/professional-communication/skills/professional-communication/README.md
new file mode 100644
index 0000000..4b74368
--- /dev/null
+++ b/dist/plugins/professional-communication/skills/professional-communication/README.md
@@ -0,0 +1,216 @@
+# Professional Communication
+
+A comprehensive guide for effective professional communication in software development contexts, covering email structure, team messaging etiquette, meeting communications, and adapting messages for different audiences.
+
+## Purpose
+
+This skill provides frameworks and best practices for clear, professional written communication. It helps software developers improve their communication effectiveness across emails, team chats, meetings, and cross-functional interactions.
+
+**Core principle:** Effective communication isn't about proving how much you know - it's about ensuring your message is received and understood.
+
+## When to Use This Skill
+
+Use this skill when you need help with:
+
+- **Email composition** - Writing professional emails to teammates, managers, or stakeholders
+- **Team messaging** - Crafting effective Slack/Teams/Discord messages
+- **Meeting preparation** - Preparing agendas, summaries, and talking points
+- **Audience adaptation** - Translating technical concepts for non-technical audiences
+- **Status updates** - Structuring progress reports and project communications
+- **Communication improvement** - Enhancing clarity and professionalism of written messages
+
+**Trigger keywords**: email, chat, teams, slack, discord, message, writing, communication, meeting, agenda, status update, report
+
+## How It Works
+
+The skill is organized around several core frameworks:
+
+### 1. The What-Why-How Structure
+A universal framework for organizing any professional message:
+- **What** - State the topic/request clearly
+- **Why** - Explain the reasoning
+- **How** - Outline next steps/action items
+
+### 2. Three Golden Rules
+1. Start with a clear subject/purpose
+2. Use bullets, headlines, and scannable formatting
+3. Put key messages first
+
+### 3. Audience Calibration
+Before communicating, consider:
+- Who is the audience?
+- What level of detail do they need?
+- What's the value for them?
+
+## Key Features
+
+### Email Best Practices
+- Subject line formulas
+- Structured email templates
+- Common email types (status update, request, escalation, FYI)
+- Email vs chat decision framework
+
+### Team Messaging Etiquette
+- When to use chat vs email
+- Thread management and @mention guidelines
+- The "No Hello" principle for async communication
+- Channel organization best practices
+
+### Technical vs Non-Technical Communication
+- Audience-specific approaches
+- Jargon translation strategies
+- Simplification without losing accuracy
+- Plain language examples
+
+### Writing Clarity Principles
+- Active vs passive voice
+- Eliminating filler words
+- The "So What?" test
+- Professional tone guidelines
+
+### Meeting Communication
+- Agenda best practices
+- Facilitation tips
+- Meeting summary format
+- Action item tracking
+
+## Usage Examples
+
+### Example 1: Writing a Status Update Email
+
+**Before (ineffective):**
+```
+Subject: Updates
+
+Hey everyone, just wanted to give you an update on the project. We've been
+working on a lot of things and making progress. There are some issues but
+we're handling them. Let me know if you have questions.
+```
+
+**After (using frameworks from this skill):**
+```
+Subject: Project X: Week 12 Status Update - On Track with Minor Delay
+
+Hi team,
+
+We're on track for the Q1 release with a minor 1-week delay due to a critical bug.
+
+**Progress This Week:**
+- Completed authentication module (100%)
+- API integration at 80% (was 60%)
+- Found critical bug in payment processing
+
+**Blockers:**
+- Payment bug requires full regression testing
+- Waiting on design approval for checkout flow
+
+**Next Steps:**
+- QA will complete retest by Thursday
+- I'll update stakeholders Friday with revised timeline
+- Design review scheduled for Monday
+
+New target date: March 15 (was March 8)
+
+Best,
+[Your name]
+```
+
+### Example 2: Team Chat Message
+
+**Before (ineffective):**
+```
+Hey
+Are you there?
+Can I ask you something?
+```
+
+**After (using "No Hello" principle):**
+```
+Hi Sarah - quick question about the deployment script.
+
+Getting a permission error on line 42 when running deploy.sh:
+`Error: Permission denied for /var/www/app`
+
+Have you seen this before? I checked file permissions and they look correct.
+```
+
+### Example 3: Technical to Non-Technical Translation
+
+**Before (too technical):**
+```
+We're implementing a microservices architecture with asynchronous message
+processing via a Kafka event bus to enable horizontal scalability.
+```
+
+**After (accessible):**
+```
+We're splitting our system into smaller, independent pieces that communicate
+through messages. This means:
+- Each part can be updated without affecting the others
+- We can easily add more resources to handle increased traffic
+- The system processes tasks in the background for better performance
+```
+
+### Example 4: Meeting Agenda
+
+**Before (vague):**
+```
+Meeting: Project Discussion
+Time: Tuesday 2pm
+Please attend.
+```
+
+**After (structured):**
+```
+Meeting: Project X Architecture Review
+Time: Tuesday 2pm-3pm
+
+**Objective:** Decide on database architecture for user data scaling
+
+**Agenda:**
+1. Review current limitations (10 min)
+2. Present three scaling options (20 min)
+3. Discuss tradeoffs (20 min)
+4. Make decision (10 min)
+
+**Preparation Required:**
+- Review the architecture doc sent Monday (link)
+- Come prepared with questions/concerns
+
+**Expected Outcome:** Decision on which architecture to implement
+```
+
+## Additional Resources
+
+This skill includes supporting reference documents:
+
+- `references/email-templates.md` - Ready-to-use email templates by type
+- `references/meeting-structures.md` - Structures for standups, retros, reviews
+- `references/jargon-simplification.md` - Technical-to-plain-language translations
+
+## Quick Reference Checklist
+
+Before sending any professional communication, verify:
+
+- [ ] Clear purpose - Can recipient understand intent in 5 seconds?
+- [ ] Right audience - Is this the appropriate person/channel?
+- [ ] Key message first - Is the main point upfront?
+- [ ] Scannable - Are there bullets, headers, short paragraphs?
+- [ ] Action clear - Does recipient know what they need to do?
+- [ ] Jargon check - Will the audience understand terminology?
+- [ ] Tone appropriate - Is it professional but not cold?
+- [ ] Proofread - Any typos or unclear phrasing?
+
+## Companion Skills
+
+- `feedback-mastery` - For difficult conversations and feedback delivery
+- `/draft-email` - Generate emails using these frameworks
+
+## Version
+
+- **v1.0.0** (2025-12-26) - Initial release
+- Last Updated: 2025-12-22
+
+---
+
+**Note:** While this skill is designed for software developers, the frameworks and principles apply to professional communication in any field.
diff --git a/dist/plugins/professional-communication/skills/professional-communication/SKILL.md b/dist/plugins/professional-communication/skills/professional-communication/SKILL.md
new file mode 100644
index 0000000..d8b50a2
--- /dev/null
+++ b/dist/plugins/professional-communication/skills/professional-communication/SKILL.md
@@ -0,0 +1,267 @@
+---
+name: professional-communication
+description: Guide technical communication for software developers. Covers email structure, team messaging etiquette, meeting agendas, and adapting messages for technical vs non-technical audiences. Use when drafting professional messages, preparing meeting communications, or improving written communication.
+allowed-tools: Read, Glob, Grep
+---
+
+# Professional Communication
+
+## Overview
+
+This skill provides frameworks and guidance for effective professional communication in software development contexts. Whether you're writing an email to stakeholders, crafting a team chat message, or preparing meeting agendas, these principles help you communicate clearly and build professional credibility.
+
+**Core principle:** Effective communication isn't about proving how much you know - it's about ensuring your message is received and understood.
+
+## When to Use This Skill
+
+Use this skill when:
+
+- Writing emails to teammates, managers, or stakeholders
+- Crafting team chat messages or async communications
+- Preparing meeting agendas or summaries
+- Translating technical concepts for non-technical audiences
+- Structuring status updates or reports
+- Improving clarity of written communication
+
+**Keywords**: email, chat, teams, slack, discord, message, writing, communication, meeting, agenda, status update, report
+
+## Core Frameworks
+
+### The What-Why-How Structure
+
+Use this universal framework to organize any professional message:
+
+| Component | Purpose | Example |
+| --- | --- | --- |
+| **What** | State the topic/request clearly | "We need to delay the release by one week" |
+| **Why** | Explain the reasoning | "Critical bug found in payment processing" |
+| **How** | Outline next steps/action items | "QA will retest by Thursday; I'll update stakeholders Friday" |
+
+**Apply to**: Emails, status updates, meeting talking points, technical explanations
+
+### Three Golden Rules for Written Communication
+
+1. **Start with a clear subject/purpose** - Recipients should immediately grasp what your message is about
+2. **Use bullets, headlines, and scannable formatting** - Nobody wants a wall of text
+3. **Key messages first** - Busy people appreciate efficiency; state your main point upfront
+
+### Audience Calibration
+
+Before communicating, ask yourself:
+
+1. **Who** are you writing to? (Technical peers, managers, stakeholders, customers)
+2. **What level of detail** do they need? (High-level overview vs implementation details)
+3. **What's the value** for them? (How does this affect their work/decisions?)
+
+## Email Best Practices
+
+### Subject Line Formula
+
+| Instead of | Try |
+| --- | --- |
+| "Project updates" | "Project X: Status Update and Next Steps" |
+| "Question" | "Quick question: API rate limiting approach" |
+| "FYI" | "FYI: Deployment scheduled for Tuesday 3pm" |
+
+### Email Structure Template
+
+```markdown
+**Subject:** [Project/Topic]: [Specific Purpose]
+
+Hi [Name],
+
+[1-2 sentences stating the key point or request upfront]
+
+**Context/Background:**
+- [Bullet point 1]
+- [Bullet point 2]
+
+**What I need from you:**
+- [Specific action or decision needed]
+- [Timeline if applicable]
+
+[Optional: Brief next steps or follow-up plan]
+
+Best,
+[Your name]
+```
+
+### Common Email Types
+
+| Type | Key Elements |
+| --- | --- |
+| **Status Update** | Progress summary, blockers, next steps, timeline |
+| **Request** | Clear ask, context, deadline, why it matters |
+| **Escalation** | Issue summary, impact, attempted solutions, needed decision |
+| **FYI/Announcement** | What changed, who's affected, any required action |
+
+**For templates**: See `references/email-templates.md`
+
+## Team Messaging Etiquette
+
+> **Note:** Examples use Slack terminology, but these principles apply equally to Microsoft Teams, Discord, or any team messaging platform.
+
+### When to Use Chat vs Email
+
+| Use Chat | Use Email |
+| --- | --- |
+| Quick questions with short answers | Detailed documentation needing records |
+| Real-time coordination | Formal communications to stakeholders |
+| Informal team discussions | Messages requiring careful review |
+| Time-sensitive updates | Complex explanations with multiple parts |
+
+### Team Messaging Best Practices
+
+1. **Use threads** - Keep main channels scannable; follow-ups go in threads
+2. **@mention thoughtfully** - Don't notify people unnecessarily
+3. **Channel organization** - Right channel for right topic
+4. **Be direct** - "Can you review my PR?" beats "Hey, are you busy?"
+5. **Async-friendly** - Write messages that don't require immediate response
+
+### The "No Hello" Principle
+
+Instead of:
+
+```text
+You: Hi
+You: Are you there?
+You: Can I ask you something?
+[waiting...]
+```
+
+Try:
+
+```text
+You: Hi Sarah - quick question about the deployment script.
+ Getting a permission error on line 42. Have you seen this before?
+ Here's the error: [paste error]
+```
+
+## Technical vs Non-Technical Communication
+
+### When to Be Technical vs Accessible
+
+| Audience | Approach |
+| --- | --- |
+| **Engineering peers** | Technical details, code examples, architecture specifics |
+| **Technical managers** | Balance of detail and high-level impact |
+| **Non-technical stakeholders** | Business impact, analogies, outcomes over implementation |
+| **Customers** | Plain language, what it means for them, avoid jargon |
+
+### Three Strategies for Simplification
+
+1. **Start with the big picture before details** - People process "why" before "how"
+2. **Simplify without losing accuracy** - Use analogies; replace jargon with plain language
+3. **Know when to switch** - Read the room; adjust based on questions and engagement
+
+### Jargon Translation Examples
+
+| Technical | Plain Language |
+| --- | --- |
+| "Microservices architecture" | "Our system is split into smaller, independent pieces that can scale separately" |
+| "Asynchronous message processing" | "Tasks are queued and processed in the background" |
+| "CI/CD pipeline" | "Automated process that tests and deploys our code" |
+| "Database migration" | "Updating how our data is organized and stored" |
+
+**For more examples**: See `references/jargon-simplification.md`
+
+## Writing Clarity Principles
+
+### Active Voice Over Passive Voice
+
+Active voice is clearer, more direct, and conveys authority:
+
+| Passive (avoid) | Active (prefer) |
+| --- | --- |
+| "A bug was identified by the team" | "The team identified a bug" |
+| "The feature will be implemented" | "We will implement the feature" |
+| "Errors were found during testing" | "Testing revealed errors" |
+
+### Eliminate Filler Words
+
+| Instead of | Use |
+| --- | --- |
+| "At this point in time" | "Now" |
+| "In the event that" | "If" |
+| "Due to the fact that" | "Because" |
+| "In order to" | "To" |
+| "I just wanted to check if" | "Can you" |
+
+### The "So What?" Test
+
+After writing, ask: "So what? Why does this matter to the reader?"
+
+If you can't answer clearly, restructure your message to lead with the value/impact.
+
+## Meeting Communication
+
+### Before: Agenda Best Practices
+
+Every meeting invite should include:
+
+1. **Clear objective** - What will be accomplished?
+2. **Agenda items** - Topics to cover with time estimates
+3. **Preparation required** - What should attendees bring/review?
+4. **Expected outcome** - Decision needed? Information sharing? Brainstorm?
+
+### During: Facilitation Tips
+
+- **Time-box discussions** - "Let's spend 5 minutes on this, then move on"
+- **Capture action items live** - Who does what by when
+- **Parking lot** - Note off-topic items for later
+
+### After: Summary Format
+
+```markdown
+**Meeting: [Topic] - [Date]**
+
+**Attendees:** [Names]
+
+**Key Decisions:**
+- [Decision 1]
+- [Decision 2]
+
+**Action Items:**
+- [ ] [Person]: [Task] - Due [Date]
+- [ ] [Person]: [Task] - Due [Date]
+
+**Next Steps:**
+- [Follow-up meeting if needed]
+- [Documents to share]
+```
+
+**For structures by meeting type**: See `references/meeting-structures.md`
+
+## Quick Reference: Communication Checklist
+
+Before sending any professional communication:
+
+- [ ] **Clear purpose** - Can the recipient understand intent in 5 seconds?
+- [ ] **Right audience** - Is this the appropriate person/channel?
+- [ ] **Key message first** - Is the main point upfront?
+- [ ] **Scannable** - Are there bullets, headers, short paragraphs?
+- [ ] **Action clear** - Does the recipient know what (if anything) they need to do?
+- [ ] **Jargon check** - Will the audience understand all terminology?
+- [ ] **Tone appropriate** - Is it professional but not cold?
+- [ ] **Proofread** - Any typos or unclear phrasing?
+
+## Additional Tools
+
+- `references/email-templates.md` - Ready-to-use email templates by type
+- `references/meeting-structures.md` - Structures for standups, retros, reviews
+- `references/jargon-simplification.md` - Technical-to-plain-language translations
+
+## Companion Skills
+
+- `feedback-mastery` - For difficult conversations and feedback delivery
+- `/draft-email` - Generate emails using these frameworks
+
+---
+
+**Last Updated:** 2025-12-22
+
+## Version History
+
+- **v1.0.0** (2025-12-26): Initial release
+
+---
diff --git a/dist/plugins/professional-communication/skills/professional-communication/references/email-templates.md b/dist/plugins/professional-communication/skills/professional-communication/references/email-templates.md
new file mode 100644
index 0000000..d851f55
--- /dev/null
+++ b/dist/plugins/professional-communication/skills/professional-communication/references/email-templates.md
@@ -0,0 +1,281 @@
+# Email Templates for Developers
+
+Ready-to-use email templates for common software development scenarios. Adapt the tone and detail level to your audience.
+
+## Status Update Email
+
+```markdown
+Subject: [Project Name]: Week [N] Status Update
+
+Hi [Team/Name],
+
+**Summary:** [One sentence on overall progress and key highlight]
+
+**Completed This Week:**
+- [Feature/task completed with brief outcome]
+- [Feature/task completed with brief outcome]
+
+**In Progress:**
+- [Current work item] - Expected completion: [Date]
+- [Current work item] - Expected completion: [Date]
+
+**Blockers/Risks:**
+- [Blocker description] - Need: [What you need to unblock]
+
+**Next Week:**
+- [Planned work items]
+
+Let me know if you have questions or need more detail on anything.
+
+Best,
+[Your name]
+```
+
+## Sprint Retrospective Summary
+
+```markdown
+Subject: Sprint [N] Retrospective Summary
+
+Hi Team,
+
+Thanks for a productive retrospective. Here's a summary of what we discussed:
+
+**What Went Well:**
+- [Positive item 1]
+- [Positive item 2]
+
+**What Could Improve:**
+- [Improvement area 1]
+- [Improvement area 2]
+
+**Action Items:**
+- [ ] [Person]: [Action] - Due: [Date]
+- [ ] [Person]: [Action] - Due: [Date]
+
+We'll revisit these in next sprint's retro. Thanks everyone!
+
+Best,
+[Your name]
+```
+
+## Request for Review/Feedback
+
+```markdown
+Subject: Review Request: [Document/PR/Design Name]
+
+Hi [Name],
+
+I'd appreciate your feedback on [document/PR/design] when you have a chance.
+
+**What it is:** [Brief description]
+
+**Link:** [URL]
+
+**What I'm looking for:**
+- [Specific feedback area 1]
+- [Specific feedback area 2]
+
+**Timeline:** [When you need feedback by, or "no rush"]
+
+Happy to walk through it together if that would help. Thanks!
+
+Best,
+[Your name]
+```
+
+## Escalation Email
+
+```markdown
+Subject: [URGENT if applicable] Escalation: [Issue Summary]
+
+Hi [Manager/Leadership],
+
+I'm escalating [issue] because [reason it needs escalation].
+
+**Issue Summary:**
+[1-2 sentences describing the problem]
+
+**Impact:**
+- [Business/technical impact]
+- [Timeline/deadline affected]
+- [Users/customers affected]
+
+**What We've Tried:**
+- [Attempted solution 1]
+- [Attempted solution 2]
+
+**Decision/Help Needed:**
+[Specific decision or support you need]
+
+**Recommended Next Steps:**
+- [Your recommended approach]
+
+I'm available to discuss further. Please let me know how you'd like to proceed.
+
+Best,
+[Your name]
+```
+
+## FYI/Announcement Email
+
+```markdown
+Subject: FYI: [What Changed/Happening]
+
+Hi [Team/Name],
+
+Quick heads up: [One sentence summary of what changed or is happening]
+
+**Details:**
+- [Key detail 1]
+- [Key detail 2]
+
+**Impact on You:**
+- [How this affects the recipient, if at all]
+
+**Action Needed:** [None / Specific action]
+
+Let me know if you have questions.
+
+Best,
+[Your name]
+```
+
+## Meeting Request Email
+
+```markdown
+Subject: Meeting Request: [Topic] - [Proposed Time Range]
+
+Hi [Name],
+
+I'd like to schedule a meeting to discuss [topic].
+
+**Purpose:** [What we need to accomplish]
+
+**Duration:** [Time estimate]
+
+**Proposed Times:**
+- [Option 1]
+- [Option 2]
+
+**Preparation:** [None needed / What to review beforehand]
+
+Let me know what works for you, or feel free to grab time on my calendar.
+
+Best,
+[Your name]
+```
+
+## Technical Decision Request
+
+```markdown
+Subject: Decision Needed: [Technical Choice]
+
+Hi [Decision Maker],
+
+We need a decision on [technical choice] for [project/feature].
+
+**Context:**
+[Brief background on why this decision is needed]
+
+**Options:**
+
+| Option | Pros | Cons | Effort |
+| --- | --- | --- | --- |
+| Option A: [Name] | [Pro] | [Con] | [Est] |
+| Option B: [Name] | [Pro] | [Con] | [Est] |
+
+**My Recommendation:** Option [X] because [brief reasoning]
+
+**Timeline:** Need decision by [date] to stay on track for [milestone]
+
+Happy to discuss further if helpful.
+
+Best,
+[Your name]
+```
+
+## Introducing Yourself to a New Team
+
+```markdown
+Subject: Introduction: [Your Name] - [Your Role]
+
+Hi Team,
+
+I'm [Name], joining as [Role] starting [Date]. Excited to be part of the team!
+
+**Background:**
+- [Brief relevant experience]
+- [What you'll be working on initially]
+
+**What I'm Looking Forward To:**
+- [Something genuine about the team/project]
+
+**How to Reach Me:**
+- Slack: [handle]
+- Preferred: [communication preference]
+
+Looking forward to meeting everyone. Happy to grab virtual coffee with anyone who wants to chat!
+
+Best,
+[Your name]
+```
+
+## Asking for Help
+
+```markdown
+Subject: Question: [Specific Topic]
+
+Hi [Name],
+
+I'm working on [task/feature] and could use your expertise on [specific area].
+
+**What I'm Trying to Do:**
+[Brief description]
+
+**What I've Tried:**
+- [Approach 1 and result]
+- [Approach 2 and result]
+
+**Where I'm Stuck:**
+[Specific question or blocker]
+
+**Relevant Context:**
+- [Link to code/doc if helpful]
+- [Error message if applicable]
+
+No rush if you're busy - let me know when you have a few minutes. Thanks!
+
+Best,
+[Your name]
+```
+
+## Following Up
+
+```markdown
+Subject: Re: [Original Subject] - Following Up
+
+Hi [Name],
+
+Following up on my earlier message about [topic].
+
+**Quick Recap:** [One sentence reminder of what you need]
+
+**Timeline:** [Any urgency or deadline]
+
+Let me know if you need anything from me or if this is still on your radar.
+
+Thanks,
+[Your name]
+```
+
+## Tips for Using Templates
+
+1. **Personalize** - Don't send templates verbatim; adapt to context and relationship
+2. **Delete irrelevant sections** - If you don't have blockers, don't include a blockers section
+3. **Match formality to relationship** - Adjust tone based on how well you know the recipient
+4. **Proofread** - Especially names, dates, and any copied content
+5. **Consider timing** - Avoid sending at midnight or over weekends unless urgent
+
+---
+
+**Related:** Return to `professional-communication` skill for guidance on writing principles.
diff --git a/dist/plugins/professional-communication/skills/professional-communication/references/jargon-simplification.md b/dist/plugins/professional-communication/skills/professional-communication/references/jargon-simplification.md
new file mode 100644
index 0000000..16456ce
--- /dev/null
+++ b/dist/plugins/professional-communication/skills/professional-communication/references/jargon-simplification.md
@@ -0,0 +1,164 @@
+# Technical Jargon Simplification Guide
+
+Translations from technical terminology to accessible language. Use when communicating with non-technical stakeholders, customers, or cross-functional teams.
+
+## When to Simplify
+
+**Simplify for:**
+
+- Non-technical stakeholders (executives, product managers, sales)
+- Customers and end users
+- Cross-functional teams (HR, finance, legal, marketing)
+- New team members still learning the domain
+- Anyone who asks "what does that mean?"
+
+**Stay technical for:**
+
+- Engineering peers who share the context
+- Technical documentation and specs
+- Code reviews and architecture discussions
+- When precision is more important than accessibility
+
+## Architecture & Infrastructure
+
+| Technical Term | Plain Language |
+| --- | --- |
+| Microservices architecture | Our system is split into smaller, independent pieces that can be updated separately |
+| Monolithic application | One large application where everything is connected together |
+| Load balancer | A traffic cop that distributes work evenly across our servers |
+| CDN (Content Delivery Network) | Servers around the world that store copies of our content closer to users |
+| Container / Docker | A standardized package that bundles our app with everything it needs to run |
+| Kubernetes / K8s | A system that automatically manages and scales our applications |
+| Serverless | We run code without managing servers; we pay only when it's actually used |
+| API (Application Programming Interface) | A way for different software systems to talk to each other |
+| Database migration | Reorganizing how our data is stored and structured |
+| Caching | Storing frequently accessed data in a fast temporary location |
+| Redundancy | Having backup systems so we can keep running if something fails |
+| Failover | Automatically switching to a backup system when the main one fails |
+
+## Development Process
+
+| Technical Term | Plain Language |
+| --- | --- |
+| CI/CD Pipeline | Automated process that tests and deploys our code |
+| Sprint | A 1-2 week work cycle where we build and deliver specific features |
+| Backlog | Our prioritized list of features and improvements to build |
+| Technical debt | Shortcuts we took that we need to fix later |
+| Refactoring | Improving the code's structure without changing what it does |
+| Code review | Team members checking each other's work before it goes live |
+| Pull request / PR | A request to add your code changes to the main project |
+| Deployment | Releasing new code to our live system |
+| Rollback | Undoing a release and going back to the previous version |
+| Feature flag | A switch that lets us turn features on/off without deploying |
+| A/B testing | Showing different versions to different users to see what works better |
+
+## Performance & Reliability
+
+| Technical Term | Plain Language |
+| --- | --- |
+| Latency | The delay between a request and response; how fast things feel |
+| Throughput | How much work the system can handle at once |
+| Scalability | The ability to handle more users or work as we grow |
+| Uptime / availability | How often the system is working and accessible |
+| SLA (Service Level Agreement) | Our promise about how reliable the service will be |
+| 99.9% uptime / "three nines" | About 8 hours of downtime per year |
+| Memory leak | The app gradually using more memory until it slows down or crashes |
+| Race condition | A bug where the outcome depends on timing, causing unpredictable behavior |
+| Bottleneck | A part of the system that limits overall performance |
+
+## Security
+
+| Technical Term | Plain Language |
+| --- | --- |
+| Authentication | Verifying who you are (username/password) |
+| Authorization | Checking what you're allowed to do |
+| Encryption | Scrambling data so only authorized people can read it |
+| SSL/TLS/HTTPS | Secure connection that protects data in transit |
+| Two-factor authentication (2FA) | A second verification step beyond your password |
+| Vulnerability | A weakness that could be exploited by attackers |
+| Penetration testing / pen test | Hiring experts to try to break into our systems |
+| Data breach | Unauthorized access to sensitive information |
+| Firewall | A security barrier that controls what traffic can enter/exit |
+
+## Data & Databases
+
+| Technical Term | Plain Language |
+| --- | --- |
+| SQL / NoSQL | Different types of databases; SQL is structured tables, NoSQL is more flexible |
+| Query | A request to get specific data from the database |
+| Schema | The structure that defines how data is organized |
+| Index | A lookup system that makes finding data faster |
+| Replication | Copying data to multiple locations for safety and speed |
+| Sharding | Splitting data across multiple databases to handle more volume |
+| ETL (Extract, Transform, Load) | Moving data from one system to another, cleaning it up along the way |
+| Data warehouse | A central repository that combines data from many sources |
+
+## Communication & APIs
+
+| Technical Term | Plain Language |
+| --- | --- |
+| REST API | A standard way for systems to communicate over the web |
+| GraphQL | A more flexible way to request exactly the data you need |
+| Webhook | Automatic notifications sent when something happens |
+| Asynchronous / async | Tasks that run in the background without blocking other work |
+| Message queue | A waiting line for tasks to be processed one at a time |
+| Real-time | Updates that happen immediately, without refreshing |
+| WebSocket | A persistent connection for instant two-way communication |
+| Rate limiting | Restricting how many requests someone can make in a time period |
+
+## Common Phrases Translated
+
+| Technical Phrase | Plain Language |
+| --- | --- |
+| "We need to optimize the query" | "We need to make this faster" |
+| "There's a bug in production" | "There's an error affecting live users" |
+| "We're experiencing degraded performance" | "Things are slower than normal" |
+| "The service is timing out" | "Requests are failing because they're taking too long" |
+| "We need to scale horizontally" | "We need to add more servers to handle the load" |
+| "There's a regression in the latest release" | "The new update broke something that used to work" |
+| "We're doing a hotfix" | "We're quickly fixing a critical issue" |
+| "That's a breaking change" | "Existing integrations will stop working unless updated" |
+| "We need to deprecate this endpoint" | "We're phasing out this feature; please switch to the new one" |
+
+## Tips for Effective Translation
+
+### 1. Lead with Impact
+
+Instead of: "We implemented Redis caching to reduce database load"
+Say: "We made the page load 3x faster by storing frequently accessed data in memory"
+
+### 2. Use Analogies
+
+| Concept | Analogy |
+| --- | --- |
+| API | Like a waiter who takes your order to the kitchen and brings back food |
+| Load balancer | Like a host at a restaurant directing guests to available tables |
+| Database index | Like the index at the back of a book that helps you find topics quickly |
+| Caching | Like keeping frequently used items on your desk instead of in a filing cabinet |
+| Encryption | Like sending a letter in a locked box that only the recipient can open |
+
+### 3. Focus on "So What?"
+
+For every technical detail, ask: "Why does this matter to my audience?"
+
+| Technical | Business Impact |
+| --- | --- |
+| "We upgraded to Node 20" | "We can now use modern features and security updates" |
+| "We containerized the application" | "Deployments are now faster and more reliable" |
+| "We added monitoring and alerting" | "We'll know about problems before customers report them" |
+
+### 4. Know When Precision Matters
+
+Some situations require technical precision:
+
+- Legal or compliance discussions
+- Security incident communications
+- Technical documentation
+- When the audience asks for details
+
+In these cases, provide the technical term with a brief explanation:
+"We're implementing TLS 1.3 encryption - this is the latest security standard for protecting data in transit."
+
+---
+
+**Related:** Return to `professional-communication` skill for writing and communication frameworks.
diff --git a/dist/plugins/professional-communication/skills/professional-communication/references/meeting-structures.md b/dist/plugins/professional-communication/skills/professional-communication/references/meeting-structures.md
new file mode 100644
index 0000000..48b058d
--- /dev/null
+++ b/dist/plugins/professional-communication/skills/professional-communication/references/meeting-structures.md
@@ -0,0 +1,333 @@
+# Meeting Structures for Developers
+
+Templates and structures for common software development meetings. Use these to run effective meetings and ensure productive outcomes.
+
+## Daily Standup
+
+**Duration:** 15 minutes max
+**Frequency:** Daily
+**Format:** Each person answers 3 questions
+
+### Structure
+
+Each team member shares (1-2 minutes max per person):
+
+1. **Yesterday:** What did I complete?
+2. **Today:** What am I working on?
+3. **Blockers:** What's in my way?
+
+### Best Practices
+
+- **Stand up** (if in person) - Keeps it short
+- **Focus on work, not activity** - "Completed feature X" beats "Attended meetings"
+- **Parking lot** - Note follow-up discussions for after standup
+- **Timebox strictly** - 15 minutes, then end
+- **Blockers get attention** - If someone's blocked, identify who can help
+
+### Anti-Patterns to Avoid
+
+- Turning into status report to manager (it's team sync, not reporting)
+- Problem-solving during standup (take it offline)
+- Going into technical details (save for pairing sessions)
+- Skipping when "nothing to report" (brief updates still valuable)
+
+---
+
+## Sprint Planning
+
+**Duration:** 1-2 hours
+**Frequency:** Start of each sprint
+**Purpose:** Agree on sprint goals and work commitment
+
+### Structure
+
+| Phase | Duration | Activity |
+| --- | --- | --- |
+| Sprint Goal | 10 min | What will this sprint accomplish? |
+| Backlog Review | 20 min | Review prioritized items |
+| Estimation | 30 min | Size items being considered |
+| Commitment | 20 min | Team commits to sprint scope |
+| Capacity Check | 10 min | Account for PTO, meetings, etc. |
+
+### Agenda Template
+
+```markdown
+1. **Sprint Goal** (10 min)
+ - Product Owner presents sprint objective
+ - Team asks clarifying questions
+
+2. **Backlog Review** (20 min)
+ - Review top items in priority order
+ - Clarify acceptance criteria
+ - Identify dependencies
+
+3. **Estimation** (30 min)
+ - Estimate items using team's method (points, t-shirts, etc.)
+ - Break down large items if needed
+
+4. **Sprint Commitment** (20 min)
+ - Team selects items that fit capacity
+ - Confirm everyone understands the work
+
+5. **Wrap-up** (10 min)
+ - Recap sprint goal and committed items
+ - Note any risks or dependencies to watch
+```
+
+### Best Practices
+
+- **Come prepared** - PO has prioritized backlog, items are refined
+- **Focus on "what" not "how"** - Save implementation details for during sprint
+- **Protect focus time** - Account for meetings, support, etc. when committing
+- **Team decides capacity** - Only team members estimate and commit
+
+---
+
+## Sprint Retrospective
+
+**Duration:** 1-1.5 hours
+**Frequency:** End of each sprint
+**Purpose:** Continuous improvement
+
+### Structure
+
+| Phase | Duration | Activity |
+| --- | --- | --- |
+| Set the Stage | 5 min | Check-in, set tone |
+| Gather Data | 20 min | Collect feedback |
+| Generate Insights | 20 min | Discuss patterns |
+| Decide Actions | 15 min | Commit to improvements |
+| Close | 5 min | Appreciate, wrap up |
+
+### Common Formats
+
+**Start/Stop/Continue:**
+
+- **Start doing:** What should we begin?
+- **Stop doing:** What should we stop?
+- **Continue doing:** What's working well?
+
+**Liked/Learned/Lacked/Longed For (4Ls):**
+
+- **Liked:** What went well?
+- **Learned:** What did we discover?
+- **Lacked:** What was missing?
+- **Longed for:** What do we wish we had?
+
+**Mad/Sad/Glad:**
+
+- **Mad:** What frustrated you?
+- **Sad:** What disappointed you?
+- **Glad:** What made you happy?
+
+### Best Practices
+
+- **Safe space** - No blame, focus on systems not people
+- **Limit action items** - 1-3 concrete improvements
+- **Follow up** - Review last retro's actions at start
+- **Vary the format** - Keep it fresh to avoid ruts
+- **Everyone participates** - Make space for quieter voices
+
+---
+
+## Architecture Review / Tech Design Review
+
+**Duration:** 45-60 minutes
+**Frequency:** As needed for significant technical decisions
+**Purpose:** Get feedback on technical approach before implementation
+
+### Structure
+
+```markdown
+1. **Context & Problem** (10 min)
+ - What problem are we solving?
+ - Why now? What's driving this?
+
+2. **Proposed Solution** (15 min)
+ - High-level architecture diagram
+ - Key components and their responsibilities
+ - Data flow
+
+3. **Trade-offs & Alternatives** (10 min)
+ - What alternatives did you consider?
+ - Why this approach over others?
+ - What are we trading off?
+
+4. **Discussion & Questions** (15 min)
+ - Open floor for questions
+ - Concerns and risks
+ - Edge cases and failure modes
+
+5. **Decision & Next Steps** (5 min)
+ - Approved / Approved with changes / Needs revision
+ - Action items and timeline
+```
+
+### Best Practices
+
+- **Share materials beforehand** - Send design doc 24-48 hours before
+- **Timebox discussion** - Don't let it become a working session
+- **Focus on architecture, not code** - Implementation details come later
+- **Document decisions** - Record the outcome in an ADR or design doc
+
+---
+
+## One-on-One (1:1)
+
+**Duration:** 30-60 minutes
+**Frequency:** Weekly or bi-weekly
+**Purpose:** Support, feedback, career growth
+
+### Structure (Flexible)
+
+```markdown
+1. **Their Topics First** (15-20 min)
+ - What's on their mind?
+ - Blockers, concerns, wins
+
+2. **Feedback Exchange** (10-15 min)
+ - Recognition for recent work
+ - Growth areas or coaching
+
+3. **Career/Growth** (10-15 min)
+ - Progress on development goals
+ - Upcoming opportunities
+
+4. **Admin/Updates** (5 min)
+ - Any org updates to share
+ - Upcoming schedule impacts
+```
+
+### Good Questions to Ask
+
+**For team members:**
+
+- "What's your biggest blocker right now?"
+- "What's one thing I could do to better support you?"
+- "What are you most proud of recently?"
+- "What would you like to be doing more of?"
+
+**For managers:**
+
+- "Is there anything you need from me?"
+- "How can I help the team succeed this sprint?"
+- "What feedback do you have for me?"
+
+### Best Practices
+
+- **Their meeting, their agenda** - Let them drive topics
+- **Don't cancel** - Consistency builds trust
+- **Take notes** - Remember what you discussed
+- **Follow through** - If you commit to something, do it
+
+---
+
+## Incident Postmortem / Blameless Review
+
+**Duration:** 60-90 minutes
+**Frequency:** After significant incidents
+**Purpose:** Learn and prevent recurrence
+
+### Structure
+
+```markdown
+1. **Timeline Review** (20 min)
+ - What happened, when?
+ - Build shared understanding of events
+
+2. **Impact Assessment** (10 min)
+ - What was affected?
+ - Customer impact, business impact
+
+3. **Root Cause Analysis** (20 min)
+ - 5 Whys or Fishbone diagram
+ - Contributing factors (not just trigger)
+
+4. **What Went Well** (10 min)
+ - What worked in our response?
+ - What should we keep doing?
+
+5. **Action Items** (15 min)
+ - Prevention measures
+ - Detection improvements
+ - Response improvements
+
+6. **Wrap-up** (5 min)
+ - Assign owners and timelines
+ - Schedule follow-up if needed
+```
+
+### Best Practices
+
+- **Blameless** - Focus on systems, not individuals
+- **Assume good intent** - People made reasonable decisions with available info
+- **Prioritize actions** - Don't try to fix everything; focus on highest impact
+- **Share learnings** - Document and share with broader team/org
+
+---
+
+## Code Review Walkthrough
+
+**Duration:** 30-45 minutes
+**Frequency:** As needed for complex changes
+**Purpose:** Deep review of significant code changes
+
+### Structure
+
+```markdown
+1. **Context Setting** (5 min)
+ - What problem does this solve?
+ - Why was this approach chosen?
+
+2. **High-Level Walkthrough** (10 min)
+ - Architecture/structure overview
+ - Key files and their purposes
+
+3. **Detailed Review** (20 min)
+ - Walk through critical paths
+ - Highlight non-obvious decisions
+ - Answer questions in real-time
+
+4. **Wrap-up** (5 min)
+ - Note remaining concerns
+ - Agree on approval path
+```
+
+### Best Practices
+
+- **Share PR link beforehand** - Let reviewers skim first
+- **Focus on logic, not style** - Linters catch style issues
+- **Author drives the walkthrough** - Explain your thinking
+- **Note follow-up items** - Track issues for separate PRs
+
+---
+
+## General Meeting Tips
+
+### Before the Meeting
+
+- [ ] Clear purpose/objective defined
+- [ ] Agenda sent in advance
+- [ ] Right people invited (and only right people)
+- [ ] Materials shared for pre-read
+- [ ] Time and duration appropriate for scope
+
+### During the Meeting
+
+- [ ] Start on time
+- [ ] State objective at opening
+- [ ] Timebox discussions
+- [ ] Capture action items live
+- [ ] Leave 5 minutes for wrap-up
+- [ ] End on time (or early!)
+
+### After the Meeting
+
+- [ ] Send summary within 24 hours
+- [ ] Action items have owners and due dates
+- [ ] Follow up on commitments
+- [ ] Cancel recurring meetings that aren't adding value
+
+---
+
+**Related:** Return to `professional-communication` skill for email and written communication guidance.
diff --git a/dist/plugins/professional-communication/skills/professional-communication/references/remote-async-communication.md b/dist/plugins/professional-communication/skills/professional-communication/references/remote-async-communication.md
new file mode 100644
index 0000000..2705a08
--- /dev/null
+++ b/dist/plugins/professional-communication/skills/professional-communication/references/remote-async-communication.md
@@ -0,0 +1,305 @@
+# Remote and Async Communication
+
+Guide to effective communication in remote-first and async-first environments.
+
+## Async-First Principles
+
+### Default to Async
+
+Before scheduling a meeting, ask: "Could this be async instead?"
+
+| Sync (Meeting) | Async (Document/Message) |
+| -------------- | ------------------------ |
+| Brainstorming with immediate building | Collecting feedback over time |
+| Sensitive/emotional conversations | Status updates |
+| Real-time collaboration | Decisions with clear options |
+| Urgent problem-solving | Non-urgent questions |
+| Relationship building | Documentation and knowledge sharing |
+
+### Why Async Matters
+
+- **Time zones:** Not everyone is online at once
+- **Deep work:** Meetings fragment focus time
+- **Inclusion:** Async gives introverts equal voice
+- **Documentation:** Async creates artifacts for later
+- **Flexibility:** People work when they're most productive
+
+## Channel Selection Guide
+
+Choose the right tool for the job:
+
+### Instant Messaging (Slack, Teams)
+
+**Best for:**
+
+- Quick questions expecting same-day answers
+- Informal team chat
+- Time-sensitive coordination
+- Celebrations and recognition
+
+**Anti-patterns:**
+
+- Long-form discussions (use docs)
+- Decisions needing documentation (use PRs or docs)
+- Anything requiring more than 3 back-and-forths
+
+### Documents (Notion, Google Docs)
+
+**Best for:**
+
+- Proposals and RFCs
+- Meeting notes and follow-ups
+- Complex decisions with multiple stakeholders
+- Knowledge that should persist
+- Async reviews and feedback
+
+**Format tips:**
+
+- Start with TL;DR
+- Use headers for scannability
+- Call out action items and decisions clearly
+- Include deadline if feedback is needed
+
+### Email
+
+**Best for:**
+
+- External communication
+- Formal announcements
+- Reaching people outside your company
+- When you need a paper trail
+
+**Avoid for:**
+
+- Internal quick questions (use Slack)
+- Collaborative editing (use docs)
+
+### Video Calls
+
+**Reserve for:**
+
+- Complex discussions needing real-time back-and-forth
+- Sensitive conversations (feedback, conflict)
+- Relationship building
+- Urgent problem-solving
+- Brainstorming and creative work
+
+**Always:**
+
+- Send agenda beforehand
+- Record for those who can't attend
+- Document decisions and action items after
+
+### PRs and Code Comments
+
+**Best for:**
+
+- Code-specific discussions
+- Technical decisions with code context
+- Review feedback
+- Architectural choices in implementation
+
+## Over-Communication
+
+In remote work, default to over-communication:
+
+### Share Context Liberally
+
+People can't see what you're working on:
+
+| Don't | Do |
+| ----- | -- |
+| Disappear for hours | Post "heads down on X, will be slow to respond" |
+| Assume people know your schedule | Share working hours in your profile |
+| Go silent when stuck | Post "blocked on X, exploring options" |
+| Complete work silently | Share progress: "Finished the API, moving to tests" |
+
+### Working Out Loud
+
+Share your thinking, not just your conclusions:
+
+**Good examples:**
+
+> "Exploring two approaches for the caching problem: Redis vs. in-memory. Leaning toward Redis for cross-instance consistency. Will share trade-offs in #architecture by EOD."
+
+And:
+
+> "Hit an unexpected issue with the auth flow - user sessions aren't persisting across subdomains. Investigating cookie settings. ETA unclear, will update in 2 hours."
+
+### When Changing Plans
+
+If priorities shift:
+
+- Communicate the change and reason
+- Update anyone who was expecting the old thing
+- Don't assume people will notice
+
+## Time Zone Awareness
+
+### Know Your Team's Time Zones
+
+Keep a quick reference:
+
+- Who overlaps with you (synchronous possible)
+- Who doesn't (async required)
+- When each person's day starts/ends
+
+### Async by Default
+
+When in doubt, don't expect immediate response:
+
+- Include context so they can reply without follow-up questions
+- Set clear but reasonable deadlines
+- Acknowledge receipt even if you can't respond fully yet
+
+### Schedule Sends
+
+Don't send messages at 2am someone else's time:
+
+- Use "schedule send" features
+- Or add context: "No response expected until your morning"
+
+### Rotating Meeting Times
+
+For regular cross-timezone meetings:
+
+- Rotate who bears the inconvenient time
+- Record meetings for those who can't attend live
+- Default to async when sync isn't essential
+
+## Documentation Over Meetings
+
+### Meeting Decision Rule
+
+Before scheduling a meeting:
+
+1. **Write first:** Draft the problem, context, and options
+2. **Collect async feedback:** Give 24-48 hours
+3. **Then decide:** If still unresolved, schedule a meeting
+
+Many meetings can be avoided if the organizer documents well enough that discussion isn't needed.
+
+### Meeting Follow-Up
+
+Every synchronous meeting should produce async artifacts:
+
+- **Notes:** Key discussion points
+- **Decisions:** What was decided and why
+- **Action items:** Who does what by when
+- **Recording:** For those who couldn't attend
+
+Share within 24 hours while context is fresh.
+
+### Recording and Summarizing
+
+For important sync meetings:
+
+- Record video/audio
+- Create written summary with timestamps
+- Call out decisions and action items
+- Share in relevant channels
+
+## Writing for Async
+
+### Frontload the Point
+
+Start with the conclusion/ask, then provide context:
+
+**Buried lead (bad):**
+> "I've been looking at our deployment pipeline and noticed that the test suite takes 45 minutes. After investigating, I found that most of the time is spent on integration tests that could be parallelized. I've put together a proposal to reduce this by 60%..."
+
+**Frontloaded (good):**
+
+> "**Proposal:** Reduce our test suite time from 45 min to 18 min by parallelizing integration tests.
+>
+> **Context:** Our deployment pipeline is slow because..."
+
+### Make It Scannable
+
+Use structure for long messages:
+
+- **Headers** for sections
+- **Bold** for key points
+- **Bullets** for lists
+- **TL;DR** at the top for long documents
+
+### Include Everything Needed
+
+The reader shouldn't need to ask follow-up questions:
+
+| Missing context | Complete context |
+| --------------- | ---------------- |
+| "The deploy failed" | "The 3pm deploy to staging failed with timeout error (link to logs). I'm investigating and will update in 1 hour." |
+| "Can you review my PR?" | "Can you review my PR (#123)? It's ~200 lines touching the auth flow. Happy to answer questions async or sync." |
+
+### Set Clear Expectations
+
+Make response expectations explicit:
+
+- **Deadline:** "Feedback needed by Friday EOD"
+- **Priority:** "Not urgent, whenever you have time"
+- **Type of response:** "Looking for approval" vs. "Want to brainstorm"
+- **Who should respond:** "@team" vs. specific people
+
+## Anti-Patterns
+
+### The Slack Novel
+
+Long-form content in chat messages:
+
+- Hard to skim
+- Gets lost in scroll
+- Can't be edited or organized
+
+**Fix:** Put it in a document, share the link.
+
+### The Ping-Pong Conversation
+
+Back-and-forth that takes 3 hours in chat but would take 10 minutes in a call:
+
+**Fix:** After 3 exchanges, offer "Want to hop on a quick call?"
+
+### The Surprise Meeting
+
+Adding meetings without context or asking availability:
+
+**Fix:** Always include agenda; ask before scheduling.
+
+### The Ghost
+
+Disappearing without communication:
+
+**Fix:** Post status when stepping away; respond to acknowledge messages even if you can't fully address them.
+
+### The Always-On Expectation
+
+Expecting immediate responses:
+
+**Fix:** Set team norms about response times; use async by default.
+
+## Team Norms
+
+Consider establishing explicit norms:
+
+```markdown
+## Our Communication Norms
+
+### Response Times
+- **Slack DM:** Within 4 working hours
+- **Slack channel:** Within 24 hours
+- **Email:** Within 48 hours
+- **Document comments:** Before stated deadline
+
+### Urgent vs. Non-Urgent
+- For truly urgent: Use @here or call
+- For everything else: Assume async
+
+### Deep Work Protection
+- No expectation of response during focus time (blocked on calendar)
+- "Do Not Disturb" is respected
+
+### Time Zone Respect
+- Core overlap hours: 10am-2pm EST
+- Meetings scheduled in overlap hours only
+- Async preferred outside overlap
+```
diff --git a/dist/plugins/qa-test-planner/skills/qa-test-planner/README.md b/dist/plugins/qa-test-planner/skills/qa-test-planner/README.md
new file mode 100644
index 0000000..968b825
--- /dev/null
+++ b/dist/plugins/qa-test-planner/skills/qa-test-planner/README.md
@@ -0,0 +1,355 @@
+# QA Test Planner
+
+A comprehensive Claude Code skill for QA engineers to generate test plans, manual test cases, regression test suites, Figma design validations, and structured bug reports.
+
+## Purpose
+
+The QA Test Planner skill helps quality assurance professionals create thorough, well-structured testing documentation quickly and consistently. It eliminates the repetitive work of formatting test plans and cases while ensuring best practices are followed for test coverage, bug reporting, and design validation.
+
+## When to Use This Skill
+
+Use the QA Test Planner skill when you need to:
+
+- Create a comprehensive test plan for a new feature or release
+- Generate manual test cases with step-by-step instructions
+- Build regression test suites (smoke, targeted, or full)
+- Validate UI implementation against Figma designs
+- Document bugs with clear reproduction steps
+- Establish testing standards for your team
+- Train new QA engineers on proper documentation
+
+### Activation
+
+This skill uses **explicit triggering** - it must be called by name:
+
+```
+/qa-test-planner
+qa-test-planner
+use the skill qa-test-planner
+```
+
+## How It Works
+
+The QA Test Planner follows a three-phase workflow:
+
+### 1. Analyze Phase
+- Parses your feature description or requirement
+- Identifies the types of testing needed (functional, UI, integration, etc.)
+- Determines scope, priorities, and edge cases to cover
+
+### 2. Generate Phase
+- Creates structured deliverables using proven templates
+- Applies QA best practices automatically
+- Includes comprehensive edge cases and test variations
+- Organizes content for easy execution and tracking
+
+### 3. Validate Phase
+- Checks completeness of generated documentation
+- Verifies traceability between requirements and tests
+- Ensures all steps are clear and actionable
+
+## Key Features
+
+### 1. Test Plan Generation
+Creates complete test plans including:
+- Executive summary with objectives and risks
+- Clear scope definition (in-scope and out-of-scope)
+- Testing strategy and approach
+- Environment requirements
+- Entry and exit criteria
+- Risk assessment with mitigations
+- Timeline and deliverables
+
+### 2. Manual Test Case Creation
+Generates structured test cases with:
+- Step-by-step test instructions
+- Expected results for each step
+- Preconditions and test data requirements
+- Priority and severity assignments
+- Post-conditions and cleanup steps
+- Edge cases and variations
+
+### 3. Regression Test Suites
+Builds tiered test suites:
+- **Smoke tests** (15-30 min) - Critical paths only
+- **Targeted regression** (30-60 min) - Affected areas
+- **Full regression** (2-4 hours) - Comprehensive coverage
+- **Sanity tests** (10-15 min) - Quick validation after hotfixes
+
+### 4. Figma Design Validation
+Integrates with Figma MCP to:
+- Extract design specifications (colors, spacing, typography)
+- Compare implementation against design system
+- Create validation checklists for UI testing
+- Document visual discrepancies as bugs
+
+### 5. Bug Report Documentation
+Generates structured bug reports with:
+- Clear reproduction steps
+- Environment details (OS, browser, device, build)
+- Expected vs actual behavior
+- Visual evidence (screenshots, videos, console logs)
+- Severity and priority classification
+- Impact assessment and workarounds
+
+## Usage Examples
+
+### Example 1: Create Test Plan
+
+**Input:**
+```
+/qa-test-planner
+Create a test plan for the user authentication feature
+```
+
+**Output:**
+A complete test plan document including:
+- Testing objectives for login, registration, password reset
+- Scope definition (web and mobile apps)
+- Test strategy (manual, exploratory, security testing)
+- Environment requirements (browsers, devices, test data)
+- Entry/exit criteria with measurable thresholds
+- Risk assessment (security vulnerabilities, third-party auth)
+- Timeline with milestones
+
+### Example 2: Generate Test Cases
+
+**Input:**
+```
+/qa-test-planner
+Generate 5 manual test cases for the checkout flow
+```
+
+**Output:**
+Five numbered test cases covering:
+1. Valid checkout with credit card
+2. Invalid credit card handling
+3. Empty cart checkout attempt
+4. Promo code application
+5. Guest vs. logged-in checkout
+
+Each includes preconditions, step-by-step instructions, expected results, test data, and edge cases.
+
+### Example 3: Build Regression Suite
+
+**Input:**
+```
+/qa-test-planner
+Build a smoke test suite for the payment module
+```
+
+**Output:**
+A prioritized smoke test suite (15-30 min execution) with:
+- Critical path tests (payment processing, refunds)
+- Execution order and dependencies
+- Pass/fail criteria
+- Quick validation checklist
+
+### Example 4: Validate Against Figma
+
+**Input:**
+```
+/qa-test-planner
+Compare the login page against the Figma design at [Figma URL]
+```
+
+**Output:**
+A validation checklist comparing:
+- Button dimensions, colors, and states
+- Typography (fonts, sizes, weights)
+- Spacing and layout
+- Responsive behavior
+- Interactive states (hover, focus, disabled)
+
+Plus test cases to verify each element and document discrepancies.
+
+### Example 5: Create Bug Report
+
+**Input:**
+```
+/qa-test-planner
+Create a bug report for: Form validation doesn't prevent submission when email field is empty
+```
+
+**Output:**
+A structured bug report with:
+- Clear title: "[Contact Form] Submission allowed with empty email field"
+- Severity: High (data quality issue)
+- Reproduction steps (numbered, specific actions)
+- Expected behavior: Form submission blocked with error message
+- Actual behavior: Form submits without email
+- Environment details
+- Visual evidence placeholder
+- Impact assessment
+
+## Interactive Scripts
+
+The skill includes bash scripts for guided test case and bug report creation:
+
+### Generate Test Cases Script
+```bash
+./scripts/generate_test_cases.sh
+```
+Prompts for:
+- Feature name
+- Test type (functional, UI, integration)
+- Number of test cases
+- Priority level
+
+### Create Bug Report Script
+```bash
+./scripts/create_bug_report.sh
+```
+Prompts for:
+- Bug title
+- Severity and priority
+- Reproduction steps
+- Environment details
+- Expected vs actual behavior
+
+## Reference Documentation
+
+The skill includes comprehensive reference guides in the `references/` directory:
+
+- **test_case_templates.md** - Standard formats for all test types
+- **bug_report_templates.md** - Bug documentation templates
+- **regression_testing.md** - Suite building and execution strategies
+- **figma_validation.md** - Design-implementation validation workflows
+
+## Quality Standards
+
+### Test Plan Checklist
+- Scope clearly defined (in/out)
+- Entry/exit criteria specified
+- Risks identified with mitigations
+- Timeline is realistic and achievable
+
+### Test Case Checklist
+- Each step has an expected result
+- Preconditions documented
+- Test data available or specified
+- Priority assigned (P0-P3)
+- Edge cases included
+
+### Bug Report Checklist
+- Reproducible steps provided
+- Environment documented completely
+- Screenshots or evidence attached
+- Severity and priority set appropriately
+
+## Anti-Patterns to Avoid
+
+The skill helps you avoid common testing mistakes:
+
+| Avoid | Why It's Bad | What to Do Instead |
+|-------|--------------|-------------------|
+| Vague test steps | Can't reproduce consistently | Use specific actions with expected results |
+| Missing preconditions | Tests fail unexpectedly | Document all setup requirements |
+| No test data | Testers get blocked | Provide sample data or generation instructions |
+| Generic bug titles | Hard to track and prioritize | Be specific: "[Feature] issue when [action]" |
+| Skipping edge cases | Miss critical bugs | Include boundary values, nulls, empty states |
+
+## Integration with Figma MCP
+
+When Figma MCP is configured, the skill can:
+
+1. Extract design specifications from Figma URLs
+2. Generate pixel-perfect validation test cases
+3. Compare implementation against design tokens
+4. Create bug reports with Figma links for UI discrepancies
+
+**Example Query:**
+```
+Get button specifications from Figma design [URL]
+```
+
+**Returns:**
+- Dimensions (width x height)
+- Colors (background, text, border with hex values)
+- Typography (font family, size, weight, line-height)
+- Spacing (padding, margin)
+- Border radius
+- Interactive states (default, hover, active, disabled)
+
+## Best Practices
+
+### Test Case Writing
+- Be specific and unambiguous
+- Include expected results for each step
+- Test one thing per test case
+- Use consistent naming conventions (TC-MODULE-###)
+- Keep test cases maintainable (update as features change)
+
+### Bug Reporting
+- Provide clear reproduction steps anyone can follow
+- Include screenshots, videos, or console logs
+- Specify exact environment details
+- Describe impact on users
+- Link to Figma designs for UI bugs
+
+### Regression Testing
+- Maintain regression suite regularly
+- Prioritize critical paths
+- Run smoke tests frequently (daily/per build)
+- Update suite after each release
+- Track coverage to identify gaps
+
+## Skill Structure
+
+```
+qa-test-planner/
+├── README.md # This file
+├── SKILL.md # Main skill definition and templates
+├── references/
+│ ├── test_case_templates.md # Test case formats
+│ ├── bug_report_templates.md # Bug documentation templates
+│ ├── regression_testing.md # Regression suite strategies
+│ └── figma_validation.md # Design validation workflows
+└── scripts/
+ ├── generate_test_cases.sh # Interactive test case generator
+ └── create_bug_report.sh # Interactive bug report creator
+```
+
+## Output Formats
+
+All deliverables are generated in **Markdown format** for easy copy-paste into:
+- Jira, Linear, GitHub Issues
+- Confluence, Notion
+- TestRail, Zephyr
+- Google Docs, Word
+
+The structured format ensures consistency across your team and makes test documentation searchable and maintainable.
+
+## Time Savings
+
+Typical time to create documentation:
+
+| Deliverable | Manual Time | With Skill | Time Saved |
+|-------------|-------------|------------|------------|
+| Test Plan | 2-3 hours | 10-15 min | 90% |
+| 10 Test Cases | 1-2 hours | 5-10 min | 85% |
+| Regression Suite | 2-4 hours | 15-20 min | 90% |
+| Bug Report | 10-15 min | 5 min | 50% |
+| Figma Validation | 30-60 min | 10-15 min | 75% |
+
+## Getting Started
+
+1. Activate the skill: `/qa-test-planner`
+2. Describe what you need (test plan, test cases, bug report, etc.)
+3. Review and customize the generated documentation
+4. Copy to your tracking system (Jira, Linear, etc.)
+
+## Support
+
+For detailed information on specific deliverables, see SKILL.md which includes:
+- Deep dive sections on each deliverable type
+- Complete templates with examples
+- QA process workflow
+- Test execution tracking
+- Coverage matrix templates
+
+---
+
+**"Testing shows the presence, not the absence of bugs."** - Edsger Dijkstra
+
+**"Quality is not an act, it is a habit."** - Aristotle
diff --git a/dist/plugins/qa-test-planner/skills/qa-test-planner/SKILL.md b/dist/plugins/qa-test-planner/skills/qa-test-planner/SKILL.md
new file mode 100644
index 0000000..a269932
--- /dev/null
+++ b/dist/plugins/qa-test-planner/skills/qa-test-planner/SKILL.md
@@ -0,0 +1,757 @@
+---
+name: qa-test-planner
+description: Generate comprehensive test plans, manual test cases, regression test suites, and bug reports for QA engineers. Includes Figma MCP integration for design validation.
+trigger: explicit
+---
+
+# QA Test Planner
+
+A comprehensive skill for QA engineers to create test plans, generate manual test cases, build regression test suites, validate designs against Figma, and document bugs effectively.
+
+> **Activation:** This skill is triggered only when explicitly called by name (e.g., `/qa-test-planner`, `qa-test-planner`, or `use the skill qa-test-planner`).
+
+---
+
+## Quick Start
+
+**Create a test plan:**
+```
+"Create a test plan for the user authentication feature"
+```
+
+**Generate test cases:**
+```
+"Generate manual test cases for the checkout flow"
+```
+
+**Build regression suite:**
+```
+"Build a regression test suite for the payment module"
+```
+
+**Validate against Figma:**
+```
+"Compare the login page against the Figma design at [URL]"
+```
+
+**Create bug report:**
+```
+"Create a bug report for the form validation issue"
+```
+
+---
+
+## Quick Reference
+
+| Task | What You Get | Time |
+|------|--------------|------|
+| Test Plan | Strategy, scope, schedule, risks | 10-15 min |
+| Test Cases | Step-by-step instructions, expected results | 5-10 min each |
+| Regression Suite | Smoke tests, critical paths, execution order | 15-20 min |
+| Figma Validation | Design-implementation comparison, discrepancy list | 10-15 min |
+| Bug Report | Reproducible steps, environment, evidence | 5 min |
+
+---
+
+## How It Works
+
+```
+Your Request
+ │
+ ▼
+┌─────────────────────────────────────────────────────┐
+│ 1. ANALYZE │
+│ • Parse feature/requirement │
+│ • Identify test types needed │
+│ • Determine scope and priorities │
+├─────────────────────────────────────────────────────┤
+│ 2. GENERATE │
+│ • Create structured deliverables │
+│ • Apply templates and best practices │
+│ • Include edge cases and variations │
+├─────────────────────────────────────────────────────┤
+│ 3. VALIDATE │
+│ • Check completeness │
+│ • Verify traceability │
+│ • Ensure actionable steps │
+└─────────────────────────────────────────────────────┘
+ │
+ ▼
+QA Deliverable Ready
+```
+
+---
+
+## Commands
+
+### Interactive Scripts
+
+| Script | Purpose | Usage |
+|--------|---------|-------|
+| `./scripts/generate_test_cases.sh` | Create test cases interactively | Step-by-step prompts |
+| `./scripts/create_bug_report.sh` | Generate bug reports | Guided input collection |
+
+### Natural Language
+
+| Request | Output |
+|---------|--------|
+| "Create test plan for {feature}" | Complete test plan document |
+| "Generate {N} test cases for {feature}" | Numbered test cases with steps |
+| "Build smoke test suite" | Critical path tests |
+| "Compare with Figma at {URL}" | Visual validation checklist |
+| "Document bug: {description}" | Structured bug report |
+
+---
+
+## Core Deliverables
+
+### 1. Test Plans
+- Test scope and objectives
+- Testing approach and strategy
+- Environment requirements
+- Entry/exit criteria
+- Risk assessment
+- Timeline and milestones
+
+### 2. Manual Test Cases
+- Step-by-step instructions
+- Expected vs actual results
+- Preconditions and setup
+- Test data requirements
+- Priority and severity
+
+### 3. Regression Suites
+- Smoke tests (15-30 min)
+- Full regression (2-4 hours)
+- Targeted regression (30-60 min)
+- Execution order and dependencies
+
+### 4. Figma Validation
+- Component-by-component comparison
+- Spacing and typography checks
+- Color and visual consistency
+- Interactive state validation
+
+### 5. Bug Reports
+- Clear reproduction steps
+- Environment details
+- Evidence (screenshots, logs)
+- Severity and priority
+
+---
+
+## Anti-Patterns
+
+| Avoid | Why | Instead |
+|-------|-----|---------|
+| Vague test steps | Can't reproduce | Specific actions + expected results |
+| Missing preconditions | Tests fail unexpectedly | Document all setup requirements |
+| No test data | Tester blocked | Provide sample data or generation |
+| Generic bug titles | Hard to track | Specific: "[Feature] issue when [action]" |
+| Skip edge cases | Miss critical bugs | Include boundary values, nulls |
+
+---
+
+## Verification Checklist
+
+**Test Plan:**
+- [ ] Scope clearly defined (in/out)
+- [ ] Entry/exit criteria specified
+- [ ] Risks identified with mitigations
+- [ ] Timeline realistic
+
+**Test Cases:**
+- [ ] Each step has expected result
+- [ ] Preconditions documented
+- [ ] Test data available
+- [ ] Priority assigned
+
+**Bug Reports:**
+- [ ] Reproducible steps
+- [ ] Environment documented
+- [ ] Screenshots/evidence attached
+- [ ] Severity/priority set
+
+---
+
+## References
+
+- [Test Case Templates](references/test_case_templates.md) - Standard formats for all test types
+- [Bug Report Templates](references/bug_report_templates.md) - Documentation templates
+- [Regression Testing Guide](references/regression_testing.md) - Suite building and execution
+- [Figma Validation Guide](references/figma_validation.md) - Design-implementation validation
+
+---
+
+
+Deep Dive: Test Case Structure
+
+
+Deep Dive: Test Plan Template
+
+
+Deep Dive: Bug Reporting
+
+
+Deep Dive: Figma MCP Integration
+
+
+Deep Dive: Regression Testing
+
+
+Deep Dive: Test Execution Tracking
+
+
+QA Process Workflow
+
+
+Best Practices
+
+---
+
+## Examples
+
+
+Example: Login Flow Test Case
+
+
+Example: Responsive Design Test Case
+
+---
+
+**"Testing shows the presence, not the absence of bugs." - Edsger Dijkstra**
+
+**"Quality is not an act, it is a habit." - Aristotle**
diff --git a/dist/plugins/qa-test-planner/skills/qa-test-planner/references/bug_report_templates.md b/dist/plugins/qa-test-planner/skills/qa-test-planner/references/bug_report_templates.md
new file mode 100644
index 0000000..ad6c7eb
--- /dev/null
+++ b/dist/plugins/qa-test-planner/skills/qa-test-planner/references/bug_report_templates.md
@@ -0,0 +1,423 @@
+# Bug Report Templates
+
+Standard templates for clear, reproducible, actionable bug documentation.
+
+---
+
+## Standard Bug Report Template
+
+```markdown
+# BUG-[ID]: [Clear, Specific Title]
+
+**Severity:** Critical | High | Medium | Low
+**Priority:** P0 | P1 | P2 | P3
+**Type:** Functional | UI | Performance | Security | Data | Crash
+**Status:** Open | In Progress | In Review | Fixed | Verified | Closed
+**Assignee:** [Developer name]
+**Reporter:** [Your name]
+**Reported Date:** YYYY-MM-DD
+
+---
+
+## Environment
+
+| Property | Value |
+|----------|-------|
+| **OS** | [Windows 11 / macOS 14 / Ubuntu 22.04] |
+| **Browser** | [Chrome 120 / Firefox 121 / Safari 17] |
+| **Device** | [Desktop / iPhone 15 / Samsung S23] |
+| **Build/Version** | [v2.5.0 / commit abc123] |
+| **Environment** | [Production / Staging / Dev] |
+| **URL** | [Exact page URL] |
+
+---
+
+## Description
+
+[2-3 sentences clearly describing what the bug is and its impact]
+
+---
+
+## Steps to Reproduce
+
+**Preconditions:**
+- [Any setup required before reproduction]
+- [Test account: user@test.com]
+
+**Steps:**
+1. [Navigate to specific URL]
+2. [Perform specific action]
+3. [Enter specific data: "example"]
+4. [Click specific button]
+5. [Observe the issue]
+
+**Reproduction Rate:** [Always / 8 out of 10 times / Intermittent]
+
+---
+
+## Expected Behavior
+
+[Clearly describe what SHOULD happen]
+
+---
+
+## Actual Behavior
+
+[Clearly describe what ACTUALLY happens]
+
+---
+
+## Visual Evidence
+
+**Screenshots:**
+- [ ] Before state: [attached]
+- [ ] After state: [attached]
+- [ ] Error message: [attached]
+
+**Video Recording:** [Link if available]
+
+**Console Errors:**
+```
+[Paste any console errors here]
+```
+
+**Network Errors:**
+```
+[Paste any failed requests here]
+```
+
+---
+
+## Impact Assessment
+
+| Aspect | Details |
+|--------|---------|
+| **Users Affected** | [All users / Subset / Specific role] |
+| **Frequency** | [Every time / Sometimes / Rarely] |
+| **Data Impact** | [Data loss / Corruption / None] |
+| **Business Impact** | [Revenue loss / User frustration / Minimal] |
+| **Workaround** | [Describe workaround if exists, or "None"] |
+
+---
+
+## Additional Context
+
+**Related Items:**
+- Feature: [FEAT-123]
+- Test Case: [TC-456]
+- Similar Bug: [BUG-789]
+- Figma Design: [URL if UI bug]
+
+**Regression Information:**
+- Is this a regression? [Yes / No]
+- Last working version: [v2.4.0]
+- First broken version: [v2.5.0]
+
+**Notes:**
+[Any additional context that might help fix the issue]
+
+---
+
+## Developer Section (To Be Filled)
+
+### Root Cause
+[Developer fills in after investigation]
+
+### Fix Description
+[Developer describes the fix approach]
+
+### Files Changed
+- [file1.js]
+- [file2.css]
+
+### Fix PR
+[Link to pull request]
+
+---
+
+## QA Verification
+
+- [ ] Fix verified in dev environment
+- [ ] Fix verified in staging
+- [ ] Regression tests passed
+- [ ] Related test cases updated
+- [ ] Ready for production
+
+**Verified By:** [QA name]
+**Verification Date:** [Date]
+**Verification Build:** [Build number]
+```
+
+---
+
+## Quick Bug Report Template
+
+For minor issues or fast documentation.
+
+```markdown
+# BUG-[ID]: [Title]
+
+**Severity:** Low | Medium
+**Environment:** [Browser, OS, Build]
+
+## Issue
+[One paragraph description]
+
+## Steps
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+## Expected
+[What should happen]
+
+## Actual
+[What happens]
+
+## Screenshot
+[Attached]
+```
+
+---
+
+## UI/Visual Bug Template
+
+For design discrepancy reports.
+
+```markdown
+# BUG-[ID]: [Component] Visual Mismatch
+
+**Severity:** Medium
+**Type:** UI
+**Figma Design:** [URL to specific component]
+
+## Design vs Implementation
+
+### Expected (Figma)
+| Property | Value |
+|----------|-------|
+| Background | #0066FF |
+| Font Size | 16px |
+| Font Weight | 600 |
+| Padding | 12px 24px |
+| Border Radius | 8px |
+
+### Actual (Implementation)
+| Property | Expected | Actual | Match |
+|----------|----------|--------|-------|
+| Background | #0066FF | #0052CC | No |
+| Font Size | 16px | 16px | Yes |
+| Font Weight | 600 | 400 | No |
+| Padding | 12px 24px | 12px 24px | Yes |
+| Border Radius | 8px | 8px | Yes |
+
+## Screenshots
+
+**Figma Design:**
+[Screenshot of Figma component]
+
+**Current Implementation:**
+[Screenshot of implemented component]
+
+**Side-by-Side:**
+[Comparison image]
+
+## Impact
+Users see inconsistent branding. Component appears different from approved design.
+```
+
+---
+
+## Performance Bug Template
+
+For speed, memory, or resource issues.
+
+```markdown
+# BUG-[ID]: [Feature] Performance Degradation
+
+**Severity:** High
+**Type:** Performance
+
+## Performance Issue
+
+**Affected Area:** [Page/Feature/API]
+**User Impact:** [Page load slow / App unresponsive / High resource usage]
+
+## Metrics
+
+| Metric | Expected | Actual | Variance |
+|--------|----------|--------|----------|
+| Page Load Time | < 2s | 8s | +300% |
+| API Response | < 200ms | 1500ms | +650% |
+| Memory Usage | < 100MB | 450MB | +350% |
+| CPU Usage | < 30% | 95% | +217% |
+
+## Environment
+- Data size: [Number of records]
+- Network: [Connection type]
+- Device specs: [RAM, CPU]
+
+## Reproduction
+1. [Load page with X records]
+2. [Perform action]
+3. [Observe slow response]
+
+## Evidence
+- Performance trace: [Link]
+- Network waterfall: [Screenshot]
+- Memory profile: [Screenshot]
+
+## Baseline
+- Previous version: [v2.4.0]
+- Previous metric: [2s load time]
+- Regression since: [v2.5.0]
+```
+
+---
+
+## Security Bug Template
+
+For vulnerabilities and security concerns.
+
+```markdown
+# BUG-[ID]: [Security Issue Title]
+
+**Severity:** Critical
+**Type:** Security
+**OWASP Category:** [A01-A10]
+**CONFIDENTIAL - DO NOT SHARE PUBLICLY**
+
+## Vulnerability
+
+**Type:** [XSS / SQL Injection / Auth Bypass / etc.]
+**Risk Level:** Critical | High | Medium | Low
+**Exploitability:** [Easy / Moderate / Difficult]
+
+## Description
+[Describe the vulnerability without providing exploit code]
+
+## Impact
+- [ ] Data exposure
+- [ ] Privilege escalation
+- [ ] Account takeover
+- [ ] Service disruption
+- [ ] Other: [specify]
+
+**Affected Data:** [User PII / Payment info / etc.]
+
+## Proof of Concept
+[Describe how to verify the issue exists - sanitize any sensitive data]
+
+## Recommended Fix
+[High-level recommendation for remediation]
+
+## References
+- [CVE if applicable]
+- [OWASP reference]
+
+## Disclosure
+- Internal report date: [Date]
+- Expected fix date: [Date]
+- Public disclosure: [N/A / Date if applicable]
+```
+
+---
+
+## Crash/Error Bug Template
+
+For application crashes and unhandled errors.
+
+```markdown
+# BUG-[ID]: [Crash/Error Description]
+
+**Severity:** Critical
+**Type:** Crash
+
+## Error Details
+
+**Error Type:** [Crash / Exception / Hang / White Screen]
+**Error Message:**
+```
+[Exact error message]
+```
+
+**Stack Trace:**
+```
+[Full stack trace]
+```
+
+## Reproduction
+
+**Frequency:** [Always / Intermittent]
+
+1. [Step to trigger crash]
+2. [Step 2]
+3. [App crashes / shows error]
+
+## Environment
+- OS: [Version]
+- App Version: [Build]
+- Memory available: [If relevant]
+- Device: [Model]
+
+## Logs
+```
+[Relevant log entries before crash]
+```
+
+## Impact
+- User data lost: [Yes/No]
+- Session terminated: [Yes/No]
+- Recovery possible: [Yes/No]
+```
+
+---
+
+## Severity Definitions
+
+| Level | Criteria | Response Time | Examples |
+|-------|----------|---------------|----------|
+| **Critical** | System down, data loss, security breach | < 4 hours | Login broken, payment fails, data exposed |
+| **High** | Major feature broken, no workaround | < 24 hours | Search not working, checkout fails |
+| **Medium** | Feature partial, workaround exists | < 1 week | Filter missing option, slow load |
+| **Low** | Cosmetic, rare edge case | Next release | Typo, minor alignment, rare crash |
+
+---
+
+## Priority vs Severity Matrix
+
+| | Low Impact | Medium Impact | High Impact | Critical Impact |
+|--|-----------|---------------|-------------|-----------------|
+| **Rare** | P3 | P3 | P2 | P1 |
+| **Sometimes** | P3 | P2 | P1 | P0 |
+| **Often** | P2 | P1 | P0 | P0 |
+| **Always** | P2 | P1 | P0 | P0 |
+
+---
+
+## Bug Title Best Practices
+
+**Good Titles:**
+- "[Login] Password reset email not sent for valid email addresses"
+- "[Checkout] Cart total shows $0 when discount code applied twice"
+- "[Dashboard] Page crashes when loading more than 1000 records"
+
+**Bad Titles:**
+- "Bug in login" (too vague)
+- "It doesn't work" (no context)
+- "Please fix ASAP!!!" (emotional, no information)
+- "Minor issue" (unclear what the issue is)
+
+---
+
+## Bug Report Checklist
+
+Before submitting:
+- [ ] Title is specific and descriptive
+- [ ] Steps can be reproduced by someone else
+- [ ] Expected vs actual clearly stated
+- [ ] Environment details complete
+- [ ] Screenshots/evidence attached
+- [ ] Severity/priority assigned
+- [ ] Checked for duplicates
+- [ ] Related items linked
diff --git a/dist/plugins/qa-test-planner/skills/qa-test-planner/references/figma_validation.md b/dist/plugins/qa-test-planner/skills/qa-test-planner/references/figma_validation.md
new file mode 100644
index 0000000..4a2b9a1
--- /dev/null
+++ b/dist/plugins/qa-test-planner/skills/qa-test-planner/references/figma_validation.md
@@ -0,0 +1,345 @@
+# Figma Design Validation with MCP
+
+Guide for validating UI implementation against Figma designs using Figma MCP.
+
+---
+
+## Prerequisites
+
+**Required:**
+- Figma MCP server configured
+- Access to Figma design files
+- Figma URLs for components/pages
+
+**Setup:**
+```bash
+# Install Figma MCP (follow official docs)
+# Configure API token
+# Verify access to design files
+```
+
+---
+
+## Validation Workflow
+
+### Step 1: Get Design Specifications
+
+**Using Figma MCP:**
+```
+"Get the specifications for the primary button from Figma file at [URL]"
+
+Response includes:
+- Dimensions (width, height)
+- Colors (background, text, border)
+- Typography (font, size, weight)
+- Spacing (padding, margin)
+- Border radius
+- States (default, hover, active, disabled)
+```
+
+### Step 2: Inspect Implementation
+
+**Browser DevTools:**
+1. Inspect element
+2. Check computed styles
+3. Verify dimensions
+4. Compare colors (use color picker)
+5. Check typography
+6. Test interactive states
+
+### Step 3: Document Discrepancies
+
+**Create test case or bug:**
+```
+TC-UI-001: Primary Button Visual Validation
+
+Design (Figma):
+- Size: 120x40px
+- Background: #0066FF
+- Border-radius: 8px
+- Font: 16px Medium #FFFFFF
+
+Implementation:
+- Size: 120x40px ✓
+- Background: #0052CC ✗ (wrong shade)
+- Border-radius: 8px ✓
+- Font: 16px Regular #FFFFFF ✗ (wrong weight)
+
+Status: FAIL
+Bugs: BUG-234, BUG-235
+```
+
+---
+
+## What to Validate
+
+### Layout & Spacing
+- [ ] Component dimensions
+- [ ] Padding (all sides)
+- [ ] Margins
+- [ ] Grid alignment
+- [ ] Responsive breakpoints
+- [ ] Container max-width
+
+**Example Query:**
+```
+"Extract spacing values for the card component from Figma"
+```
+
+### Typography
+- [ ] Font family
+- [ ] Font size
+- [ ] Font weight
+- [ ] Line height
+- [ ] Letter spacing
+- [ ] Text color
+- [ ] Text alignment
+
+**Example Query:**
+```
+"Get typography specifications for all heading levels from Figma design system"
+```
+
+### Colors
+- [ ] Background colors
+- [ ] Text colors
+- [ ] Border colors
+- [ ] Shadow colors
+- [ ] Gradient values
+- [ ] Opacity values
+
+**Example Query:**
+```
+"List all color tokens used in the navigation component"
+```
+
+### Components
+- [ ] Icon sizes and colors
+- [ ] Button states
+- [ ] Input field styling
+- [ ] Checkbox/radio appearance
+- [ ] Dropdown styling
+- [ ] Card components
+
+**Example Query:**
+```
+"Compare the implemented dropdown menu with Figma design at [URL]"
+```
+
+### Interactive States
+- [ ] Default state
+- [ ] Hover state
+- [ ] Active/pressed state
+- [ ] Focus state
+- [ ] Disabled state
+- [ ] Loading state
+- [ ] Error state
+
+---
+
+## Common Discrepancies
+
+### Typography Mismatches
+- Wrong font weight (e.g., Regular instead of Medium)
+- Incorrect font size
+- Missing line-height
+- Color hex codes off by a shade
+
+### Spacing Issues
+- Padding not matching
+- Inconsistent margins
+- Grid misalignment
+- Component spacing varies
+
+### Color Differences
+- Hex values off (#0066FF vs #0052CC)
+- Opacity not applied
+- Gradient angles wrong
+- Shadow colors incorrect
+
+### Responsive Behavior
+- Breakpoints don't match
+- Mobile layout different
+- Tablet view inconsistent
+- Scaling not as designed
+
+---
+
+## Test Case Template
+
+```markdown
+## TC-UI-XXX: [Component] Visual Validation
+
+**Figma Design:** [URL to specific component]
+
+### Desktop (1920x1080)
+
+**Layout:**
+- [ ] Width: XXXpx
+- [ ] Height: XXXpx
+- [ ] Padding: XXpx XXpx XXpx XXpx
+- [ ] Margin: XXpx
+
+**Typography:**
+- [ ] Font: [Family] [Weight]
+- [ ] Size: XXpx
+- [ ] Line-height: XXpx
+- [ ] Color: #XXXXXX
+
+**Colors:**
+- [ ] Background: #XXXXXX
+- [ ] Border: Xpx solid #XXXXXX
+- [ ] Shadow: XXpx XXpx XXpx rgba(X,X,X,X)
+
+**Interactive States:**
+- [ ] Hover: [changes]
+- [ ] Active: [changes]
+- [ ] Focus: [changes]
+- [ ] Disabled: [changes]
+
+### Tablet (768px)
+- [ ] [Responsive changes]
+
+### Mobile (375px)
+- [ ] [Responsive changes]
+
+### Status
+- [ ] PASS - All match
+- [ ] FAIL - Discrepancies found
+- [ ] BLOCKED - Design incomplete
+```
+
+---
+
+## Figma MCP Queries
+
+### Component Specifications
+```
+"Get complete specifications for the [component name] from Figma at [URL]"
+"Extract all button variants from the design system"
+"List typography styles defined in Figma"
+```
+
+### Color System
+```
+"Show me all color tokens in the Figma design system"
+"What colors are used in the navigation bar design?"
+"Get the exact hex values for primary, secondary, and accent colors"
+```
+
+### Spacing & Layout
+```
+"What are the padding values for the card component?"
+"Extract grid specifications from the page layout"
+"Get spacing tokens (8px, 16px, 24px, etc.)"
+```
+
+### Responsive Breakpoints
+```
+"What are the defined breakpoints in this Figma design?"
+"Show mobile vs desktop layout differences for [component]"
+```
+
+---
+
+## Bug Report for UI Discrepancies
+
+```markdown
+# BUG-XXX: [Component] doesn't match Figma design
+
+**Severity:** Medium (UI)
+**Type:** Visual
+
+## Design vs Implementation
+
+**Figma Design:** [URL]
+
+**Expected (from Figma):**
+- Button background: #0066FF
+- Font weight: 600 (Semi-bold)
+- Padding: 12px 24px
+
+**Actual (in implementation):**
+- Button background: #0052CC ❌
+- Font weight: 400 (Regular) ❌
+- Padding: 12px 24px ✓
+
+## Screenshots
+
+- Figma design: [attach]
+- Current implementation: [attach]
+- Side-by-side comparison: [attach]
+
+## Impact
+
+Users see inconsistent branding. Button appears less prominent than designed.
+```
+
+---
+
+## Automation Ideas
+
+### Visual Regression Testing
+- Capture screenshots
+- Compare against Figma exports
+- Highlight pixel differences
+- Tools: Percy, Chromatic, BackstopJS
+
+### Design Token Validation
+- Extract Figma design tokens
+- Compare with CSS variables
+- Flag mismatches
+- Automate with scripts
+
+---
+
+## Best Practices
+
+**DO:**
+- ✅ Always reference specific Figma URLs
+- ✅ Test all component states
+- ✅ Check responsive breakpoints
+- ✅ Document exact values (not "close enough")
+- ✅ Screenshot both design and implementation
+- ✅ Test in multiple browsers
+
+**DON'T:**
+- ❌ Assume "it looks right"
+- ❌ Skip hover/active states
+- ❌ Ignore small color differences
+- ❌ Test only on one screen size
+- ❌ Forget to check typography
+- ❌ Miss spacing issues
+
+---
+
+## Checklist for UI Test Cases
+
+Per component:
+- [ ] Figma URL documented
+- [ ] Desktop layout validated
+- [ ] Mobile/tablet responsive checked
+- [ ] All interactive states tested
+- [ ] Colors match exactly (use color picker)
+- [ ] Typography specifications correct
+- [ ] Spacing (padding/margins) accurate
+- [ ] Icons match design
+- [ ] Shadows/borders match
+- [ ] Animations match timing/easing
+
+---
+
+## Quick Reference
+
+| Element | What to Check | Tool |
+|---------|---------------|------|
+| Colors | Hex values exact | Browser color picker |
+| Spacing | Padding/margin px | DevTools computed styles |
+| Typography | Font, size, weight | DevTools font panel |
+| Layout | Width, height, position | DevTools box model |
+| States | Hover, active, focus | Manual interaction |
+| Responsive | Breakpoint behavior | DevTools device mode |
+
+---
+
+**Remember:** Pixel-perfect implementation builds user trust and brand consistency.
diff --git a/dist/plugins/qa-test-planner/skills/qa-test-planner/references/regression_testing.md b/dist/plugins/qa-test-planner/skills/qa-test-planner/references/regression_testing.md
new file mode 100644
index 0000000..eba0e77
--- /dev/null
+++ b/dist/plugins/qa-test-planner/skills/qa-test-planner/references/regression_testing.md
@@ -0,0 +1,371 @@
+# Regression Testing Guide
+
+Comprehensive guide to regression testing strategies and execution.
+
+---
+
+## What is Regression Testing?
+
+**Definition:** Re-testing existing functionality to ensure new changes haven't broken anything.
+
+**When to run:**
+- Before every release
+- After bug fixes
+- After new features
+- After refactoring
+- Weekly/nightly builds
+
+---
+
+## Regression Test Suite Structure
+
+### 1. Smoke Test Suite (15-30 min)
+
+**Purpose:** Quick sanity check
+
+**When:** Daily, before detailed testing
+
+**Coverage:**
+- Critical user paths
+- Core functionality
+- System health checks
+- Build stability
+
+**Example Smoke Suite:**
+```
+SMOKE-001: User can login
+SMOKE-002: User can navigate to main features
+SMOKE-003: Critical API endpoints respond
+SMOKE-004: Database connectivity works
+SMOKE-005: User can complete primary action
+SMOKE-006: User can logout
+```
+
+### 2. Full Regression Suite (2-4 hours)
+
+**Purpose:** Comprehensive validation
+
+**When:** Before releases, weekly
+
+**Coverage:**
+- All functional test cases
+- Integration scenarios
+- UI validation
+- Data integrity
+- Security checks
+
+### 3. Targeted Regression (30-60 min)
+
+**Purpose:** Test impacted areas
+
+**When:** After specific changes
+
+**Coverage:**
+- Modified feature area
+- Related components
+- Integration points
+- Dependent functionality
+
+---
+
+## Building a Regression Suite
+
+### Step 1: Identify Critical Paths
+
+**Questions:**
+- What can users absolutely NOT live without?
+- What generates revenue?
+- What handles sensitive data?
+- What's used most frequently?
+
+**Example Critical Paths:**
+- User authentication
+- Payment processing
+- Data submission
+- Report generation
+- Core business logic
+
+### Step 2: Prioritize Test Cases
+
+**P0 (Must Run):**
+- Business-critical functionality
+- Security-related tests
+- Data integrity checks
+- Revenue-impacting features
+
+**P1 (Should Run):**
+- Major features
+- Common user flows
+- Integration points
+- Performance checks
+
+**P2 (Nice to Run):**
+- Minor features
+- Edge cases
+- UI polish
+- Optional functionality
+
+### Step 3: Group by Feature Area
+
+```
+Authentication & Authorization
+├─ Login/Logout
+├─ Password reset
+├─ Session management
+└─ Permissions
+
+Payment Processing
+├─ Checkout flow
+├─ Payment methods
+├─ Refunds
+└─ Receipt generation
+
+User Management
+├─ Profile updates
+├─ Preferences
+├─ Account settings
+└─ Data export
+```
+
+---
+
+## Regression Suite Examples
+
+### E-commerce Regression Suite
+
+**Smoke Tests (20 min):**
+1. Homepage loads
+2. User can login
+3. Product search works
+4. Add to cart functions
+5. Checkout accessible
+6. Payment gateway responds
+
+**Full Regression (3 hours):**
+
+**User Account (30 min):**
+- Registration
+- Login/Logout
+- Password reset
+- Profile updates
+- Address management
+
+**Product Catalog (45 min):**
+- Browse categories
+- Search functionality
+- Filters and sorting
+- Product details
+- Image zoom
+- Reviews display
+
+**Shopping Cart (30 min):**
+- Add items
+- Update quantities
+- Remove items
+- Apply discounts
+- Save for later
+- Cart persistence
+
+**Checkout & Payment (45 min):**
+- Guest checkout
+- Registered user checkout
+- Multiple addresses
+- Payment methods
+- Order confirmation
+- Email notifications
+
+**Order Management (30 min):**
+- Order history
+- Order tracking
+- Cancellations
+- Returns/Refunds
+- Reorders
+
+---
+
+## Execution Strategy
+
+### Test Execution Order
+
+**1. Smoke first**
+- If smoke fails → stop, fix build
+- If smoke passes → proceed to full regression
+
+**2. P0 tests next**
+- Critical functionality
+- Must pass before proceeding
+
+**3. P1 then P2**
+- Complete remaining tests
+- Track failures
+
+**4. Exploratory**
+- Unscripted testing
+- Find unexpected issues
+
+### Pass/Fail Criteria
+
+**PASS:**
+- All P0 tests pass
+- 90%+ P1 tests pass
+- No critical bugs open
+- Performance acceptable
+
+**FAIL (Block Release):**
+- Any P0 test fails
+- Critical bug discovered
+- Security vulnerability
+- Data loss scenario
+
+**CONDITIONAL PASS:**
+- P1 failures with workarounds
+- Known issues documented
+- Fix plan in place
+
+---
+
+## Regression Test Management
+
+### Test Suite Maintenance
+
+**Monthly Review:**
+- Remove obsolete tests
+- Update changed functionality
+- Add new critical paths
+- Optimize slow tests
+
+**After Each Release:**
+- Update test data
+- Fix broken tests
+- Add regression for bugs found
+- Document changes
+
+### Automation Considerations
+
+**Good Candidates for Automation:**
+- Stable, repetitive tests
+- Smoke tests
+- API tests
+- Data validation
+- Cross-browser checks
+
+**Keep Manual:**
+- Exploratory testing
+- Usability evaluation
+- Visual design validation
+- Complex user scenarios
+
+---
+
+## Regression Test Execution Report
+
+```markdown
+# Regression Test Report: Release 2.5.0
+
+**Date:** 2024-01-15
+**Build:** v2.5.0-rc1
+**Tester:** QA Team
+**Environment:** Staging
+
+## Summary
+
+| Suite | Total | Pass | Fail | Blocked | Pass Rate |
+|-------|-------|------|------|---------|-----------|
+| Smoke | 10 | 10 | 0 | 0 | 100% |
+| P0 Critical | 25 | 23 | 2 | 0 | 92% |
+| P1 High | 50 | 47 | 2 | 1 | 94% |
+| P2 Medium | 40 | 38 | 1 | 1 | 95% |
+| **TOTAL** | **125** | **118** | **5** | **2** | **94%** |
+
+## Critical Failures (P0)
+
+### BUG-234: Payment processing fails for Visa
+- **Test:** TC-PAY-001
+- **Impact:** High - Blocks 40% of transactions
+- **Status:** In Progress
+- **ETA:** 2024-01-16
+
+### BUG-235: User session expires prematurely
+- **Test:** TC-AUTH-045
+- **Impact:** Medium - Users logged out unexpectedly
+- **Status:** Under investigation
+
+## Recommendation
+
+**Status:** ⚠️ CONDITIONAL GO
+- Fix BUG-234 (payment) before release
+- BUG-235 acceptable with documented workaround
+- Retest after fixes
+- Final regression run before production deployment
+
+## Risks
+
+- Payment issue could impact revenue
+- Session bug may frustrate users
+- Limited time before release deadline
+
+## Next Steps
+
+1. Fix BUG-234 by EOD
+2. Retest payment flow
+3. Document session workaround
+4. Final smoke test before release
+```
+
+---
+
+## Common Pitfalls
+
+**❌ Don't:**
+- Run same tests without updating
+- Skip regression "to save time"
+- Ignore failures in low-priority tests
+- Test only happy paths
+- Forget to update test data
+- Run regression once and forget
+
+**✅ Do:**
+- Maintain suite regularly
+- Run regression consistently
+- Investigate all failures
+- Include edge cases
+- Keep test data fresh
+- Automate repetitive tests
+
+---
+
+## Regression Checklist
+
+**Before Execution:**
+- [ ] Test environment ready
+- [ ] Build deployed
+- [ ] Test data prepared
+- [ ] Previous bugs verified fixed
+- [ ] Test suite reviewed/updated
+
+**During Execution:**
+- [ ] Follow test execution order
+- [ ] Document all failures
+- [ ] Screenshot/record issues
+- [ ] Note unexpected behavior
+- [ ] Track blockers
+
+**After Execution:**
+- [ ] Compile results
+- [ ] File new bugs
+- [ ] Update test cases
+- [ ] Report to stakeholders
+- [ ] Archive artifacts
+
+---
+
+## Quick Reference
+
+| Suite Type | Duration | Frequency | Coverage |
+|------------|----------|-----------|----------|
+| Smoke | 15-30 min | Daily | Critical paths |
+| Targeted | 30-60 min | Per change | Affected areas |
+| Full | 2-4 hours | Weekly/Release | Comprehensive |
+| Sanity | 10-15 min | After hotfix | Quick validation |
+
+**Remember:** Regression testing is insurance against breaking existing functionality.
diff --git a/dist/plugins/qa-test-planner/skills/qa-test-planner/references/test_case_templates.md b/dist/plugins/qa-test-planner/skills/qa-test-planner/references/test_case_templates.md
new file mode 100644
index 0000000..a78ef42
--- /dev/null
+++ b/dist/plugins/qa-test-planner/skills/qa-test-planner/references/test_case_templates.md
@@ -0,0 +1,430 @@
+# Test Case Templates
+
+Standard templates for creating consistent, comprehensive test cases.
+
+---
+
+## Standard Test Case Template
+
+```markdown
+## TC-[ID]: [Test Case Title]
+
+**Priority:** P0 (Critical) | P1 (High) | P2 (Medium) | P3 (Low)
+**Type:** Functional | UI | Integration | Regression | Performance | Security
+**Status:** Not Run | Pass | Fail | Blocked | Skipped
+**Estimated Time:** X minutes
+**Created:** YYYY-MM-DD
+**Last Updated:** YYYY-MM-DD
+
+---
+
+### Objective
+
+[Clear statement of what this test validates and why it matters]
+
+---
+
+### Preconditions
+
+- [ ] [Setup requirement 1]
+- [ ] [Setup requirement 2]
+- [ ] [Test data/accounts needed]
+- [ ] [Environment configuration]
+
+---
+
+### Test Steps
+
+1. **[Action to perform]**
+ - Input: [specific data if any]
+ - **Expected:** [What should happen]
+
+2. **[Action to perform]**
+ - Input: [specific data if any]
+ - **Expected:** [What should happen]
+
+3. **[Action to perform]**
+ - Input: [specific data if any]
+ - **Expected:** [What should happen]
+
+---
+
+### Test Data
+
+| Field | Value | Notes |
+|-------|-------|-------|
+| [Field 1] | [Value] | [Any special handling] |
+| [Field 2] | [Value] | [Any special handling] |
+
+**Test Account:**
+- Username: [test user]
+- Password: [test password]
+- Role: [user type]
+
+---
+
+### Post-conditions
+
+- [System state after successful test]
+- [Cleanup required]
+- [Data to verify/restore]
+
+---
+
+### Edge Cases & Variations
+
+| Variation | Input | Expected Result |
+|-----------|-------|-----------------|
+| Empty input | "" | Validation error shown |
+| Max length | 256 chars | Accepted/Truncated |
+| Special chars | @#$% | Handled correctly |
+
+---
+
+### Related Test Cases
+
+- TC-XXX: [Related scenario]
+- TC-YYY: [Prerequisite test]
+
+---
+
+### Execution History
+
+| Date | Tester | Build | Result | Bug ID | Notes |
+|------|--------|-------|--------|--------|-------|
+| | | | | | |
+
+---
+
+### Notes
+
+[Additional context, known issues, or considerations]
+```
+
+---
+
+## Functional Test Case Template
+
+For testing business logic and feature functionality.
+
+```markdown
+## TC-FUNC-[ID]: [Feature] - [Scenario]
+
+**Priority:** P[0-3]
+**Type:** Functional
+**Module:** [Feature/Module name]
+**Requirement:** REQ-XXX
+
+### Objective
+Verify that [feature] behaves correctly when [scenario]
+
+### Preconditions
+- User logged in as [role]
+- [Feature prerequisite]
+- Test data: [dataset]
+
+### Test Steps
+
+1. Navigate to [page/feature]
+ **Expected:** [Page loads correctly]
+
+2. Perform [action]
+ **Input:** [test data]
+ **Expected:** [System response]
+
+3. Verify [result]
+ **Expected:** [Success criteria]
+
+### Boundary Tests
+- Minimum value: [test]
+- Maximum value: [test]
+- Null/empty: [test]
+
+### Negative Tests
+- Invalid input: [test]
+- Unauthorized access: [test]
+- Missing required fields: [test]
+```
+
+---
+
+## UI/Visual Test Case Template
+
+For validating visual appearance and design compliance.
+
+```markdown
+## TC-UI-[ID]: [Component/Page] Visual Validation
+
+**Priority:** P[0-3]
+**Type:** UI/Visual
+**Figma Design:** [URL]
+**Breakpoints:** Desktop | Tablet | Mobile
+
+### Objective
+Verify [component] matches Figma design specifications
+
+### Preconditions
+- Browser: [Chrome/Firefox/Safari]
+- Screen resolution: [specified]
+- Theme: [Light/Dark]
+
+### Visual Specifications
+
+**Layout:**
+| Property | Expected | Actual | Status |
+|----------|----------|--------|--------|
+| Width | XXXpx | | [ ] |
+| Height | XXXpx | | [ ] |
+| Padding | XX XX XX XX | | [ ] |
+| Margin | XX XX XX XX | | [ ] |
+
+**Typography:**
+| Property | Expected | Actual | Status |
+|----------|----------|--------|--------|
+| Font | [Family] | | [ ] |
+| Size | XXpx | | [ ] |
+| Weight | XXX | | [ ] |
+| Line-height | XXpx | | [ ] |
+| Color | #XXXXXX | | [ ] |
+
+**Colors:**
+| Element | Expected | Actual | Status |
+|---------|----------|--------|--------|
+| Background | #XXXXXX | | [ ] |
+| Border | #XXXXXX | | [ ] |
+| Text | #XXXXXX | | [ ] |
+
+**Interactive States:**
+- [ ] Default state matches design
+- [ ] Hover state matches design
+- [ ] Active/pressed state matches design
+- [ ] Focus state matches design
+- [ ] Disabled state matches design
+
+### Responsive Checks
+
+**Desktop (1920px):**
+- [ ] Layout correct
+- [ ] All elements visible
+
+**Tablet (768px):**
+- [ ] Layout adapts correctly
+- [ ] Touch targets adequate
+
+**Mobile (375px):**
+- [ ] Layout stacks correctly
+- [ ] Content readable
+- [ ] Navigation accessible
+```
+
+---
+
+## Integration Test Case Template
+
+For testing component interactions and data flow.
+
+```markdown
+## TC-INT-[ID]: [System A] to [System B] Integration
+
+**Priority:** P[0-3]
+**Type:** Integration
+**Systems:** [List integrated systems]
+**API Endpoint:** [endpoint if applicable]
+
+### Objective
+Verify data flows correctly from [source] to [destination]
+
+### Preconditions
+- [System A] running
+- [System B] running
+- Test credentials configured
+- Network connectivity verified
+
+### Test Steps
+
+1. Trigger [action] in [System A]
+ **Input:** [data payload]
+ **Expected:** Request sent to [System B]
+
+2. Verify [System B] receives data
+ **Expected:**
+ - Status code: 200
+ - Response format: JSON
+ - Data transformation correct
+
+3. Verify [System A] handles response
+ **Expected:** [UI update/confirmation]
+
+### Data Validation
+| Field | Source Value | Transformed Value | Status |
+|-------|--------------|-------------------|--------|
+| [field1] | [value] | [expected] | [ ] |
+| [field2] | [value] | [expected] | [ ] |
+
+### Error Scenarios
+- [ ] Network timeout handling
+- [ ] Invalid response handling
+- [ ] Authentication failure handling
+- [ ] Rate limiting handling
+```
+
+---
+
+## Regression Test Case Template
+
+For ensuring existing functionality remains intact.
+
+```markdown
+## TC-REG-[ID]: [Feature] Regression
+
+**Priority:** P[0-3]
+**Type:** Regression
+**Original Feature:** [Feature name]
+**Last Modified:** [Date]
+
+### Objective
+Verify [feature] still works correctly after recent changes
+
+### Context
+Recent changes that may affect this feature:
+- [Change 1]
+- [Change 2]
+
+### Critical Path Tests
+
+1. [ ] Core functionality works
+2. [ ] Data persistence correct
+3. [ ] UI renders properly
+4. [ ] Error handling intact
+
+### Integration Points
+- [ ] [Dependent feature 1] still works
+- [ ] [Dependent feature 2] still works
+- [ ] API contracts unchanged
+
+### Performance Baseline
+- Expected load time: < Xs
+- Expected response time: < Xms
+```
+
+---
+
+## Security Test Case Template
+
+For validating security controls and vulnerabilities.
+
+```markdown
+## TC-SEC-[ID]: [Security Control] Validation
+
+**Priority:** P0 (Critical)
+**Type:** Security
+**OWASP Category:** [A01-A10]
+**Risk Level:** Critical | High | Medium | Low
+
+### Objective
+Verify [security control] prevents [vulnerability/attack]
+
+### Preconditions
+- Test account with [role]
+- Security testing tools configured
+- Audit logging enabled
+
+### Test Steps
+
+1. Attempt [attack vector]
+ **Input:** [malicious payload]
+ **Expected:** Request blocked/sanitized
+
+2. Verify security control response
+ **Expected:**
+ - Error message: Generic (no info leak)
+ - Log entry: Attack attempt recorded
+ - Account: Not compromised
+
+### Attack Vectors
+- [ ] SQL injection
+- [ ] XSS (stored/reflected)
+- [ ] CSRF
+- [ ] Authentication bypass
+- [ ] Authorization escalation
+
+### Compliance Check
+- [ ] [Regulation] requirement met
+- [ ] Audit trail complete
+- [ ] Data encrypted
+```
+
+---
+
+## Performance Test Case Template
+
+For validating speed, scalability, and resource usage.
+
+```markdown
+## TC-PERF-[ID]: [Feature] Performance
+
+**Priority:** P[0-3]
+**Type:** Performance
+**Baseline:** [Previous metrics]
+
+### Objective
+Verify [feature] meets performance requirements
+
+### Preconditions
+- Load testing tool configured
+- Baseline metrics recorded
+- Test environment isolated
+
+### Performance Criteria
+
+| Metric | Target | Acceptable | Actual | Status |
+|--------|--------|------------|--------|--------|
+| Response time | < 200ms | < 500ms | | [ ] |
+| Throughput | > 1000 req/s | > 500 req/s | | [ ] |
+| Error rate | < 0.1% | < 1% | | [ ] |
+| CPU usage | < 70% | < 85% | | [ ] |
+| Memory usage | < 70% | < 85% | | [ ] |
+
+### Load Scenarios
+
+1. **Normal load:** X concurrent users
+ - Duration: 5 minutes
+ - Expected: All metrics within target
+
+2. **Peak load:** Y concurrent users
+ - Duration: 10 minutes
+ - Expected: All metrics within acceptable
+
+3. **Stress test:** Z concurrent users
+ - Duration: Until failure
+ - Expected: Graceful degradation
+
+### Results
+[Document actual results and comparison to baseline]
+```
+
+---
+
+## Quick Reference: Test Case Naming
+
+| Type | Prefix | Example |
+|------|--------|---------|
+| Functional | TC-FUNC- | TC-FUNC-001 |
+| UI/Visual | TC-UI- | TC-UI-045 |
+| Integration | TC-INT- | TC-INT-012 |
+| Regression | TC-REG- | TC-REG-089 |
+| Security | TC-SEC- | TC-SEC-005 |
+| Performance | TC-PERF- | TC-PERF-023 |
+| API | TC-API- | TC-API-067 |
+| Smoke | SMOKE- | SMOKE-001 |
+
+---
+
+## Priority Definitions
+
+| Priority | Description | When to Run |
+|----------|-------------|-------------|
+| P0 | Critical path, blocks release | Every build |
+| P1 | Major features, high impact | Daily/Weekly |
+| P2 | Standard features, moderate impact | Weekly/Release |
+| P3 | Minor features, low impact | Release only |
diff --git a/dist/plugins/qa-test-planner/skills/qa-test-planner/scripts/create_bug_report.sh b/dist/plugins/qa-test-planner/skills/qa-test-planner/scripts/create_bug_report.sh
new file mode 100755
index 0000000..921cdf2
--- /dev/null
+++ b/dist/plugins/qa-test-planner/skills/qa-test-planner/scripts/create_bug_report.sh
@@ -0,0 +1,276 @@
+#!/bin/bash
+
+# Bug Report Generator
+# Create structured, reproducible bug reports
+
+set -e
+
+# Colors
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+MAGENTA='\033[0;35m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+echo -e "${RED}╔══════════════════════════════════════════════════╗${NC}"
+echo -e "${RED}║ Bug Report Generator ║${NC}"
+echo -e "${RED}╚══════════════════════════════════════════════════╝${NC}"
+echo ""
+
+prompt_input() {
+ local prompt_text="$1"
+ local var_name="$2"
+ local required="$3"
+
+ while true; do
+ echo -e "${CYAN}${prompt_text}${NC}"
+ read -r input
+
+ if [ -n "$input" ]; then
+ eval "$var_name=\"$input\""
+ break
+ elif [ "$required" != "true" ]; then
+ eval "$var_name=\"\""
+ break
+ else
+ echo -e "${RED}This field is required.${NC}"
+ fi
+ done
+}
+
+# Bug ID
+BUG_ID="BUG-$(date +%Y%m%d%H%M%S)"
+echo -e "${YELLOW}Auto-generated Bug ID: $BUG_ID${NC}"
+echo ""
+
+# Basic Info
+prompt_input "Bug title (clear, specific):" BUG_TITLE true
+
+echo ""
+echo "Severity:"
+echo "1) Critical - System crash, data loss, security issue"
+echo "2) High - Major feature broken, no workaround"
+echo "3) Medium - Feature partially broken, workaround exists"
+echo "4) Low - Cosmetic, minor inconvenience"
+echo ""
+
+prompt_input "Select severity (1-4):" SEVERITY_NUM true
+
+case $SEVERITY_NUM in
+ 1) SEVERITY="Critical" ;;
+ 2) SEVERITY="High" ;;
+ 3) SEVERITY="Medium" ;;
+ 4) SEVERITY="Low" ;;
+ *) SEVERITY="Medium" ;;
+esac
+
+echo ""
+echo "Priority:"
+echo "1) P0 - Blocks release"
+echo "2) P1 - Fix before release"
+echo "3) P2 - Fix in next release"
+echo "4) P3 - Fix when possible"
+echo ""
+
+prompt_input "Select priority (1-4):" PRIORITY_NUM true
+
+case $PRIORITY_NUM in
+ 1) PRIORITY="P0" ;;
+ 2) PRIORITY="P1" ;;
+ 3) PRIORITY="P2" ;;
+ 4) PRIORITY="P3" ;;
+ *) PRIORITY="P2" ;;
+esac
+
+# Environment
+echo ""
+echo -e "${MAGENTA}━━━ Environment Details ━━━${NC}"
+echo ""
+
+prompt_input "Operating System (e.g., Windows 11, macOS 14):" OS true
+prompt_input "Browser & Version (e.g., Chrome 120, Firefox 121):" BROWSER true
+prompt_input "Device (e.g., Desktop, iPhone 15):" DEVICE false
+prompt_input "Build/Version number:" BUILD true
+prompt_input "URL or page where bug occurs:" URL false
+
+# Bug Description
+echo ""
+echo -e "${MAGENTA}━━━ Bug Description ━━━${NC}"
+echo ""
+
+prompt_input "Brief description of the issue:" DESCRIPTION true
+
+# Reproduction Steps
+echo ""
+echo -e "${MAGENTA}━━━ Steps to Reproduce ━━━${NC}"
+echo ""
+
+echo "Enter reproduction steps (one per line, press Enter twice when done):"
+REPRO_STEPS=""
+STEP_NUM=1
+while true; do
+ read -r line
+ if [ -z "$line" ]; then
+ break
+ fi
+ REPRO_STEPS="${REPRO_STEPS}${STEP_NUM}. ${line}\n"
+ ((STEP_NUM++))
+done
+
+# Expected vs Actual
+echo ""
+prompt_input "Expected behavior:" EXPECTED true
+prompt_input "Actual behavior:" ACTUAL true
+
+# Additional Info
+echo ""
+echo -e "${MAGENTA}━━━ Additional Information ━━━${NC}"
+echo ""
+
+prompt_input "Console errors (paste if any):" CONSOLE_ERRORS false
+prompt_input "Frequency (Always/Sometimes/Rare):" FREQUENCY false
+prompt_input "How many users affected (estimate):" USER_IMPACT false
+prompt_input "Workaround available? (describe if yes):" WORKAROUND false
+prompt_input "Related test case ID:" TEST_CASE false
+prompt_input "Figma design link (if UI bug):" FIGMA_LINK false
+prompt_input "First noticed (date/build):" FIRST_NOTICED false
+
+FILENAME="${BUG_ID}.md"
+
+OUTPUT_DIR="."
+if [ ! -z "$1" ]; then
+ OUTPUT_DIR="$1"
+fi
+
+OUTPUT_FILE="$OUTPUT_DIR/$FILENAME"
+
+echo ""
+echo -e "${BLUE}Generating bug report...${NC}"
+echo ""
+
+cat > "$OUTPUT_FILE" << EOF
+# ${BUG_ID}: ${BUG_TITLE}
+
+**Severity:** ${SEVERITY}
+**Priority:** ${PRIORITY}
+**Type:** ${TEST_TYPE:-Functional}
+**Status:** Open
+**Reported:** $(date +%Y-%m-%d)
+**Reporter:** [Your Name]
+
+---
+
+## Environment
+
+- **OS:** ${OS}
+- **Browser:** ${BROWSER}
+- **Device:** ${DEVICE:-Desktop}
+- **Build:** ${BUILD}
+- **URL:** ${URL:-N/A}
+
+---
+
+## Description
+
+${DESCRIPTION}
+
+---
+
+## Steps to Reproduce
+
+${REPRO_STEPS}
+
+---
+
+## Expected Behavior
+
+${EXPECTED}
+
+---
+
+## Actual Behavior
+
+${ACTUAL}
+
+---
+
+## Visual Evidence
+
+- [ ] Screenshot attached
+- [ ] Screen recording attached
+- [ ] Console logs attached
+
+**Console Errors:**
+\`\`\`
+${CONSOLE_ERRORS:-None}
+\`\`\`
+
+---
+
+## Impact
+
+- **Frequency:** ${FREQUENCY:-Unknown}
+- **User Impact:** ${USER_IMPACT:-Unknown}
+- **Workaround:** ${WORKAROUND:-None available}
+
+---
+
+## Additional Context
+
+${FIGMA_LINK:+**Figma Design:** ${FIGMA_LINK}}
+
+${TEST_CASE:+**Related Test Case:** ${TEST_CASE}}
+
+${FIRST_NOTICED:+**First Noticed:** ${FIRST_NOTICED}}
+
+**Is this a regression?** [Yes/No - if yes, since when]
+
+---
+
+## Root Cause
+
+[To be filled by developer]
+
+---
+
+## Fix
+
+[To be filled by developer]
+
+---
+
+## Verification
+
+- [ ] Bug fix verified in dev environment
+- [ ] Regression testing completed
+- [ ] Related test cases passing
+- [ ] Ready for release
+
+**Verified By:** ___________
+**Date:** ___________
+
+---
+
+## Comments
+
+[Discussion and updates]
+
+EOF
+
+echo -e "${GREEN}✅ Bug report generated successfully!${NC}"
+echo ""
+echo -e "File location: ${BLUE}$OUTPUT_FILE${NC}"
+echo ""
+echo -e "${RED}⚠️ IMPORTANT NEXT STEPS:${NC}"
+echo "1. Attach screenshots/screen recordings"
+echo "2. Add console errors if available"
+echo "3. Verify reproduction steps work"
+echo "4. Submit to bug tracking system"
+if [ -n "$FIGMA_LINK" ]; then
+ echo "5. Verify against Figma design"
+fi
+echo ""
+echo -e "${CYAN}Tip: Clear, reproducible steps = faster fixes${NC}"
+echo ""
diff --git a/dist/plugins/qa-test-planner/skills/qa-test-planner/scripts/generate_test_cases.sh b/dist/plugins/qa-test-planner/skills/qa-test-planner/scripts/generate_test_cases.sh
new file mode 100755
index 0000000..a257be9
--- /dev/null
+++ b/dist/plugins/qa-test-planner/skills/qa-test-planner/scripts/generate_test_cases.sh
@@ -0,0 +1,302 @@
+#!/bin/bash
+
+# Manual Test Case Generator
+# Interactive workflow for creating comprehensive test cases
+
+set -e
+
+# Colors
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+MAGENTA='\033[0;35m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+echo -e "${BLUE}╔══════════════════════════════════════════════════╗${NC}"
+echo -e "${BLUE}║ Manual Test Case Generator ║${NC}"
+echo -e "${BLUE}╚══════════════════════════════════════════════════╝${NC}"
+echo ""
+
+# Helper functions
+prompt_input() {
+ local prompt_text="$1"
+ local var_name="$2"
+ local required="$3"
+
+ while true; do
+ echo -e "${CYAN}${prompt_text}${NC}"
+ read -r input
+
+ if [ -n "$input" ]; then
+ eval "$var_name=\"$input\""
+ break
+ elif [ "$required" != "true" ]; then
+ eval "$var_name=\"\""
+ break
+ else
+ echo -e "${RED}This field is required.${NC}"
+ fi
+ done
+}
+
+# Step 1: Basic Info
+echo -e "${MAGENTA}━━━ Step 1: Test Case Basics ━━━${NC}"
+echo ""
+
+prompt_input "Test Case ID (e.g., TC-LOGIN-001):" TC_ID true
+prompt_input "Test Case Title:" TC_TITLE true
+
+echo ""
+echo "Priority:"
+echo "1) P0 - Critical (blocks release)"
+echo "2) P1 - High (important features)"
+echo "3) P2 - Medium (nice to have)"
+echo "4) P3 - Low (minor issues)"
+echo ""
+
+prompt_input "Select priority (1-4):" PRIORITY_NUM true
+
+case $PRIORITY_NUM in
+ 1) PRIORITY="P0 (Critical)" ;;
+ 2) PRIORITY="P1 (High)" ;;
+ 3) PRIORITY="P2 (Medium)" ;;
+ 4) PRIORITY="P3 (Low)" ;;
+ *) PRIORITY="P2 (Medium)" ;;
+esac
+
+echo ""
+echo "Test Type:"
+echo "1) Functional"
+echo "2) UI/Visual"
+echo "3) Integration"
+echo "4) Regression"
+echo "5) Performance"
+echo "6) Security"
+echo ""
+
+prompt_input "Select test type (1-6):" TYPE_NUM true
+
+case $TYPE_NUM in
+ 1) TEST_TYPE="Functional" ;;
+ 2) TEST_TYPE="UI/Visual" ;;
+ 3) TEST_TYPE="Integration" ;;
+ 4) TEST_TYPE="Regression" ;;
+ 5) TEST_TYPE="Performance" ;;
+ 6) TEST_TYPE="Security" ;;
+ *) TEST_TYPE="Functional" ;;
+esac
+
+prompt_input "Estimated test time (minutes):" EST_TIME false
+
+# Step 2: Objective and Description
+echo ""
+echo -e "${MAGENTA}━━━ Step 2: Test Objective ━━━${NC}"
+echo ""
+
+prompt_input "What are you testing? (objective):" OBJECTIVE true
+prompt_input "Why is this test important?" WHY_IMPORTANT false
+
+# Step 3: Preconditions
+echo ""
+echo -e "${MAGENTA}━━━ Step 3: Preconditions ━━━${NC}"
+echo ""
+
+echo "Enter preconditions (one per line, press Enter twice when done):"
+PRECONDITIONS=""
+while true; do
+ read -r line
+ if [ -z "$line" ]; then
+ break
+ fi
+ PRECONDITIONS="${PRECONDITIONS}- ${line}\n"
+done
+
+# Step 4: Test Steps
+echo ""
+echo -e "${MAGENTA}━━━ Step 4: Test Steps ━━━${NC}"
+echo ""
+
+echo "Enter test steps (format: action | expected result)"
+echo "Type 'done' when finished"
+echo ""
+
+TEST_STEPS=""
+STEP_NUM=1
+
+while true; do
+ echo -e "${YELLOW}Step $STEP_NUM:${NC}"
+ prompt_input "Action:" ACTION false
+
+ if [ "$ACTION" = "done" ] || [ -z "$ACTION" ]; then
+ break
+ fi
+
+ prompt_input "Expected result:" EXPECTED true
+
+ TEST_STEPS="${TEST_STEPS}${STEP_NUM}. ${ACTION}\n **Expected:** ${EXPECTED}\n\n"
+ ((STEP_NUM++))
+done
+
+# Step 5: Test Data
+echo ""
+echo -e "${MAGENTA}━━━ Step 5: Test Data ━━━${NC}"
+echo ""
+
+prompt_input "Test data required (e.g., user credentials, sample data):" TEST_DATA false
+
+# Step 6: Figma Design (if UI test)
+echo ""
+if [ "$TEST_TYPE" = "UI/Visual" ]; then
+ echo -e "${MAGENTA}━━━ Step 6: Figma Design Validation ━━━${NC}"
+ echo ""
+
+ prompt_input "Figma design URL (if applicable):" FIGMA_URL false
+ prompt_input "Visual elements to validate:" VISUAL_CHECKS false
+fi
+
+# Step 7: Edge Cases
+echo ""
+echo -e "${MAGENTA}━━━ Step 7: Additional Info ━━━${NC}"
+echo ""
+
+prompt_input "Edge cases or variations to consider:" EDGE_CASES false
+prompt_input "Related test cases (IDs):" RELATED_TCS false
+prompt_input "Notes or comments:" NOTES false
+
+# Generate filename
+FILENAME="${TC_ID}.md"
+FILENAME="${FILENAME//[^a-zA-Z0-9_-]/}"
+
+OUTPUT_DIR="."
+if [ ! -z "$1" ]; then
+ OUTPUT_DIR="$1"
+fi
+
+OUTPUT_FILE="$OUTPUT_DIR/$FILENAME"
+
+# Generate test case
+echo ""
+echo -e "${BLUE}Generating test case...${NC}"
+echo ""
+
+cat > "$OUTPUT_FILE" << EOF
+# ${TC_ID}: ${TC_TITLE}
+
+**Priority:** ${PRIORITY}
+**Type:** ${TEST_TYPE}
+**Status:** Not Run
+**Estimated Time:** ${EST_TIME:-TBD} minutes
+**Created:** $(date +%Y-%m-%d)
+
+---
+
+## Objective
+
+${OBJECTIVE}
+
+${WHY_IMPORTANT:+**Why this matters:** ${WHY_IMPORTANT}}
+
+---
+
+## Preconditions
+
+${PRECONDITIONS}
+
+---
+
+## Test Steps
+
+${TEST_STEPS}
+
+---
+
+## Test Data
+
+${TEST_DATA:-No specific test data required}
+
+---
+
+EOF
+
+# Add Figma section if UI test
+if [ "$TEST_TYPE" = "UI/Visual" ] && [ -n "$FIGMA_URL" ]; then
+ cat >> "$OUTPUT_FILE" << EOF
+## Visual Validation (Figma)
+
+**Design Reference:** ${FIGMA_URL}
+
+**Elements to validate:**
+${VISUAL_CHECKS}
+
+**Verification checklist:**
+- [ ] Layout matches Figma design
+- [ ] Spacing (padding/margins) accurate
+- [ ] Typography (font, size, weight, color) correct
+- [ ] Colors match design system
+- [ ] Component states (hover, active, disabled) implemented
+- [ ] Responsive behavior as designed
+
+---
+
+EOF
+fi
+
+cat >> "$OUTPUT_FILE" << EOF
+## Post-conditions
+
+- [Describe system state after test execution]
+- [Any cleanup required]
+
+---
+
+## Edge Cases & Variations
+
+${EDGE_CASES:-Consider boundary values, null inputs, special characters, concurrent users}
+
+---
+
+## Related Test Cases
+
+${RELATED_TCS:-None}
+
+---
+
+## Execution History
+
+| Date | Tester | Build | Result | Notes |
+|------|--------|-------|--------|-------|
+| | | | Not Run | |
+
+---
+
+## Notes
+
+${NOTES}
+
+---
+
+## Attachments
+
+- [ ] Screenshots
+- [ ] Screen recordings
+- [ ] Console logs
+- [ ] Network traces
+
+EOF
+
+echo -e "${GREEN}✅ Test case generated successfully!${NC}"
+echo ""
+echo -e "File location: ${BLUE}$OUTPUT_FILE${NC}"
+echo ""
+echo -e "${YELLOW}Next steps:${NC}"
+echo "1. Review test case for completeness"
+echo "2. Add to test suite"
+echo "3. Execute test and update results"
+if [ "$TEST_TYPE" = "UI/Visual" ] && [ -n "$FIGMA_URL" ]; then
+ echo "4. Validate against Figma design using MCP"
+fi
+echo ""
+echo -e "${CYAN}Tip: Create multiple test cases for comprehensive coverage${NC}"
+echo ""
diff --git a/dist/plugins/react-dev/skills/react-dev/README.md b/dist/plugins/react-dev/skills/react-dev/README.md
new file mode 100644
index 0000000..320b970
--- /dev/null
+++ b/dist/plugins/react-dev/skills/react-dev/README.md
@@ -0,0 +1,404 @@
+# React TypeScript Development Skill
+
+## Purpose
+
+The `react-dev` skill provides comprehensive TypeScript patterns and best practices for building type-safe React applications. It serves as a complete reference for modern React development with TypeScript, covering React 18-19 features, including Server Components, type-safe routing, and proper event handling.
+
+This skill exists to eliminate TypeScript guesswork in React development by providing compile-time guarantees, confident refactoring, and production-ready patterns that catch bugs before runtime.
+
+## When to Use
+
+Activate this skill when working on:
+
+- **Building typed React components** - Creating new components with proper TypeScript types
+- **Implementing generic components** - Tables, lists, modals, form fields that work with any data type
+- **Typing event handlers and forms** - Mouse events, form submissions, input changes, keyboard events
+- **Using React 19 features** - Actions, Server Components, `use()` hook, `useActionState`
+- **Router integration** - TanStack Router or React Router v7 with type safety
+- **Custom hooks with proper typing** - Creating reusable hooks with correct return types
+- **Migrating to React 19** - Understanding breaking changes and new patterns
+
+**Trigger phrases:**
+- "Build a typed React component"
+- "Type this event handler"
+- "Create a generic Table/List/Modal"
+- "Use React 19 Server Components"
+- "Type-safe routing with TanStack/React Router"
+- "How do I type this hook?"
+- "React TypeScript best practices"
+
+**Not for:**
+- Non-React TypeScript projects
+- Vanilla JavaScript React (without TypeScript)
+- React Native-specific patterns
+
+## How It Works
+
+The skill provides progressive disclosure of React TypeScript knowledge:
+
+1. **Core patterns loaded immediately** - Component props, event handlers, hooks typing
+2. **Advanced patterns referenced on-demand** - Generic components, Server Components, routing
+3. **Reference files for deep dives** - Detailed examples and edge cases only loaded when needed
+4. **React 19 migration guidance** - Breaking changes and new APIs clearly marked
+
+The skill is structured around:
+- **Quick reference sections** - Common patterns you can copy immediately
+- **Detailed reference files** - In-depth examples and explanations
+- **Rules and anti-patterns** - What to always do and what to never do
+- **Version-specific guidance** - React 18 vs React 19 differences highlighted
+
+## Key Features
+
+### 1. React 19 Breaking Changes
+
+Covers all major breaking changes in React 19:
+
+- **ref as prop** - No more `forwardRef`, refs are regular props now
+- **useActionState** - Replaces deprecated `useFormState`
+- **use() hook** - Unwraps promises and context in components
+- **Migration patterns** - Step-by-step guides for updating existing code
+
+### 2. Component Patterns
+
+Type-safe patterns for common component scenarios:
+
+- **Props typing** - Extending native HTML elements with `ComponentPropsWithoutRef`
+- **Children typing** - `ReactNode`, `ReactElement`, render props
+- **Discriminated unions** - Type-safe variant props (e.g., button vs link)
+- **Generic components** - Reusable components that infer types from data
+
+### 3. Event Handler Typing
+
+Specific event types for accurate TypeScript inference:
+
+- Mouse events (`MouseEvent`)
+- Form events (`FormEvent`)
+- Input changes (`ChangeEvent`)
+- Keyboard events (`KeyboardEvent`)
+- Focus, drag, clipboard, touch, wheel events (in reference docs)
+
+### 4. Hooks Typing
+
+Proper TypeScript patterns for all React hooks:
+
+- `useState` - Explicit types for unions and nullable values
+- `useRef` - DOM refs (null) vs mutable refs (direct access)
+- `useReducer` - Discriminated union actions
+- `useContext` - Null guard patterns
+- Custom hooks - Tuple returns with `as const`
+
+### 5. Server Components (React 19)
+
+Modern patterns for Server Components and Server Actions:
+
+- Async components with direct data fetching
+- Server Actions with `'use server'` directive
+- Client components consuming Server Actions
+- Promise handoff with `use()` hook
+- Parallel fetching and streaming
+
+### 6. Type-Safe Routing
+
+Comprehensive routing patterns for both major routers:
+
+- **TanStack Router** - Compile-time type safety with Zod validation
+- **React Router v7** - Auto-generated types with Framework Mode
+- Type-safe params, search params, loaders, actions
+
+### 7. Generic Components
+
+Reusable components that work with any data type:
+
+- Tables with type-safe columns
+- Lists with constrained generics
+- Modals, selects, form fields
+- Render props and keyof patterns
+
+## Prerequisites
+
+- **React 18 or 19** - Patterns are optimized for modern React
+- **TypeScript 5.0+** - Uses latest TypeScript features
+- **Router (optional)** - TanStack Router or React Router v7 for routing patterns
+- **Zod (optional)** - For TanStack Router search param validation
+
+## Usage Examples
+
+### Example 1: Type-Safe Button Component
+
+```typescript
+type ButtonProps = {
+ variant: 'primary' | 'secondary';
+} & React.ComponentPropsWithoutRef<'button'>;
+
+function Button({ variant, children, ...props }: ButtonProps) {
+ return (
+
+ {children}
+
+ );
+}
+
+// Usage
+ console.log(e.currentTarget.disabled)}>
+ Click me
+
+```
+
+### Example 2: Generic Table Component
+
+```typescript
+type Column = {
+ key: keyof T;
+ header: string;
+ render?: (value: T[keyof T], item: T) => React.ReactNode;
+};
+
+type TableProps = {
+ data: T[];
+ columns: Column[];
+ keyExtractor: (item: T) => string | number;
+};
+
+function Table({ data, columns, keyExtractor }: TableProps) {
+ return (
+
+
+ {columns.map(col => {col.header} )}
+
+
+ {data.map(item => (
+
+ {columns.map(col => (
+
+ {col.render ? col.render(item[col.key], item) : String(item[col.key])}
+
+ ))}
+
+ ))}
+
+
+ );
+}
+
+// Usage - types are inferred!
+type User = { id: number; name: string; email: string };
+const users: User[] = [...];
+
+ user.id}
+/>
+```
+
+### Example 3: React 19 Server Action with Form
+
+```typescript
+// actions/user.ts
+'use server';
+
+export async function updateUser(userId: string, formData: FormData) {
+ const name = formData.get('name') as string;
+ await db.user.update({
+ where: { id: userId },
+ data: { name }
+ });
+ revalidatePath(`/users/${userId}`);
+ return { success: true };
+}
+
+// UserForm.tsx
+'use client';
+
+import { useActionState } from 'react';
+import { updateUser } from '@/actions/user';
+
+function UserForm({ userId }: { userId: string }) {
+ const [state, formAction, isPending] = useActionState(
+ (prev, formData) => updateUser(userId, formData),
+ {}
+ );
+
+ return (
+
+ );
+}
+```
+
+### Example 4: Type-Safe Event Handlers
+
+```typescript
+function Form() {
+ const handleSubmit = (e: React.FormEvent) => {
+ e.preventDefault();
+ const formData = new FormData(e.currentTarget);
+ console.log(Object.fromEntries(formData));
+ };
+
+ const handleChange = (e: React.ChangeEvent) => {
+ console.log(e.target.value); // Typed correctly!
+ };
+
+ const handleKeyDown = (e: React.KeyboardEvent) => {
+ if (e.key === 'Enter') {
+ e.currentTarget.blur(); // currentTarget is typed as HTMLInputElement
+ }
+ };
+
+ return (
+
+ );
+}
+```
+
+### Example 5: Custom Hook with Proper Typing
+
+```typescript
+function useToggle(initial = false) {
+ const [value, setValue] = useState(initial);
+ const toggle = () => setValue(v => !v);
+ return [value, toggle] as const; // Tuple type preserved!
+}
+
+// Usage
+const [isOpen, toggleOpen] = useToggle(false);
+// isOpen is boolean, toggleOpen is () => void
+```
+
+### Example 6: TanStack Router Type-Safe Route
+
+```typescript
+import { createRoute } from '@tanstack/react-router';
+import { z } from 'zod';
+
+const userRoute = createRoute({
+ path: '/users/$userId',
+ component: UserPage,
+ loader: async ({ params }) => ({
+ user: await fetchUser(params.userId)
+ }),
+ validateSearch: z.object({
+ tab: z.enum(['profile', 'settings']).optional(),
+ page: z.number().int().positive().default(1),
+ }),
+});
+
+function UserPage() {
+ // All fully typed from the route definition!
+ const { user } = useLoaderData({ from: userRoute.id });
+ const { tab, page } = useSearch({ from: userRoute.id });
+ const { userId } = useParams({ from: userRoute.id });
+
+ return {user.name} - {tab} - Page {page}
;
+}
+```
+
+## Output
+
+The skill provides:
+
+1. **Code examples** - Copy-paste ready TypeScript code
+2. **Type definitions** - Exact types to use for your scenarios
+3. **Pattern explanations** - Why patterns work and when to use them
+4. **Migration guides** - Step-by-step updates for React 19
+5. **Reference links** - Pointers to detailed documentation when needed
+
+## Best Practices
+
+### Always Do
+
+✅ **Use specific event types** - `MouseEvent` not `React.MouseEvent`
+✅ **Explicit `useState` for unions/null** - `useState(null)`
+✅ **Extend native elements** - `ComponentPropsWithoutRef<'button'>`
+✅ **Discriminated unions for variants** - Type-safe props based on variant
+✅ **`as const` for tuple returns** - Preserve tuple types in custom hooks
+✅ **`ref` as prop in React 19** - No `forwardRef` needed
+✅ **`useActionState` for forms** - Not deprecated `useFormState`
+✅ **Type-safe routing patterns** - Use provided router patterns
+
+### Never Do
+
+❌ **Use `any` for event handlers** - Defeats TypeScript's purpose
+❌ **Use `JSX.Element` for children** - Use `ReactNode` instead
+❌ **Use `forwardRef` in React 19+** - It's deprecated
+❌ **Use `useFormState`** - Deprecated in React 19
+❌ **Forget null handling for DOM refs** - Always use `ref?.current`
+❌ **Mix Server/Client in same file** - Will cause hydration errors
+❌ **Await promises before `use()`** - Defeats streaming/Suspense
+
+### Progressive Enhancement
+
+1. **Start simple** - Basic component props and event handlers
+2. **Add constraints** - Discriminated unions, generic constraints
+3. **Leverage inference** - Let TypeScript infer types from usage
+4. **Reference docs when stuck** - Deep dive into specific patterns
+
+### Reference File Organization
+
+The skill includes detailed reference files:
+
+- **hooks.md** - `useState`, `useRef`, `useReducer`, `useContext`, custom hooks
+- **event-handlers.md** - All event types, generic handlers, edge cases
+- **react-19-patterns.md** - `useActionState`, `use()`, `useOptimistic`, migration
+- **generic-components.md** - Table, Select, List, Modal, FormField patterns
+- **server-components.md** - Async components, Server Actions, streaming
+- **tanstack-router.md** - TanStack Router typed routes, search params, navigation
+- **react-router.md** - React Router v7 loaders, actions, type generation
+
+These files are loaded on-demand to keep context efficient. The skill will reference them when deeper knowledge is needed.
+
+## Context Efficiency
+
+This skill follows progressive disclosure principles:
+
+- **Core patterns in SKILL.md** - Most common use cases immediately available
+- **Reference files on-demand** - Deep dives only when needed
+- **Script-free design** - Pure knowledge, no executable scripts needed
+- **Single-level references** - Direct links, no nested includes
+
+This keeps the skill's context footprint minimal while providing comprehensive coverage when needed.
+
+## Version Compatibility
+
+- **React 18** - All patterns work, ignore React 19-specific sections
+- **React 19** - Full support including Server Components, `use()`, `useActionState`
+- **TypeScript 5.0+** - Recommended for best type inference
+- **TanStack Router** - Any version supporting `createRoute`
+- **React Router v7+** - Framework Mode for auto-generated types
+
+## Getting Started
+
+1. **Install the skill** in Claude Code or add to claude.ai project knowledge
+2. **Mention React TypeScript** in your conversation or request
+3. **Reference specific patterns** - "How do I type this event handler?"
+4. **Let Claude suggest patterns** - Describe what you're building
+5. **Explore reference docs** - Ask for deep dives when needed
+
+## Related Skills
+
+- **typescript-patterns** - General TypeScript patterns beyond React
+- **frontend-testing** - Testing typed React components
+- **component-library** - Building design systems with TypeScript
+
+---
+
+**Version:** 1.0.0
+**Last Updated:** 2026-01-20
+**Maintained by:** Softaworks Agent Skills
diff --git a/dist/plugins/react-dev/skills/react-dev/SKILL.md b/dist/plugins/react-dev/skills/react-dev/SKILL.md
new file mode 100644
index 0000000..bd288f3
--- /dev/null
+++ b/dist/plugins/react-dev/skills/react-dev/SKILL.md
@@ -0,0 +1,391 @@
+---
+name: react-dev
+version: 1.0.0
+description: This skill should be used when building React components with TypeScript, typing hooks, handling events, or when React TypeScript, React 19, Server Components are mentioned. Covers type-safe patterns for React 18-19 including generic components, proper event typing, and routing integration (TanStack Router, React Router).
+---
+
+# React TypeScript
+
+Type-safe React = compile-time guarantees = confident refactoring.
+
+
+
+- Building typed React components
+- Implementing generic components
+- Typing event handlers, forms, refs
+- Using React 19 features (Actions, Server Components, use())
+- Router integration (TanStack Router, React Router)
+- Custom hooks with proper typing
+
+NOT for: non-React TypeScript, vanilla JS React
+
+
+
+
+
+React 19 breaking changes require migration. Key patterns:
+
+**ref as prop** - forwardRef deprecated:
+
+```typescript
+// React 19 - ref as regular prop
+type ButtonProps = {
+ ref?: React.Ref;
+} & React.ComponentPropsWithoutRef<'button'>;
+
+function Button({ ref, children, ...props }: ButtonProps) {
+ return {children} ;
+}
+```
+
+**useActionState** - replaces useFormState:
+
+```typescript
+import { useActionState } from 'react';
+
+type FormState = { errors?: string[]; success?: boolean };
+
+function Form() {
+ const [state, formAction, isPending] = useActionState(submitAction, {});
+ return ;
+}
+```
+
+**use()** - unwraps promises/context:
+
+```typescript
+function UserProfile({ userPromise }: { userPromise: Promise }) {
+ const user = use(userPromise); // Suspends until resolved
+ return {user.name}
;
+}
+```
+
+See [react-19-patterns.md](references/react-19-patterns.md) for useOptimistic, useTransition, migration checklist.
+
+
+
+
+
+**Props** - extend native elements:
+
+```typescript
+type ButtonProps = {
+ variant: 'primary' | 'secondary';
+} & React.ComponentPropsWithoutRef<'button'>;
+
+function Button({ variant, children, ...props }: ButtonProps) {
+ return {children} ;
+}
+```
+
+**Children typing**:
+
+```typescript
+type Props = {
+ children: React.ReactNode; // Anything renderable
+ icon: React.ReactElement; // Single element
+ render: (data: T) => React.ReactNode; // Render prop
+};
+```
+
+**Discriminated unions** for variant props:
+
+```typescript
+type ButtonProps =
+ | { variant: 'link'; href: string }
+ | { variant: 'button'; onClick: () => void };
+
+function Button(props: ButtonProps) {
+ if (props.variant === 'link') {
+ return Link ;
+ }
+ return Button ;
+}
+```
+
+
+
+
+
+Use specific event types for accurate target typing:
+
+```typescript
+// Mouse
+function handleClick(e: React.MouseEvent) {
+ e.currentTarget.disabled = true;
+}
+
+// Form
+function handleSubmit(e: React.FormEvent) {
+ e.preventDefault();
+ const formData = new FormData(e.currentTarget);
+}
+
+// Input
+function handleChange(e: React.ChangeEvent) {
+ console.log(e.target.value);
+}
+
+// Keyboard
+function handleKeyDown(e: React.KeyboardEvent) {
+ if (e.key === 'Enter') e.currentTarget.blur();
+}
+```
+
+See [event-handlers.md](references/event-handlers.md) for focus, drag, clipboard, touch, wheel events.
+
+
+
+
+
+**useState** - explicit for unions/null:
+
+```typescript
+const [user, setUser] = useState(null);
+const [status, setStatus] = useState<'idle' | 'loading'>('idle');
+```
+
+**useRef** - null for DOM, value for mutable:
+
+```typescript
+const inputRef = useRef(null); // DOM - use ?.
+const countRef = useRef(0); // Mutable - direct access
+```
+
+**useReducer** - discriminated unions for actions:
+
+```typescript
+type Action =
+ | { type: 'increment' }
+ | { type: 'set'; payload: number };
+
+function reducer(state: State, action: Action): State {
+ switch (action.type) {
+ case 'set': return { ...state, count: action.payload };
+ default: return state;
+ }
+}
+```
+
+**Custom hooks** - tuple returns with as const:
+
+```typescript
+function useToggle(initial = false) {
+ const [value, setValue] = useState(initial);
+ const toggle = () => setValue(v => !v);
+ return [value, toggle] as const;
+}
+```
+
+**useContext** - null guard pattern:
+
+```typescript
+const UserContext = createContext(null);
+
+function useUser() {
+ const user = useContext(UserContext);
+ if (!user) throw new Error('useUser outside UserProvider');
+ return user;
+}
+```
+
+See [hooks.md](references/hooks.md) for useCallback, useMemo, useImperativeHandle, useSyncExternalStore.
+
+
+
+
+
+Generic components infer types from props - no manual annotations at call site.
+
+**Pattern** - keyof T for column keys, render props for custom rendering:
+
+```typescript
+type Column = {
+ key: keyof T;
+ header: string;
+ render?: (value: T[keyof T], item: T) => React.ReactNode;
+};
+
+type TableProps = {
+ data: T[];
+ columns: Column[];
+ keyExtractor: (item: T) => string | number;
+};
+
+function Table({ data, columns, keyExtractor }: TableProps) {
+ return (
+
+
+ {columns.map(col => {col.header} )}
+
+
+ {data.map(item => (
+
+ {columns.map(col => (
+
+ {col.render ? col.render(item[col.key], item) : String(item[col.key])}
+
+ ))}
+
+ ))}
+
+
+ );
+}
+```
+
+**Constrained generics** for required properties:
+
+```typescript
+type HasId = { id: string | number };
+
+function List({ items }: { items: T[] }) {
+ return ;
+}
+```
+
+See [generic-components.md](examples/generic-components.md) for Select, List, Modal, FormField patterns.
+
+
+
+
+
+React 19 Server Components run on server, can be async.
+
+**Async data fetching**:
+
+```typescript
+export default async function UserPage({ params }: { params: { id: string } }) {
+ const user = await fetchUser(params.id);
+ return {user.name}
;
+}
+```
+
+**Server Actions** - 'use server' for mutations:
+
+```typescript
+'use server';
+
+export async function updateUser(userId: string, formData: FormData) {
+ await db.user.update({ where: { id: userId }, data: { ... } });
+ revalidatePath(`/users/${userId}`);
+}
+```
+
+**Client + Server Action**:
+
+```typescript
+'use client';
+
+import { useActionState } from 'react';
+import { updateUser } from '@/actions/user';
+
+function UserForm({ userId }: { userId: string }) {
+ const [state, formAction, isPending] = useActionState(
+ (prev, formData) => updateUser(userId, formData), {}
+ );
+ return ;
+}
+```
+
+**use() for promise handoff**:
+
+```typescript
+// Server: pass promise without await
+async function Page() {
+ const userPromise = fetchUser('123');
+ return }) {
+ const user = use(userPromise);
+ return {user.name}
;
+}
+```
+
+See [server-components.md](examples/server-components.md) for parallel fetching, streaming, error boundaries.
+
+
+
+
+
+Both TanStack Router and React Router v7 provide type-safe routing solutions.
+
+**TanStack Router** - Compile-time type safety with Zod validation:
+
+```typescript
+import { createRoute } from '@tanstack/react-router';
+import { z } from 'zod';
+
+const userRoute = createRoute({
+ path: '/users/$userId',
+ component: UserPage,
+ loader: async ({ params }) => ({ user: await fetchUser(params.userId) }),
+ validateSearch: z.object({
+ tab: z.enum(['profile', 'settings']).optional(),
+ page: z.number().int().positive().default(1),
+ }),
+});
+
+function UserPage() {
+ const { user } = useLoaderData({ from: userRoute.id });
+ const { tab, page } = useSearch({ from: userRoute.id });
+ const { userId } = useParams({ from: userRoute.id });
+}
+```
+
+**React Router v7** - Automatic type generation with Framework Mode:
+
+```typescript
+import type { Route } from "./+types/user";
+
+export async function loader({ params }: Route.LoaderArgs) {
+ return { user: await fetchUser(params.userId) };
+}
+
+export default function UserPage({ loaderData }: Route.ComponentProps) {
+ const { user } = loaderData; // Typed from loader
+ return {user.name} ;
+}
+```
+
+See [tanstack-router.md](references/tanstack-router.md) for TanStack patterns and [react-router.md](references/react-router.md) for React Router patterns.
+
+
+
+
+
+ALWAYS:
+- Specific event types (MouseEvent, ChangeEvent, etc)
+- Explicit useState for unions/null
+- ComponentPropsWithoutRef for native element extension
+- Discriminated unions for variant props
+- as const for tuple returns
+- ref as prop in React 19 (no forwardRef)
+- useActionState for form actions
+- Type-safe routing patterns (see routing section)
+
+NEVER:
+- any for event handlers
+- JSX.Element for children (use ReactNode)
+- forwardRef in React 19+
+- useFormState (deprecated)
+- Forget null handling for DOM refs
+- Mix Server/Client components in same file
+- Await promises when passing to use()
+
+
+
+
+
+- [hooks.md](references/hooks.md) - useState, useRef, useReducer, useContext, custom hooks
+- [event-handlers.md](references/event-handlers.md) - all event types, generic handlers
+- [react-19-patterns.md](references/react-19-patterns.md) - useActionState, use(), useOptimistic, migration
+- [generic-components.md](examples/generic-components.md) - Table, Select, List, Modal patterns
+- [server-components.md](examples/server-components.md) - async components, Server Actions, streaming
+- [tanstack-router.md](references/tanstack-router.md) - TanStack Router typed routes, search params, navigation
+- [react-router.md](references/react-router.md) - React Router v7 loaders, actions, type generation, forms
+
+
diff --git a/dist/plugins/react-dev/skills/react-dev/examples/generic-components.md b/dist/plugins/react-dev/skills/react-dev/examples/generic-components.md
new file mode 100644
index 0000000..090a94b
--- /dev/null
+++ b/dist/plugins/react-dev/skills/react-dev/examples/generic-components.md
@@ -0,0 +1,579 @@
+# Generic Component Patterns
+
+Generic components provide type safety while maintaining reusability. TypeScript infers generic type parameters from prop values — no manual type annotations needed at call site.
+
+## Generic Table Component
+
+Full-featured table with typed columns, custom rendering, sorting.
+
+```typescript
+type Column = {
+ key: keyof T;
+ header: string;
+ render?: (value: T[keyof T], item: T) => React.ReactNode;
+ sortable?: boolean;
+};
+
+type TableProps = {
+ data: T[];
+ columns: Column[];
+ keyExtractor: (item: T) => string | number;
+ onSort?: (key: keyof T, direction: 'asc' | 'desc') => void;
+ className?: string;
+};
+
+function Table({
+ data,
+ columns,
+ keyExtractor,
+ onSort,
+ className,
+}: TableProps) {
+ const [sortKey, setSortKey] = React.useState(null);
+ const [sortDir, setSortDir] = React.useState<'asc' | 'desc'>('asc');
+
+ const handleSort = (key: keyof T) => {
+ const newDir = sortKey === key && sortDir === 'asc' ? 'desc' : 'asc';
+ setSortKey(key);
+ setSortDir(newDir);
+ onSort?.(key, newDir);
+ };
+
+ return (
+
+
+
+ {columns.map((col) => (
+
+ {col.sortable ? (
+ handleSort(col.key)}>
+ {col.header}
+ {sortKey === col.key && (sortDir === 'asc' ? ' ↑' : ' ↓')}
+
+ ) : (
+ col.header
+ )}
+
+ ))}
+
+
+
+ {data.map((item) => (
+
+ {columns.map((col) => (
+
+ {col.render
+ ? col.render(item[col.key], item)
+ : String(item[col.key])}
+
+ ))}
+
+ ))}
+
+
+ );
+}
+```
+
+Usage:
+
+```typescript
+type User = {
+ id: number;
+ name: string;
+ email: string;
+ role: 'admin' | 'user';
+ createdAt: Date;
+};
+
+function UserTable({ users }: { users: User[] }) {
+ const [sortedUsers, setSortedUsers] = React.useState(users);
+
+ const handleSort = (key: keyof User, direction: 'asc' | 'desc') => {
+ const sorted = [...users].sort((a, b) => {
+ if (a[key] < b[key]) return direction === 'asc' ? -1 : 1;
+ if (a[key] > b[key]) return direction === 'asc' ? 1 : -1;
+ return 0;
+ });
+ setSortedUsers(sorted);
+ };
+
+ return (
+ {email} ,
+ },
+ {
+ key: 'role',
+ header: 'Role',
+ render: (role) => (
+
+ {role}
+
+ ),
+ },
+ {
+ key: 'createdAt',
+ header: 'Created',
+ render: (date) => new Date(date).toLocaleDateString(),
+ sortable: true,
+ },
+ ]}
+ keyExtractor={(user) => user.id}
+ onSort={handleSort}
+ />
+ );
+}
+```
+
+## Generic Select/Dropdown
+
+Type-safe select with custom option rendering, searching.
+
+```typescript
+type SelectProps = {
+ options: T[];
+ value: T | null;
+ onChange: (value: T) => void;
+ getLabel: (option: T) => string;
+ getValue: (option: T) => string | number;
+ placeholder?: string;
+ disabled?: boolean;
+ searchable?: boolean;
+};
+
+function Select({
+ options,
+ value,
+ onChange,
+ getLabel,
+ getValue,
+ placeholder = 'Select...',
+ disabled = false,
+ searchable = false,
+}: SelectProps) {
+ const [search, setSearch] = React.useState('');
+ const [isOpen, setIsOpen] = React.useState(false);
+
+ const filtered = searchable
+ ? options.filter((opt) =>
+ getLabel(opt).toLowerCase().includes(search.toLowerCase())
+ )
+ : options;
+
+ const handleSelect = (option: T) => {
+ onChange(option);
+ setIsOpen(false);
+ setSearch('');
+ };
+
+ return (
+
+
setIsOpen(!isOpen)}
+ disabled={disabled}
+ className="select-trigger"
+ >
+ {value ? getLabel(value) : placeholder}
+
+
+ {isOpen && (
+
+ {searchable && (
+
setSearch(e.target.value)}
+ placeholder="Search..."
+ autoFocus
+ />
+ )}
+
+ {filtered.map((option) => (
+ handleSelect(option)}
+ className={value === option ? 'selected' : ''}
+ >
+ {getLabel(option)}
+
+ ))}
+
+
+ )}
+
(null);
+
+ return (
+ `${c.flag} ${c.name}`}
+ getValue={(c) => c.code}
+ searchable
+ placeholder="Select country"
+ />
+ );
+}
+```
+
+## Generic List with Render Props
+
+Flexible list rendering with type-safe render props.
+
+```typescript
+type ListProps = {
+ items: T[];
+ renderItem: (item: T, index: number) => React.ReactNode;
+ renderEmpty?: () => React.ReactNode;
+ keyExtractor: (item: T, index: number) => string | number;
+ className?: string;
+ as?: 'ul' | 'ol' | 'div';
+};
+
+function List({
+ items,
+ renderItem,
+ renderEmpty,
+ keyExtractor,
+ className,
+ as: Component = 'ul',
+}: ListProps) {
+ if (items.length === 0 && renderEmpty) {
+ return <>{renderEmpty()};
+ }
+
+ return (
+
+ {items.map((item, index) => {
+ const key = keyExtractor(item, index);
+ const element = renderItem(item, index);
+
+ return Component === 'div' ? (
+ {element}
+ ) : (
+ {element}
+ );
+ })}
+
+ );
+}
+```
+
+Usage:
+
+```typescript
+type Task = {
+ id: string;
+ title: string;
+ completed: boolean;
+ priority: 'low' | 'medium' | 'high';
+};
+
+function TaskList({ tasks }: { tasks: Task[] }) {
+ return (
+ task.id}
+ renderItem={(task) => (
+
+ {task.title}
+
+ )}
+ renderEmpty={() => (
+ No tasks yet. Add one to get started!
+ )}
+ as="div"
+ />
+ );
+}
+```
+
+## Constrained Generic Components
+
+Use constraints to ensure required properties or methods.
+
+```typescript
+// Constraint: items must have `id` property
+type HasId = { id: string | number };
+
+type GridProps = {
+ items: T[];
+ renderCard: (item: T) => React.ReactNode;
+ columns?: 2 | 3 | 4;
+};
+
+function Grid({
+ items,
+ renderCard,
+ columns = 3,
+}: GridProps) {
+ return (
+
+ {items.map((item) => (
+
+ {renderCard(item)}
+
+ ))}
+
(
+
+
+
{product.name}
+
${product.price}
+
= {
+ pairs: Array<[K, V]>;
+ renderKey: (key: K) => React.ReactNode;
+ renderValue: (value: V) => React.ReactNode;
+};
+
+function KeyValueList({ pairs, renderKey, renderValue }: PairProps) {
+ return (
+
+ {pairs.map(([key, value], index) => (
+
+ {renderKey(key)}
+ {renderValue(value)}
+
+ ))}
+
+ );
+}
+
+// Usage
+type MetricKey = 'cpu' | 'memory' | 'disk';
+type MetricValue = { current: number; max: number };
+
+const metrics: Array<[MetricKey, MetricValue]> = [
+ ['cpu', { current: 45, max: 100 }],
+ ['memory', { current: 8, max: 16 }],
+ ['disk', { current: 250, max: 500 }],
+];
+
+ {key.toUpperCase()} }
+ renderValue={(val) => (
+
+ {val.current}/{val.max}
+
+ )}
+/>;
+```
+
+## Generic Form Field Component
+
+Reusable form field with type-safe value handling.
+
+```typescript
+type FieldProps = {
+ name: string;
+ label: string;
+ value: T;
+ onChange: (value: T) => void;
+ type: 'text' | 'number' | 'email' | 'password';
+ error?: string;
+ required?: boolean;
+};
+
+function FormField({
+ name,
+ label,
+ value,
+ onChange,
+ type,
+ error,
+ required = false,
+}: FieldProps) {
+ const handleChange = (e: React.ChangeEvent) => {
+ const newValue =
+ type === 'number' ? (Number(e.target.value) as T) : (e.target.value as T);
+ onChange(newValue);
+ };
+
+ return (
+
+
+ {label}
+ {required && * }
+
+
+ {error}
+
+ )}
+
+ );
+}
+
+// Usage
+function UserForm() {
+ const [name, setName] = React.useState('');
+ const [age, setAge] = React.useState(0);
+
+ return (
+
+ );
+}
+```
+
+## Generic Modal/Dialog
+
+Type-safe modal with generic result type.
+
+```typescript
+type ModalProps = {
+ isOpen: boolean;
+ onClose: (result?: T) => void;
+ title: string;
+ children: (submit: (result: T) => void) => React.ReactNode;
+};
+
+function Modal({ isOpen, onClose, title, children }: ModalProps) {
+ if (!isOpen) return null;
+
+ const handleSubmit = (result: T) => {
+ onClose(result);
+ };
+
+ return (
+
+
+
+ {title}
+ onClose()}>×
+
+
{children(handleSubmit)}
+
+
({
+ name: '',
+ email: '',
+ });
+
+ const handleModalClose = (result?: UserFormData) => {
+ if (result) {
+ console.log('User submitted:', result);
+ }
+ setShowModal(false);
+ };
+
+ return (
+ <>
+ setShowModal(true)}>Add User
+
+
+ isOpen={showModal}
+ onClose={handleModalClose}
+ title="Add New User"
+ >
+ {(submit) => (
+
+ )}
+
+
+ );
+}
+```
diff --git a/dist/plugins/react-dev/skills/react-dev/examples/server-components.md b/dist/plugins/react-dev/skills/react-dev/examples/server-components.md
new file mode 100644
index 0000000..43a9b34
--- /dev/null
+++ b/dist/plugins/react-dev/skills/react-dev/examples/server-components.md
@@ -0,0 +1,579 @@
+# Server Components and Server Actions
+
+React 19 Server Components run on server, can be async, enable zero-bundle data fetching. Server Actions handle mutations with progressive enhancement.
+
+## Async Server Component
+
+Server Components can be async functions — await data fetching directly.
+
+```typescript
+// app/users/[id]/page.tsx
+type PageProps = {
+ params: { id: string };
+ searchParams?: { tab?: string; edit?: string };
+};
+
+export default async function UserPage({ params, searchParams }: PageProps) {
+ // Runs on server - no client bundle
+ const user = await fetchUser(params.id);
+ const posts = await fetchUserPosts(params.id);
+
+ return (
+
+
+ {user.name}
+ {user.email}
+
+
+
+
+ {searchParams?.edit === 'true' && (
+
+ )}
+
{
+ const res = await fetch(`https://api.example.com/users/${id}`, {
+ cache: 'no-store', // Or 'force-cache', 'revalidate'
+ });
+ if (!res.ok) throw new Error('Failed to fetch user');
+ return res.json();
+}
+```
+
+## Parallel Data Fetching
+
+Fetch multiple resources in parallel with Promise.all.
+
+```typescript
+type DashboardProps = {
+ params: { userId: string };
+};
+
+export default async function Dashboard({ params }: DashboardProps) {
+ // Parallel fetching
+ const [user, stats, activity] = await Promise.all([
+ fetchUser(params.userId),
+ fetchUserStats(params.userId),
+ fetchRecentActivity(params.userId),
+ ]);
+
+ return (
+
+ );
+}
+```
+
+## Sequential vs Waterfall Fetching
+
+```typescript
+// ❌ Waterfall - slow
+async function SlowPage() {
+ const user = await fetchUser('123');
+ const posts = await fetchUserPosts(user.id); // Waits for user
+ const comments = await fetchPostComments(posts[0].id); // Waits for posts
+ return ...
;
+}
+
+// ✅ Parallel - fast
+async function FastPage() {
+ const userPromise = fetchUser('123');
+ const postsPromise = fetchUserPosts('123');
+
+ const [user, posts] = await Promise.all([userPromise, postsPromise]);
+
+ // If comments depend on posts, fetch after
+ const comments = await fetchPostComments(posts[0].id);
+
+ return ...
;
+}
+```
+
+## Server Actions - Form Mutations
+
+Server Actions marked with 'use server' — run on server, callable from client.
+
+```typescript
+// actions/user.ts
+'use server';
+
+import { revalidatePath, revalidateTag } from 'next/cache';
+import { redirect } from 'next/navigation';
+import { z } from 'zod';
+
+const updateUserSchema = z.object({
+ name: z.string().min(2, 'Name must be at least 2 characters'),
+ email: z.string().email('Invalid email address'),
+ bio: z.string().max(500, 'Bio must be less than 500 characters').optional(),
+});
+
+type FormState = {
+ success?: boolean;
+ errors?: Record;
+ message?: string;
+};
+
+export async function updateUser(
+ userId: string,
+ prevState: FormState,
+ formData: FormData
+): Promise {
+ // Validate
+ const parsed = updateUserSchema.safeParse({
+ name: formData.get('name'),
+ email: formData.get('email'),
+ bio: formData.get('bio'),
+ });
+
+ if (!parsed.success) {
+ return {
+ success: false,
+ errors: parsed.error.flatten().fieldErrors,
+ };
+ }
+
+ try {
+ // Mutate database
+ await db.user.update({
+ where: { id: userId },
+ data: parsed.data,
+ });
+
+ // Revalidate cached data
+ revalidatePath(`/users/${userId}`);
+ revalidateTag(`user-${userId}`);
+
+ return { success: true, message: 'Profile updated successfully' };
+ } catch (error) {
+ return {
+ success: false,
+ message: 'Failed to update profile. Please try again.',
+ };
+ }
+}
+
+export async function deleteUser(userId: string) {
+ await db.user.delete({ where: { id: userId } });
+ revalidatePath('/users');
+ redirect('/users'); // Navigate after mutation
+}
+```
+
+## Client Component Using Server Action
+
+```typescript
+// components/UserForm.tsx
+'use client';
+
+import { useActionState } from 'react';
+import { updateUser } from '@/actions/user';
+
+type FormState = {
+ success?: boolean;
+ errors?: Record