Compare commits
18 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
1bd7db87b9 | ||
|
|
41576e7664 | ||
|
|
c3e5876b7c | ||
|
|
da230d00b0 | ||
|
|
674fa7703d | ||
|
|
a9ff10d511 | ||
|
|
1f753cd190 | ||
|
|
87671ce026 | ||
|
|
582828237b | ||
|
|
e78acd582e | ||
|
|
33e0d7d22e | ||
|
|
fee1d98d5c | ||
|
|
56e2ccf719 | ||
|
|
c299e36360 | ||
|
|
4e8e5069fa | ||
|
|
36f99442fe | ||
|
|
13f16b7585 | ||
|
|
ebb8f19937 |
21
CHANGELOG.md
21
CHANGELOG.md
@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
|
||||
---
|
||||
|
||||
## [2.6.0] - 2026-01-21 - "Everything Skills Edition"
|
||||
|
||||
### Added
|
||||
|
||||
- **8 Verified Skills** from [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code):
|
||||
- `cc-skill-backend-patterns`
|
||||
- `cc-skill-clickhouse-io`
|
||||
- `cc-skill-coding-standards`
|
||||
- `cc-skill-continuous-learning`
|
||||
- `cc-skill-frontend-patterns`
|
||||
- `cc-skill-project-guidelines-example`
|
||||
- `cc-skill-security-review`
|
||||
- `cc-skill-strategic-compact`
|
||||
- **Documentation**: New `WALKTHROUGH.md` for import process details.
|
||||
|
||||
### Changed
|
||||
|
||||
- **Skill Cleanup**: Removed 27 unwanted agents, commands, and rules from the `everything-claude-code` import to focus strictly on skills.
|
||||
- **Index**: Regenerated `skills_index.json` (Total: 233 skills).
|
||||
- **Credits**: Updated README credits and registry.
|
||||
|
||||
## [1.0.0] - 2026-01-19 - "Marketing Edition"
|
||||
|
||||
### Added
|
||||
|
||||
401
CONTRIBUTING.md
Normal file
401
CONTRIBUTING.md
Normal file
@@ -0,0 +1,401 @@
|
||||
# 🤝 Contributing Guide - Make It Easy for Everyone!
|
||||
|
||||
**Thank you for wanting to make this repo better!** This guide shows you exactly how to contribute, even if you're new to open source.
|
||||
|
||||
---
|
||||
|
||||
## Ways to Contribute
|
||||
|
||||
You don't need to be an expert! Here are ways anyone can help:
|
||||
|
||||
### 1. Improve Documentation (Easiest!)
|
||||
- Fix typos or grammar
|
||||
- Make explanations clearer
|
||||
- Add examples to existing skills
|
||||
- Translate documentation to other languages
|
||||
|
||||
### 2. Report Issues
|
||||
- Found something confusing? Tell us!
|
||||
- Skill not working? Let us know!
|
||||
- Have suggestions? We want to hear them!
|
||||
|
||||
### 3. Create New Skills
|
||||
- Share your expertise as a skill
|
||||
- Fill gaps in the current collection
|
||||
- Improve existing skills
|
||||
|
||||
### 4. Test and Validate
|
||||
- Try skills and report what works/doesn't work
|
||||
- Test on different AI tools
|
||||
- Suggest improvements
|
||||
|
||||
---
|
||||
|
||||
## How to Improve Documentation
|
||||
|
||||
### Super Easy Method (No Git Knowledge Needed!)
|
||||
|
||||
1. **Find the file** you want to improve on GitHub
|
||||
2. **Click the pencil icon** (✏️) to edit
|
||||
3. **Make your changes** in the browser
|
||||
4. **Click "Propose changes"** at the bottom
|
||||
5. **Done!** We'll review and merge it
|
||||
|
||||
### Using Git (If You Know How)
|
||||
|
||||
```bash
|
||||
# 1. Fork the repo on GitHub (click the Fork button)
|
||||
|
||||
# 2. Clone your fork
|
||||
git clone https://github.com/YOUR-USERNAME/antigravity-awesome-skills.git
|
||||
cd antigravity-awesome-skills
|
||||
|
||||
# 3. Create a branch
|
||||
git checkout -b improve-docs
|
||||
|
||||
# 4. Make your changes
|
||||
# Edit files in your favorite editor
|
||||
|
||||
# 5. Commit and push
|
||||
git add .
|
||||
git commit -m "docs: make XYZ clearer"
|
||||
git push origin improve-docs
|
||||
|
||||
# 6. Open a Pull Request on GitHub
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How to Create a New Skill
|
||||
|
||||
### What Makes a Good Skill?
|
||||
|
||||
A skill should:
|
||||
- ✅ Solve a specific problem
|
||||
- ✅ Be reusable across projects
|
||||
- ✅ Have clear instructions
|
||||
- ✅ Include examples when possible
|
||||
|
||||
### Step-by-Step: Create Your First Skill
|
||||
|
||||
#### Step 1: Choose Your Skill Topic
|
||||
|
||||
Ask yourself:
|
||||
- What am I good at?
|
||||
- What do I wish my AI assistant knew better?
|
||||
- What task do I do repeatedly?
|
||||
|
||||
**Examples:**
|
||||
- "I'm good at Docker, let me create a Docker skill"
|
||||
- "I wish AI understood Tailwind better"
|
||||
- "I keep setting up the same testing patterns"
|
||||
|
||||
#### Step 2: Create the Folder Structure
|
||||
|
||||
```bash
|
||||
# Navigate to the skills directory
|
||||
cd skills/
|
||||
|
||||
# Create your skill folder (use lowercase with hyphens)
|
||||
mkdir my-awesome-skill
|
||||
|
||||
# Create the SKILL.md file
|
||||
cd my-awesome-skill
|
||||
touch SKILL.md
|
||||
```
|
||||
|
||||
#### Step 3: Write Your SKILL.md
|
||||
|
||||
Every skill needs this basic structure:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-awesome-skill
|
||||
description: "Brief one-line description of what this skill does"
|
||||
---
|
||||
|
||||
# Skill Title
|
||||
|
||||
## Overview
|
||||
|
||||
Explain what this skill does and when to use it.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
- Use when [scenario 1]
|
||||
- Use when [scenario 2]
|
||||
- Use when [scenario 3]
|
||||
|
||||
## How It Works
|
||||
|
||||
### Step 1: [First Step]
|
||||
Explain what to do first...
|
||||
|
||||
### Step 2: [Second Step]
|
||||
Explain the next step...
|
||||
|
||||
### Step 3: [Final Step]
|
||||
Explain how to finish...
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: [Common Use Case]
|
||||
\`\`\`
|
||||
Show example code or commands here
|
||||
\`\`\`
|
||||
|
||||
### Example 2: [Another Use Case]
|
||||
\`\`\`
|
||||
More examples...
|
||||
\`\`\`
|
||||
|
||||
## Best Practices
|
||||
|
||||
- ✅ Do this
|
||||
- ✅ Also do this
|
||||
- ❌ Don't do this
|
||||
- ❌ Avoid this
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Problem:** Description of common issue
|
||||
**Solution:** How to fix it
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Link to documentation](https://example.com)
|
||||
- [Tutorial](https://example.com)
|
||||
```
|
||||
|
||||
#### Step 4: Test Your Skill
|
||||
|
||||
1. **Copy it to your AI tool's skills directory:**
|
||||
```bash
|
||||
cp -r skills/my-awesome-skill ~/.agent/skills/
|
||||
```
|
||||
|
||||
2. **Try using it:**
|
||||
```
|
||||
@my-awesome-skill help me with [task]
|
||||
```
|
||||
|
||||
3. **Does it work?** Great! If not, refine it.
|
||||
|
||||
#### Step 5: Validate Your Skill
|
||||
|
||||
Run the validation script:
|
||||
|
||||
```bash
|
||||
python3 scripts/validate_skills.py
|
||||
```
|
||||
|
||||
This checks:
|
||||
- ✅ SKILL.md exists
|
||||
- ✅ Frontmatter is correct
|
||||
- ✅ Name matches folder name
|
||||
- ✅ Description exists
|
||||
|
||||
#### Step 6: Submit Your Skill
|
||||
|
||||
```bash
|
||||
# 1. Add your skill
|
||||
git add skills/my-awesome-skill/
|
||||
|
||||
# 2. Commit with a clear message
|
||||
git commit -m "feat: add my-awesome-skill for [purpose]"
|
||||
|
||||
# 3. Push to your fork
|
||||
git push origin my-branch
|
||||
|
||||
# 4. Open a Pull Request on GitHub
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Skill Template (Copy & Paste)
|
||||
|
||||
Save time! Copy this template:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: your-skill-name
|
||||
description: "One sentence describing what this skill does and when to use it"
|
||||
---
|
||||
|
||||
# Your Skill Name
|
||||
|
||||
## Overview
|
||||
|
||||
[2-3 sentences explaining what this skill does]
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
- Use when you need to [scenario 1]
|
||||
- Use when you want to [scenario 2]
|
||||
- Use when working with [scenario 3]
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### Concept 1
|
||||
[Explain key concept]
|
||||
|
||||
### Concept 2
|
||||
[Explain another key concept]
|
||||
|
||||
## Step-by-Step Guide
|
||||
|
||||
### 1. [First Step Name]
|
||||
[Detailed instructions]
|
||||
|
||||
### 2. [Second Step Name]
|
||||
[Detailed instructions]
|
||||
|
||||
### 3. [Third Step Name]
|
||||
[Detailed instructions]
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: [Use Case Name]
|
||||
\`\`\`language
|
||||
// Example code here
|
||||
\`\`\`
|
||||
|
||||
**Explanation:** [What this example demonstrates]
|
||||
|
||||
### Example 2: [Another Use Case]
|
||||
\`\`\`language
|
||||
// More example code
|
||||
\`\`\`
|
||||
|
||||
**Explanation:** [What this example demonstrates]
|
||||
|
||||
## Best Practices
|
||||
|
||||
- ✅ **Do:** [Good practice]
|
||||
- ✅ **Do:** [Another good practice]
|
||||
- ❌ **Don't:** [What to avoid]
|
||||
- ❌ **Don't:** [Another thing to avoid]
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Problem: [Common Issue]
|
||||
**Symptoms:** [How you know this is the problem]
|
||||
**Solution:** [How to fix it]
|
||||
|
||||
### Problem: [Another Issue]
|
||||
**Symptoms:** [How you know this is the problem]
|
||||
**Solution:** [How to fix it]
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `@related-skill-1` - [When to use this instead]
|
||||
- `@related-skill-2` - [How this complements your skill]
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Official Documentation](https://example.com)
|
||||
- [Tutorial](https://example.com)
|
||||
- [Community Guide](https://example.com)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How to Report Issues
|
||||
|
||||
### Found a Bug?
|
||||
|
||||
1. **Check existing issues** - Maybe it's already reported
|
||||
2. **Open a new issue** with this info:
|
||||
- What skill has the problem?
|
||||
- What AI tool are you using?
|
||||
- What did you expect to happen?
|
||||
- What actually happened?
|
||||
- Steps to reproduce
|
||||
|
||||
### Found Something Confusing?
|
||||
|
||||
1. **Open an issue** titled: "Documentation unclear: [topic]"
|
||||
2. **Explain:**
|
||||
- What part is confusing?
|
||||
- What did you expect to find?
|
||||
- How could it be clearer?
|
||||
|
||||
---
|
||||
|
||||
## Contribution Checklist
|
||||
|
||||
Before submitting your contribution:
|
||||
|
||||
- [ ] My skill has a clear, descriptive name
|
||||
- [ ] The `SKILL.md` has proper frontmatter (name + description)
|
||||
- [ ] I've included examples
|
||||
- [ ] I've tested the skill with an AI assistant
|
||||
- [ ] I've run `python3 scripts/validate_skills.py`
|
||||
- [ ] My commit message is clear (e.g., "feat: add docker-compose skill")
|
||||
- [ ] I've checked for typos and grammar
|
||||
|
||||
---
|
||||
|
||||
## Commit Message Guidelines
|
||||
|
||||
Use these prefixes:
|
||||
|
||||
- `feat:` - New skill or major feature
|
||||
- `docs:` - Documentation improvements
|
||||
- `fix:` - Bug fixes
|
||||
- `refactor:` - Code improvements without changing functionality
|
||||
- `test:` - Adding or updating tests
|
||||
- `chore:` - Maintenance tasks
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
feat: add kubernetes-deployment skill
|
||||
docs: improve getting started guide
|
||||
fix: correct typo in stripe-integration skill
|
||||
docs: add examples to react-best-practices
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Learning Resources
|
||||
|
||||
### New to Git/GitHub?
|
||||
- [GitHub's Hello World Guide](https://guides.github.com/activities/hello-world/)
|
||||
- [Git Basics](https://git-scm.com/book/en/v2/Getting-Started-Git-Basics)
|
||||
|
||||
### New to Markdown?
|
||||
- [Markdown Guide](https://www.markdownguide.org/basic-syntax/)
|
||||
- [GitHub Markdown](https://guides.github.com/features/mastering-markdown/)
|
||||
|
||||
### New to Open Source?
|
||||
- [First Contributions](https://github.com/firstcontributions/first-contributions)
|
||||
- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
|
||||
|
||||
---
|
||||
|
||||
## Need Help?
|
||||
|
||||
- **Questions?** Open a [Discussion](https://github.com/sickn33/antigravity-awesome-skills/discussions)
|
||||
- **Stuck?** Open an [Issue](https://github.com/sickn33/antigravity-awesome-skills/issues)
|
||||
- **Want feedback?** Open a [Draft Pull Request](https://github.com/sickn33/antigravity-awesome-skills/pulls)
|
||||
|
||||
---
|
||||
|
||||
## Recognition
|
||||
|
||||
All contributors are recognized in our [Contributors](https://github.com/sickn33/antigravity-awesome-skills/graphs/contributors) page!
|
||||
|
||||
---
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
- Be respectful and inclusive
|
||||
- Welcome newcomers
|
||||
- Focus on constructive feedback
|
||||
- Help others learn
|
||||
|
||||
---
|
||||
|
||||
**Thank you for making this project better for everyone!**
|
||||
|
||||
Every contribution, no matter how small, makes a difference. Whether you fix a typo, improve a sentence, or create a whole new skill - you're helping thousands of developers!
|
||||
528
FAQ.md
Normal file
528
FAQ.md
Normal file
@@ -0,0 +1,528 @@
|
||||
# ❓ Frequently Asked Questions (FAQ)
|
||||
|
||||
**Got questions?** You're not alone! Here are answers to the most common questions about Antigravity Awesome Skills.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 General Questions
|
||||
|
||||
### What are "skills" exactly?
|
||||
|
||||
Skills are specialized instruction files that teach AI assistants how to handle specific tasks. Think of them as expert knowledge modules that your AI can load on-demand.
|
||||
|
||||
**Simple analogy:** Just like you might consult different experts (a lawyer, a doctor, a mechanic), skills let your AI become an expert in different areas when you need them.
|
||||
|
||||
---
|
||||
|
||||
### Do I need to install all 179 skills?
|
||||
|
||||
**No!** When you clone the repository, all skills are available, but your AI only loads them when you explicitly invoke them with `@skill-name` or `/skill-name`.
|
||||
|
||||
It's like having a library - all the books are there, but you only read the ones you need.
|
||||
|
||||
---
|
||||
|
||||
### Which AI tools work with these skills?
|
||||
|
||||
These skills work with any AI coding assistant that supports the `SKILL.md` format:
|
||||
|
||||
- ✅ **Claude Code** (Anthropic CLI)
|
||||
- ✅ **Gemini CLI** (Google)
|
||||
- ✅ **Codex CLI** (OpenAI)
|
||||
- ✅ **Cursor** (AI IDE)
|
||||
- ✅ **Antigravity IDE**
|
||||
- ✅ **OpenCode**
|
||||
- ⚠️ **GitHub Copilot** (partial support)
|
||||
|
||||
---
|
||||
|
||||
### Are these skills free to use?
|
||||
|
||||
**Yes!** This repository is licensed under MIT License, which means:
|
||||
- ✅ Free for personal use
|
||||
- ✅ Free for commercial use
|
||||
- ✅ You can modify them
|
||||
- ✅ You can redistribute them
|
||||
|
||||
---
|
||||
|
||||
### Do skills work offline?
|
||||
|
||||
The skill files themselves are stored locally on your computer, but your AI assistant needs an internet connection to function. So:
|
||||
- ✅ Skills are local files
|
||||
- ❌ AI assistant needs internet
|
||||
|
||||
---
|
||||
|
||||
## Installation & Setup
|
||||
|
||||
### Where should I install the skills?
|
||||
|
||||
The universal path that works with most tools is `.agent/skills/`:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
|
||||
```
|
||||
|
||||
**Tool-specific paths:**
|
||||
- Claude Code: `.claude/skills/` or `.agent/skills/`
|
||||
- Gemini CLI: `.gemini/skills/` or `.agent/skills/`
|
||||
- Cursor: `.cursor/skills/` or project root
|
||||
- Antigravity: `.agent/skills/`
|
||||
|
||||
---
|
||||
|
||||
### Can I install skills in multiple projects?
|
||||
|
||||
**Yes!** You have two options:
|
||||
|
||||
**Option 1: Global Installation** (recommended)
|
||||
Install once in your home directory, works for all projects:
|
||||
```bash
|
||||
cd ~
|
||||
git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
|
||||
```
|
||||
|
||||
**Option 2: Per-Project Installation**
|
||||
Install in each project directory:
|
||||
```bash
|
||||
cd /path/to/your/project
|
||||
git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### How do I update skills to the latest version?
|
||||
|
||||
Navigate to your skills directory and pull the latest changes:
|
||||
|
||||
```bash
|
||||
cd .agent/skills
|
||||
git pull origin main
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Can I install only specific skills?
|
||||
|
||||
**Yes!** You can manually copy individual skill folders:
|
||||
|
||||
```bash
|
||||
# Clone the full repo first
|
||||
git clone https://github.com/sickn33/antigravity-awesome-skills.git temp-skills
|
||||
|
||||
# Copy only the skills you want
|
||||
mkdir -p .agent/skills
|
||||
cp -r temp-skills/skills/brainstorming .agent/skills/
|
||||
cp -r temp-skills/skills/stripe-integration .agent/skills/
|
||||
|
||||
# Clean up
|
||||
rm -rf temp-skills
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Using Skills
|
||||
|
||||
### How do I invoke a skill?
|
||||
|
||||
Use the `@` symbol followed by the skill name:
|
||||
|
||||
```
|
||||
@skill-name your request here
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
@brainstorming help me design a todo app
|
||||
@stripe-integration add subscription billing
|
||||
@systematic-debugging fix this test failure
|
||||
```
|
||||
|
||||
Some tools also support `/skill-name` syntax.
|
||||
|
||||
---
|
||||
|
||||
### How do I know which skill to use?
|
||||
|
||||
**Method 1: Browse the README**
|
||||
Check the [Full Skill Registry](README.md#full-skill-registry-179179) organized by category
|
||||
|
||||
**Method 2: Search by keyword**
|
||||
```bash
|
||||
ls skills/ | grep "keyword"
|
||||
```
|
||||
|
||||
**Method 3: Ask your AI**
|
||||
```
|
||||
What skills are available for [topic]?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Can I use multiple skills at once?
|
||||
|
||||
**Yes!** You can invoke multiple skills in the same conversation:
|
||||
|
||||
```
|
||||
@brainstorming help me design this feature
|
||||
|
||||
[After brainstorming...]
|
||||
|
||||
@test-driven-development now let's implement it with tests
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### What if a skill doesn't work?
|
||||
|
||||
**Troubleshooting steps:**
|
||||
|
||||
1. **Check installation path**
|
||||
```bash
|
||||
ls .agent/skills/
|
||||
```
|
||||
|
||||
2. **Verify skill exists**
|
||||
```bash
|
||||
ls .agent/skills/skill-name/
|
||||
```
|
||||
|
||||
3. **Check SKILL.md exists**
|
||||
```bash
|
||||
cat .agent/skills/skill-name/SKILL.md
|
||||
```
|
||||
|
||||
4. **Try restarting your AI assistant**
|
||||
|
||||
5. **Check for typos in skill name**
|
||||
- Use `@brainstorming` not `@brain-storming`
|
||||
- Names are case-sensitive in some tools
|
||||
|
||||
6. **Report the issue**
|
||||
[Open an issue](https://github.com/sickn33/antigravity-awesome-skills/issues) with details
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
### I'm new to open source. Can I still contribute?
|
||||
|
||||
**Absolutely!** Everyone starts somewhere. We welcome contributions from beginners:
|
||||
|
||||
- Fix typos or grammar
|
||||
- Improve documentation clarity
|
||||
- Add examples to existing skills
|
||||
- Report issues or confusing parts
|
||||
|
||||
Check out [CONTRIBUTING.md](CONTRIBUTING.md) for step-by-step instructions.
|
||||
|
||||
---
|
||||
|
||||
### Do I need to know how to code to contribute?
|
||||
|
||||
**No!** Many valuable contributions don't require coding:
|
||||
|
||||
- **Documentation improvements** - Make things clearer
|
||||
- **Examples** - Add real-world usage examples
|
||||
- **Issue reporting** - Tell us what's confusing
|
||||
- **Testing** - Try skills and report what works
|
||||
|
||||
---
|
||||
|
||||
### How do I create a new skill?
|
||||
|
||||
**Quick version:**
|
||||
|
||||
1. Create a folder: `skills/my-skill-name/`
|
||||
2. Create `SKILL.md` with frontmatter and content
|
||||
3. Test it with your AI assistant
|
||||
4. Run validation: `python3 scripts/validate_skills.py`
|
||||
5. Submit a Pull Request
|
||||
|
||||
**Detailed version:** See [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
|
||||
---
|
||||
|
||||
### What makes a good skill?
|
||||
|
||||
A good skill:
|
||||
- ✅ Solves a specific problem
|
||||
- ✅ Has clear, actionable instructions
|
||||
- ✅ Includes examples
|
||||
- ✅ Is reusable across projects
|
||||
- ✅ Follows the standard structure
|
||||
|
||||
See [SKILL_ANATOMY.md](docs/SKILL_ANATOMY.md) for details.
|
||||
|
||||
---
|
||||
|
||||
### How long does it take for my contribution to be reviewed?
|
||||
|
||||
Review times vary, but typically:
|
||||
- **Simple fixes** (typos, docs): 1-3 days
|
||||
- **New skills**: 3-7 days
|
||||
- **Major changes**: 1-2 weeks
|
||||
|
||||
You can speed this up by:
|
||||
- Following the contribution guidelines
|
||||
- Writing clear commit messages
|
||||
- Testing your changes
|
||||
- Responding to feedback quickly
|
||||
|
||||
---
|
||||
|
||||
## Technical Questions
|
||||
|
||||
### What's the difference between SKILL.md and README.md?
|
||||
|
||||
- **SKILL.md** (required): The actual skill definition that the AI reads
|
||||
- **README.md** (optional): Human-readable documentation about the skill
|
||||
|
||||
The AI primarily uses `SKILL.md`, while developers read `README.md`.
|
||||
|
||||
---
|
||||
|
||||
### Can I use scripts or code in my skill?
|
||||
|
||||
**Yes!** Skills can include:
|
||||
- `scripts/` - Helper scripts
|
||||
- `examples/` - Example code
|
||||
- `templates/` - Code templates
|
||||
- `references/` - Documentation
|
||||
|
||||
Reference them in your `SKILL.md`:
|
||||
```markdown
|
||||
Run the setup script:
|
||||
\`\`\`bash
|
||||
bash scripts/setup.sh
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### What programming languages can skills cover?
|
||||
|
||||
**Any language!** Current skills cover:
|
||||
- JavaScript/TypeScript
|
||||
- Python
|
||||
- Go
|
||||
- Rust
|
||||
- Swift
|
||||
- Kotlin
|
||||
- Shell scripting
|
||||
- And many more...
|
||||
|
||||
---
|
||||
|
||||
### Can skills call other skills?
|
||||
|
||||
**Yes!** Skills can reference other skills:
|
||||
|
||||
```markdown
|
||||
## Workflow
|
||||
|
||||
1. First, use `@brainstorming` to design
|
||||
2. Then, use `@writing-plans` to plan
|
||||
3. Finally, use `@test-driven-development` to implement
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### How do I validate my skill before submitting?
|
||||
|
||||
Run the validation script:
|
||||
|
||||
```bash
|
||||
python3 scripts/validate_skills.py
|
||||
```
|
||||
|
||||
This checks:
|
||||
- ✅ SKILL.md exists
|
||||
- ✅ Frontmatter is valid
|
||||
- ✅ Name matches folder name
|
||||
- ✅ Description exists
|
||||
|
||||
---
|
||||
|
||||
## Learning & Best Practices
|
||||
|
||||
### Which skills should I try first?
|
||||
|
||||
**For beginners:**
|
||||
- `@brainstorming` - Design before coding
|
||||
- `@systematic-debugging` - Fix bugs methodically
|
||||
- `@git-pushing` - Commit with good messages
|
||||
|
||||
**For developers:**
|
||||
- `@test-driven-development` - Write tests first
|
||||
- `@react-best-practices` - Modern React patterns
|
||||
- `@senior-fullstack` - Full-stack development
|
||||
|
||||
**For security:**
|
||||
- `@ethical-hacking-methodology` - Security basics
|
||||
- `@burp-suite-testing` - Web app testing
|
||||
|
||||
---
|
||||
|
||||
### How do I learn to write good skills?
|
||||
|
||||
**Learning path:**
|
||||
|
||||
1. **Read existing skills** - Study 5-10 well-written skills
|
||||
2. **Use skills** - Try them with your AI assistant
|
||||
3. **Read guides** - Check [SKILL_ANATOMY.md](docs/SKILL_ANATOMY.md)
|
||||
4. **Start simple** - Create a basic skill first
|
||||
5. **Get feedback** - Submit and learn from reviews
|
||||
6. **Iterate** - Improve based on feedback
|
||||
|
||||
**Recommended skills to study:**
|
||||
- `skills/brainstorming/SKILL.md` - Clear structure
|
||||
- `skills/systematic-debugging/SKILL.md` - Comprehensive
|
||||
- `skills/git-pushing/SKILL.md` - Simple and focused
|
||||
|
||||
---
|
||||
|
||||
### Are there any skills for learning AI/ML?
|
||||
|
||||
**Yes!** Check out:
|
||||
- `@rag-engineer` - RAG systems
|
||||
- `@prompt-engineering` - Prompt design
|
||||
- `@langgraph` - Multi-agent systems
|
||||
- `@ai-agents-architect` - Agent architecture
|
||||
- `@llm-app-patterns` - LLM application patterns
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### My AI assistant doesn't recognize skills
|
||||
|
||||
**Possible causes:**
|
||||
|
||||
1. **Wrong installation path**
|
||||
- Check your tool's documentation for the correct path
|
||||
- Try `.agent/skills/` as the universal path
|
||||
|
||||
2. **Skill name typo**
|
||||
- Verify the exact skill name: `ls .agent/skills/`
|
||||
- Use the exact name from the folder
|
||||
|
||||
3. **Tool doesn't support skills**
|
||||
- Verify your tool supports the SKILL.md format
|
||||
- Check the [Compatibility](#-compatibility) section
|
||||
|
||||
4. **Need to restart**
|
||||
- Restart your AI assistant after installing skills
|
||||
|
||||
---
|
||||
|
||||
### A skill gives incorrect or outdated advice
|
||||
|
||||
**Please report it!**
|
||||
|
||||
1. [Open an issue](https://github.com/sickn33/antigravity-awesome-skills/issues)
|
||||
2. Include:
|
||||
- Which skill
|
||||
- What's incorrect
|
||||
- What should it say instead
|
||||
- Links to correct documentation
|
||||
|
||||
We'll update it quickly!
|
||||
|
||||
---
|
||||
|
||||
### Can I modify skills for my own use?
|
||||
|
||||
**Yes!** The MIT License allows you to:
|
||||
- ✅ Modify skills for your needs
|
||||
- ✅ Create private versions
|
||||
- ✅ Customize for your team
|
||||
|
||||
**To modify:**
|
||||
1. Copy the skill to a new location
|
||||
2. Edit the SKILL.md file
|
||||
3. Use your modified version
|
||||
|
||||
**Consider contributing improvements back!**
|
||||
|
||||
---
|
||||
|
||||
## Statistics & Info
|
||||
|
||||
### How many skills are there?
|
||||
|
||||
**179 skills** across 10+ categories as of the latest update.
|
||||
|
||||
---
|
||||
|
||||
### How often are skills updated?
|
||||
|
||||
- **Bug fixes**: As soon as reported
|
||||
- **New skills**: Added regularly by contributors
|
||||
- **Updates**: When best practices change
|
||||
|
||||
**Stay updated:**
|
||||
```bash
|
||||
cd .agent/skills
|
||||
git pull origin main
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Who maintains this repository?
|
||||
|
||||
This is a community-driven project with contributions from:
|
||||
- Original creators
|
||||
- Open source contributors
|
||||
- AI coding assistant users worldwide
|
||||
|
||||
See [Credits & Sources](README.md#credits--sources) for attribution.
|
||||
|
||||
---
|
||||
|
||||
## Still Have Questions?
|
||||
|
||||
### Where can I get help?
|
||||
|
||||
- **[GitHub Discussions](https://github.com/sickn33/antigravity-awesome-skills/discussions)** - Ask questions
|
||||
- **[GitHub Issues](https://github.com/sickn33/antigravity-awesome-skills/issues)** - Report bugs
|
||||
- **Documentation** - Read the guides in this repo
|
||||
- **Community** - Connect with other users
|
||||
|
||||
---
|
||||
|
||||
### How can I stay updated?
|
||||
|
||||
- **Star the repository** on GitHub
|
||||
- **Watch the repository** for updates
|
||||
- **Subscribe to releases** for notifications
|
||||
- **Follow contributors** on social media
|
||||
|
||||
---
|
||||
|
||||
### Can I use these skills commercially?
|
||||
|
||||
**Yes!** The MIT License permits commercial use. You can:
|
||||
- ✅ Use in commercial projects
|
||||
- ✅ Use in client work
|
||||
- ✅ Include in paid products
|
||||
- ✅ Modify for commercial purposes
|
||||
|
||||
**Only requirement:** Keep the license notice.
|
||||
|
||||
---
|
||||
|
||||
## 💡 Pro Tips
|
||||
|
||||
- Start with `@brainstorming` before building anything new
|
||||
- Use `@systematic-debugging` when stuck on bugs
|
||||
- Try `@test-driven-development` for better code quality
|
||||
- Explore `@skill-creator` to make your own skills
|
||||
- Read skill descriptions to understand when to use them
|
||||
|
||||
---
|
||||
|
||||
**Question not answered?**
|
||||
|
||||
[Open a discussion](https://github.com/sickn33/antigravity-awesome-skills/discussions) and we'll help you out! 🙌
|
||||
201
GETTING_STARTED.md
Normal file
201
GETTING_STARTED.md
Normal file
@@ -0,0 +1,201 @@
|
||||
# Getting Started with Antigravity Awesome Skills
|
||||
|
||||
**New here? This guide will help you understand and use this repository in 5 minutes!**
|
||||
|
||||
---
|
||||
|
||||
## 🤔 What Are "Skills"?
|
||||
|
||||
Think of skills as **specialized instruction manuals** for AI coding assistants.
|
||||
|
||||
**Simple analogy:** Just like you might hire different experts (a designer, a security expert, a marketer), these skills let your AI assistant become an expert in specific areas when you need them.
|
||||
|
||||
---
|
||||
|
||||
## 📦 What's Inside This Repository?
|
||||
|
||||
This repo contains **179 ready-to-use skills** organized in the `skills/` folder. Each skill is a folder with at least one file: `SKILL.md`
|
||||
|
||||
```
|
||||
skills/
|
||||
├── brainstorming/
|
||||
│ └── SKILL.md ← The skill definition
|
||||
├── stripe-integration/
|
||||
│ └── SKILL.md
|
||||
├── react-best-practices/
|
||||
│ └── SKILL.md
|
||||
└── ... (176 more skills)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How Do Skills Work?
|
||||
|
||||
### Step 1: Install Skills
|
||||
Copy the skills to your AI tool's directory:
|
||||
|
||||
```bash
|
||||
# For most AI tools (Claude Code, Gemini CLI, etc.)
|
||||
git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
|
||||
```
|
||||
|
||||
### Step 2: Use a Skill
|
||||
In your AI chat, mention the skill:
|
||||
|
||||
```
|
||||
@brainstorming help me design a todo app
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```
|
||||
/stripe-integration add payment processing to my app
|
||||
```
|
||||
|
||||
### Step 3: The AI Becomes an Expert
|
||||
The AI loads that skill's knowledge and helps you with specialized expertise!
|
||||
|
||||
---
|
||||
|
||||
## Which AI Tools Work With This?
|
||||
|
||||
| Tool | Works? | Installation Path |
|
||||
|------|--------|-------------------|
|
||||
| **Claude Code** | ✅ Yes | `.claude/skills/` or `.agent/skills/` |
|
||||
| **Gemini CLI** | ✅ Yes | `.gemini/skills/` or `.agent/skills/` |
|
||||
| **Cursor** | ✅ Yes | `.cursor/skills/` |
|
||||
| **GitHub Copilot** | ⚠️ Partial | Copy to `.github/copilot/` |
|
||||
| **Antigravity IDE** | ✅ Yes | `.agent/skills/` |
|
||||
|
||||
---
|
||||
|
||||
## Skill Categories (Simplified)
|
||||
|
||||
### **Creative & Design** (10 skills)
|
||||
Make beautiful things: UI design, art, themes, web components
|
||||
- Try: `@frontend-design`, `@canvas-design`, `@ui-ux-pro-max`
|
||||
|
||||
### **Development** (25 skills)
|
||||
Write better code: testing, debugging, React patterns, architecture
|
||||
- Try: `@test-driven-development`, `@systematic-debugging`, `@react-best-practices`
|
||||
|
||||
### **Security** (50 skills)
|
||||
Ethical hacking and penetration testing tools
|
||||
- Try: `@ethical-hacking-methodology`, `@burp-suite-testing`
|
||||
|
||||
### **AI & Agents** (30 skills)
|
||||
Build AI apps: RAG, LangGraph, prompt engineering, voice agents
|
||||
- Try: `@rag-engineer`, `@prompt-engineering`, `@langgraph`
|
||||
|
||||
### **Documents** (4 skills)
|
||||
Work with Word, Excel, PowerPoint, PDF files
|
||||
- Try: `@docx-official`, `@xlsx-official`, `@pdf-official`
|
||||
|
||||
### **Marketing** (23 skills)
|
||||
Grow your product: SEO, copywriting, ads, email campaigns
|
||||
- Try: `@copywriting`, `@seo-audit`, `@page-cro`
|
||||
|
||||
### **Integrations** (25 skills)
|
||||
Connect to services: Stripe, Firebase, Twilio, Discord, Slack
|
||||
- Try: `@stripe-integration`, `@firebase`, `@clerk-auth`
|
||||
|
||||
---
|
||||
|
||||
## Your First Skill: A Quick Example
|
||||
|
||||
Let's try the **brainstorming** skill:
|
||||
|
||||
1. **Open your AI assistant** (Claude Code, Cursor, etc.)
|
||||
|
||||
2. **Type this:**
|
||||
```
|
||||
@brainstorming I want to build a simple weather app
|
||||
```
|
||||
|
||||
3. **What happens:**
|
||||
- The AI loads the brainstorming skill
|
||||
- It asks you questions one at a time
|
||||
- It helps you design the app before coding
|
||||
- It creates a design document for you
|
||||
|
||||
4. **Result:** You get a well-thought-out plan instead of jumping straight to code!
|
||||
|
||||
---
|
||||
|
||||
## How to Find the Right Skill
|
||||
|
||||
### Method 1: Browse by Category
|
||||
Check the [Full Skill Registry](README.md#full-skill-registry-179179) in the main README
|
||||
|
||||
### Method 2: Search by Keyword
|
||||
Use your file explorer or terminal:
|
||||
```bash
|
||||
# Find skills related to "testing"
|
||||
ls skills/ | grep test
|
||||
|
||||
# Find skills related to "auth"
|
||||
ls skills/ | grep auth
|
||||
```
|
||||
|
||||
### Method 3: Look at the Index
|
||||
Check `skills_index.json` for a machine-readable list
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Want to Contribute?
|
||||
|
||||
Great! Here's how:
|
||||
|
||||
### Option 1: Improve Documentation
|
||||
- Make READMEs clearer
|
||||
- Add more examples
|
||||
- Fix typos or confusing parts
|
||||
|
||||
### Option 2: Create a New Skill
|
||||
See our [CONTRIBUTING.md](CONTRIBUTING.md) for step-by-step instructions
|
||||
|
||||
### Option 3: Report Issues
|
||||
Found something confusing? [Open an issue](https://github.com/sickn33/antigravity-awesome-skills/issues)
|
||||
|
||||
---
|
||||
|
||||
## ❓ Common Questions
|
||||
|
||||
### Q: Do I need to install all 179 skills?
|
||||
**A:** No! Clone the whole repo, and your AI will only load skills when you use them.
|
||||
|
||||
### Q: Can I create my own skills?
|
||||
**A:** Yes! Check out the `@skill-creator` skill or read [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
|
||||
### Q: What if my AI tool isn't listed?
|
||||
**A:** If it supports the `SKILL.md` format, try `.agent/skills/` - it's the universal path.
|
||||
|
||||
### Q: Are these skills free?
|
||||
**A:** Yes! MIT License. Use them however you want.
|
||||
|
||||
### Q: Do skills work offline?
|
||||
**A:** The skill files are local, but your AI assistant needs internet to function.
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. ✅ Install the skills in your AI tool
|
||||
2. ✅ Try 2-3 skills from different categories
|
||||
3. ✅ Read [CONTRIBUTING.md](CONTRIBUTING.md) if you want to help
|
||||
4. ✅ Star the repo if you find it useful! ⭐
|
||||
|
||||
---
|
||||
|
||||
## 💡 Pro Tips
|
||||
|
||||
- **Start with `@brainstorming`** before building anything new
|
||||
- **Use `@systematic-debugging`** when you're stuck on a bug
|
||||
- **Try `@test-driven-development`** to write better code
|
||||
- **Explore `@skill-creator`** to make your own skills
|
||||
|
||||
---
|
||||
|
||||
**Still confused?** Open an issue and we'll help you out! 🙌
|
||||
|
||||
**Ready to dive deeper?** Check out the main [README.md](README.md) for the complete skill list.
|
||||
445
README.md
445
README.md
@@ -1,6 +1,6 @@
|
||||
# 🌌 Antigravity Awesome Skills: 179+ Agentic Skills for Claude Code, Gemini CLI, Cursor, Copilot & More
|
||||
# 🌌 Antigravity Awesome Skills: 233+ Agentic Skills for Claude Code, Gemini CLI, Cursor, Copilot & More
|
||||
|
||||
> **The Ultimate Collection of 179+ Universal Agentic Skills for AI Coding Assistants — Claude Code, Gemini CLI, Codex CLI, Antigravity IDE, GitHub Copilot, Cursor, OpenCode**
|
||||
> **The Ultimate Collection of 233+ Universal Agentic Skills for AI Coding Assistants — Claude Code, Gemini CLI, Codex CLI, Antigravity IDE, GitHub Copilot, Cursor, OpenCode**
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://claude.ai)
|
||||
@@ -11,7 +11,7 @@
|
||||
[](https://github.com/opencode-ai/opencode)
|
||||
[](https://github.com/anthropics/antigravity)
|
||||
|
||||
**Antigravity Awesome Skills** is a curated, battle-tested library of **179 high-performance agentic skills** designed to work seamlessly across all major AI coding assistants:
|
||||
**Antigravity Awesome Skills** is a curated, battle-tested library of **233 high-performance agentic skills** designed to work seamlessly across all major AI coding assistants:
|
||||
|
||||
- 🟣 **Claude Code** (Anthropic CLI)
|
||||
- 🔵 **Gemini CLI** (Google DeepMind)
|
||||
@@ -25,6 +25,7 @@ This repository provides essential skills to transform your AI assistant into a
|
||||
|
||||
## 📍 Table of Contents
|
||||
|
||||
- [🚀 New Here? Start Here!](#-new-here-start-here)
|
||||
- [🔌 Compatibility](#-compatibility)
|
||||
- [Features & Categories](#features--categories)
|
||||
- [Full Skill Registry](#full-skill-registry-155155)
|
||||
@@ -35,6 +36,34 @@ This repository provides essential skills to transform your AI assistant into a
|
||||
|
||||
---
|
||||
|
||||
## New Here? Start Here!
|
||||
|
||||
**First time using this repository?** We've created beginner-friendly guides to help you get started:
|
||||
|
||||
- **[GETTING_STARTED.md](GETTING_STARTED.md)** - Complete beginner's guide (5-minute read)
|
||||
- **[CONTRIBUTING.md](CONTRIBUTING.md)** - How to contribute (step-by-step)
|
||||
- **[SKILL_ANATOMY.md](docs/SKILL_ANATOMY.md)** - Understanding how skills work
|
||||
- **[VISUAL_GUIDE.md](docs/VISUAL_GUIDE.md)** - Visual guide with diagrams
|
||||
|
||||
**Quick Start:**
|
||||
|
||||
```bash
|
||||
# 1. Install skills
|
||||
git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
|
||||
|
||||
# 2. Use a skill in your AI assistant
|
||||
@brainstorming help me design a todo app
|
||||
```
|
||||
|
||||
That's it! Your AI assistant now has 233 specialized skills. 🎉
|
||||
|
||||
**Additional Resources:**
|
||||
|
||||
- 💡 **[Real-World Examples](docs/EXAMPLES.md)** - See skills in action
|
||||
- ❓ **[FAQ](FAQ.md)** - Common questions answered
|
||||
|
||||
---
|
||||
|
||||
## 🔌 Compatibility
|
||||
|
||||
These skills follow the universal **SKILL.md** format and work with any AI coding assistant that supports agentic skills:
|
||||
@@ -80,193 +109,236 @@ The repository is organized into several key areas of expertise:
|
||||
|
||||
---
|
||||
|
||||
## Full Skill Registry (179/179)
|
||||
## Full Skill Registry (233/233)
|
||||
|
||||
Below is the complete list of available skills. Each skill folder contains a `SKILL.md` that can be imported into Antigravity or Claude Code.
|
||||
|
||||
> [!NOTE] > **Document Skills**: We provide both **community** and **official Anthropic** versions for DOCX, PDF, PPTX, and XLSX. Locally, the official versions are used by default (via symlinks). In the repository, both versions are available for flexibility.
|
||||
|
||||
| Skill Name | Description | Path |
|
||||
| :-------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------- |
|
||||
| **3D Web Experience** | Expert in building 3D experiences for the web - Three.js, React Three Fiber, Spline, WebGL. | `skills/3d-web-experience` |
|
||||
| **A/B Test Setup** | Plan and implement A/B tests with proper experiment design, statistical significance, and test analysis. | `skills/ab-test-setup` |
|
||||
| **Active Directory Attacks** | This skill should be used when the user asks to "attack Active Directory", "exploit AD", "Kerberoasting", "DCSync", "pass-the-hash", "BloodHound enumeration", "Golden Ticket", "Silver Ticket", "AS-REP roasting", "NTLM relay", or needs guidance on Windows domain penetration testing. | `skills/active-directory-attacks` |
|
||||
| **Address GitHub Comments** | Use when you need to address review or issue comments on an open GitHub Pull Request using the gh CLI. | `skills/address-github-comments` |
|
||||
| **Agent Evaluation** | Testing and benchmarking LLM agents including behavioral testing, capability assessment, reliability metrics. | `skills/agent-evaluation` |
|
||||
| **Agent Manager Skill** | Use when you need to manage multiple local CLI agents via tmux sessions (start/stop/monitor/assign) with cron-friendly scheduling. | `skills/agent-manager-skill` |
|
||||
| **Agent Memory Systems** | Memory architecture for agents: short-term, long-term (vector stores), and cognitive architectures. | `skills/agent-memory-systems` |
|
||||
| **Agent Tool Builder** | Tool design from schema to error handling. JSON Schema best practices, validation, and MCP. | `skills/agent-tool-builder` |
|
||||
| **AI Agents Architect** | Expert in autonomous AI agents. Tool use, memory systems, planning strategies, multi-agent orchestration. | `skills/ai-agents-architect` |
|
||||
| **AI Product** | LLM integration patterns, RAG architecture, prompt engineering, AI UX, and cost optimization. | `skills/ai-product` |
|
||||
| **AI Wrapper Product** | Building products that wrap AI APIs into focused tools. Prompt engineering, cost management. | `skills/ai-wrapper-product` |
|
||||
| **Algolia Search** | Algolia search implementation, indexing strategies, React InstantSearch, relevance tuning. | `skills/algolia-search` |
|
||||
| **Algorithmic Art** | Creating algorithmic art using p5. | `skills/algorithmic-art` |
|
||||
| **Analytics Tracking** | Set up analytics tracking with GA4, GTM, and custom event implementations for marketing measurement. | `skills/analytics-tracking` |
|
||||
| **API Fuzzing for Bug Bounty** | This skill should be used when the user asks to "test API security", "fuzz APIs", "find IDOR vulnerabilities", "test REST API", "test GraphQL", "API penetration testing", "bug bounty API testing", or needs guidance on API security assessment techniques. | `skills/api-fuzzing-bug-bounty` |
|
||||
| **App Store Optimization** | Complete App Store Optimization (ASO) toolkit for researching, optimizing, and tracking mobile app performance on Apple App Store and Google Play Store. | `skills/app-store-optimization` |
|
||||
| **Autonomous Agent Patterns** | "Design patterns for building autonomous coding agents. | `skills/autonomous-agent-patterns` |
|
||||
| **Autonomous Agents** | AI systems that independently decompose goals, plan actions, execute tools. ReAct, reflection. | `skills/autonomous-agents` |
|
||||
| **AWS Penetration Testing** | This skill should be used when the user asks to "pentest AWS", "test AWS security", "enumerate IAM", "exploit cloud infrastructure", "AWS privilege escalation", "S3 bucket testing", "metadata SSRF", "Lambda exploitation", or needs guidance on Amazon Web Services security assessment. | `skills/aws-penetration-testing` |
|
||||
| **AWS Serverless** | Serverless on AWS. Lambda, API Gateway, DynamoDB, SQS/SNS, SAM/CDK deployment. | `skills/aws-serverless` |
|
||||
| **Azure Functions** | Azure Functions patterns. Isolated worker model, Durable Functions, cold start optimization. | `skills/azure-functions` |
|
||||
| **Backend Guidelines** | Comprehensive backend development guide for Node. | `skills/backend-dev-guidelines` |
|
||||
| **BlockRun** | Agent wallet for LLM micropayments. Use when user needs capabilities Claude lacks (image generation, real-time X/Twitter data) or explicitly requests external models ("blockrun", "use grok", "use gpt", "dall-e", "deepseek"). | `skills/blockrun` |
|
||||
| **Brainstorming** | "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. | `skills/brainstorming` |
|
||||
| **Brand Guidelines (Anthropic)** | Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. | `skills/brand-guidelines-anthropic` |
|
||||
| **Brand Guidelines (Community)** | Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. | `skills/brand-guidelines-community` |
|
||||
| **Broken Authentication Testing** | This skill should be used when the user asks to "test for broken authentication vulnerabilities", "assess session management security", "perform credential stuffing tests", "evaluate password policies", "test for session fixation", or "identify authentication bypass flaws". | `skills/broken-authentication` |
|
||||
| **Browser Automation** | Browser automation with Playwright and Puppeteer. Testing, scraping, agentic control. | `skills/browser-automation` |
|
||||
| **Browser Extension Builder** | Building browser extensions - Chrome, Firefox. Manifest v3, content scripts, monetization. | `skills/browser-extension-builder` |
|
||||
| **BullMQ Specialist** | BullMQ for Redis-backed job queues, background processing in Node.js/TypeScript. | `skills/bullmq-specialist` |
|
||||
| **Bun Development** | "Modern JavaScript/TypeScript development with Bun runtime. | `skills/bun-development` |
|
||||
| **Burp Suite Web Application Testing** | This skill should be used when the user asks to "intercept HTTP traffic", "modify web requests", "use Burp Suite for testing", "perform web vulnerability scanning", "test with Burp Repeater", "analyze HTTP history", or "configure proxy for web testing". | `skills/burp-suite-testing` |
|
||||
| **Canvas Design** | Create beautiful visual art in . | `skills/canvas-design` |
|
||||
| **Claude Code Guide** | Master guide for using Claude Code effectively. | `skills/claude-code-guide` |
|
||||
| **Claude D3.js** | Creating interactive data visualisations using d3. | `skills/claude-d3js-skill` |
|
||||
| **Clerk Auth** | Clerk auth implementation, middleware, organizations, webhooks, user sync. | `skills/clerk-auth` |
|
||||
| **Cloud Penetration Testing** | This skill should be used when the user asks to "perform cloud penetration testing", "assess Azure or AWS or GCP security", "enumerate cloud resources", "exploit cloud misconfigurations", "test O365 security", "extract secrets from cloud environments", or "audit cloud infrastructure". | `skills/cloud-penetration-testing` |
|
||||
| **Computer Use Agents** | AI agents that interact with computers like humans. Screen control, sandboxing. | `skills/computer-use-agents` |
|
||||
| **Concise Planning** | Use when a user asks for a plan for a coding task, to generate a clear, actionable, and atomic checklist. | `skills/concise-planning` |
|
||||
| **Competitor Alternatives** | Create compelling competitor comparison and alternative pages for SEO and conversions. | `skills/competitor-alternatives` |
|
||||
| **Content Creator** | Create SEO-optimized marketing content with consistent brand voice. | `skills/content-creator` |
|
||||
| **Context Window Management** | Managing LLM context windows. Summarization, trimming, routing. | `skills/context-window-management` |
|
||||
| **Conversation Memory** | Persistent memory for LLM conversations. Short-term, long-term, entity-based memory. | `skills/conversation-memory` |
|
||||
| **Core Components** | Core component library and design system patterns. | `skills/core-components` |
|
||||
| **Copy Editing** | Edit and polish existing marketing copy with a systematic seven-sweeps framework. | `skills/copy-editing` |
|
||||
| **Copywriting** | Write compelling marketing copy for homepages, landing pages, pricing pages, and feature pages. | `skills/copywriting` |
|
||||
| **CrewAI** | Role-based multi-agent framework. Agent design, task definition, crew orchestration. | `skills/crewai` |
|
||||
| **Cross-Site Scripting and HTML Injection Testing** | This skill should be used when the user asks to "test for XSS vulnerabilities", "perform cross-site scripting attacks", "identify HTML injection flaws", "exploit client-side injection vulnerabilities", "steal cookies via XSS", or "bypass content security policies". | `skills/xss-html-injection` |
|
||||
| **Discord Bot Architect** | Production Discord bots. Discord.js, Pycord, slash commands, sharding. | `skills/discord-bot-architect` |
|
||||
| **Dispatching Parallel Agents** | Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies. | `skills/dispatching-parallel-agents` |
|
||||
| **Doc Co-authoring** | Guide users through a structured workflow for co-authoring documentation. | `skills/doc-coauthoring` |
|
||||
| **DOCX (Official)** | "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. | `skills/docx-official` |
|
||||
| **Email Sequence** | Create and optimize email sequences, drip campaigns, and lifecycle email programs. | `skills/email-sequence` |
|
||||
| **Email Systems** | Transactional email, marketing automation, deliverability, infrastructure. | `skills/email-systems` |
|
||||
| **Ethical Hacking Methodology** | This skill should be used when the user asks to "learn ethical hacking", "understand penetration testing lifecycle", "perform reconnaissance", "conduct security scanning", "exploit vulnerabilities", or "write penetration test reports". | `skills/ethical-hacking-methodology` |
|
||||
| **Executing Plans** | Use when you have a written implementation plan to execute in a separate session with review checkpoints. | `skills/executing-plans` |
|
||||
| **File Organizer** | Intelligently organizes files and folders by understanding context, finding duplicates, and suggesting better organizational structures. | `skills/file-organizer` |
|
||||
| **File Path Traversal Testing** | This skill should be used when the user asks to "test for directory traversal", "exploit path traversal vulnerabilities", "read arbitrary files through web applications", "find LFI vulnerabilities", or "access files outside web root". | `skills/file-path-traversal` |
|
||||
| **File Uploads** | File uploads and cloud storage. S3, Cloudflare R2, presigned URLs. | `skills/file-uploads` |
|
||||
| **Finishing Dev Branch** | Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup. | `skills/finishing-a-development-branch` |
|
||||
| **Firebase** | Firebase Auth, Firestore, Realtime Database, Cloud Functions, Storage. | `skills/firebase` |
|
||||
| **Form CRO** | Optimize lead capture forms, contact forms, demo request forms for higher conversion rates. | `skills/form-cro` |
|
||||
| **Free Tool Strategy** | Plan and build free tools for marketing, lead generation, and SEO value. | `skills/free-tool-strategy` |
|
||||
| **Frontend Design** | Create distinctive, production-grade frontend interfaces with high design quality. | `skills/frontend-design` |
|
||||
| **Frontend Guidelines** | Frontend development guidelines for React/TypeScript applications. | `skills/frontend-dev-guidelines` |
|
||||
| **GCP Cloud Run** | Serverless on GCP. Cloud Run services and functions, Pub/Sub. | `skills/gcp-cloud-run` |
|
||||
| **Git Pushing** | Stage, commit, and push git changes with conventional commit messages. | `skills/git-pushing` |
|
||||
| **GitHub Workflow Automation** | "Automate GitHub workflows with AI assistance. | `skills/github-workflow-automation` |
|
||||
| **GraphQL** | Schema design, resolvers, DataLoader, federation, Apollo/urql integration. | `skills/graphql` |
|
||||
| **HTML Injection Testing** | This skill should be used when the user asks to "test for HTML injection", "inject HTML into web pages", "perform HTML injection attacks", "deface web applications", or "test content injection vulnerabilities". | `skills/html-injection-testing` |
|
||||
| **HubSpot Integration** | HubSpot CRM integration. OAuth, CRM objects, webhooks, custom objects. | `skills/hubspot-integration` |
|
||||
| **IDOR Vulnerability Testing** | This skill should be used when the user asks to "test for insecure direct object references," "find IDOR vulnerabilities," "exploit broken access control," "enumerate user IDs or object references," or "bypass authorization to access other users' data. | `skills/idor-testing` |
|
||||
| **Inngest** | Inngest for serverless background jobs, event-driven workflows. | `skills/inngest` |
|
||||
| **Interactive Portfolio** | Building portfolios that land jobs. Developer, designer portfolios. | `skills/interactive-portfolio` |
|
||||
| **Internal Comms (Anthropic)** | A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. | `skills/internal-comms-anthropic` |
|
||||
| **Internal Comms (Community)** | A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. | `skills/internal-comms-community` |
|
||||
| **JavaScript Mastery** | "Comprehensive JavaScript reference covering 33+ essential concepts every developer should know. | `skills/javascript-mastery` |
|
||||
| **Kaizen** | Guide for continuous improvement, error proofing, and standardization. | `skills/kaizen` |
|
||||
| **Langfuse** | Open-source LLM observability. Tracing, prompt management, evaluation. | `skills/langfuse` |
|
||||
| **LangGraph** | Stateful, multi-actor AI applications. Graph construction, persistence. | `skills/langgraph` |
|
||||
| **Launch Strategy** | Plan product launches, feature announcements, and go-to-market strategies. | `skills/launch-strategy` |
|
||||
| **Linux Privilege Escalation** | This skill should be used when the user asks to "escalate privileges on Linux", "find privesc vectors on Linux systems", "exploit sudo misconfigurations", "abuse SUID binaries", "exploit cron jobs for root access", "enumerate Linux systems for privilege escalation", or "gain root access from low-privilege shell". | `skills/linux-privilege-escalation` |
|
||||
| **Linux Shell Scripting** | This skill should be used when the user asks to "create bash scripts", "automate Linux tasks", "monitor system resources", "backup files", "manage users", or "write production shell scripts". | `skills/linux-shell-scripting` |
|
||||
| **LLM App Patterns** | "Production-ready patterns for building LLM applications. | `skills/llm-app-patterns` |
|
||||
| **Loki Mode** | Multi-agent autonomous startup system for Claude Code. | `skills/loki-mode` |
|
||||
| **Marketing Ideas** | 140 proven SaaS marketing ideas and strategies organized by category. | `skills/marketing-ideas` |
|
||||
| **Marketing Psychology** | 70+ mental models and psychological principles for marketing and persuasion. | `skills/marketing-psychology` |
|
||||
| **MCP Builder** | Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. | `skills/mcp-builder` |
|
||||
| **Metasploit Framework** | This skill should be used when the user asks to "use Metasploit for penetration testing", "exploit vulnerabilities with msfconsole", "create payloads with msfvenom", "perform post-exploitation", "use auxiliary modules for scanning", or "develop custom exploits". | `skills/metasploit-framework` |
|
||||
| **Moodle External API Development** | Create custom external web service APIs for Moodle LMS. Use when implementing web services for course management, user tracking, quiz operations, or custom plugin functionality. Covers parameter validation, database operations, error handling, service registration, and Moodle coding standards. | `skills/moodle-external-api-development` |
|
||||
| **Micro-SaaS Launcher** | Launching small SaaS products fast. Idea validation, MVP, pricing. | `skills/micro-saas-launcher` |
|
||||
| **Neon Postgres** | Neon serverless Postgres, branching, connection pooling, Prisma integration. | `skills/neon-postgres` |
|
||||
| **Network 101** | This skill should be used when the user asks to "set up a web server", "configure HTTP or HTTPS", "perform SNMP enumeration", "configure SMB shares", "test network services", or needs guidance on configuring and testing network services for penetration testing labs. | `skills/network-101` |
|
||||
| **Next.js Supabase Auth** | Supabase Auth with Next.js App Router. Auth middleware. | `skills/nextjs-supabase-auth` |
|
||||
| **NotebookLM** | Use this skill to query your Google NotebookLM notebooks directly from Claude Code for source-grounded, citation-backed answers from Gemini. | `skills/notebooklm` |
|
||||
| **Notion Template Business** | Building and selling Notion templates. Design, pricing, marketing. | `skills/notion-template-business` |
|
||||
| **Onboarding CRO** | Optimize post-signup onboarding, user activation, and time-to-value. | `skills/onboarding-cro` |
|
||||
| **PDF (Official)** | Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. | `skills/pdf-official` |
|
||||
| **Pentest Checklist** | This skill should be used when the user asks to "plan a penetration test", "create a security assessment checklist", "prepare for penetration testing", "define pentest scope", "follow security testing best practices", or needs a structured methodology for penetration testing engagements. | `skills/pentest-checklist` |
|
||||
| **Pentest Commands** | This skill should be used when the user asks to "run pentest commands", "scan with nmap", "use metasploit exploits", "crack passwords with hydra or john", "scan web vulnerabilities with nikto", "enumerate networks", or needs essential penetration testing command references. | `skills/pentest-commands` |
|
||||
| **Page CRO** | Conversion rate optimization for marketing pages - homepages, landing pages, pricing pages. | `skills/page-cro` |
|
||||
| **Paid Ads** | Create and optimize paid ad campaigns on Google Ads, Meta, LinkedIn, and other platforms. | `skills/paid-ads` |
|
||||
| **Paywall Upgrade CRO** | Optimize in-app paywalls, upgrade screens, and freemium conversion moments. | `skills/paywall-upgrade-cro` |
|
||||
| **Personal Tool Builder** | Building custom tools. Rapid prototyping, local-first apps, CLI tools. | `skills/personal-tool-builder` |
|
||||
| **Plaid Fintech** | Plaid API for banking. Link token flows, transactions, ACH. | `skills/plaid-fintech` |
|
||||
| **Planning With Files** | Implements Manus-style file-based planning for complex tasks. | `skills/planning-with-files` |
|
||||
| **Playwright Automation** | Complete browser automation with Playwright. | `skills/playwright-skill` |
|
||||
| **Popup CRO** | Create and optimize popups, modals, and overlays for conversion. | `skills/popup-cro` |
|
||||
| **PPTX (Official)** | "Presentation creation, editing, and analysis. | `skills/pptx-official` |
|
||||
| **Privilege Escalation Methods** | This skill should be used when the user asks to "escalate privileges", "get root access", "become administrator", "privesc techniques", "abuse sudo", "exploit SUID binaries", "Kerberoasting", "pass-the-ticket", "token impersonation", or needs guidance on post-exploitation privilege escalation for Linux or Windows systems. | `skills/privilege-escalation-methods` |
|
||||
| **Pricing Strategy** | Design pricing, packaging, and monetization strategy for SaaS products. | `skills/pricing-strategy` |
|
||||
| **Product Toolkit** | Comprehensive toolkit for product managers including RICE prioritization, customer interview analysis, PRD templates, discovery frameworks, and go-to-market strategies. | `skills/product-manager-toolkit` |
|
||||
| **Prompt Caching** | Caching strategies for LLM prompts. Anthropic caching, CAG. | `skills/prompt-caching` |
|
||||
| **Prompt Engineer** | Designing prompts for LLM applications. Structure, evaluation. | `skills/prompt-engineer` |
|
||||
| **Prompt Engineering** | Expert guide on prompt engineering patterns, best practices, and optimization techniques. | `skills/prompt-engineering` |
|
||||
| **Prompt Library** | "Curated collection of high-quality prompts for various use cases. | `skills/prompt-library` |
|
||||
| **Programmatic SEO** | Build SEO-driven pages at scale using templates and data. | `skills/programmatic-seo` |
|
||||
| **RAG Engineer** | Building RAG systems. Embedding models, vector databases, chunking. | `skills/rag-engineer` |
|
||||
| **RAG Implementation** | RAG patterns. Chunking, embeddings, vector stores. | `skills/rag-implementation` |
|
||||
| **React Best Practices** | React and Next. | `skills/react-best-practices` |
|
||||
| **React UI Patterns** | Modern React UI patterns for loading states, error handling, and data fetching. | `skills/react-ui-patterns` |
|
||||
| **Receiving Code Review** | Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation. | `skills/receiving-code-review` |
|
||||
| **Red Team Tools and Methodology** | This skill should be used when the user asks to "follow red team methodology", "perform bug bounty hunting", "automate reconnaissance", "hunt for XSS vulnerabilities", "enumerate subdomains", or needs security researcher techniques and tool configurations from top bug bounty hunters. | `skills/red-team-tools` |
|
||||
| **Referral Program** | Design referral programs, affiliate programs, and word-of-mouth strategies. | `skills/referral-program` |
|
||||
| **Requesting Code Review** | Use when completing tasks, implementing major features, or before merging to verify work meets requirements. | `skills/requesting-code-review` |
|
||||
| **Salesforce Development** | Salesforce integration, Apex development, Lightning components. | `skills/salesforce-development` |
|
||||
| **Schema Markup** | Add structured data and JSON-LD schema markup for SEO and rich snippets. | `skills/schema-markup` |
|
||||
| **Scroll Experience** | GSAP/Framer scroll-driven storytelling. Parallax effects. | `skills/scroll-experience` |
|
||||
| **Security Scanning Tools** | This skill should be used when the user asks to "perform vulnerability scanning", "scan networks for open ports", "assess web application security", "scan wireless networks", "detect malware", "check cloud security", or "evaluate system compliance". | `skills/scanning-tools` |
|
||||
| **Segment CDP** | Segment customer data platform. Event tracking, identity resolution. | `skills/segment-cdp` |
|
||||
| **Senior Architect** | Comprehensive software architecture skill for designing scalable, maintainable systems using ReactJS, NextJS, NodeJS, Express, React Native, Swift, Kotlin, Flutter, Postgres, GraphQL, Go, Python. | `skills/senior-architect` |
|
||||
| **Senior Fullstack** | Comprehensive fullstack development skill for building complete web applications with React, Next. | `skills/senior-fullstack` |
|
||||
| **SEO Audit** | Audit technical and on-page SEO issues for better search rankings. | `skills/seo-audit` |
|
||||
| **Shodan Reconnaissance and Pentesting** | This skill should be used when the user asks to "search for exposed devices on the internet," "perform Shodan reconnaissance," "find vulnerable services using Shodan," "scan IP ranges with Shodan," or "discover IoT devices and open ports. | `skills/shodan-reconnaissance` |
|
||||
| **Shopify Apps** | Building Shopify apps. App Bridge, Polaris, webhooks. | `skills/shopify-apps` |
|
||||
| **Shopify Development** | Build Shopify apps, extensions, themes using GraphQL Admin API, Shopify CLI, Polaris UI, and Liquid. Use when user asks about "shopify app", "checkout extension", "shopify theme", "liquid template", "polaris", "shopify graphql", "shopify webhook", or "metafields". | `skills/shopify-development` |
|
||||
| **Signup Flow CRO** | Optimize signup, registration, and trial activation flows for higher conversions. | `skills/signup-flow-cro` |
|
||||
| **Skill Creator** | Guide for creating effective skills. | `skills/skill-creator` |
|
||||
| **Skill Developer** | Create and manage Claude Code skills following Anthropic best practices. | `skills/skill-developer` |
|
||||
| **Slack Bot Builder** | Production Slack bots. Bolt framework, slash commands, modals. | `skills/slack-bot-builder` |
|
||||
| **Slack GIF Creator** | Knowledge and utilities for creating animated GIFs optimized for Slack. | `skills/slack-gif-creator` |
|
||||
| **SMTP Penetration Testing** | This skill should be used when the user asks to "perform SMTP penetration testing", "enumerate email users", "test for open mail relays", "grab SMTP banners", "brute force email credentials", or "assess mail server security". | `skills/smtp-penetration-testing` |
|
||||
| **Social Content** | Create and schedule social media content for LinkedIn, Twitter/X, and other platforms. | `skills/social-content` |
|
||||
| **Software Architecture** | Guide for quality focused software architecture. | `skills/software-architecture` |
|
||||
| **SQL Injection Testing** | This skill should be used when the user asks to "test for SQL injection vulnerabilities", "perform SQLi attacks", "bypass authentication using SQL injection", "extract database information through injection", "detect SQL injection flaws", or "exploit database query vulnerabilities". | `skills/sql-injection-testing` |
|
||||
| **SQLMap Database Penetration Testing** | This skill should be used when the user asks to "automate SQL injection testing," "enumerate database structure," "extract database credentials using sqlmap," "dump tables and columns from a vulnerable database," or "perform automated database penetration testing. | `skills/sqlmap-database-pentesting` |
|
||||
| **SSH Penetration Testing** | This skill should be used when the user asks to "pentest SSH services", "enumerate SSH configurations", "brute force SSH credentials", "exploit SSH vulnerabilities", "perform SSH tunneling", or "audit SSH security". | `skills/ssh-penetration-testing` |
|
||||
| **Stripe Integration** | Stripe patterns. Checkout, subscriptions, payment intents, webhooks. | `skills/stripe-integration` |
|
||||
| **Subagent Driven Dev** | Use when executing implementation plans with independent tasks in the current session. | `skills/subagent-driven-development` |
|
||||
| **Systematic Debugging** | Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes. | `skills/systematic-debugging` |
|
||||
| **TDD** | Use when implementing any feature or bugfix, before writing implementation code. | `skills/test-driven-development` |
|
||||
| **Telegram Bot Builder** | Building Telegram bots. Bot API, inline mode, payments, Mini Apps. | `skills/telegram-bot-builder` |
|
||||
| **Telegram Mini App** | TON Connect, Telegram Mini Apps, wallet integration. | `skills/telegram-mini-app` |
|
||||
| **Test Fixing** | Run tests and systematically fix all failing tests using smart error grouping. | `skills/test-fixing` |
|
||||
| **Testing Patterns** | Jest testing patterns, factory functions, mocking strategies, and TDD workflow. | `skills/testing-patterns` |
|
||||
| **Theme Factory** | Toolkit for styling artifacts with a theme. | `skills/theme-factory` |
|
||||
| **Top 100 Vulnerabilities** | This skill should be used when the user asks to "identify web application vulnerabilities", "explain common security flaws", "understand vulnerability categories", "learn about injection attacks", "review access control weaknesses", "analyze API security issues", "assess security misconfigurations", "understand client-side vulnerabilities", "examine mobile and IoT security flaws", or "reference the OWASP-aligned vulnerability taxonomy". | `skills/top-web-vulnerabilities` |
|
||||
| **Trigger.dev** | Trigger.dev for serverless background jobs. Long-running tasks. | `skills/trigger-dev` |
|
||||
| **Twilio Communications** | Twilio for SMS, voice, video. Programmable messaging, OTP. | `skills/twilio-communications` |
|
||||
| **UI/UX Pro Max** | "UI/UX design intelligence. | `skills/ui-ux-pro-max` |
|
||||
| **Upstash QStash** | Upstash QStash for serverless message queues. | `skills/upstash-qstash` |
|
||||
| **Using Git Worktrees** | Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification. | `skills/using-git-worktrees` |
|
||||
| **Using Superpowers** | Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions. | `skills/using-superpowers` |
|
||||
| **Vercel Deployment** | Vercel deployment. Edge functions, preview deployments. | `skills/vercel-deployment` |
|
||||
| **Verification Before Completion** | Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always. | `skills/verification-before-completion` |
|
||||
| **Viral Generator Builder** | Building shareable generators that go viral. | `skills/viral-generator-builder` |
|
||||
| **Voice Agents** | Voice-based AI assistants. Speech-to-text, real-time conversation. | `skills/voice-agents` |
|
||||
| **Voice AI Development** | Voice AI patterns. Wake words, streaming ASR, emotional TTS. | `skills/voice-ai-development` |
|
||||
| **Web Artifacts** | Suite of tools for creating elaborate, multi-component claude. | `skills/web-artifacts-builder` |
|
||||
| **Web Design Guidelines** | Review UI code for Web Interface Guidelines compliance. | `skills/web-design-guidelines` |
|
||||
| **Webapp Testing** | Toolkit for interacting with and testing local web applications using Playwright. | `skills/webapp-testing` |
|
||||
| **Windows Privilege Escalation** | This skill should be used when the user asks to "escalate privileges on Windows," "find Windows privesc vectors," "enumerate Windows for privilege escalation," "exploit Windows misconfigurations," or "perform post-exploitation privilege escalation. | `skills/windows-privilege-escalation` |
|
||||
| **Wireshark Network Traffic Analysis** | This skill should be used when the user asks to "analyze network traffic with Wireshark", "capture packets for troubleshooting", "filter PCAP files", "follow TCP/UDP streams", "detect network anomalies", "investigate suspicious traffic", or "perform protocol analysis". | `skills/wireshark-analysis` |
|
||||
| **WordPress Penetration Testing** | This skill should be used when the user asks to "pentest WordPress sites", "scan WordPress for vulnerabilities", "enumerate WordPress users, themes, or plugins", "exploit WordPress vulnerabilities", or "use WPScan". | `skills/wordpress-penetration-testing` |
|
||||
| **Workflow Automation** | "Design and implement automated workflows combining visual logic with custom code. | `skills/workflow-automation` |
|
||||
| **Writing Plans** | Use when you have a spec or requirements for a multi-step task, before touching code. | `skills/writing-plans` |
|
||||
| **Writing Skills** | Use when creating new skills, editing existing skills, or verifying skills work before deployment. | `skills/writing-skills` |
|
||||
| **XLSX (Official)** | "Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis, and visualization. | `skills/xlsx-official` |
|
||||
| **Zapier/Make Patterns** | No-code automation. Zapier, Make, n8n workflows. | `skills/zapier-make-patterns` |
|
||||
| Skill Name | Description | Path |
|
||||
| :-------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------- |
|
||||
| **3D Web Experience** | Expert in building 3D experiences for the web - Three.js, React Three Fiber, Spline, WebGL. | `skills/3d-web-experience` |
|
||||
| **A/B Test Setup** | Plan and implement A/B tests with proper experiment design, statistical significance, and test analysis. | `skills/ab-test-setup` |
|
||||
| **Active Directory Attacks** | This skill should be used when the user asks to "attack Active Directory", "exploit AD", "Kerberoasting", "DCSync", "pass-the-hash", "BloodHound enumeration", "Golden Ticket", "Silver Ticket", "AS-REP roasting", "NTLM relay", or needs guidance on Windows domain penetration testing. | `skills/active-directory-attacks` |
|
||||
| **Address GitHub Comments** | Use when you need to address review or issue comments on an open GitHub Pull Request using the gh CLI. | `skills/address-github-comments` |
|
||||
| **Agent Evaluation** | Testing and benchmarking LLM agents including behavioral testing, capability assessment, reliability metrics. | `skills/agent-evaluation` |
|
||||
| **Agent Manager Skill** | Use when you need to manage multiple local CLI agents via tmux sessions (start/stop/monitor/assign) with cron-friendly scheduling. | `skills/agent-manager-skill` |
|
||||
| **Agent Memory Systems** | Memory architecture for agents: short-term, long-term (vector stores), and cognitive architectures. | `skills/agent-memory-systems` |
|
||||
| **Agent Tool Builder** | Tool design from schema to error handling. JSON Schema best practices, validation, and MCP. | `skills/agent-tool-builder` |
|
||||
| **AI Agents Architect** | Expert in autonomous AI agents. Tool use, memory systems, planning strategies, multi-agent orchestration. | `skills/ai-agents-architect` |
|
||||
| **AI Product** | LLM integration patterns, RAG architecture, prompt engineering, AI UX, and cost optimization. | `skills/ai-product` |
|
||||
| **AI Wrapper Product** | Building products that wrap AI APIs into focused tools. Prompt engineering, cost management. | `skills/ai-wrapper-product` |
|
||||
| **Algolia Search** | Algolia search implementation, indexing strategies, React InstantSearch, relevance tuning. | `skills/algolia-search` |
|
||||
| **Algorithmic Art** | Creating algorithmic art using p5. | `skills/algorithmic-art` |
|
||||
| **Analytics Tracking** | Set up analytics tracking with GA4, GTM, and custom event implementations for marketing measurement. | `skills/analytics-tracking` |
|
||||
| **API Fuzzing for Bug Bounty** | This skill should be used when the user asks to "test API security", "fuzz APIs", "find IDOR vulnerabilities", "test REST API", "test GraphQL", "API penetration testing", "bug bounty API testing", or needs guidance on API security assessment techniques. | `skills/api-fuzzing-bug-bounty` |
|
||||
| **API Patterns** | API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning. | `skills/api-patterns` |
|
||||
| **App Builder** | Main application building orchestrator. Creates full-stack applications from natural language requests. | `skills/app-builder` |
|
||||
| **App Store Optimization** | Complete App Store Optimization (ASO) toolkit for researching, optimizing, and tracking mobile app performance on Apple App Store and Google Play Store. | `skills/app-store-optimization` |
|
||||
| **Architecture** | Architectural decision-making framework. Requirements analysis, trade-off evaluation, ADR documentation. | `skills/architecture` |
|
||||
| **Autonomous Agent Patterns** | "Design patterns for building autonomous coding agents. | `skills/autonomous-agent-patterns` |
|
||||
| **Autonomous Agents** | AI systems that independently decompose goals, plan actions, execute tools. ReAct, reflection. | `skills/autonomous-agents` |
|
||||
| **AWS Penetration Testing** | This skill should be used when the user asks to "pentest AWS", "test AWS security", "enumerate IAM", "exploit cloud infrastructure", "AWS privilege escalation", "S3 bucket testing", "metadata SSRF", "Lambda exploitation", or needs guidance on Amazon Web Services security assessment. | `skills/aws-penetration-testing` |
|
||||
| **AWS Serverless** | Serverless on AWS. Lambda, API Gateway, DynamoDB, SQS/SNS, SAM/CDK deployment. | `skills/aws-serverless` |
|
||||
| **Azure Functions** | Azure Functions patterns. Isolated worker model, Durable Functions, cold start optimization. | `skills/azure-functions` |
|
||||
| **Backend Guidelines** | Comprehensive backend development guide for Node. | `skills/backend-dev-guidelines` |
|
||||
| **Bash Linux** | Bash/Linux terminal patterns. Critical commands, piping, error handling, scripting. | `skills/bash-linux` |
|
||||
| **Behavioral Modes** | AI operational modes (brainstorm, implement, debug, review, teach, ship, orchestrate). | `skills/behavioral-modes` |
|
||||
| **BlockRun** | Agent wallet for LLM micropayments. Use when user needs capabilities Claude lacks (image generation, real-time X/Twitter data) or explicitly requests external models ("blockrun", "use grok", "use gpt", "dall-e", "deepseek"). | `skills/blockrun` |
|
||||
| **Brainstorming** | "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. | `skills/brainstorming` |
|
||||
| **Brand Guidelines (Anthropic)** | Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. | `skills/brand-guidelines-anthropic` |
|
||||
| **Brand Guidelines (Community)** | Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. | `skills/brand-guidelines-community` |
|
||||
| **Broken Authentication Testing** | This skill should be used when the user asks to "test for broken authentication vulnerabilities", "assess session management security", "perform credential stuffing tests", "evaluate password policies", "test for session fixation", or "identify authentication bypass flaws". | `skills/broken-authentication` |
|
||||
| **Browser Automation** | Browser automation with Playwright and Puppeteer. Testing, scraping, agentic control. | `skills/browser-automation` |
|
||||
| **Browser Extension Builder** | Building browser extensions - Chrome, Firefox. Manifest v3, content scripts, monetization. | `skills/browser-extension-builder` |
|
||||
| **BullMQ Specialist** | BullMQ for Redis-backed job queues, background processing in Node.js/TypeScript. | `skills/bullmq-specialist` |
|
||||
| **Bun Development** | "Modern JavaScript/TypeScript development with Bun runtime. | `skills/bun-development` |
|
||||
| **Burp Suite Web Application Testing** | This skill should be used when the user asks to "intercept HTTP traffic", "modify web requests", "use Burp Suite for testing", "perform web vulnerability scanning", "test with Burp Repeater", "analyze HTTP history", or "configure proxy for web testing". | `skills/burp-suite-testing` |
|
||||
| **Canvas Design** | Create beautiful visual art in . | `skills/canvas-design` |
|
||||
| **CC Skill: Backend Patterns** | Backend architecture patterns from everything-claude-code. API design, database, caching, error handling. | `skills/cc-skill-backend-patterns` |
|
||||
| **CC Skill: ClickHouse IO** | ClickHouse analytics patterns from everything-claude-code. | `skills/cc-skill-clickhouse-io` |
|
||||
| **CC Skill: Coding Standards** | Language best practices from everything-claude-code. | `skills/cc-skill-coding-standards` |
|
||||
| **CC Skill: Continuous Learning** | Continuous learning patterns from everything-claude-code. | `skills/cc-skill-continuous-learning` |
|
||||
| **CC Skill: Frontend Patterns** | React/Next.js patterns from everything-claude-code. | `skills/cc-skill-frontend-patterns` |
|
||||
| **CC Skill: Project Guidelines Example** | Example project-specific skill from everything-claude-code. | `skills/cc-skill-project-guidelines-example` |
|
||||
| **CC Skill: Security Review** | Security checklist skill from everything-claude-code. | `skills/cc-skill-security-review` |
|
||||
| **CC Skill: Strategic Compact** | Strategic planning skill from everything-claude-code. | `skills/cc-skill-strategic-compact` |
|
||||
| **Claude Code Guide** | Master guide for using Claude Code effectively. | `skills/claude-code-guide` |
|
||||
| **Claude D3.js** | Creating interactive data visualisations using d3. | `skills/claude-d3js-skill` |
|
||||
| **Clean Code** | Pragmatic coding standards - concise, direct, no over-engineering, no unnecessary comments. | `skills/clean-code` |
|
||||
| **Clerk Auth** | Clerk auth implementation, middleware, organizations, webhooks, user sync. | `skills/clerk-auth` |
|
||||
| **Cloud Penetration Testing** | This skill should be used when the user asks to "perform cloud penetration testing", "assess Azure or AWS or GCP security", "enumerate cloud resources", "exploit cloud misconfigurations", "test O365 security", "extract secrets from cloud environments", or "audit cloud infrastructure". | `skills/cloud-penetration-testing` |
|
||||
| **Code Review Checklist** | Code review guidelines covering code quality, security, and best practices. | `skills/code-review-checklist` |
|
||||
| **Competitor Alternatives** | Create compelling competitor comparison and alternative pages for SEO and conversions. | `skills/competitor-alternatives` |
|
||||
| **Computer Use Agents** | AI agents that interact with computers like humans. Screen control, sandboxing. | `skills/computer-use-agents` |
|
||||
| **Concise Planning** | Use when a user asks for a plan for a coding task, to generate a clear, actionable, and atomic checklist. | `skills/concise-planning` |
|
||||
| **Content Creator** | Create SEO-optimized marketing content with consistent brand voice. | `skills/content-creator` |
|
||||
| **Context Window Management** | Managing LLM context windows. Summarization, trimming, routing. | `skills/context-window-management` |
|
||||
| **Conversation Memory** | Persistent memory for LLM conversations. Short-term, long-term, entity-based memory. | `skills/conversation-memory` |
|
||||
| **Copy Editing** | Edit and polish existing marketing copy with a systematic seven-sweeps framework. | `skills/copy-editing` |
|
||||
| **Copywriting** | Write compelling marketing copy for homepages, landing pages, pricing pages, and feature pages. | `skills/copywriting` |
|
||||
| **Core Components** | Core component library and design system patterns. | `skills/core-components` |
|
||||
| **CrewAI** | Role-based multi-agent framework. Agent design, task definition, crew orchestration. | `skills/crewai` |
|
||||
| **Cross-Site Scripting and HTML Injection Testing** | This skill should be used when the user asks to "test for XSS vulnerabilities", "perform cross-site scripting attacks", "identify HTML injection flaws", "exploit client-side injection vulnerabilities", "steal cookies via XSS", or "bypass content security policies". | `skills/xss-html-injection` |
|
||||
| **Database Design** | Database design principles. Schema design, indexing strategy, ORM selection, serverless databases. | `skills/database-design` |
|
||||
| **Deployment Procedures** | Production deployment principles. Safe deployment workflows, rollback strategies, and verification. | `skills/deployment-procedures` |
|
||||
| **Discord Bot Architect** | Production Discord bots. Discord.js, Pycord, slash commands, sharding. | `skills/discord-bot-architect` |
|
||||
| **Dispatching Parallel Agents** | Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies. | `skills/dispatching-parallel-agents` |
|
||||
| **Doc Co-authoring** | Guide users through a structured workflow for co-authoring documentation. | `skills/doc-coauthoring` |
|
||||
| **Docker Expert** | Docker containerization expert. Multi-stage builds, image optimization, container security, Docker Compose. | `skills/docker-expert` |
|
||||
| **Documentation Templates** | Documentation templates and structure guidelines. README, API docs, code comments. | `skills/documentation-templates` |
|
||||
| **DOCX (Official)** | "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. | `skills/docx-official` |
|
||||
| **Email Sequence** | Create and optimize email sequences, drip campaigns, and lifecycle email programs. | `skills/email-sequence` |
|
||||
| **Email Systems** | Transactional email, marketing automation, deliverability, infrastructure. | `skills/email-systems` |
|
||||
| **Ethical Hacking Methodology** | This skill should be used when the user asks to "learn ethical hacking", "understand penetration testing lifecycle", "perform reconnaissance", "conduct security scanning", "exploit vulnerabilities", or "write penetration test reports". | `skills/ethical-hacking-methodology` |
|
||||
| **Executing Plans** | Use when you have a written implementation plan to execute in a separate session with review checkpoints. | `skills/executing-plans` |
|
||||
| **File Organizer** | Intelligently organizes files and folders by understanding context, finding duplicates, and suggesting better organizational structures. | `skills/file-organizer` |
|
||||
| **File Path Traversal Testing** | This skill should be used when the user asks to "test for directory traversal", "exploit path traversal vulnerabilities", "read arbitrary files through web applications", "find LFI vulnerabilities", or "access files outside web root". | `skills/file-path-traversal` |
|
||||
| **File Uploads** | File uploads and cloud storage. S3, Cloudflare R2, presigned URLs. | `skills/file-uploads` |
|
||||
| **Finishing Dev Branch** | Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup. | `skills/finishing-a-development-branch` |
|
||||
| **Firebase** | Firebase Auth, Firestore, Realtime Database, Cloud Functions, Storage. | `skills/firebase` |
|
||||
| **Form CRO** | Optimize lead capture forms, contact forms, demo request forms for higher conversion rates. | `skills/form-cro` |
|
||||
| **Free Tool Strategy** | Plan and build free tools for marketing, lead generation, and SEO value. | `skills/free-tool-strategy` |
|
||||
| **Frontend Design** | Create distinctive, production-grade frontend interfaces with high design quality. | `skills/frontend-design` |
|
||||
| **Frontend Guidelines** | Frontend development guidelines for React/TypeScript applications. | `skills/frontend-dev-guidelines` |
|
||||
| **Game Development** | Game development orchestrator. Routes to platform-specific skills based on project needs. | `skills/game-development` |
|
||||
| **GCP Cloud Run** | Serverless on GCP. Cloud Run services and functions, Pub/Sub. | `skills/gcp-cloud-run` |
|
||||
| **GEO Fundamentals** | Generative Engine Optimization for AI search engines (ChatGPT, Claude, Perplexity). | `skills/geo-fundamentals` |
|
||||
| **Git Pushing** | Stage, commit, and push git changes with conventional commit messages. | `skills/git-pushing` |
|
||||
| **GitHub Workflow Automation** | "Automate GitHub workflows with AI assistance. | `skills/github-workflow-automation` |
|
||||
| **GraphQL** | Schema design, resolvers, DataLoader, federation, Apollo/urql integration. | `skills/graphql` |
|
||||
| **HTML Injection Testing** | This skill should be used when the user asks to "test for HTML injection", "inject HTML into web pages", "perform HTML injection attacks", "deface web applications", or "test content injection vulnerabilities". | `skills/html-injection-testing` |
|
||||
| **HubSpot Integration** | HubSpot CRM integration. OAuth, CRM objects, webhooks, custom objects. | `skills/hubspot-integration` |
|
||||
| **i18n Localization** | Internationalization and localization patterns. Detecting hardcoded strings, managing translations. | `skills/i18n-localization` |
|
||||
| **IDOR Vulnerability Testing** | This skill should be used when the user asks to "test for insecure direct object references," "find IDOR vulnerabilities," "exploit broken access control," "enumerate user IDs or object references," or "bypass authorization to access other users' data. | `skills/idor-testing` |
|
||||
| **Inngest** | Inngest for serverless background jobs, event-driven workflows. | `skills/inngest` |
|
||||
| **Interactive Portfolio** | Building portfolios that land jobs. Developer, designer portfolios. | `skills/interactive-portfolio` |
|
||||
| **Internal Comms (Anthropic)** | A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. | `skills/internal-comms-anthropic` |
|
||||
| **Internal Comms (Community)** | A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. | `skills/internal-comms-community` |
|
||||
| **JavaScript Mastery** | "Comprehensive JavaScript reference covering 33+ essential concepts every developer should know. | `skills/javascript-mastery` |
|
||||
| **Kaizen** | Guide for continuous improvement, error proofing, and standardization. | `skills/kaizen` |
|
||||
| **Langfuse** | Open-source LLM observability. Tracing, prompt management, evaluation. | `skills/langfuse` |
|
||||
| **LangGraph** | Stateful, multi-actor AI applications. Graph construction, persistence. | `skills/langgraph` |
|
||||
| **Launch Strategy** | Plan product launches, feature announcements, and go-to-market strategies. | `skills/launch-strategy` |
|
||||
| **Lint and Validate** | Automatic quality control, linting, and static analysis procedures. | `skills/lint-and-validate` |
|
||||
| **Linux Privilege Escalation** | This skill should be used when the user asks to "escalate privileges on Linux", "find privesc vectors on Linux systems", "exploit sudo misconfigurations", "abuse SUID binaries", "exploit cron jobs for root access", "enumerate Linux systems for privilege escalation", or "gain root access from low-privilege shell". | `skills/linux-privilege-escalation` |
|
||||
| **Linux Shell Scripting** | This skill should be used when the user asks to "create bash scripts", "automate Linux tasks", "monitor system resources", "backup files", "manage users", or "write production shell scripts". | `skills/linux-shell-scripting` |
|
||||
| **LLM App Patterns** | "Production-ready patterns for building LLM applications. | `skills/llm-app-patterns` |
|
||||
| **Loki Mode** | Multi-agent autonomous startup system for Claude Code. | `skills/loki-mode` |
|
||||
| **Marketing Ideas** | 140 proven SaaS marketing ideas and strategies organized by category. | `skills/marketing-ideas` |
|
||||
| **Marketing Psychology** | 70+ mental models and psychological principles for marketing and persuasion. | `skills/marketing-psychology` |
|
||||
| **MCP Builder** | Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. | `skills/mcp-builder` |
|
||||
| **Metasploit Framework** | This skill should be used when the user asks to "use Metasploit for penetration testing", "exploit vulnerabilities with msfconsole", "create payloads with msfvenom", "perform post-exploitation", "use auxiliary modules for scanning", or "develop custom exploits". | `skills/metasploit-framework` |
|
||||
| **Micro-SaaS Launcher** | Launching small SaaS products fast. Idea validation, MVP, pricing. | `skills/micro-saas-launcher` |
|
||||
| **Mobile Design** | Mobile-first design thinking for iOS and Android apps. Touch interaction, performance patterns. | `skills/mobile-design` |
|
||||
| **Moodle External API Development** | Create custom external web service APIs for Moodle LMS. Use when implementing web services for course management, user tracking, quiz operations, or custom plugin functionality. Covers parameter validation, database operations, error handling, service registration, and Moodle coding standards. | `skills/moodle-external-api-development` |
|
||||
| **Neon Postgres** | Neon serverless Postgres, branching, connection pooling, Prisma integration. | `skills/neon-postgres` |
|
||||
| **NestJS Expert** | Nest.js framework expert. Module architecture, dependency injection, middleware, guards, interceptors. | `skills/nestjs-expert` |
|
||||
| **Network 101** | This skill should be used when the user asks to "set up a web server", "configure HTTP or HTTPS", "perform SNMP enumeration", "configure SMB shares", "test network services", or needs guidance on configuring and testing network services for penetration testing labs. | `skills/network-101` |
|
||||
| **Next.js Best Practices** | Next.js App Router principles. Server Components, data fetching, routing patterns. | `skills/nextjs-best-practices` |
|
||||
| **Next.js Supabase Auth** | Supabase Auth with Next.js App Router. Auth middleware. | `skills/nextjs-supabase-auth` |
|
||||
| **Node.js Best Practices** | Node.js development principles. Framework selection, async patterns, security, architecture. | `skills/nodejs-best-practices` |
|
||||
| **NotebookLM** | Use this skill to query your Google NotebookLM notebooks directly from Claude Code for source-grounded, citation-backed answers from Gemini. | `skills/notebooklm` |
|
||||
| **Notion Template Business** | Building and selling Notion templates. Design, pricing, marketing. | `skills/notion-template-business` |
|
||||
| **Onboarding CRO** | Optimize post-signup onboarding, user activation, and time-to-value. | `skills/onboarding-cro` |
|
||||
| **Page CRO** | Conversion rate optimization for marketing pages - homepages, landing pages, pricing pages. | `skills/page-cro` |
|
||||
| **Paid Ads** | Create and optimize paid ad campaigns on Google Ads, Meta, LinkedIn, and other platforms. | `skills/paid-ads` |
|
||||
| **Parallel Agents** | Multi-agent orchestration patterns. Use when multiple independent tasks can run with different domain expertise. | `skills/parallel-agents` |
|
||||
| **Paywall Upgrade CRO** | Optimize in-app paywalls, upgrade screens, and freemium conversion moments. | `skills/paywall-upgrade-cro` |
|
||||
| **PDF (Official)** | Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. | `skills/pdf-official` |
|
||||
| **Pentest Checklist** | This skill should be used when the user asks to "plan a penetration test", "create a security assessment checklist", "prepare for penetration testing", "define pentest scope", "follow security testing best practices", or needs a structured methodology for penetration testing engagements. | `skills/pentest-checklist` |
|
||||
| **Pentest Commands** | This skill should be used when the user asks to "run pentest commands", "scan with nmap", "use metasploit exploits", "crack passwords with hydra or john", "scan web vulnerabilities with nikto", "enumerate networks", or needs essential penetration testing command references. | `skills/pentest-commands` |
|
||||
| **Performance Profiling** | Performance profiling principles. Measurement, analysis, and optimization techniques. | `skills/performance-profiling` |
|
||||
| **Personal Tool Builder** | Building custom tools. Rapid prototyping, local-first apps, CLI tools. | `skills/personal-tool-builder` |
|
||||
| **Plaid Fintech** | Plaid API for banking. Link token flows, transactions, ACH. | `skills/plaid-fintech` |
|
||||
| **Plan Writing** | Structured task planning with clear breakdowns, dependencies, and verification criteria. | `skills/plan-writing` |
|
||||
| **Planning With Files** | Implements Manus-style file-based planning for complex tasks. | `skills/planning-with-files` |
|
||||
| **Playwright Automation** | Complete browser automation with Playwright. | `skills/playwright-skill` |
|
||||
| **Popup CRO** | Create and optimize popups, modals, and overlays for conversion. | `skills/popup-cro` |
|
||||
| **PowerShell Windows** | PowerShell Windows patterns. Critical pitfalls, operator syntax, error handling. | `skills/powershell-windows` |
|
||||
| **PPTX (Official)** | "Presentation creation, editing, and analysis. | `skills/pptx-official` |
|
||||
| **Pricing Strategy** | Design pricing, packaging, and monetization strategy for SaaS products. | `skills/pricing-strategy` |
|
||||
| **Prisma Expert** | Prisma ORM expert for schema design, migrations, query optimization, relations modeling. | `skills/prisma-expert` |
|
||||
| **Privilege Escalation Methods** | This skill should be used when the user asks to "escalate privileges", "get root access", "become administrator", "privesc techniques", "abuse sudo", "exploit SUID binaries", "Kerberoasting", "pass-the-ticket", "token impersonation", or needs guidance on post-exploitation privilege escalation for Linux or Windows systems. | `skills/privilege-escalation-methods` |
|
||||
| **Product Toolkit** | Comprehensive toolkit for product managers including RICE prioritization, customer interview analysis, PRD templates, discovery frameworks, and go-to-market strategies. | `skills/product-manager-toolkit` |
|
||||
| **Programmatic SEO** | Build SEO-driven pages at scale using templates and data. | `skills/programmatic-seo` |
|
||||
| **Prompt Caching** | Caching strategies for LLM prompts. Anthropic caching, CAG. | `skills/prompt-caching` |
|
||||
| **Prompt Engineer** | Designing prompts for LLM applications. Structure, evaluation. | `skills/prompt-engineer` |
|
||||
| **Prompt Engineering** | Expert guide on prompt engineering patterns, best practices, and optimization techniques. | `skills/prompt-engineering` |
|
||||
| **Prompt Library** | "Curated collection of high-quality prompts for various use cases. | `skills/prompt-library` |
|
||||
| **Python Patterns** | Python development principles. Framework selection, async patterns, type hints, project structure. | `skills/python-patterns` |
|
||||
| **RAG Engineer** | Building RAG systems. Embedding models, vector databases, chunking. | `skills/rag-engineer` |
|
||||
| **RAG Implementation** | RAG patterns. Chunking, embeddings, vector stores. | `skills/rag-implementation` |
|
||||
| **React Best Practices** | React and Next. | `skills/react-best-practices` |
|
||||
| **React Patterns** | Modern React patterns and principles. Hooks, composition, performance, TypeScript best practices. | `skills/react-patterns` |
|
||||
| **React UI Patterns** | Modern React UI patterns for loading states, error handling, and data fetching. | `skills/react-ui-patterns` |
|
||||
| **Research Engineer** | Academic Research Engineer persona with scientific rigor, zero hallucinations, and optimal language selection for high-precision engineering tasks. | `skills/research-engineer` |
|
||||
| **Receiving Code Review** | Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation. | `skills/receiving-code-review` |
|
||||
| **Red Team Tactics** | Red team tactics principles based on MITRE ATT&CK. Attack phases, detection evasion, reporting. | `skills/red-team-tactics` |
|
||||
| **Remotion Best Practices** | Best practices for Remotion - Video creation in React. Includes 28 modular rules for animations, audio, video, captions, 3D, charts, transitions, and more. | `skills/remotion-best-practices` |
|
||||
| **Red Team Tools and Methodology** | This skill should be used when the user asks to "follow red team methodology", "perform bug bounty hunting", "automate reconnaissance", "hunt for XSS vulnerabilities", "enumerate subdomains", or needs security researcher techniques and tool configurations from top bug bounty hunters. | `skills/red-team-tools` |
|
||||
| **Referral Program** | Design referral programs, affiliate programs, and word-of-mouth strategies. | `skills/referral-program` |
|
||||
| **Requesting Code Review** | Use when completing tasks, implementing major features, or before merging to verify work meets requirements. | `skills/requesting-code-review` |
|
||||
| **Salesforce Development** | Salesforce integration, Apex development, Lightning components. | `skills/salesforce-development` |
|
||||
| **Schema Markup** | Add structured data and JSON-LD schema markup for SEO and rich snippets. | `skills/schema-markup` |
|
||||
| **Scroll Experience** | GSAP/Framer scroll-driven storytelling. Parallax effects. | `skills/scroll-experience` |
|
||||
| **Security Scanning Tools** | This skill should be used when the user asks to "perform vulnerability scanning", "scan networks for open ports", "assess web application security", "scan wireless networks", "detect malware", "check cloud security", or "evaluate system compliance". | `skills/scanning-tools` |
|
||||
| **Segment CDP** | Segment customer data platform. Event tracking, identity resolution. | `skills/segment-cdp` |
|
||||
| **Senior Architect** | Comprehensive software architecture skill for designing scalable, maintainable systems using ReactJS, NextJS, NodeJS, Express, React Native, Swift, Kotlin, Flutter, Postgres, GraphQL, Go, Python. | `skills/senior-architect` |
|
||||
| **Senior Fullstack** | Comprehensive fullstack development skill for building complete web applications with React, Next. | `skills/senior-fullstack` |
|
||||
| **SEO Audit** | Audit technical and on-page SEO issues for better search rankings. | `skills/seo-audit` |
|
||||
| **SEO Fundamentals** | SEO fundamentals, E-E-A-T, Core Web Vitals, and Google algorithm principles. | `skills/seo-fundamentals` |
|
||||
| **Server Management** | Server management principles. Process management, monitoring strategy, and scaling decisions. | `skills/server-management` |
|
||||
| **Shodan Reconnaissance and Pentesting** | This skill should be used when the user asks to "search for exposed devices on the internet," "perform Shodan reconnaissance," "find vulnerable services using Shodan," "scan IP ranges with Shodan," or "discover IoT devices and open ports. | `skills/shodan-reconnaissance` |
|
||||
| **Shopify Apps** | Building Shopify apps. App Bridge, Polaris, webhooks. | `skills/shopify-apps` |
|
||||
| **Shopify Development** | Build Shopify apps, extensions, themes using GraphQL Admin API, Shopify CLI, Polaris UI, and Liquid. Use when user asks about "shopify app", "checkout extension", "shopify theme", "liquid template", "polaris", "shopify graphql", "shopify webhook", or "metafields". | `skills/shopify-development` |
|
||||
| **Signup Flow CRO** | Optimize signup, registration, and trial activation flows for higher conversions. | `skills/signup-flow-cro` |
|
||||
| **Skill Creator** | Guide for creating effective skills. | `skills/skill-creator` |
|
||||
| **Skill Developer** | Create and manage Claude Code skills following Anthropic best practices. | `skills/skill-developer` |
|
||||
| **Slack Bot Builder** | Production Slack bots. Bolt framework, slash commands, modals. | `skills/slack-bot-builder` |
|
||||
| **Slack GIF Creator** | Knowledge and utilities for creating animated GIFs optimized for Slack. | `skills/slack-gif-creator` |
|
||||
| **SMTP Penetration Testing** | This skill should be used when the user asks to "perform SMTP penetration testing", "enumerate email users", "test for open mail relays", "grab SMTP banners", "brute force email credentials", or "assess mail server security". | `skills/smtp-penetration-testing` |
|
||||
| **Social Content** | Create and schedule social media content for LinkedIn, Twitter/X, and other platforms. | `skills/social-content` |
|
||||
| **Software Architecture** | Guide for quality focused software architecture. | `skills/software-architecture` |
|
||||
| **SQL Injection Testing** | This skill should be used when the user asks to "test for SQL injection vulnerabilities", "perform SQLi attacks", "bypass authentication using SQL injection", "extract database information through injection", "detect SQL injection flaws", or "exploit database query vulnerabilities". | `skills/sql-injection-testing` |
|
||||
| **SQLMap Database Penetration Testing** | This skill should be used when the user asks to "automate SQL injection testing," "enumerate database structure," "extract database credentials using sqlmap," "dump tables and columns from a vulnerable database," or "perform automated database penetration testing. | `skills/sqlmap-database-pentesting` |
|
||||
| **SSH Penetration Testing** | This skill should be used when the user asks to "pentest SSH services", "enumerate SSH configurations", "brute force SSH credentials", "exploit SSH vulnerabilities", "perform SSH tunneling", or "audit SSH security". | `skills/ssh-penetration-testing` |
|
||||
| **Stripe Integration** | Stripe patterns. Checkout, subscriptions, payment intents, webhooks. | `skills/stripe-integration` |
|
||||
| **Subagent Driven Dev** | Use when executing implementation plans with independent tasks in the current session. | `skills/subagent-driven-development` |
|
||||
| **Systematic Debugging** | Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes. | `skills/systematic-debugging` |
|
||||
| **Tailwind Patterns** | Tailwind CSS v4 principles. CSS-first configuration, container queries, design token architecture. | `skills/tailwind-patterns` |
|
||||
| **TDD** | Use when implementing any feature or bugfix, before writing implementation code. | `skills/test-driven-development` |
|
||||
| **TDD Workflow** | Test-Driven Development workflow principles. RED-GREEN-REFACTOR cycle. | `skills/tdd-workflow` |
|
||||
| **Telegram Bot Builder** | Building Telegram bots. Bot API, inline mode, payments, Mini Apps. | `skills/telegram-bot-builder` |
|
||||
| **Telegram Mini App** | TON Connect, Telegram Mini Apps, wallet integration. | `skills/telegram-mini-app` |
|
||||
| **Test Fixing** | Run tests and systematically fix all failing tests using smart error grouping. | `skills/test-fixing` |
|
||||
| **Testing Patterns** | Jest testing patterns, factory functions, mocking strategies, and TDD workflow. | `skills/testing-patterns` |
|
||||
| **Theme Factory** | Toolkit for styling artifacts with a theme. | `skills/theme-factory` |
|
||||
| **Top 100 Vulnerabilities** | This skill should be used when the user asks to "identify web application vulnerabilities", "explain common security flaws", "understand vulnerability categories", "learn about injection attacks", "review access control weaknesses", "analyze API security issues", "assess security misconfigurations", "understand client-side vulnerabilities", "examine mobile and IoT security flaws", or "reference the OWASP-aligned vulnerability taxonomy". | `skills/top-web-vulnerabilities` |
|
||||
| **Trigger.dev** | Trigger.dev for serverless background jobs. Long-running tasks. | `skills/trigger-dev` |
|
||||
| **Twilio Communications** | Twilio for SMS, voice, video. Programmable messaging, OTP. | `skills/twilio-communications` |
|
||||
| **TypeScript Expert** | TypeScript expert with deep knowledge of type-level programming, performance optimization, migration strategies. | `skills/typescript-expert` |
|
||||
| **UI/UX Pro Max** | "UI/UX design intelligence. | `skills/ui-ux-pro-max` |
|
||||
| **Upstash QStash** | Upstash QStash for serverless message queues. | `skills/upstash-qstash` |
|
||||
| **Using Git Worktrees** | Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification. | `skills/using-git-worktrees` |
|
||||
| **Using Superpowers** | Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions. | `skills/using-superpowers` |
|
||||
| **Vercel Deployment** | Vercel deployment. Edge functions, preview deployments. | `skills/vercel-deployment` |
|
||||
| **Verification Before Completion** | Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always. | `skills/verification-before-completion` |
|
||||
| **Viral Generator Builder** | Building shareable generators that go viral. | `skills/viral-generator-builder` |
|
||||
| **Voice Agents** | Voice-based AI assistants. Speech-to-text, real-time conversation. | `skills/voice-agents` |
|
||||
| **Voice AI Development** | Voice AI patterns. Wake words, streaming ASR, emotional TTS. | `skills/voice-ai-development` |
|
||||
| **Vulnerability Scanner** | Advanced vulnerability analysis principles. OWASP 2025, Supply Chain Security, attack surface mapping. | `skills/vulnerability-scanner` |
|
||||
| **Web Artifacts** | Suite of tools for creating elaborate, multi-component claude. | `skills/web-artifacts-builder` |
|
||||
| **Web Design Guidelines** | Review UI code for Web Interface Guidelines compliance. | `skills/web-design-guidelines` |
|
||||
| **Webapp Testing** | Toolkit for interacting with and testing local web applications using Playwright. | `skills/webapp-testing` |
|
||||
| **Windows Privilege Escalation** | This skill should be used when the user asks to "escalate privileges on Windows," "find Windows privesc vectors," "enumerate Windows for privilege escalation," "exploit Windows misconfigurations," or "perform post-exploitation privilege escalation. | `skills/windows-privilege-escalation` |
|
||||
| **Wireshark Network Traffic Analysis** | This skill should be used when the user asks to "analyze network traffic with Wireshark", "capture packets for troubleshooting", "filter PCAP files", "follow TCP/UDP streams", "detect network anomalies", "investigate suspicious traffic", or "perform protocol analysis". | `skills/wireshark-analysis` |
|
||||
| **WordPress Penetration Testing** | This skill should be used when the user asks to "pentest WordPress sites", "scan WordPress for vulnerabilities", "enumerate WordPress users, themes, or plugins", "exploit WordPress vulnerabilities", or "use WPScan". | `skills/wordpress-penetration-testing` |
|
||||
| **Workflow Automation** | "Design and implement automated workflows combining visual logic with custom code. | `skills/workflow-automation` |
|
||||
| **Writing Plans** | Use when you have a spec or requirements for a multi-step task, before touching code. | `skills/writing-plans` |
|
||||
| **Writing Skills** | Use when creating new skills, editing existing skills, or verifying skills work before deployment. | `skills/writing-skills` |
|
||||
| **XLSX (Official)** | "Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis, and visualization. | `skills/xlsx-official` |
|
||||
| **Zapier/Make Patterns** | No-code automation. Zapier, Make, n8n workflows. | `skills/zapier-make-patterns` |
|
||||
|
||||
> [!TIP]
|
||||
> Use the `validate_skills.py` script in the `scripts/` directory to ensure all skills are properly formatted and ready for use.
|
||||
@@ -315,6 +387,7 @@ This collection would not be possible without the incredible work of the Claude
|
||||
|
||||
- **[anthropics/skills](https://github.com/anthropics/skills)**: Official Anthropic skills repository - Document manipulation (DOCX, PDF, PPTX, XLSX), Brand Guidelines, Internal Communications.
|
||||
- **[anthropics/claude-cookbooks](https://github.com/anthropics/claude-cookbooks)**: Official notebooks and recipes for building with Claude.
|
||||
- **[remotion-dev/skills](https://github.com/remotion-dev/skills)**: Official Remotion skills - Video creation in React with 28 modular rules.
|
||||
- **[vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills)**: Vercel Labs official skills - React Best Practices, Web Design Guidelines.
|
||||
- **[openai/skills](https://github.com/openai/skills)**: OpenAI Codex skills catalog - Agent skills, Skill Creator, Concise Planning.
|
||||
|
||||
@@ -331,6 +404,8 @@ This collection would not be possible without the incredible work of the Claude
|
||||
- **[zircote/.claude](https://github.com/zircote/.claude)**: Shopify development skill reference.
|
||||
- **[vibeforge1111/vibeship-spawner-skills](https://github.com/vibeforge1111/vibeship-spawner-skills)**: AI Agents, Integrations, Maker Tools (57 skills, Apache 2.0).
|
||||
- **[coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills)**: Marketing skills for CRO, copywriting, SEO, paid ads, and growth (23 skills, MIT).
|
||||
- **[vudovn/antigravity-kit](https://github.com/vudovn/antigravity-kit)**: AI Agent templates with Skills, Agents, and Workflows (33 skills, MIT).
|
||||
- **[affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code)**: Complete Claude Code configuration collection from Anthropic hackathon winner - skills only (8 skills, MIT).
|
||||
|
||||
### Inspirations
|
||||
|
||||
|
||||
760
docs/EXAMPLES.md
Normal file
760
docs/EXAMPLES.md
Normal file
@@ -0,0 +1,760 @@
|
||||
# 💡 Real-World Examples - See Skills in Action
|
||||
|
||||
**Learn by example!** This guide shows you real conversations using different skills.
|
||||
|
||||
---
|
||||
|
||||
## Example 1: Designing a Feature with @brainstorming
|
||||
|
||||
### The Scenario
|
||||
You want to add a "dark mode" feature to your app, but you're not sure how to approach it.
|
||||
|
||||
### The Conversation
|
||||
|
||||
```
|
||||
You: @brainstorming I want to add dark mode to my React app
|
||||
|
||||
AI: Great! Let me help you think through this. First, let me check your
|
||||
current project structure...
|
||||
|
||||
[AI examines your files]
|
||||
|
||||
I see you're using React with Tailwind CSS. Now, let's understand
|
||||
your requirements:
|
||||
|
||||
What's your primary goal for dark mode?
|
||||
a) User preference (toggle in settings)
|
||||
b) System preference (follow OS setting)
|
||||
c) Both (with manual override)
|
||||
|
||||
You: c) Both
|
||||
|
||||
AI: Perfect! That's the best user experience. Next question:
|
||||
|
||||
Where should the dark mode toggle be located?
|
||||
a) In the main navigation
|
||||
b) In a settings page
|
||||
c) In a dropdown menu
|
||||
d) Multiple locations
|
||||
|
||||
You: a) In the main navigation
|
||||
|
||||
AI: Good choice for accessibility. One more question:
|
||||
|
||||
Should dark mode preference persist across sessions?
|
||||
a) Yes, save to localStorage
|
||||
b) Yes, save to user account (requires backend)
|
||||
c) No, reset each session
|
||||
|
||||
You: a) Yes, save to localStorage
|
||||
|
||||
AI: Excellent! Now I have a clear picture. Let me present the design...
|
||||
|
||||
## Dark Mode Implementation Design
|
||||
|
||||
### Architecture Overview
|
||||
We'll use React Context for state management, Tailwind's dark mode
|
||||
utilities, and localStorage for persistence. The system will:
|
||||
1. Check OS preference on first visit
|
||||
2. Allow manual override via toggle
|
||||
3. Persist preference in localStorage
|
||||
|
||||
Does this approach look good so far?
|
||||
|
||||
You: Yes, continue
|
||||
|
||||
AI: [Continues with detailed design sections...]
|
||||
|
||||
[After design is complete]
|
||||
|
||||
I've saved the design to docs/plans/2026-01-20-dark-mode-design.md
|
||||
|
||||
Ready to set up for implementation?
|
||||
|
||||
You: Yes
|
||||
|
||||
AI: I'll create an isolated workspace using git worktrees and write an
|
||||
implementation plan. One moment...
|
||||
```
|
||||
|
||||
### What Happened
|
||||
- ✅ AI asked focused questions one at a time
|
||||
- ✅ Explored your specific context
|
||||
- ✅ Presented design in sections
|
||||
- ✅ Saved documentation
|
||||
- ✅ Prepared for implementation
|
||||
|
||||
---
|
||||
|
||||
## Example 2: Debugging with @systematic-debugging
|
||||
|
||||
### The Scenario
|
||||
Your tests are failing, but you're not sure why.
|
||||
|
||||
### The Conversation
|
||||
|
||||
```
|
||||
You: @systematic-debugging My tests are failing with "Cannot read property
|
||||
'map' of undefined"
|
||||
|
||||
AI: Let me help you debug this systematically. First, I'll gather information:
|
||||
|
||||
1. Running the failing test to see the full error...
|
||||
|
||||
[AI runs: npm test]
|
||||
|
||||
I see the error occurs in UserList.test.tsx at line 45. Let me examine
|
||||
the test file and the component...
|
||||
|
||||
[AI reads both files]
|
||||
|
||||
## Hypothesis
|
||||
The test is failing because `users` prop is undefined when the component
|
||||
renders. This suggests the mock data isn't being passed correctly.
|
||||
|
||||
## Verification
|
||||
Let me check the test setup...
|
||||
|
||||
[AI examines test]
|
||||
|
||||
Found it! The test is calling:
|
||||
```typescript
|
||||
render(<UserList />)
|
||||
```
|
||||
|
||||
But UserList requires a `users` prop. The component expects:
|
||||
```typescript
|
||||
interface UserListProps {
|
||||
users: User[];
|
||||
}
|
||||
```
|
||||
|
||||
## Solution
|
||||
The test should pass the users prop:
|
||||
```typescript
|
||||
const mockUsers = [
|
||||
{ id: 1, name: 'Alice' },
|
||||
{ id: 2, name: 'Bob' }
|
||||
];
|
||||
|
||||
render(<UserList users={mockUsers} />)
|
||||
```
|
||||
|
||||
Should I apply this fix?
|
||||
|
||||
You: Yes
|
||||
|
||||
AI: [Applies fix and runs tests]
|
||||
|
||||
✅ All tests passing!
|
||||
|
||||
## Root Cause
|
||||
The test was missing required props. This is a common issue when
|
||||
components are refactored to require props that were previously optional.
|
||||
|
||||
## Prevention
|
||||
Consider adding TypeScript strict mode to catch these at compile time:
|
||||
```json
|
||||
"strict": true,
|
||||
"strictNullChecks": true
|
||||
```
|
||||
|
||||
Would you like me to add this to your tsconfig.json?
|
||||
```
|
||||
|
||||
### What Happened
|
||||
- ✅ Systematic investigation
|
||||
- ✅ Clear hypothesis
|
||||
- ✅ Verification before fixing
|
||||
- ✅ Root cause analysis
|
||||
- ✅ Prevention suggestions
|
||||
|
||||
---
|
||||
|
||||
## Example 3: Adding Payments with @stripe-integration
|
||||
|
||||
### The Scenario
|
||||
You need to add subscription billing to your SaaS app.
|
||||
|
||||
### The Conversation
|
||||
|
||||
```
|
||||
You: @stripe-integration I need to add monthly subscription billing
|
||||
|
||||
AI: I'll help you implement Stripe subscriptions. Let me understand your
|
||||
requirements:
|
||||
|
||||
Current stack detected:
|
||||
- Next.js 14 (App Router)
|
||||
- TypeScript
|
||||
- Prisma with PostgreSQL
|
||||
|
||||
For subscription billing, we'll need:
|
||||
|
||||
1. **Stripe Setup**
|
||||
- Stripe account and API keys
|
||||
- Webhook endpoint for events
|
||||
- Product and price IDs
|
||||
|
||||
2. **Backend Implementation**
|
||||
- API routes for checkout
|
||||
- Webhook handler
|
||||
- Database schema for subscriptions
|
||||
|
||||
3. **Frontend Implementation**
|
||||
- Pricing page
|
||||
- Checkout flow
|
||||
- Subscription management
|
||||
|
||||
Let's start with the backend. First, install dependencies:
|
||||
|
||||
```bash
|
||||
npm install stripe @stripe/stripe-js
|
||||
```
|
||||
|
||||
Now, let's create the database schema...
|
||||
|
||||
[AI provides Prisma schema]
|
||||
|
||||
```prisma
|
||||
model User {
|
||||
id String @id @default(cuid())
|
||||
email String @unique
|
||||
stripeCustomerId String? @unique
|
||||
subscriptions Subscription[]
|
||||
}
|
||||
|
||||
model Subscription {
|
||||
id String @id @default(cuid())
|
||||
userId String
|
||||
user User @relation(fields: [userId], references: [id])
|
||||
stripeSubscriptionId String @unique
|
||||
status String
|
||||
priceId String
|
||||
currentPeriodEnd DateTime
|
||||
createdAt DateTime @default(now())
|
||||
updatedAt DateTime @updatedAt
|
||||
}
|
||||
```
|
||||
|
||||
Next, let's create the checkout API route...
|
||||
|
||||
[AI provides complete implementation with:]
|
||||
- API route for creating checkout sessions
|
||||
- Webhook handler for subscription events
|
||||
- Helper functions for Stripe operations
|
||||
- Error handling and logging
|
||||
- TypeScript types
|
||||
|
||||
Now for the frontend...
|
||||
|
||||
[AI provides:]
|
||||
- Pricing page component
|
||||
- Checkout button component
|
||||
- Subscription status display
|
||||
- Tailwind styling
|
||||
|
||||
Finally, let's set up the webhook:
|
||||
|
||||
1. In Stripe Dashboard, add webhook endpoint:
|
||||
`https://yourdomain.com/api/webhooks/stripe`
|
||||
|
||||
2. Select these events:
|
||||
- customer.subscription.created
|
||||
- customer.subscription.updated
|
||||
- customer.subscription.deleted
|
||||
- invoice.payment_succeeded
|
||||
- invoice.payment_failed
|
||||
|
||||
3. Copy the webhook secret to your .env:
|
||||
```
|
||||
STRIPE_WEBHOOK_SECRET=whsec_...
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
Test locally with Stripe CLI:
|
||||
```bash
|
||||
stripe listen --forward-to localhost:3000/api/webhooks/stripe
|
||||
stripe trigger customer.subscription.created
|
||||
```
|
||||
|
||||
## Security Checklist
|
||||
- ✅ API keys in environment variables
|
||||
- ✅ Webhook signature verification
|
||||
- ✅ Server-side price validation
|
||||
- ✅ Idempotency keys for operations
|
||||
|
||||
Ready to test the implementation?
|
||||
```
|
||||
|
||||
### What Happened
|
||||
- ✅ Detected existing stack
|
||||
- ✅ Provided complete implementation
|
||||
- ✅ Included database schema
|
||||
- ✅ Added security best practices
|
||||
- ✅ Included testing instructions
|
||||
|
||||
---
|
||||
|
||||
## Example 4: Writing Copy with @copywriting
|
||||
|
||||
### The Scenario
|
||||
You need compelling copy for your SaaS landing page.
|
||||
|
||||
### The Conversation
|
||||
|
||||
```
|
||||
You: @copywriting Write homepage copy for my project management tool
|
||||
|
||||
AI: I'll help you create compelling homepage copy. First, let me understand
|
||||
your product:
|
||||
|
||||
What makes your project management tool different from competitors
|
||||
like Asana, Trello, or Monday.com?
|
||||
|
||||
You: It's specifically built for remote teams with built-in video standups
|
||||
and async communication features
|
||||
|
||||
AI: Excellent differentiator! Who is your primary target audience?
|
||||
a) Startups and small teams (2-20 people)
|
||||
b) Mid-size companies (20-200 people)
|
||||
c) Enterprise (200+ people)
|
||||
d) Freelancers and agencies
|
||||
|
||||
You: a) Startups and small teams
|
||||
|
||||
AI: Perfect. What's the main pain point you solve?
|
||||
|
||||
You: Remote teams waste time in unnecessary meetings and lose context
|
||||
in async communication
|
||||
|
||||
AI: Great! Now I have what I need. Here's your homepage copy:
|
||||
|
||||
---
|
||||
|
||||
## Hero Section
|
||||
|
||||
**Headline:**
|
||||
Run Your Remote Team Without the Meeting Overload
|
||||
|
||||
**Subheadline:**
|
||||
The project management tool built for distributed teams. Replace
|
||||
status meetings with async video standups and keep everyone in sync
|
||||
without the Zoom fatigue.
|
||||
|
||||
**CTA:**
|
||||
Start Free Trial → (No credit card required)
|
||||
|
||||
---
|
||||
|
||||
## Problem Section
|
||||
|
||||
**Headline:**
|
||||
Remote Work Shouldn't Mean More Meetings
|
||||
|
||||
**Body:**
|
||||
Your team is distributed across time zones. You're spending hours in
|
||||
status meetings just to stay aligned. Async updates get lost in Slack.
|
||||
Context disappears. Productivity suffers.
|
||||
|
||||
Sound familiar?
|
||||
|
||||
---
|
||||
|
||||
## Solution Section
|
||||
|
||||
**Headline:**
|
||||
Stay Aligned Without the Meeting Marathon
|
||||
|
||||
**Features:**
|
||||
|
||||
📹 **Async Video Standups**
|
||||
Record quick video updates on your schedule. Your team watches when
|
||||
it works for them. No more 9am calls for your teammate in Tokyo.
|
||||
|
||||
💬 **Context-Rich Communication**
|
||||
Every task, comment, and decision stays connected. No more hunting
|
||||
through Slack threads or email chains.
|
||||
|
||||
📊 **Visual Progress Tracking**
|
||||
See what's happening at a glance. Kanban boards, timelines, and
|
||||
dashboards that actually make sense.
|
||||
|
||||
🔔 **Smart Notifications**
|
||||
Get notified about what matters. Ignore the rest. Your focus time
|
||||
is sacred.
|
||||
|
||||
---
|
||||
|
||||
## Social Proof Section
|
||||
|
||||
**Headline:**
|
||||
Trusted by Remote Teams Worldwide
|
||||
|
||||
[Testimonial placeholders with structure]
|
||||
|
||||
---
|
||||
|
||||
## CTA Section
|
||||
|
||||
**Headline:**
|
||||
Ready to Reclaim Your Calendar?
|
||||
|
||||
**Body:**
|
||||
Join 500+ remote teams who've cut meeting time by 60% while staying
|
||||
more aligned than ever.
|
||||
|
||||
**CTA:**
|
||||
Start Your Free 14-Day Trial →
|
||||
|
||||
No credit card required. Cancel anytime.
|
||||
|
||||
---
|
||||
|
||||
## Copy Notes
|
||||
|
||||
**Tone:** Professional but conversational
|
||||
**Focus:** Pain point (too many meetings) → Solution (async video)
|
||||
**Differentiation:** Built specifically for remote teams
|
||||
**Social proof:** Quantified benefit (60% fewer meetings)
|
||||
|
||||
Would you like me to:
|
||||
1. Write alternative versions for A/B testing?
|
||||
2. Create copy for specific feature pages?
|
||||
3. Write email sequences for onboarding?
|
||||
```
|
||||
|
||||
### What Happened
|
||||
- ✅ Asked clarifying questions
|
||||
- ✅ Identified unique value proposition
|
||||
- ✅ Created benefit-focused copy
|
||||
- ✅ Included clear CTAs
|
||||
- ✅ Provided copy notes for consistency
|
||||
|
||||
---
|
||||
|
||||
## Example 5: Test-Driven Development with @test-driven-development
|
||||
|
||||
### The Scenario
|
||||
You need to implement a new feature: user authentication.
|
||||
|
||||
### The Conversation
|
||||
|
||||
```
|
||||
You: @test-driven-development I need to implement user login functionality
|
||||
|
||||
AI: Perfect! Let's use TDD to build this. Following the Red-Green-Refactor
|
||||
cycle, we'll write tests first, then implement.
|
||||
|
||||
## Step 1: Write the First Test (RED)
|
||||
|
||||
Let's start with the simplest case - successful login:
|
||||
|
||||
```typescript
|
||||
// auth.test.ts
|
||||
import { login } from './auth';
|
||||
|
||||
describe('login', () => {
|
||||
it('should return user data for valid credentials', async () => {
|
||||
const result = await login({
|
||||
email: 'user@example.com',
|
||||
password: 'correct-password'
|
||||
});
|
||||
|
||||
expect(result.success).toBe(true);
|
||||
expect(result.user).toHaveProperty('id');
|
||||
expect(result.user).toHaveProperty('email');
|
||||
expect(result.token).toBeDefined();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
Let's run this test to see it fail:
|
||||
|
||||
[AI runs: npm test]
|
||||
|
||||
✅ Test fails as expected (auth.ts doesn't exist yet)
|
||||
|
||||
## Step 2: Write Minimal Implementation (GREEN)
|
||||
|
||||
Now let's write just enough code to make this test pass:
|
||||
|
||||
```typescript
|
||||
// auth.ts
|
||||
interface LoginCredentials {
|
||||
email: string;
|
||||
password: string;
|
||||
}
|
||||
|
||||
interface LoginResult {
|
||||
success: boolean;
|
||||
user?: {
|
||||
id: string;
|
||||
email: string;
|
||||
};
|
||||
token?: string;
|
||||
}
|
||||
|
||||
export async function login(
|
||||
credentials: LoginCredentials
|
||||
): Promise<LoginResult> {
|
||||
// Minimal implementation to pass the test
|
||||
return {
|
||||
success: true,
|
||||
user: {
|
||||
id: '1',
|
||||
email: credentials.email
|
||||
},
|
||||
token: 'fake-token'
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
[AI runs: npm test]
|
||||
|
||||
✅ Test passes!
|
||||
|
||||
## Step 3: Add Next Test (RED)
|
||||
|
||||
Now let's test the failure case:
|
||||
|
||||
```typescript
|
||||
it('should return error for invalid credentials', async () => {
|
||||
const result = await login({
|
||||
email: 'user@example.com',
|
||||
password: 'wrong-password'
|
||||
});
|
||||
|
||||
expect(result.success).toBe(false);
|
||||
expect(result.error).toBe('Invalid credentials');
|
||||
expect(result.user).toBeUndefined();
|
||||
expect(result.token).toBeUndefined();
|
||||
});
|
||||
```
|
||||
|
||||
[AI runs: npm test]
|
||||
|
||||
❌ Test fails (always returns success)
|
||||
|
||||
## Step 4: Implement Real Logic (GREEN)
|
||||
|
||||
Now let's add actual authentication:
|
||||
|
||||
```typescript
|
||||
import bcrypt from 'bcrypt';
|
||||
import jwt from 'jsonwebtoken';
|
||||
import { db } from './db';
|
||||
|
||||
export async function login(
|
||||
credentials: LoginCredentials
|
||||
): Promise<LoginResult> {
|
||||
// Find user
|
||||
const user = await db.user.findUnique({
|
||||
where: { email: credentials.email }
|
||||
});
|
||||
|
||||
if (!user) {
|
||||
return {
|
||||
success: false,
|
||||
error: 'Invalid credentials'
|
||||
};
|
||||
}
|
||||
|
||||
// Verify password
|
||||
const validPassword = await bcrypt.compare(
|
||||
credentials.password,
|
||||
user.passwordHash
|
||||
);
|
||||
|
||||
if (!validPassword) {
|
||||
return {
|
||||
success: false,
|
||||
error: 'Invalid credentials'
|
||||
};
|
||||
}
|
||||
|
||||
// Generate token
|
||||
const token = jwt.sign(
|
||||
{ userId: user.id },
|
||||
process.env.JWT_SECRET!,
|
||||
{ expiresIn: '7d' }
|
||||
);
|
||||
|
||||
return {
|
||||
success: true,
|
||||
user: {
|
||||
id: user.id,
|
||||
email: user.email
|
||||
},
|
||||
token
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
[AI runs: npm test]
|
||||
|
||||
✅ All tests pass!
|
||||
|
||||
## Step 5: Add Edge Cases
|
||||
|
||||
Let's add more tests for edge cases:
|
||||
|
||||
```typescript
|
||||
it('should handle missing email', async () => {
|
||||
const result = await login({
|
||||
email: '',
|
||||
password: 'password'
|
||||
});
|
||||
|
||||
expect(result.success).toBe(false);
|
||||
expect(result.error).toBe('Email is required');
|
||||
});
|
||||
|
||||
it('should handle missing password', async () => {
|
||||
const result = await login({
|
||||
email: 'user@example.com',
|
||||
password: ''
|
||||
});
|
||||
|
||||
expect(result.success).toBe(false);
|
||||
expect(result.error).toBe('Password is required');
|
||||
});
|
||||
|
||||
it('should handle database errors gracefully', async () => {
|
||||
// Mock database error
|
||||
jest.spyOn(db.user, 'findUnique').mockRejectedValue(
|
||||
new Error('Database connection failed')
|
||||
);
|
||||
|
||||
const result = await login({
|
||||
email: 'user@example.com',
|
||||
password: 'password'
|
||||
});
|
||||
|
||||
expect(result.success).toBe(false);
|
||||
expect(result.error).toBe('An error occurred');
|
||||
});
|
||||
```
|
||||
|
||||
[AI implements validation and error handling]
|
||||
|
||||
## Step 6: Refactor (REFACTOR)
|
||||
|
||||
Now that all tests pass, let's refactor for better code quality:
|
||||
|
||||
```typescript
|
||||
// Extract validation
|
||||
function validateCredentials(credentials: LoginCredentials): string | null {
|
||||
if (!credentials.email) return 'Email is required';
|
||||
if (!credentials.password) return 'Password is required';
|
||||
return null;
|
||||
}
|
||||
|
||||
// Extract user verification
|
||||
async function verifyUser(
|
||||
email: string,
|
||||
password: string
|
||||
): Promise<User | null> {
|
||||
const user = await db.user.findUnique({ where: { email } });
|
||||
if (!user) return null;
|
||||
|
||||
const valid = await bcrypt.compare(password, user.passwordHash);
|
||||
return valid ? user : null;
|
||||
}
|
||||
|
||||
// Main function is now cleaner
|
||||
export async function login(
|
||||
credentials: LoginCredentials
|
||||
): Promise<LoginResult> {
|
||||
try {
|
||||
const validationError = validateCredentials(credentials);
|
||||
if (validationError) {
|
||||
return { success: false, error: validationError };
|
||||
}
|
||||
|
||||
const user = await verifyUser(
|
||||
credentials.email,
|
||||
credentials.password
|
||||
);
|
||||
|
||||
if (!user) {
|
||||
return { success: false, error: 'Invalid credentials' };
|
||||
}
|
||||
|
||||
const token = generateToken(user.id);
|
||||
|
||||
return {
|
||||
success: true,
|
||||
user: { id: user.id, email: user.email },
|
||||
token
|
||||
};
|
||||
} catch (error) {
|
||||
console.error('Login error:', error);
|
||||
return { success: false, error: 'An error occurred' };
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
[AI runs: npm test]
|
||||
|
||||
✅ All tests still pass after refactoring!
|
||||
|
||||
## Summary
|
||||
|
||||
We've implemented login functionality using TDD:
|
||||
- ✅ 5 tests covering happy path, errors, and edge cases
|
||||
- ✅ Clean, testable code
|
||||
- ✅ Proper error handling
|
||||
- ✅ Type safety with TypeScript
|
||||
|
||||
Next steps:
|
||||
1. Add rate limiting tests
|
||||
2. Add session management tests
|
||||
3. Add logout functionality
|
||||
|
||||
Should I continue with these?
|
||||
```
|
||||
|
||||
### What Happened
|
||||
- ✅ Followed Red-Green-Refactor cycle
|
||||
- ✅ Wrote tests before implementation
|
||||
- ✅ Covered edge cases
|
||||
- ✅ Refactored with confidence
|
||||
- ✅ Maintained test coverage
|
||||
|
||||
---
|
||||
|
||||
## Key Takeaways
|
||||
|
||||
### What Makes These Examples Effective?
|
||||
|
||||
1. **Skills ask clarifying questions** before jumping to solutions
|
||||
2. **Skills provide context-aware help** based on your project
|
||||
3. **Skills follow best practices** for their domain
|
||||
4. **Skills include complete examples** not just snippets
|
||||
5. **Skills explain the "why"** not just the "how"
|
||||
|
||||
### How to Get Similar Results
|
||||
|
||||
1. **Be specific** in your requests
|
||||
2. **Provide context** about your project
|
||||
3. **Answer questions** the skill asks
|
||||
4. **Review suggestions** before applying
|
||||
5. **Iterate** based on results
|
||||
|
||||
---
|
||||
|
||||
## Try These Yourself!
|
||||
|
||||
Pick a skill and try it with your own project:
|
||||
|
||||
- **Planning:** `@brainstorming` or `@writing-plans`
|
||||
- **Development:** `@test-driven-development` or `@react-best-practices`
|
||||
- **Debugging:** `@systematic-debugging` or `@test-fixing`
|
||||
- **Integration:** `@stripe-integration` or `@firebase`
|
||||
- **Marketing:** `@copywriting` or `@seo-audit`
|
||||
|
||||
---
|
||||
|
||||
**Want more examples?** Check individual skill folders for additional examples and use cases!
|
||||
545
docs/SKILL_ANATOMY.md
Normal file
545
docs/SKILL_ANATOMY.md
Normal file
@@ -0,0 +1,545 @@
|
||||
# Anatomy of a Skill - Understanding the Structure
|
||||
|
||||
**Want to understand how skills work under the hood?** This guide breaks down every part of a skill file.
|
||||
|
||||
---
|
||||
|
||||
## 📁 Basic Folder Structure
|
||||
|
||||
```
|
||||
skills/
|
||||
└── my-skill-name/
|
||||
├── SKILL.md ← Required: The main skill definition
|
||||
├── examples/ ← Optional: Example files
|
||||
│ ├── example1.js
|
||||
│ └── example2.py
|
||||
├── scripts/ ← Optional: Helper scripts
|
||||
│ └── helper.sh
|
||||
├── templates/ ← Optional: Code templates
|
||||
│ └── template.tsx
|
||||
├── references/ ← Optional: Reference documentation
|
||||
│ └── api-docs.md
|
||||
└── README.md ← Optional: Additional documentation
|
||||
```
|
||||
|
||||
**Key Rule:** Only `SKILL.md` is required. Everything else is optional!
|
||||
|
||||
---
|
||||
|
||||
## SKILL.md Structure
|
||||
|
||||
Every `SKILL.md` file has two main parts:
|
||||
|
||||
### 1. Frontmatter (Metadata)
|
||||
### 2. Content (Instructions)
|
||||
|
||||
Let's break down each part:
|
||||
|
||||
---
|
||||
|
||||
## Part 1: Frontmatter
|
||||
|
||||
The frontmatter is at the very top, wrapped in `---`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-skill-name
|
||||
description: "Brief description of what this skill does"
|
||||
---
|
||||
```
|
||||
|
||||
### Required Fields
|
||||
|
||||
#### `name`
|
||||
- **What it is:** The skill's identifier
|
||||
- **Format:** lowercase-with-hyphens
|
||||
- **Must match:** The folder name exactly
|
||||
- **Example:** `stripe-integration`
|
||||
|
||||
#### `description`
|
||||
- **What it is:** One-sentence summary
|
||||
- **Format:** String in quotes
|
||||
- **Length:** Keep it under 150 characters
|
||||
- **Example:** `"Stripe payment integration patterns including checkout, subscriptions, and webhooks"`
|
||||
|
||||
### Optional Fields
|
||||
|
||||
Some skills include additional metadata:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-skill-name
|
||||
description: "Brief description"
|
||||
version: "1.0.0"
|
||||
author: "Your Name"
|
||||
tags: ["react", "typescript", "testing"]
|
||||
---
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Part 2: Content
|
||||
|
||||
After the frontmatter comes the actual skill content. Here's the recommended structure:
|
||||
|
||||
### Recommended Sections
|
||||
|
||||
#### 1. Title (H1)
|
||||
```markdown
|
||||
# Skill Title
|
||||
```
|
||||
- Use a clear, descriptive title
|
||||
- Usually matches or expands on the skill name
|
||||
|
||||
#### 2. Overview
|
||||
```markdown
|
||||
## Overview
|
||||
|
||||
A brief explanation of what this skill does and why it exists.
|
||||
2-4 sentences is perfect.
|
||||
```
|
||||
|
||||
#### 3. When to Use
|
||||
```markdown
|
||||
## When to Use This Skill
|
||||
|
||||
- Use when you need to [scenario 1]
|
||||
- Use when working with [scenario 2]
|
||||
- Use when the user asks about [scenario 3]
|
||||
```
|
||||
|
||||
**Why this matters:** Helps the AI know when to activate this skill
|
||||
|
||||
#### 4. Core Instructions
|
||||
```markdown
|
||||
## How It Works
|
||||
|
||||
### Step 1: [Action]
|
||||
Detailed instructions...
|
||||
|
||||
### Step 2: [Action]
|
||||
More instructions...
|
||||
```
|
||||
|
||||
**This is the heart of your skill** - clear, actionable steps
|
||||
|
||||
#### 5. Examples
|
||||
```markdown
|
||||
## Examples
|
||||
|
||||
### Example 1: [Use Case]
|
||||
\`\`\`javascript
|
||||
// Example code
|
||||
\`\`\`
|
||||
|
||||
### Example 2: [Another Use Case]
|
||||
\`\`\`javascript
|
||||
// More code
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
**Why examples matter:** They show the AI exactly what good output looks like
|
||||
|
||||
#### 6. Best Practices
|
||||
```markdown
|
||||
## Best Practices
|
||||
|
||||
- ✅ Do this
|
||||
- ✅ Also do this
|
||||
- ❌ Don't do this
|
||||
- ❌ Avoid this
|
||||
```
|
||||
|
||||
#### 7. Common Pitfalls
|
||||
```markdown
|
||||
## Common Pitfalls
|
||||
|
||||
- **Problem:** Description
|
||||
**Solution:** How to fix it
|
||||
```
|
||||
|
||||
#### 8. Related Skills
|
||||
```markdown
|
||||
## Related Skills
|
||||
|
||||
- `@other-skill` - When to use this instead
|
||||
- `@complementary-skill` - How this works together
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Writing Effective Instructions
|
||||
|
||||
### Use Clear, Direct Language
|
||||
|
||||
**❌ Bad:**
|
||||
```markdown
|
||||
You might want to consider possibly checking if the user has authentication.
|
||||
```
|
||||
|
||||
**✅ Good:**
|
||||
```markdown
|
||||
Check if the user is authenticated before proceeding.
|
||||
```
|
||||
|
||||
### Use Action Verbs
|
||||
|
||||
**❌ Bad:**
|
||||
```markdown
|
||||
The file should be created...
|
||||
```
|
||||
|
||||
**✅ Good:**
|
||||
```markdown
|
||||
Create the file...
|
||||
```
|
||||
|
||||
### Be Specific
|
||||
|
||||
**❌ Bad:**
|
||||
```markdown
|
||||
Set up the database properly.
|
||||
```
|
||||
|
||||
**✅ Good:**
|
||||
```markdown
|
||||
1. Create a PostgreSQL database
|
||||
2. Run migrations: `npm run migrate`
|
||||
3. Seed initial data: `npm run seed`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Optional Components
|
||||
|
||||
### Scripts Directory
|
||||
|
||||
If your skill needs helper scripts:
|
||||
|
||||
```
|
||||
scripts/
|
||||
├── setup.sh ← Setup automation
|
||||
├── validate.py ← Validation tools
|
||||
└── generate.js ← Code generators
|
||||
```
|
||||
|
||||
**Reference them in SKILL.md:**
|
||||
```markdown
|
||||
Run the setup script:
|
||||
\`\`\`bash
|
||||
bash scripts/setup.sh
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### Examples Directory
|
||||
|
||||
Real-world examples that demonstrate the skill:
|
||||
|
||||
```
|
||||
examples/
|
||||
├── basic-usage.js
|
||||
├── advanced-pattern.ts
|
||||
└── full-implementation/
|
||||
├── index.js
|
||||
└── config.json
|
||||
```
|
||||
|
||||
### Templates Directory
|
||||
|
||||
Reusable code templates:
|
||||
|
||||
```
|
||||
templates/
|
||||
├── component.tsx
|
||||
├── test.spec.ts
|
||||
└── config.json
|
||||
```
|
||||
|
||||
**Reference in SKILL.md:**
|
||||
```markdown
|
||||
Use this template as a starting point:
|
||||
\`\`\`typescript
|
||||
{{#include templates/component.tsx}}
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### References Directory
|
||||
|
||||
External documentation or API references:
|
||||
|
||||
```
|
||||
references/
|
||||
├── api-docs.md
|
||||
├── best-practices.md
|
||||
└── troubleshooting.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Skill Size Guidelines
|
||||
|
||||
### Minimum Viable Skill
|
||||
- **Frontmatter:** name + description
|
||||
- **Content:** 100-200 words
|
||||
- **Sections:** Overview + Instructions
|
||||
|
||||
### Standard Skill
|
||||
- **Frontmatter:** name + description
|
||||
- **Content:** 300-800 words
|
||||
- **Sections:** Overview + When to Use + Instructions + Examples
|
||||
|
||||
### Comprehensive Skill
|
||||
- **Frontmatter:** name + description + optional fields
|
||||
- **Content:** 800-2000 words
|
||||
- **Sections:** All recommended sections
|
||||
- **Extras:** Scripts, examples, templates
|
||||
|
||||
**Rule of thumb:** Start small, expand based on feedback
|
||||
|
||||
---
|
||||
|
||||
## Formatting Best Practices
|
||||
|
||||
### Use Markdown Effectively
|
||||
|
||||
#### Code Blocks
|
||||
Always specify the language:
|
||||
```markdown
|
||||
\`\`\`javascript
|
||||
const example = "code";
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
#### Lists
|
||||
Use consistent formatting:
|
||||
```markdown
|
||||
- Item 1
|
||||
- Item 2
|
||||
- Sub-item 2.1
|
||||
- Sub-item 2.2
|
||||
```
|
||||
|
||||
#### Emphasis
|
||||
- **Bold** for important terms: `**important**`
|
||||
- *Italic* for emphasis: `*emphasis*`
|
||||
- `Code` for commands/code: `` `code` ``
|
||||
|
||||
#### Links
|
||||
```markdown
|
||||
[Link text](https://example.com)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Quality Checklist
|
||||
|
||||
Before finalizing your skill:
|
||||
|
||||
### Content Quality
|
||||
- [ ] Instructions are clear and actionable
|
||||
- [ ] Examples are realistic and helpful
|
||||
- [ ] No typos or grammar errors
|
||||
- [ ] Technical accuracy verified
|
||||
|
||||
### Structure
|
||||
- [ ] Frontmatter is valid YAML
|
||||
- [ ] Name matches folder name
|
||||
- [ ] Sections are logically organized
|
||||
- [ ] Headings follow hierarchy (H1 → H2 → H3)
|
||||
|
||||
### Completeness
|
||||
- [ ] Overview explains the "why"
|
||||
- [ ] Instructions explain the "how"
|
||||
- [ ] Examples show the "what"
|
||||
- [ ] Edge cases are addressed
|
||||
|
||||
### Usability
|
||||
- [ ] A beginner could follow this
|
||||
- [ ] An expert would find it useful
|
||||
- [ ] The AI can parse it correctly
|
||||
- [ ] It solves a real problem
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Real-World Example Analysis
|
||||
|
||||
Let's analyze a real skill: `brainstorming`
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: brainstorming
|
||||
description: "You MUST use this before any creative work..."
|
||||
---
|
||||
```
|
||||
|
||||
**Analysis:**
|
||||
- ✅ Clear name
|
||||
- ✅ Strong description with urgency ("MUST use")
|
||||
- ✅ Explains when to use it
|
||||
|
||||
```markdown
|
||||
# Brainstorming Ideas Into Designs
|
||||
|
||||
## Overview
|
||||
Help turn ideas into fully formed designs...
|
||||
```
|
||||
|
||||
**Analysis:**
|
||||
- ✅ Clear title
|
||||
- ✅ Concise overview
|
||||
- ✅ Explains the value proposition
|
||||
|
||||
```markdown
|
||||
## The Process
|
||||
|
||||
**Understanding the idea:**
|
||||
- Check out the current project state first
|
||||
- Ask questions one at a time
|
||||
```
|
||||
|
||||
**Analysis:**
|
||||
- ✅ Broken into clear phases
|
||||
- ✅ Specific, actionable steps
|
||||
- ✅ Easy to follow
|
||||
|
||||
---
|
||||
|
||||
## Advanced Patterns
|
||||
|
||||
### Conditional Logic
|
||||
|
||||
```markdown
|
||||
## Instructions
|
||||
|
||||
If the user is working with React:
|
||||
- Use functional components
|
||||
- Prefer hooks over class components
|
||||
|
||||
If the user is working with Vue:
|
||||
- Use Composition API
|
||||
- Follow Vue 3 patterns
|
||||
```
|
||||
|
||||
### Progressive Disclosure
|
||||
|
||||
```markdown
|
||||
## Basic Usage
|
||||
[Simple instructions for common cases]
|
||||
|
||||
## Advanced Usage
|
||||
[Complex patterns for power users]
|
||||
```
|
||||
|
||||
### Cross-References
|
||||
|
||||
```markdown
|
||||
## Related Workflows
|
||||
|
||||
1. First, use `@brainstorming` to design
|
||||
2. Then, use `@writing-plans` to plan
|
||||
3. Finally, use `@test-driven-development` to implement
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Skill Effectiveness Metrics
|
||||
|
||||
How to know if your skill is good:
|
||||
|
||||
### Clarity Test
|
||||
- Can someone unfamiliar with the topic follow it?
|
||||
- Are there any ambiguous instructions?
|
||||
|
||||
### Completeness Test
|
||||
- Does it cover the happy path?
|
||||
- Does it handle edge cases?
|
||||
- Are error scenarios addressed?
|
||||
|
||||
### Usefulness Test
|
||||
- Does it solve a real problem?
|
||||
- Would you use this yourself?
|
||||
- Does it save time or improve quality?
|
||||
|
||||
---
|
||||
|
||||
## Learning from Existing Skills
|
||||
|
||||
### Study These Examples
|
||||
|
||||
**For Beginners:**
|
||||
- `skills/brainstorming/SKILL.md` - Clear structure
|
||||
- `skills/git-pushing/SKILL.md` - Simple and focused
|
||||
- `skills/copywriting/SKILL.md` - Good examples
|
||||
|
||||
**For Advanced:**
|
||||
- `skills/systematic-debugging/SKILL.md` - Comprehensive
|
||||
- `skills/react-best-practices/SKILL.md` - Multiple files
|
||||
- `skills/loki-mode/SKILL.md` - Complex workflows
|
||||
|
||||
---
|
||||
|
||||
## 💡 Pro Tips
|
||||
|
||||
1. **Start with the "When to Use" section** - This clarifies the skill's purpose
|
||||
2. **Write examples first** - They help you understand what you're teaching
|
||||
3. **Test with an AI** - See if it actually works before submitting
|
||||
4. **Get feedback** - Ask others to review your skill
|
||||
5. **Iterate** - Skills improve over time based on usage
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
### ❌ Mistake 1: Too Vague
|
||||
```markdown
|
||||
## Instructions
|
||||
Make the code better.
|
||||
```
|
||||
|
||||
**✅ Fix:**
|
||||
```markdown
|
||||
## Instructions
|
||||
1. Extract repeated logic into functions
|
||||
2. Add error handling for edge cases
|
||||
3. Write unit tests for core functionality
|
||||
```
|
||||
|
||||
### ❌ Mistake 2: Too Complex
|
||||
```markdown
|
||||
## Instructions
|
||||
[5000 words of dense technical jargon]
|
||||
```
|
||||
|
||||
**✅ Fix:**
|
||||
Break into multiple skills or use progressive disclosure
|
||||
|
||||
### ❌ Mistake 3: No Examples
|
||||
```markdown
|
||||
## Instructions
|
||||
[Instructions without any code examples]
|
||||
```
|
||||
|
||||
**✅ Fix:**
|
||||
Add at least 2-3 realistic examples
|
||||
|
||||
### ❌ Mistake 4: Outdated Information
|
||||
```markdown
|
||||
Use React class components...
|
||||
```
|
||||
|
||||
**✅ Fix:**
|
||||
Keep skills updated with current best practices
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Next Steps
|
||||
|
||||
1. **Read 3-5 existing skills** to see different styles
|
||||
2. **Try the skill template** from CONTRIBUTING.md
|
||||
3. **Create a simple skill** for something you know well
|
||||
4. **Test it** with your AI assistant
|
||||
5. **Share it** via Pull Request
|
||||
|
||||
---
|
||||
|
||||
**Remember:** Every expert was once a beginner. Start simple, learn from feedback, and improve over time! 🚀
|
||||
504
docs/VISUAL_GUIDE.md
Normal file
504
docs/VISUAL_GUIDE.md
Normal file
@@ -0,0 +1,504 @@
|
||||
# Visual Quick Start Guide
|
||||
|
||||
**Learn by seeing!** This guide uses diagrams and visual examples to help you understand skills.
|
||||
|
||||
---
|
||||
|
||||
## The Big Picture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ YOU (Developer) │
|
||||
│ ↓ │
|
||||
│ "Help me build a payment system" │
|
||||
│ ↓ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ AI ASSISTANT │
|
||||
│ ↓ │
|
||||
│ Loads @stripe-integration skill │
|
||||
│ ↓ │
|
||||
│ Becomes an expert in Stripe payments │
|
||||
│ ↓ │
|
||||
│ Provides specialized help with code examples │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📦 Repository Structure (Visual)
|
||||
|
||||
```
|
||||
antigravity-awesome-skills/
|
||||
│
|
||||
├── 📄 README.md ← Overview & skill list
|
||||
├── 📄 GETTING_STARTED.md ← Start here! (NEW)
|
||||
├── 📄 CONTRIBUTING.md ← How to contribute (NEW)
|
||||
│
|
||||
├── 📁 skills/ ← All 179 skills live here
|
||||
│ │
|
||||
│ ├── 📁 brainstorming/
|
||||
│ │ └── 📄 SKILL.md ← Skill definition
|
||||
│ │
|
||||
│ ├── 📁 stripe-integration/
|
||||
│ │ ├── 📄 SKILL.md
|
||||
│ │ └── 📁 examples/ ← Optional extras
|
||||
│ │
|
||||
│ ├── 📁 react-best-practices/
|
||||
│ │ ├── 📄 SKILL.md
|
||||
│ │ ├── 📁 rules/
|
||||
│ │ └── 📄 README.md
|
||||
│ │
|
||||
│ └── ... (176 more skills)
|
||||
│
|
||||
├── 📁 scripts/ ← Validation & management
|
||||
│ ├── validate_skills.py
|
||||
│ └── generate_index.py
|
||||
│
|
||||
└── 📁 docs/ ← Documentation (NEW)
|
||||
├── 📄 SKILL_ANATOMY.md ← How skills work
|
||||
└── 📄 VISUAL_GUIDE.md ← This file!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How Skills Work (Flow Diagram)
|
||||
|
||||
```
|
||||
┌──────────────┐
|
||||
│ 1. INSTALL │ Copy skills to .agent/skills/
|
||||
└──────┬───────┘
|
||||
│
|
||||
↓
|
||||
┌──────────────┐
|
||||
│ 2. INVOKE │ Type: @skill-name in AI chat
|
||||
└──────┬───────┘
|
||||
│
|
||||
↓
|
||||
┌──────────────┐
|
||||
│ 3. LOAD │ AI reads SKILL.md file
|
||||
└──────┬───────┘
|
||||
│
|
||||
↓
|
||||
┌──────────────┐
|
||||
│ 4. EXECUTE │ AI follows skill instructions
|
||||
└──────┬───────┘
|
||||
│
|
||||
↓
|
||||
┌──────────────┐
|
||||
│ 5. RESULT │ You get specialized help!
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Skill Categories (Visual Map)
|
||||
|
||||
```
|
||||
┌─────────────────────────┐
|
||||
│ 179 AWESOME SKILLS │
|
||||
└────────────┬────────────┘
|
||||
│
|
||||
┌────────────────────────┼────────────────────────┐
|
||||
│ │ │
|
||||
┌────▼────┐ ┌──────▼──────┐ ┌──────▼──────┐
|
||||
│ CREATIVE│ │ DEVELOPMENT │ │ SECURITY │
|
||||
│ (10) │ │ (25) │ │ (50) │
|
||||
└────┬────┘ └──────┬──────┘ └──────┬──────┘
|
||||
│ │ │
|
||||
• UI/UX Design • TDD • Ethical Hacking
|
||||
• Canvas Art • Debugging • Metasploit
|
||||
• Themes • React Patterns • Burp Suite
|
||||
• SQLMap
|
||||
│ │ │
|
||||
└────────────────────────┼────────────────────────┘
|
||||
│
|
||||
┌────────────────────────┼────────────────────────┐
|
||||
│ │ │
|
||||
┌────▼────┐ ┌──────▼──────┐ ┌──────▼──────┐
|
||||
│ AI │ │ DOCUMENTS │ │ MARKETING │
|
||||
│ (30) │ │ (4) │ │ (23) │
|
||||
└────┬────┘ └──────┬──────┘ └──────┬──────┘
|
||||
│ │ │
|
||||
• RAG Systems • DOCX • SEO
|
||||
• LangGraph • PDF • Copywriting
|
||||
• Prompt Eng. • PPTX • CRO
|
||||
• Voice Agents • XLSX • Paid Ads
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Skill File Anatomy (Visual)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ SKILL.md │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌───────────────────────────────────────────────┐ │
|
||||
│ │ FRONTMATTER (Metadata) │ │
|
||||
│ │ ───────────────────────────────────────────── │ │
|
||||
│ │ --- │ │
|
||||
│ │ name: my-skill │ │
|
||||
│ │ description: "What this skill does" │ │
|
||||
│ │ --- │ │
|
||||
│ └───────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌───────────────────────────────────────────────┐ │
|
||||
│ │ CONTENT (Instructions) │ │
|
||||
│ │ ───────────────────────────────────────────── │ │
|
||||
│ │ │ │
|
||||
│ │ # Skill Title │ │
|
||||
│ │ │ │
|
||||
│ │ ## Overview │ │
|
||||
│ │ What this skill does... │ │
|
||||
│ │ │ │
|
||||
│ │ ## When to Use │ │
|
||||
│ │ - Use when... │ │
|
||||
│ │ │ │
|
||||
│ │ ## Instructions │ │
|
||||
│ │ 1. First step... │ │
|
||||
│ │ 2. Second step... │ │
|
||||
│ │ │ │
|
||||
│ │ ## Examples │ │
|
||||
│ │ ```javascript │ │
|
||||
│ │ // Example code │ │
|
||||
│ │ ``` │ │
|
||||
│ │ │ │
|
||||
│ └───────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Installation (Visual Steps)
|
||||
|
||||
### Step 1: Clone the Repository
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ Terminal │
|
||||
├─────────────────────────────────────────┤
|
||||
│ $ git clone https://github.com/ │
|
||||
│ sickn33/antigravity-awesome-skills │
|
||||
│ .agent/skills │
|
||||
│ │
|
||||
│ ✓ Cloning into '.agent/skills'... │
|
||||
│ ✓ Done! │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Step 2: Verify Installation
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ File Explorer │
|
||||
├─────────────────────────────────────────┤
|
||||
│ 📁 .agent/ │
|
||||
│ └── 📁 skills/ │
|
||||
│ ├── 📁 brainstorming/ │
|
||||
│ ├── 📁 stripe-integration/ │
|
||||
│ ├── 📁 react-best-practices/ │
|
||||
│ └── ... (176 more) │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Step 3: Use a Skill
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ AI Assistant Chat │
|
||||
├─────────────────────────────────────────┤
|
||||
│ You: @brainstorming help me design │
|
||||
│ a todo app │
|
||||
│ │
|
||||
│ AI: Great! Let me help you think │
|
||||
│ through this. First, let's │
|
||||
│ understand your requirements... │
|
||||
│ │
|
||||
│ What's the primary use case? │
|
||||
│ a) Personal task management │
|
||||
│ b) Team collaboration │
|
||||
│ c) Project planning │
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example: Using a Skill (Step-by-Step)
|
||||
|
||||
### Scenario: You want to add Stripe payments to your app
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ STEP 1: Identify the Need │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ "I need to add payment processing to my app" │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ STEP 2: Find the Right Skill │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Search: "payment" or "stripe" │
|
||||
│ Found: @stripe-integration │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ STEP 3: Invoke the Skill │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ You: @stripe-integration help me add subscription billing │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ STEP 4: AI Loads Skill Knowledge │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ • Stripe API patterns │
|
||||
│ • Webhook handling │
|
||||
│ • Subscription management │
|
||||
│ • Best practices │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ STEP 5: Get Expert Help │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ AI provides: │
|
||||
│ • Code examples │
|
||||
│ • Setup instructions │
|
||||
│ • Security considerations │
|
||||
│ • Testing strategies │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Finding Skills (Visual Guide)
|
||||
|
||||
### Method 1: Browse by Category
|
||||
```
|
||||
README.md → Scroll to "Full Skill Registry" → Find category → Pick skill
|
||||
```
|
||||
|
||||
### Method 2: Search by Keyword
|
||||
```
|
||||
Terminal → ls skills/ | grep "keyword" → See matching skills
|
||||
```
|
||||
|
||||
### Method 3: Use the Index
|
||||
```
|
||||
Open skills_index.json → Search for keyword → Find skill path
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Creating Your First Skill (Visual Workflow)
|
||||
|
||||
```
|
||||
┌──────────────┐
|
||||
│ 1. IDEA │ "I want to share my Docker knowledge"
|
||||
└──────┬───────┘
|
||||
│
|
||||
↓
|
||||
┌──────────────┐
|
||||
│ 2. CREATE │ mkdir skills/docker-mastery
|
||||
└──────┬───────┘ touch skills/docker-mastery/SKILL.md
|
||||
│
|
||||
↓
|
||||
┌──────────────┐
|
||||
│ 3. WRITE │ Add frontmatter + content
|
||||
└──────┬───────┘ (Use template from CONTRIBUTING.md)
|
||||
│
|
||||
↓
|
||||
┌──────────────┐
|
||||
│ 4. TEST │ Copy to .agent/skills/
|
||||
└──────┬───────┘ Try: @docker-mastery
|
||||
│
|
||||
↓
|
||||
┌──────────────┐
|
||||
│ 5. VALIDATE │ python3 scripts/validate_skills.py
|
||||
└──────┬───────┘
|
||||
│
|
||||
↓
|
||||
┌──────────────┐
|
||||
│ 6. SUBMIT │ git commit + push + Pull Request
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Skill Complexity Levels
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ SKILL COMPLEXITY │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ SIMPLE STANDARD COMPLEX │
|
||||
│ ────── ──────── ─────── │
|
||||
│ │
|
||||
│ • 1 file • 1 file • Multiple │
|
||||
│ • 100-200 words • 300-800 words • 800-2000 │
|
||||
│ • Basic structure • Full structure • Scripts │
|
||||
│ • No extras • Examples • Examples │
|
||||
│ • Best practices • Templates│
|
||||
│ • Docs │
|
||||
│ Example: Example: Example: │
|
||||
│ git-pushing brainstorming loki-mode │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Contribution Impact (Visual)
|
||||
|
||||
```
|
||||
Your Contribution
|
||||
│
|
||||
├─→ Improves Documentation
|
||||
│ │
|
||||
│ └─→ Helps 1000s of developers understand
|
||||
│
|
||||
├─→ Creates New Skill
|
||||
│ │
|
||||
│ └─→ Enables new capabilities for everyone
|
||||
│
|
||||
├─→ Fixes Bug/Typo
|
||||
│ │
|
||||
│ └─→ Prevents confusion for future users
|
||||
│
|
||||
└─→ Adds Example
|
||||
│
|
||||
└─→ Makes learning easier for beginners
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Learning Path (Visual Roadmap)
|
||||
|
||||
```
|
||||
START HERE
|
||||
│
|
||||
↓
|
||||
┌─────────────────┐
|
||||
│ Read │
|
||||
│ GETTING_STARTED │
|
||||
└────────┬────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────┐
|
||||
│ Try 2-3 Skills │
|
||||
│ in AI Assistant │
|
||||
└────────┬────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────┐
|
||||
│ Read │
|
||||
│ SKILL_ANATOMY │
|
||||
└────────┬────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────┐
|
||||
│ Study Existing │
|
||||
│ Skills │
|
||||
└────────┬────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────┐
|
||||
│ Create Simple │
|
||||
│ Skill │
|
||||
└────────┬────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────┐
|
||||
│ Read │
|
||||
│ CONTRIBUTING │
|
||||
└────────┬────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────┐
|
||||
│ Submit PR │
|
||||
└────────┬────────┘
|
||||
│
|
||||
↓
|
||||
CONTRIBUTOR! 🎉
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 Quick Tips (Visual Cheatsheet)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ QUICK REFERENCE │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 📥 INSTALL │
|
||||
│ git clone [repo] .agent/skills │
|
||||
│ │
|
||||
│ 🎯 USE │
|
||||
│ @skill-name [your request] │
|
||||
│ │
|
||||
│ 🔍 FIND │
|
||||
│ ls skills/ | grep "keyword" │
|
||||
│ │
|
||||
│ ✅ VALIDATE │
|
||||
│ python3 scripts/validate_skills.py │
|
||||
│ │
|
||||
│ 📝 CREATE │
|
||||
│ 1. mkdir skills/my-skill │
|
||||
│ 2. Create SKILL.md with frontmatter │
|
||||
│ 3. Add content │
|
||||
│ 4. Test & validate │
|
||||
│ 5. Submit PR │
|
||||
│ │
|
||||
│ 🆘 HELP │
|
||||
│ • GETTING_STARTED.md - Basics │
|
||||
│ • CONTRIBUTING.md - How to contribute │
|
||||
│ • SKILL_ANATOMY.md - Deep dive │
|
||||
│ • GitHub Issues - Ask questions │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Success Stories (Visual Timeline)
|
||||
|
||||
```
|
||||
Day 1: Install skills
|
||||
│
|
||||
└─→ "Wow, @brainstorming helped me design my app!"
|
||||
|
||||
Day 3: Use 5 different skills
|
||||
│
|
||||
└─→ "These skills save me so much time!"
|
||||
|
||||
Week 1: Create first skill
|
||||
│
|
||||
└─→ "I shared my expertise as a skill!"
|
||||
|
||||
Week 2: Skill gets merged
|
||||
│
|
||||
└─→ "My skill is helping others! 🎉"
|
||||
|
||||
Month 1: Regular contributor
|
||||
│
|
||||
└─→ "I've contributed 5 skills and improved docs!"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. ✅ **Understand** the visual structure
|
||||
2. ✅ **Install** skills in your AI tool
|
||||
3. ✅ **Try** 2-3 skills from different categories
|
||||
4. ✅ **Read** CONTRIBUTING.md
|
||||
5. ✅ **Create** your first skill
|
||||
6. ✅ **Share** with the community
|
||||
|
||||
---
|
||||
|
||||
**Visual learner?** This guide should help! Still have questions? Check out:
|
||||
- [GETTING_STARTED.md](../GETTING_STARTED.md) - Text-based intro
|
||||
- [SKILL_ANATOMY.md](SKILL_ANATOMY.md) - Detailed breakdown
|
||||
- [CONTRIBUTING.md](../CONTRIBUTING.md) - How to contribute
|
||||
|
||||
**Ready to contribute?** You've got this! 💪
|
||||
@@ -1,6 +1,9 @@
|
||||
---
|
||||
name: Active Directory Attacks
|
||||
description: This skill should be used when the user asks to "attack Active Directory", "exploit AD", "Kerberoasting", "DCSync", "pass-the-hash", "BloodHound enumeration", "Golden Ticket", "Silver Ticket", "AS-REP roasting", "NTLM relay", or needs guidance on Windows domain penetration testing.
|
||||
metadata:
|
||||
author: zebbern
|
||||
version: "1.1"
|
||||
---
|
||||
|
||||
# Active Directory Attacks
|
||||
|
||||
@@ -1,6 +1,9 @@
|
||||
---
|
||||
name: API Fuzzing for Bug Bounty
|
||||
description: This skill should be used when the user asks to "test API security", "fuzz APIs", "find IDOR vulnerabilities", "test REST API", "test GraphQL", "API penetration testing", "bug bounty API testing", or needs guidance on API security assessment techniques.
|
||||
metadata:
|
||||
author: zebbern
|
||||
version: "1.1"
|
||||
---
|
||||
|
||||
# API Fuzzing for Bug Bounty
|
||||
|
||||
81
skills/api-patterns/SKILL.md
Normal file
81
skills/api-patterns/SKILL.md
Normal file
@@ -0,0 +1,81 @@
|
||||
---
|
||||
name: api-patterns
|
||||
description: API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.
|
||||
allowed-tools: Read, Write, Edit, Glob, Grep
|
||||
---
|
||||
|
||||
# API Patterns
|
||||
|
||||
> API design principles and decision-making for 2025.
|
||||
> **Learn to THINK, not copy fixed patterns.**
|
||||
|
||||
## 🎯 Selective Reading Rule
|
||||
|
||||
**Read ONLY files relevant to the request!** Check the content map, find what you need.
|
||||
|
||||
---
|
||||
|
||||
## 📑 Content Map
|
||||
|
||||
| File | Description | When to Read |
|
||||
|------|-------------|--------------|
|
||||
| `api-style.md` | REST vs GraphQL vs tRPC decision tree | Choosing API type |
|
||||
| `rest.md` | Resource naming, HTTP methods, status codes | Designing REST API |
|
||||
| `response.md` | Envelope pattern, error format, pagination | Response structure |
|
||||
| `graphql.md` | Schema design, when to use, security | Considering GraphQL |
|
||||
| `trpc.md` | TypeScript monorepo, type safety | TS fullstack projects |
|
||||
| `versioning.md` | URI/Header/Query versioning | API evolution planning |
|
||||
| `auth.md` | JWT, OAuth, Passkey, API Keys | Auth pattern selection |
|
||||
| `rate-limiting.md` | Token bucket, sliding window | API protection |
|
||||
| `documentation.md` | OpenAPI/Swagger best practices | Documentation |
|
||||
| `security-testing.md` | OWASP API Top 10, auth/authz testing | Security audits |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Related Skills
|
||||
|
||||
| Need | Skill |
|
||||
|------|-------|
|
||||
| API implementation | `@[skills/backend-development]` |
|
||||
| Data structure | `@[skills/database-design]` |
|
||||
| Security details | `@[skills/security-hardening]` |
|
||||
|
||||
---
|
||||
|
||||
## ✅ Decision Checklist
|
||||
|
||||
Before designing an API:
|
||||
|
||||
- [ ] **Asked user about API consumers?**
|
||||
- [ ] **Chosen API style for THIS context?** (REST/GraphQL/tRPC)
|
||||
- [ ] **Defined consistent response format?**
|
||||
- [ ] **Planned versioning strategy?**
|
||||
- [ ] **Considered authentication needs?**
|
||||
- [ ] **Planned rate limiting?**
|
||||
- [ ] **Documentation approach defined?**
|
||||
|
||||
---
|
||||
|
||||
## ❌ Anti-Patterns
|
||||
|
||||
**DON'T:**
|
||||
- Default to REST for everything
|
||||
- Use verbs in REST endpoints (/getUsers)
|
||||
- Return inconsistent response formats
|
||||
- Expose internal errors to clients
|
||||
- Skip rate limiting
|
||||
|
||||
**DO:**
|
||||
- Choose API style based on context
|
||||
- Ask about client requirements
|
||||
- Document thoroughly
|
||||
- Use appropriate status codes
|
||||
|
||||
---
|
||||
|
||||
## Script
|
||||
|
||||
| Script | Purpose | Command |
|
||||
|--------|---------|---------|
|
||||
| `scripts/api_validator.py` | API endpoint validation | `python scripts/api_validator.py <project_path>` |
|
||||
|
||||
42
skills/api-patterns/api-style.md
Normal file
42
skills/api-patterns/api-style.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# API Style Selection (2025)
|
||||
|
||||
> REST vs GraphQL vs tRPC - Hangi durumda hangisi?
|
||||
|
||||
## Decision Tree
|
||||
|
||||
```
|
||||
Who are the API consumers?
|
||||
│
|
||||
├── Public API / Multiple platforms
|
||||
│ └── REST + OpenAPI (widest compatibility)
|
||||
│
|
||||
├── Complex data needs / Multiple frontends
|
||||
│ └── GraphQL (flexible queries)
|
||||
│
|
||||
├── TypeScript frontend + backend (monorepo)
|
||||
│ └── tRPC (end-to-end type safety)
|
||||
│
|
||||
├── Real-time / Event-driven
|
||||
│ └── WebSocket + AsyncAPI
|
||||
│
|
||||
└── Internal microservices
|
||||
└── gRPC (performance) or REST (simplicity)
|
||||
```
|
||||
|
||||
## Comparison
|
||||
|
||||
| Factor | REST | GraphQL | tRPC |
|
||||
|--------|------|---------|------|
|
||||
| **Best for** | Public APIs | Complex apps | TS monorepos |
|
||||
| **Learning curve** | Low | Medium | Low (if TS) |
|
||||
| **Over/under fetching** | Common | Solved | Solved |
|
||||
| **Type safety** | Manual (OpenAPI) | Schema-based | Automatic |
|
||||
| **Caching** | HTTP native | Complex | Client-based |
|
||||
|
||||
## Selection Questions
|
||||
|
||||
1. Who are the API consumers?
|
||||
2. Is the frontend TypeScript?
|
||||
3. How complex are the data relationships?
|
||||
4. Is caching critical?
|
||||
5. Public or internal API?
|
||||
24
skills/api-patterns/auth.md
Normal file
24
skills/api-patterns/auth.md
Normal file
@@ -0,0 +1,24 @@
|
||||
# Authentication Patterns
|
||||
|
||||
> Choose auth pattern based on use case.
|
||||
|
||||
## Selection Guide
|
||||
|
||||
| Pattern | Best For |
|
||||
|---------|----------|
|
||||
| **JWT** | Stateless, microservices |
|
||||
| **Session** | Traditional web, simple |
|
||||
| **OAuth 2.0** | Third-party integration |
|
||||
| **API Keys** | Server-to-server, public APIs |
|
||||
| **Passkey** | Modern passwordless (2025+) |
|
||||
|
||||
## JWT Principles
|
||||
|
||||
```
|
||||
Important:
|
||||
├── Always verify signature
|
||||
├── Check expiration
|
||||
├── Include minimal claims
|
||||
├── Use short expiry + refresh tokens
|
||||
└── Never store sensitive data in JWT
|
||||
```
|
||||
26
skills/api-patterns/documentation.md
Normal file
26
skills/api-patterns/documentation.md
Normal file
@@ -0,0 +1,26 @@
|
||||
# API Documentation Principles
|
||||
|
||||
> Good docs = happy developers = API adoption.
|
||||
|
||||
## OpenAPI/Swagger Essentials
|
||||
|
||||
```
|
||||
Include:
|
||||
├── All endpoints with examples
|
||||
├── Request/response schemas
|
||||
├── Authentication requirements
|
||||
├── Error response formats
|
||||
└── Rate limiting info
|
||||
```
|
||||
|
||||
## Good Documentation Has
|
||||
|
||||
```
|
||||
Essentials:
|
||||
├── Quick start / Getting started
|
||||
├── Authentication guide
|
||||
├── Complete API reference
|
||||
├── Error handling guide
|
||||
├── Code examples (multiple languages)
|
||||
└── Changelog
|
||||
```
|
||||
41
skills/api-patterns/graphql.md
Normal file
41
skills/api-patterns/graphql.md
Normal file
@@ -0,0 +1,41 @@
|
||||
# GraphQL Principles
|
||||
|
||||
> Flexible queries for complex, interconnected data.
|
||||
|
||||
## When to Use
|
||||
|
||||
```
|
||||
✅ Good fit:
|
||||
├── Complex, interconnected data
|
||||
├── Multiple frontend platforms
|
||||
├── Clients need flexible queries
|
||||
├── Evolving data requirements
|
||||
└── Reducing over-fetching matters
|
||||
|
||||
❌ Poor fit:
|
||||
├── Simple CRUD operations
|
||||
├── File upload heavy
|
||||
├── HTTP caching important
|
||||
└── Team unfamiliar with GraphQL
|
||||
```
|
||||
|
||||
## Schema Design Principles
|
||||
|
||||
```
|
||||
Principles:
|
||||
├── Think in graphs, not endpoints
|
||||
├── Design for evolvability (no versions)
|
||||
├── Use connections for pagination
|
||||
├── Be specific with types (not generic "data")
|
||||
└── Handle nullability thoughtfully
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
```
|
||||
Protect against:
|
||||
├── Query depth attacks → Set max depth
|
||||
├── Query complexity → Calculate cost
|
||||
├── Batching abuse → Limit batch size
|
||||
├── Introspection → Disable in production
|
||||
```
|
||||
31
skills/api-patterns/rate-limiting.md
Normal file
31
skills/api-patterns/rate-limiting.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# Rate Limiting Principles
|
||||
|
||||
> Protect your API from abuse and overload.
|
||||
|
||||
## Why Rate Limit
|
||||
|
||||
```
|
||||
Protect against:
|
||||
├── Brute force attacks
|
||||
├── Resource exhaustion
|
||||
├── Cost overruns (if pay-per-use)
|
||||
└── Unfair usage
|
||||
```
|
||||
|
||||
## Strategy Selection
|
||||
|
||||
| Type | How | When |
|
||||
|------|-----|------|
|
||||
| **Token bucket** | Burst allowed, refills over time | Most APIs |
|
||||
| **Sliding window** | Smooth distribution | Strict limits |
|
||||
| **Fixed window** | Simple counters per window | Basic needs |
|
||||
|
||||
## Response Headers
|
||||
|
||||
```
|
||||
Include in headers:
|
||||
├── X-RateLimit-Limit (max requests)
|
||||
├── X-RateLimit-Remaining (requests left)
|
||||
├── X-RateLimit-Reset (when limit resets)
|
||||
└── Return 429 when exceeded
|
||||
```
|
||||
37
skills/api-patterns/response.md
Normal file
37
skills/api-patterns/response.md
Normal file
@@ -0,0 +1,37 @@
|
||||
# Response Format Principles
|
||||
|
||||
> Consistency is key - choose a format and stick to it.
|
||||
|
||||
## Common Patterns
|
||||
|
||||
```
|
||||
Choose one:
|
||||
├── Envelope pattern ({ success, data, error })
|
||||
├── Direct data (just return the resource)
|
||||
└── HAL/JSON:API (hypermedia)
|
||||
```
|
||||
|
||||
## Error Response
|
||||
|
||||
```
|
||||
Include:
|
||||
├── Error code (for programmatic handling)
|
||||
├── User message (for display)
|
||||
├── Details (for debugging, field-level errors)
|
||||
├── Request ID (for support)
|
||||
└── NOT internal details (security!)
|
||||
```
|
||||
|
||||
## Pagination Types
|
||||
|
||||
| Type | Best For | Trade-offs |
|
||||
|------|----------|------------|
|
||||
| **Offset** | Simple, jumpable | Performance on large datasets |
|
||||
| **Cursor** | Large datasets | Can't jump to page |
|
||||
| **Keyset** | Performance critical | Requires sortable key |
|
||||
|
||||
### Selection Questions
|
||||
|
||||
1. How large is the dataset?
|
||||
2. Do users need to jump to specific pages?
|
||||
3. Is data frequently changing?
|
||||
40
skills/api-patterns/rest.md
Normal file
40
skills/api-patterns/rest.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# REST Principles
|
||||
|
||||
> Resource-based API design - nouns not verbs.
|
||||
|
||||
## Resource Naming Rules
|
||||
|
||||
```
|
||||
Principles:
|
||||
├── Use NOUNS, not verbs (resources, not actions)
|
||||
├── Use PLURAL forms (/users not /user)
|
||||
├── Use lowercase with hyphens (/user-profiles)
|
||||
├── Nest for relationships (/users/123/posts)
|
||||
└── Keep shallow (max 3 levels deep)
|
||||
```
|
||||
|
||||
## HTTP Method Selection
|
||||
|
||||
| Method | Purpose | Idempotent? | Body? |
|
||||
|--------|---------|-------------|-------|
|
||||
| **GET** | Read resource(s) | Yes | No |
|
||||
| **POST** | Create new resource | No | Yes |
|
||||
| **PUT** | Replace entire resource | Yes | Yes |
|
||||
| **PATCH** | Partial update | No | Yes |
|
||||
| **DELETE** | Remove resource | Yes | No |
|
||||
|
||||
## Status Code Selection
|
||||
|
||||
| Situation | Code | Why |
|
||||
|-----------|------|-----|
|
||||
| Success (read) | 200 | Standard success |
|
||||
| Created | 201 | New resource created |
|
||||
| No content | 204 | Success, nothing to return |
|
||||
| Bad request | 400 | Malformed request |
|
||||
| Unauthorized | 401 | Missing/invalid auth |
|
||||
| Forbidden | 403 | Valid auth, no permission |
|
||||
| Not found | 404 | Resource doesn't exist |
|
||||
| Conflict | 409 | State conflict (duplicate) |
|
||||
| Validation error | 422 | Valid syntax, invalid data |
|
||||
| Rate limited | 429 | Too many requests |
|
||||
| Server error | 500 | Our fault |
|
||||
211
skills/api-patterns/scripts/api_validator.py
Normal file
211
skills/api-patterns/scripts/api_validator.py
Normal file
@@ -0,0 +1,211 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
API Validator - Checks API endpoints for best practices.
|
||||
Validates OpenAPI specs, response formats, and common issues.
|
||||
"""
|
||||
import sys
|
||||
import json
|
||||
import re
|
||||
from pathlib import Path
|
||||
|
||||
# Fix Windows console encoding for Unicode output
|
||||
try:
|
||||
sys.stdout.reconfigure(encoding='utf-8', errors='replace')
|
||||
sys.stderr.reconfigure(encoding='utf-8', errors='replace')
|
||||
except AttributeError:
|
||||
pass # Python < 3.7
|
||||
|
||||
def find_api_files(project_path: Path) -> list:
|
||||
"""Find API-related files."""
|
||||
patterns = [
|
||||
"**/*api*.ts", "**/*api*.js", "**/*api*.py",
|
||||
"**/routes/*.ts", "**/routes/*.js", "**/routes/*.py",
|
||||
"**/controllers/*.ts", "**/controllers/*.js",
|
||||
"**/endpoints/*.ts", "**/endpoints/*.py",
|
||||
"**/*.openapi.json", "**/*.openapi.yaml",
|
||||
"**/swagger.json", "**/swagger.yaml",
|
||||
"**/openapi.json", "**/openapi.yaml"
|
||||
]
|
||||
|
||||
files = []
|
||||
for pattern in patterns:
|
||||
files.extend(project_path.glob(pattern))
|
||||
|
||||
# Exclude node_modules, etc.
|
||||
return [f for f in files if not any(x in str(f) for x in ['node_modules', '.git', 'dist', 'build', '__pycache__'])]
|
||||
|
||||
def check_openapi_spec(file_path: Path) -> dict:
|
||||
"""Check OpenAPI/Swagger specification."""
|
||||
issues = []
|
||||
passed = []
|
||||
|
||||
try:
|
||||
content = file_path.read_text(encoding='utf-8')
|
||||
|
||||
if file_path.suffix == '.json':
|
||||
spec = json.loads(content)
|
||||
else:
|
||||
# Basic YAML check
|
||||
if 'openapi:' in content or 'swagger:' in content:
|
||||
passed.append("[OK] OpenAPI/Swagger version defined")
|
||||
else:
|
||||
issues.append("[X] No OpenAPI version found")
|
||||
|
||||
if 'paths:' in content:
|
||||
passed.append("[OK] Paths section exists")
|
||||
else:
|
||||
issues.append("[X] No paths defined")
|
||||
|
||||
if 'components:' in content or 'definitions:' in content:
|
||||
passed.append("[OK] Schema components defined")
|
||||
|
||||
return {'file': str(file_path), 'passed': passed, 'issues': issues, 'type': 'openapi'}
|
||||
|
||||
# JSON OpenAPI checks
|
||||
if 'openapi' in spec or 'swagger' in spec:
|
||||
passed.append("[OK] OpenAPI version defined")
|
||||
|
||||
if 'info' in spec:
|
||||
if 'title' in spec['info']:
|
||||
passed.append("[OK] API title defined")
|
||||
if 'version' in spec['info']:
|
||||
passed.append("[OK] API version defined")
|
||||
if 'description' not in spec['info']:
|
||||
issues.append("[!] API description missing")
|
||||
|
||||
if 'paths' in spec:
|
||||
path_count = len(spec['paths'])
|
||||
passed.append(f"[OK] {path_count} endpoints defined")
|
||||
|
||||
# Check each path
|
||||
for path, methods in spec['paths'].items():
|
||||
for method, details in methods.items():
|
||||
if method in ['get', 'post', 'put', 'patch', 'delete']:
|
||||
if 'responses' not in details:
|
||||
issues.append(f"[X] {method.upper()} {path}: No responses defined")
|
||||
if 'summary' not in details and 'description' not in details:
|
||||
issues.append(f"[!] {method.upper()} {path}: No description")
|
||||
|
||||
except Exception as e:
|
||||
issues.append(f"[X] Parse error: {e}")
|
||||
|
||||
return {'file': str(file_path), 'passed': passed, 'issues': issues, 'type': 'openapi'}
|
||||
|
||||
def check_api_code(file_path: Path) -> dict:
|
||||
"""Check API code for common issues."""
|
||||
issues = []
|
||||
passed = []
|
||||
|
||||
try:
|
||||
content = file_path.read_text(encoding='utf-8')
|
||||
|
||||
# Check for error handling
|
||||
error_patterns = [
|
||||
r'try\s*{', r'try:', r'\.catch\(',
|
||||
r'except\s+', r'catch\s*\('
|
||||
]
|
||||
has_error_handling = any(re.search(p, content) for p in error_patterns)
|
||||
if has_error_handling:
|
||||
passed.append("[OK] Error handling present")
|
||||
else:
|
||||
issues.append("[X] No error handling found")
|
||||
|
||||
# Check for status codes
|
||||
status_patterns = [
|
||||
r'status\s*\(\s*\d{3}\s*\)', r'statusCode\s*[=:]\s*\d{3}',
|
||||
r'HttpStatus\.', r'status_code\s*=\s*\d{3}',
|
||||
r'\.status\(\d{3}\)', r'res\.status\('
|
||||
]
|
||||
has_status = any(re.search(p, content) for p in status_patterns)
|
||||
if has_status:
|
||||
passed.append("[OK] HTTP status codes used")
|
||||
else:
|
||||
issues.append("[!] No explicit HTTP status codes")
|
||||
|
||||
# Check for validation
|
||||
validation_patterns = [
|
||||
r'validate', r'schema', r'zod', r'joi', r'yup',
|
||||
r'pydantic', r'@Body\(', r'@Query\('
|
||||
]
|
||||
has_validation = any(re.search(p, content, re.I) for p in validation_patterns)
|
||||
if has_validation:
|
||||
passed.append("[OK] Input validation present")
|
||||
else:
|
||||
issues.append("[!] No input validation detected")
|
||||
|
||||
# Check for auth middleware
|
||||
auth_patterns = [
|
||||
r'auth', r'jwt', r'bearer', r'token',
|
||||
r'middleware', r'guard', r'@Authenticated'
|
||||
]
|
||||
has_auth = any(re.search(p, content, re.I) for p in auth_patterns)
|
||||
if has_auth:
|
||||
passed.append("[OK] Authentication/authorization detected")
|
||||
|
||||
# Check for rate limiting
|
||||
rate_patterns = [r'rateLimit', r'throttle', r'rate.?limit']
|
||||
has_rate = any(re.search(p, content, re.I) for p in rate_patterns)
|
||||
if has_rate:
|
||||
passed.append("[OK] Rate limiting present")
|
||||
|
||||
# Check for logging
|
||||
log_patterns = [r'console\.log', r'logger\.', r'logging\.', r'log\.']
|
||||
has_logging = any(re.search(p, content) for p in log_patterns)
|
||||
if has_logging:
|
||||
passed.append("[OK] Logging present")
|
||||
|
||||
except Exception as e:
|
||||
issues.append(f"[X] Read error: {e}")
|
||||
|
||||
return {'file': str(file_path), 'passed': passed, 'issues': issues, 'type': 'code'}
|
||||
|
||||
def main():
|
||||
target = sys.argv[1] if len(sys.argv) > 1 else "."
|
||||
project_path = Path(target)
|
||||
|
||||
print("\n" + "=" * 60)
|
||||
print(" API VALIDATOR - Endpoint Best Practices Check")
|
||||
print("=" * 60 + "\n")
|
||||
|
||||
api_files = find_api_files(project_path)
|
||||
|
||||
if not api_files:
|
||||
print("[!] No API files found.")
|
||||
print(" Looking for: routes/, controllers/, api/, openapi.json/yaml")
|
||||
sys.exit(0)
|
||||
|
||||
results = []
|
||||
for file_path in api_files[:15]: # Limit
|
||||
if 'openapi' in file_path.name.lower() or 'swagger' in file_path.name.lower():
|
||||
result = check_openapi_spec(file_path)
|
||||
else:
|
||||
result = check_api_code(file_path)
|
||||
results.append(result)
|
||||
|
||||
# Print results
|
||||
total_issues = 0
|
||||
total_passed = 0
|
||||
|
||||
for result in results:
|
||||
print(f"\n[FILE] {result['file']} [{result['type']}]")
|
||||
for item in result['passed']:
|
||||
print(f" {item}")
|
||||
total_passed += 1
|
||||
for item in result['issues']:
|
||||
print(f" {item}")
|
||||
if item.startswith("[X]"):
|
||||
total_issues += 1
|
||||
|
||||
print("\n" + "=" * 60)
|
||||
print(f"[RESULTS] {total_passed} passed, {total_issues} critical issues")
|
||||
print("=" * 60)
|
||||
|
||||
if total_issues == 0:
|
||||
print("[OK] API validation passed")
|
||||
sys.exit(0)
|
||||
else:
|
||||
print("[X] Fix critical issues before deployment")
|
||||
sys.exit(1)
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
122
skills/api-patterns/security-testing.md
Normal file
122
skills/api-patterns/security-testing.md
Normal file
@@ -0,0 +1,122 @@
|
||||
# API Security Testing
|
||||
|
||||
> Principles for testing API security. OWASP API Top 10, authentication, authorization testing.
|
||||
|
||||
---
|
||||
|
||||
## OWASP API Security Top 10
|
||||
|
||||
| Vulnerability | Test Focus |
|
||||
|---------------|------------|
|
||||
| **API1: BOLA** | Access other users' resources |
|
||||
| **API2: Broken Auth** | JWT, session, credentials |
|
||||
| **API3: Property Auth** | Mass assignment, data exposure |
|
||||
| **API4: Resource Consumption** | Rate limiting, DoS |
|
||||
| **API5: Function Auth** | Admin endpoints, role bypass |
|
||||
| **API6: Business Flow** | Logic abuse, automation |
|
||||
| **API7: SSRF** | Internal network access |
|
||||
| **API8: Misconfiguration** | Debug endpoints, CORS |
|
||||
| **API9: Inventory** | Shadow APIs, old versions |
|
||||
| **API10: Unsafe Consumption** | Third-party API trust |
|
||||
|
||||
---
|
||||
|
||||
## Authentication Testing
|
||||
|
||||
### JWT Testing
|
||||
|
||||
| Check | What to Test |
|
||||
|-------|--------------|
|
||||
| Algorithm | None, algorithm confusion |
|
||||
| Secret | Weak secrets, brute force |
|
||||
| Claims | Expiration, issuer, audience |
|
||||
| Signature | Manipulation, key injection |
|
||||
|
||||
### Session Testing
|
||||
|
||||
| Check | What to Test |
|
||||
|-------|--------------|
|
||||
| Generation | Predictability |
|
||||
| Storage | Client-side security |
|
||||
| Expiration | Timeout enforcement |
|
||||
| Invalidation | Logout effectiveness |
|
||||
|
||||
---
|
||||
|
||||
## Authorization Testing
|
||||
|
||||
| Test Type | Approach |
|
||||
|-----------|----------|
|
||||
| **Horizontal** | Access peer users' data |
|
||||
| **Vertical** | Access higher privilege functions |
|
||||
| **Context** | Access outside allowed scope |
|
||||
|
||||
### BOLA/IDOR Testing
|
||||
|
||||
1. Identify resource IDs in requests
|
||||
2. Capture request with user A's session
|
||||
3. Replay with user B's session
|
||||
4. Check for unauthorized access
|
||||
|
||||
---
|
||||
|
||||
## Input Validation Testing
|
||||
|
||||
| Injection Type | Test Focus |
|
||||
|----------------|------------|
|
||||
| SQL | Query manipulation |
|
||||
| NoSQL | Document queries |
|
||||
| Command | System commands |
|
||||
| LDAP | Directory queries |
|
||||
|
||||
**Approach:** Test all parameters, try type coercion, test boundaries, check error messages.
|
||||
|
||||
---
|
||||
|
||||
## Rate Limiting Testing
|
||||
|
||||
| Aspect | Check |
|
||||
|--------|-------|
|
||||
| Existence | Is there any limit? |
|
||||
| Bypass | Headers, IP rotation |
|
||||
| Scope | Per-user, per-IP, global |
|
||||
|
||||
**Bypass techniques:** X-Forwarded-For, different HTTP methods, case variations, API versioning.
|
||||
|
||||
---
|
||||
|
||||
## GraphQL Security
|
||||
|
||||
| Test | Focus |
|
||||
|------|-------|
|
||||
| Introspection | Schema disclosure |
|
||||
| Batching | Query DoS |
|
||||
| Nesting | Depth-based DoS |
|
||||
| Authorization | Field-level access |
|
||||
|
||||
---
|
||||
|
||||
## Security Testing Checklist
|
||||
|
||||
**Authentication:**
|
||||
- [ ] Test for bypass
|
||||
- [ ] Check credential strength
|
||||
- [ ] Verify token security
|
||||
|
||||
**Authorization:**
|
||||
- [ ] Test BOLA/IDOR
|
||||
- [ ] Check privilege escalation
|
||||
- [ ] Verify function access
|
||||
|
||||
**Input:**
|
||||
- [ ] Test all parameters
|
||||
- [ ] Check for injection
|
||||
|
||||
**Config:**
|
||||
- [ ] Check CORS
|
||||
- [ ] Verify headers
|
||||
- [ ] Test error handling
|
||||
|
||||
---
|
||||
|
||||
> **Remember:** APIs are the backbone of modern apps. Test them like attackers will.
|
||||
41
skills/api-patterns/trpc.md
Normal file
41
skills/api-patterns/trpc.md
Normal file
@@ -0,0 +1,41 @@
|
||||
# tRPC Principles
|
||||
|
||||
> End-to-end type safety for TypeScript monorepos.
|
||||
|
||||
## When to Use
|
||||
|
||||
```
|
||||
✅ Perfect fit:
|
||||
├── TypeScript on both ends
|
||||
├── Monorepo structure
|
||||
├── Internal tools
|
||||
├── Rapid development
|
||||
└── Type safety critical
|
||||
|
||||
❌ Poor fit:
|
||||
├── Non-TypeScript clients
|
||||
├── Public API
|
||||
├── Need REST conventions
|
||||
└── Multiple language backends
|
||||
```
|
||||
|
||||
## Key Benefits
|
||||
|
||||
```
|
||||
Why tRPC:
|
||||
├── Zero schema maintenance
|
||||
├── End-to-end type inference
|
||||
├── IDE autocomplete across stack
|
||||
├── Instant API changes reflected
|
||||
└── No code generation step
|
||||
```
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
```
|
||||
Common setups:
|
||||
├── Next.js + tRPC (most common)
|
||||
├── Monorepo with shared types
|
||||
├── Remix + tRPC
|
||||
└── Any TS frontend + backend
|
||||
```
|
||||
22
skills/api-patterns/versioning.md
Normal file
22
skills/api-patterns/versioning.md
Normal file
@@ -0,0 +1,22 @@
|
||||
# Versioning Strategies
|
||||
|
||||
> Plan for API evolution from day one.
|
||||
|
||||
## Decision Factors
|
||||
|
||||
| Strategy | Implementation | Trade-offs |
|
||||
|----------|---------------|------------|
|
||||
| **URI** | /v1/users | Clear, easy caching |
|
||||
| **Header** | Accept-Version: 1 | Cleaner URLs, harder discovery |
|
||||
| **Query** | ?version=1 | Easy to add, messy |
|
||||
| **None** | Evolve carefully | Best for internal, risky for public |
|
||||
|
||||
## Versioning Philosophy
|
||||
|
||||
```
|
||||
Consider:
|
||||
├── Public API? → Version in URI
|
||||
├── Internal only? → May not need versioning
|
||||
├── GraphQL? → Typically no versions (evolve schema)
|
||||
├── tRPC? → Types enforce compatibility
|
||||
```
|
||||
75
skills/app-builder/SKILL.md
Normal file
75
skills/app-builder/SKILL.md
Normal file
@@ -0,0 +1,75 @@
|
||||
---
|
||||
name: app-builder
|
||||
description: Main application building orchestrator. Creates full-stack applications from natural language requests. Determines project type, selects tech stack, coordinates agents.
|
||||
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent
|
||||
---
|
||||
|
||||
# App Builder - Application Building Orchestrator
|
||||
|
||||
> Analyzes user's requests, determines tech stack, plans structure, and coordinates agents.
|
||||
|
||||
## 🎯 Selective Reading Rule
|
||||
|
||||
**Read ONLY files relevant to the request!** Check the content map, find what you need.
|
||||
|
||||
| File | Description | When to Read |
|
||||
|------|-------------|--------------|
|
||||
| `project-detection.md` | Keyword matrix, project type detection | Starting new project |
|
||||
| `tech-stack.md` | 2025 default stack, alternatives | Choosing technologies |
|
||||
| `agent-coordination.md` | Agent pipeline, execution order | Coordinating multi-agent work |
|
||||
| `scaffolding.md` | Directory structure, core files | Creating project structure |
|
||||
| `feature-building.md` | Feature analysis, error handling | Adding features to existing project |
|
||||
| `templates/SKILL.md` | **Project templates** | Scaffolding new project |
|
||||
|
||||
---
|
||||
|
||||
## 📦 Templates (13)
|
||||
|
||||
Quick-start scaffolding for new projects. **Read the matching template only!**
|
||||
|
||||
| Template | Tech Stack | When to Use |
|
||||
|----------|------------|-------------|
|
||||
| [nextjs-fullstack](templates/nextjs-fullstack/TEMPLATE.md) | Next.js + Prisma | Full-stack web app |
|
||||
| [nextjs-saas](templates/nextjs-saas/TEMPLATE.md) | Next.js + Stripe | SaaS product |
|
||||
| [nextjs-static](templates/nextjs-static/TEMPLATE.md) | Next.js + Framer | Landing page |
|
||||
| [nuxt-app](templates/nuxt-app/TEMPLATE.md) | Nuxt 3 + Pinia | Vue full-stack app |
|
||||
| [express-api](templates/express-api/TEMPLATE.md) | Express + JWT | REST API |
|
||||
| [python-fastapi](templates/python-fastapi/TEMPLATE.md) | FastAPI | Python API |
|
||||
| [react-native-app](templates/react-native-app/TEMPLATE.md) | Expo + Zustand | Mobile app |
|
||||
| [flutter-app](templates/flutter-app/TEMPLATE.md) | Flutter + Riverpod | Cross-platform mobile |
|
||||
| [electron-desktop](templates/electron-desktop/TEMPLATE.md) | Electron + React | Desktop app |
|
||||
| [chrome-extension](templates/chrome-extension/TEMPLATE.md) | Chrome MV3 | Browser extension |
|
||||
| [cli-tool](templates/cli-tool/TEMPLATE.md) | Node.js + Commander | CLI app |
|
||||
| [monorepo-turborepo](templates/monorepo-turborepo/TEMPLATE.md) | Turborepo + pnpm | Monorepo |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Related Agents
|
||||
|
||||
| Agent | Role |
|
||||
|-------|------|
|
||||
| `project-planner` | Task breakdown, dependency graph |
|
||||
| `frontend-specialist` | UI components, pages |
|
||||
| `backend-specialist` | API, business logic |
|
||||
| `database-architect` | Schema, migrations |
|
||||
| `devops-engineer` | Deployment, preview |
|
||||
|
||||
---
|
||||
|
||||
## Usage Example
|
||||
|
||||
```
|
||||
User: "Make an Instagram clone with photo sharing and likes"
|
||||
|
||||
App Builder Process:
|
||||
1. Project type: Social Media App
|
||||
2. Tech stack: Next.js + Prisma + Cloudinary + Clerk
|
||||
3. Create plan:
|
||||
├─ Database schema (users, posts, likes, follows)
|
||||
├─ API routes (12 endpoints)
|
||||
├─ Pages (feed, profile, upload)
|
||||
└─ Components (PostCard, Feed, LikeButton)
|
||||
4. Coordinate agents
|
||||
5. Report progress
|
||||
6. Start preview
|
||||
```
|
||||
71
skills/app-builder/agent-coordination.md
Normal file
71
skills/app-builder/agent-coordination.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# Agent Coordination
|
||||
|
||||
> How App Builder orchestrates specialist agents.
|
||||
|
||||
## Agent Pipeline
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ APP BUILDER (Orchestrator) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ PROJECT PLANNER │
|
||||
│ • Task breakdown │
|
||||
│ • Dependency graph │
|
||||
│ • File structure planning │
|
||||
│ • Create {task-slug}.md in project root (MANDATORY) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ CHECKPOINT: PLAN VERIFICATION │
|
||||
│ 🔴 VERIFY: Does {task-slug}.md exist in project root? │
|
||||
│ 🔴 If NO → STOP → Create plan file first │
|
||||
│ 🔴 If YES → Proceed to specialist agents │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌───────────────────┼───────────────────┐
|
||||
▼ ▼ ▼
|
||||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||||
│ DATABASE │ │ BACKEND │ │ FRONTEND │
|
||||
│ ARCHITECT │ │ SPECIALIST │ │ SPECIALIST │
|
||||
│ │ │ │ │ │
|
||||
│ • Schema design │ │ • API routes │ │ • Components │
|
||||
│ • Migrations │ │ • Controllers │ │ • Pages │
|
||||
│ • Seed data │ │ • Middleware │ │ • Styling │
|
||||
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||||
│ │ │
|
||||
└───────────────────┼───────────────────┘
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ PARALLEL PHASE (Optional) │
|
||||
│ • Security Auditor → Vulnerability check │
|
||||
│ • Test Engineer → Unit tests │
|
||||
│ • Performance Optimizer → Bundle analysis │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ DEVOPS ENGINEER │
|
||||
│ • Environment setup │
|
||||
│ • Preview deployment │
|
||||
│ • Health check │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Execution Order
|
||||
|
||||
| Phase | Agent(s) | Parallel? | Prerequisite | CHECKPOINT |
|
||||
|-------|----------|-----------|--------------|------------|
|
||||
| 0 | Socratic Gate | ❌ | - | ✅ Ask 3 questions |
|
||||
| 1 | Project Planner | ❌ | Questions answered | ✅ **PLAN.md created** |
|
||||
| 1.5 | **PLAN VERIFICATION** | ❌ | PLAN.md exists | ✅ **File exists in root** |
|
||||
| 2 | Database Architect | ❌ | Plan ready | Schema defined |
|
||||
| 3 | Backend Specialist | ❌ | Schema ready | API routes created |
|
||||
| 4 | Frontend Specialist | ✅ | API ready (partial) | UI components ready |
|
||||
| 5 | Security Auditor, Test Engineer | ✅ | Code ready | Tests & audit pass |
|
||||
| 6 | DevOps Engineer | ❌ | All code ready | Deployment ready |
|
||||
|
||||
> 🔴 **CRITICAL:** Phase 1.5 is MANDATORY. No specialist agents proceed without PLAN.md verification.
|
||||
53
skills/app-builder/feature-building.md
Normal file
53
skills/app-builder/feature-building.md
Normal file
@@ -0,0 +1,53 @@
|
||||
# Feature Building
|
||||
|
||||
> How to analyze and implement new features.
|
||||
|
||||
## Feature Analysis
|
||||
|
||||
```
|
||||
Request: "add payment system"
|
||||
|
||||
Analysis:
|
||||
├── Required Changes:
|
||||
│ ├── Database: orders, payments tables
|
||||
│ ├── Backend: /api/checkout, /api/webhooks/stripe
|
||||
│ ├── Frontend: CheckoutForm, PaymentSuccess
|
||||
│ └── Config: Stripe API keys
|
||||
│
|
||||
├── Dependencies:
|
||||
│ ├── stripe package
|
||||
│ └── Existing user authentication
|
||||
│
|
||||
└── Estimated Time: 15-20 minutes
|
||||
```
|
||||
|
||||
## Iterative Enhancement Process
|
||||
|
||||
```
|
||||
1. Analyze existing project
|
||||
2. Create change plan
|
||||
3. Present plan to user
|
||||
4. Get approval
|
||||
5. Apply changes
|
||||
6. Test
|
||||
7. Show preview
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error Type | Solution Strategy |
|
||||
|------------|-------------------|
|
||||
| TypeScript Error | Fix type, add missing import |
|
||||
| Missing Dependency | Run npm install |
|
||||
| Port Conflict | Suggest alternative port |
|
||||
| Database Error | Check migration, validate connection |
|
||||
|
||||
## Recovery Strategy
|
||||
|
||||
```
|
||||
1. Detect error
|
||||
2. Try automatic fix
|
||||
3. If failed, report to user
|
||||
4. Suggest alternative
|
||||
5. Rollback if necessary
|
||||
```
|
||||
34
skills/app-builder/project-detection.md
Normal file
34
skills/app-builder/project-detection.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# Project Type Detection
|
||||
|
||||
> Analyze user requests to determine project type and template.
|
||||
|
||||
## Keyword Matrix
|
||||
|
||||
| Keywords | Project Type | Template |
|
||||
|----------|--------------|----------|
|
||||
| blog, post, article | Blog | astro-static |
|
||||
| e-commerce, product, cart, payment | E-commerce | nextjs-saas |
|
||||
| dashboard, panel, management | Admin Dashboard | nextjs-fullstack |
|
||||
| api, backend, service, rest | API Service | express-api |
|
||||
| python, fastapi, django | Python API | python-fastapi |
|
||||
| mobile, android, ios, react native | Mobile App (RN) | react-native-app |
|
||||
| flutter, dart | Mobile App (Flutter) | flutter-app |
|
||||
| portfolio, personal, cv | Portfolio | nextjs-static |
|
||||
| crm, customer, sales | CRM | nextjs-fullstack |
|
||||
| saas, subscription, stripe | SaaS | nextjs-saas |
|
||||
| landing, promotional, marketing | Landing Page | nextjs-static |
|
||||
| docs, documentation | Documentation | astro-static |
|
||||
| extension, plugin, chrome | Browser Extension | chrome-extension |
|
||||
| desktop, electron | Desktop App | electron-desktop |
|
||||
| cli, command line, terminal | CLI Tool | cli-tool |
|
||||
| monorepo, workspace | Monorepo | monorepo-turborepo |
|
||||
|
||||
## Detection Process
|
||||
|
||||
```
|
||||
1. Tokenize user request
|
||||
2. Extract keywords
|
||||
3. Determine project type
|
||||
4. Detect missing information → forward to conversation-manager
|
||||
5. Suggest tech stack
|
||||
```
|
||||
118
skills/app-builder/scaffolding.md
Normal file
118
skills/app-builder/scaffolding.md
Normal file
@@ -0,0 +1,118 @@
|
||||
# Project Scaffolding
|
||||
|
||||
> Directory structure and core files for new projects.
|
||||
|
||||
---
|
||||
|
||||
## Next.js Full-Stack Structure (2025 Optimized)
|
||||
|
||||
```
|
||||
project-name/
|
||||
├── src/
|
||||
│ ├── app/ # Routes only (thin layer)
|
||||
│ │ ├── layout.tsx
|
||||
│ │ ├── page.tsx
|
||||
│ │ ├── globals.css
|
||||
│ │ ├── (auth)/ # Route group - auth pages
|
||||
│ │ │ ├── login/page.tsx
|
||||
│ │ │ └── register/page.tsx
|
||||
│ │ ├── (dashboard)/ # Route group - dashboard layout
|
||||
│ │ │ ├── layout.tsx
|
||||
│ │ │ └── page.tsx
|
||||
│ │ └── api/
|
||||
│ │ └── [resource]/route.ts
|
||||
│ │
|
||||
│ ├── features/ # Feature-based modules
|
||||
│ │ ├── auth/
|
||||
│ │ │ ├── components/
|
||||
│ │ │ ├── hooks/
|
||||
│ │ │ ├── actions.ts # Server Actions
|
||||
│ │ │ ├── queries.ts # Data fetching
|
||||
│ │ │ └── types.ts
|
||||
│ │ ├── products/
|
||||
│ │ │ ├── components/
|
||||
│ │ │ ├── actions.ts
|
||||
│ │ │ └── queries.ts
|
||||
│ │ └── cart/
|
||||
│ │ └── ...
|
||||
│ │
|
||||
│ ├── shared/ # Shared utilities
|
||||
│ │ ├── components/ui/ # Reusable UI components
|
||||
│ │ ├── lib/ # Utils, helpers
|
||||
│ │ └── hooks/ # Global hooks
|
||||
│ │
|
||||
│ └── server/ # Server-only code
|
||||
│ ├── db/ # Database client (Prisma)
|
||||
│ ├── auth/ # Auth config
|
||||
│ └── services/ # External API integrations
|
||||
│
|
||||
├── prisma/
|
||||
│ ├── schema.prisma
|
||||
│ ├── migrations/
|
||||
│ └── seed.ts
|
||||
│
|
||||
├── public/
|
||||
├── .env.example
|
||||
├── .env.local
|
||||
├── package.json
|
||||
├── tailwind.config.ts
|
||||
├── tsconfig.json
|
||||
└── README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Structure Principles
|
||||
|
||||
| Principle | Implementation |
|
||||
|-----------|----------------|
|
||||
| **Feature isolation** | Each feature in `features/` with its own components, hooks, actions |
|
||||
| **Server/Client separation** | Server-only code in `server/`, prevents accidental client imports |
|
||||
| **Thin routes** | `app/` only for routing, logic lives in `features/` |
|
||||
| **Route groups** | `(groupName)/` for layout sharing without URL impact |
|
||||
| **Shared code** | `shared/` for truly reusable UI and utilities |
|
||||
|
||||
---
|
||||
|
||||
## Core Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `package.json` | Dependencies |
|
||||
| `tsconfig.json` | TypeScript + path aliases (`@/features/*`) |
|
||||
| `tailwind.config.ts` | Tailwind config |
|
||||
| `.env.example` | Environment template |
|
||||
| `README.md` | Project documentation |
|
||||
| `.gitignore` | Git ignore rules |
|
||||
| `prisma/schema.prisma` | Database schema |
|
||||
|
||||
---
|
||||
|
||||
## Path Aliases (tsconfig.json)
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"paths": {
|
||||
"@/*": ["./src/*"],
|
||||
"@/features/*": ["./src/features/*"],
|
||||
"@/shared/*": ["./src/shared/*"],
|
||||
"@/server/*": ["./src/server/*"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## When to Use What
|
||||
|
||||
| Need | Location |
|
||||
|------|----------|
|
||||
| New page/route | `app/(group)/page.tsx` |
|
||||
| Feature component | `features/[name]/components/` |
|
||||
| Server action | `features/[name]/actions.ts` |
|
||||
| Data fetching | `features/[name]/queries.ts` |
|
||||
| Reusable button/input | `shared/components/ui/` |
|
||||
| Database query | `server/db/` |
|
||||
| External API call | `server/services/` |
|
||||
40
skills/app-builder/tech-stack.md
Normal file
40
skills/app-builder/tech-stack.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# Tech Stack Selection (2025)
|
||||
|
||||
> Default and alternative technology choices for web applications.
|
||||
|
||||
## Default Stack (Web App - 2025)
|
||||
|
||||
```yaml
|
||||
Frontend:
|
||||
framework: Next.js 16 (Stable)
|
||||
language: TypeScript 5.7+
|
||||
styling: Tailwind CSS v4
|
||||
state: React 19 Actions / Server Components
|
||||
bundler: Turbopack (Stable for Dev)
|
||||
|
||||
Backend:
|
||||
runtime: Node.js 23
|
||||
framework: Next.js API Routes / Hono (for Edge)
|
||||
validation: Zod / TypeBox
|
||||
|
||||
Database:
|
||||
primary: PostgreSQL
|
||||
orm: Prisma / Drizzle
|
||||
hosting: Supabase / Neon
|
||||
|
||||
Auth:
|
||||
provider: Auth.js (v5) / Clerk
|
||||
|
||||
Monorepo:
|
||||
tool: Turborepo 2.0
|
||||
```
|
||||
|
||||
## Alternative Options
|
||||
|
||||
| Need | Default | Alternative |
|
||||
|------|---------|-------------|
|
||||
| Real-time | - | Supabase Realtime, Socket.io |
|
||||
| File storage | - | Cloudinary, S3 |
|
||||
| Payment | Stripe | LemonSqueezy, Paddle |
|
||||
| Email | - | Resend, SendGrid |
|
||||
| Search | - | Algolia, Typesense |
|
||||
39
skills/app-builder/templates/SKILL.md
Normal file
39
skills/app-builder/templates/SKILL.md
Normal file
@@ -0,0 +1,39 @@
|
||||
---
|
||||
name: templates
|
||||
description: Project scaffolding templates for new applications. Use when creating new projects from scratch. Contains 12 templates for various tech stacks.
|
||||
allowed-tools: Read, Glob, Grep
|
||||
---
|
||||
|
||||
# Project Templates
|
||||
|
||||
> Quick-start templates for scaffolding new projects.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Selective Reading Rule
|
||||
|
||||
**Read ONLY the template matching user's project type!**
|
||||
|
||||
| Template | Tech Stack | When to Use |
|
||||
|----------|------------|-------------|
|
||||
| [nextjs-fullstack](nextjs-fullstack/TEMPLATE.md) | Next.js + Prisma | Full-stack web app |
|
||||
| [nextjs-saas](nextjs-saas/TEMPLATE.md) | Next.js + Stripe | SaaS product |
|
||||
| [nextjs-static](nextjs-static/TEMPLATE.md) | Next.js + Framer | Landing page |
|
||||
| [express-api](express-api/TEMPLATE.md) | Express + JWT | REST API |
|
||||
| [python-fastapi](python-fastapi/TEMPLATE.md) | FastAPI | Python API |
|
||||
| [react-native-app](react-native-app/TEMPLATE.md) | Expo + Zustand | Mobile app |
|
||||
| [flutter-app](flutter-app/TEMPLATE.md) | Flutter + Riverpod | Cross-platform |
|
||||
| [electron-desktop](electron-desktop/TEMPLATE.md) | Electron + React | Desktop app |
|
||||
| [chrome-extension](chrome-extension/TEMPLATE.md) | Chrome MV3 | Browser extension |
|
||||
| [cli-tool](cli-tool/TEMPLATE.md) | Node.js + Commander | CLI app |
|
||||
| [monorepo-turborepo](monorepo-turborepo/TEMPLATE.md) | Turborepo + pnpm | Monorepo |
|
||||
| [astro-static](astro-static/TEMPLATE.md) | Astro + MDX | Blog / Docs |
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
1. User says "create [type] app"
|
||||
2. Match to appropriate template
|
||||
3. Read ONLY that template's TEMPLATE.md
|
||||
4. Follow its tech stack and structure
|
||||
76
skills/app-builder/templates/astro-static/TEMPLATE.md
Normal file
76
skills/app-builder/templates/astro-static/TEMPLATE.md
Normal file
@@ -0,0 +1,76 @@
|
||||
---
|
||||
name: astro-static
|
||||
description: Astro static site template principles. Content-focused websites, blogs, documentation.
|
||||
---
|
||||
|
||||
# Astro Static Site Template
|
||||
|
||||
## Tech Stack
|
||||
|
||||
| Component | Technology |
|
||||
|-----------|------------|
|
||||
| Framework | Astro 4.x |
|
||||
| Content | MDX + Content Collections |
|
||||
| Styling | Tailwind CSS |
|
||||
| Integrations | Sitemap, RSS, SEO |
|
||||
| Output | Static/SSG |
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
project-name/
|
||||
├── src/
|
||||
│ ├── components/ # .astro components
|
||||
│ ├── content/ # MDX content
|
||||
│ │ ├── blog/
|
||||
│ │ └── config.ts # Collection schemas
|
||||
│ ├── layouts/ # Page layouts
|
||||
│ ├── pages/ # File-based routing
|
||||
│ └── styles/
|
||||
├── public/ # Static assets
|
||||
├── astro.config.mjs
|
||||
└── package.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Concepts
|
||||
|
||||
| Concept | Description |
|
||||
|---------|-------------|
|
||||
| Content Collections | Type-safe content with Zod schemas |
|
||||
| Islands Architecture | Partial hydration for interactivity |
|
||||
| Zero JS by default | Static HTML unless needed |
|
||||
| MDX Support | Markdown with components |
|
||||
|
||||
---
|
||||
|
||||
## Setup Steps
|
||||
|
||||
1. `npm create astro@latest {{name}}`
|
||||
2. Add integrations: `npx astro add mdx tailwind sitemap`
|
||||
3. Configure `astro.config.mjs`
|
||||
4. Create content collections
|
||||
5. `npm run dev`
|
||||
|
||||
---
|
||||
|
||||
## Deployment
|
||||
|
||||
| Platform | Method |
|
||||
|----------|--------|
|
||||
| Vercel | Auto-detected |
|
||||
| Netlify | Auto-detected |
|
||||
| Cloudflare Pages | Auto-detected |
|
||||
| GitHub Pages | Build + deploy action |
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Use Content Collections for type safety
|
||||
- Leverage static generation
|
||||
- Add islands only where needed
|
||||
- Optimize images with Astro Image
|
||||
92
skills/app-builder/templates/chrome-extension/TEMPLATE.md
Normal file
92
skills/app-builder/templates/chrome-extension/TEMPLATE.md
Normal file
@@ -0,0 +1,92 @@
|
||||
---
|
||||
name: chrome-extension
|
||||
description: Chrome Extension template principles. Manifest V3, React, TypeScript.
|
||||
---
|
||||
|
||||
# Chrome Extension Template
|
||||
|
||||
## Tech Stack
|
||||
|
||||
| Component | Technology |
|
||||
|-----------|------------|
|
||||
| Manifest | V3 |
|
||||
| UI | React 18 |
|
||||
| Language | TypeScript |
|
||||
| Styling | Tailwind CSS |
|
||||
| Bundler | Vite |
|
||||
| Storage | Chrome Storage API |
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
project-name/
|
||||
├── src/
|
||||
│ ├── popup/ # Extension popup
|
||||
│ ├── options/ # Options page
|
||||
│ ├── background/ # Service worker
|
||||
│ ├── content/ # Content scripts
|
||||
│ ├── components/
|
||||
│ ├── hooks/
|
||||
│ └── lib/
|
||||
│ ├── storage.ts # Chrome storage helpers
|
||||
│ └── messaging.ts # Message passing
|
||||
├── public/
|
||||
│ ├── icons/
|
||||
│ └── manifest.json
|
||||
└── package.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Manifest V3 Concepts
|
||||
|
||||
| Component | Purpose |
|
||||
|-----------|---------|
|
||||
| Service Worker | Background processing |
|
||||
| Content Scripts | Page injection |
|
||||
| Popup | User interface |
|
||||
| Options Page | Settings |
|
||||
|
||||
---
|
||||
|
||||
## Permissions
|
||||
|
||||
| Permission | Use |
|
||||
|------------|-----|
|
||||
| storage | Save user data |
|
||||
| activeTab | Current tab access |
|
||||
| scripting | Inject scripts |
|
||||
| host_permissions | Site access |
|
||||
|
||||
---
|
||||
|
||||
## Setup Steps
|
||||
|
||||
1. `npm create vite {{name}} -- --template react-ts`
|
||||
2. Add Chrome types: `npm install -D @types/chrome`
|
||||
3. Configure Vite for multi-entry
|
||||
4. Create manifest.json
|
||||
5. `npm run dev` (watch mode)
|
||||
6. Load in Chrome: `chrome://extensions` → Load unpacked
|
||||
|
||||
---
|
||||
|
||||
## Development Tips
|
||||
|
||||
| Task | Method |
|
||||
|------|--------|
|
||||
| Debug Popup | Right-click icon → Inspect |
|
||||
| Debug Background | Extensions page → Service worker |
|
||||
| Debug Content | DevTools console on page |
|
||||
| Hot Reload | `npm run dev` with watch |
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Use type-safe messaging
|
||||
- Wrap Chrome APIs in promises
|
||||
- Minimize permissions
|
||||
- Handle offline gracefully
|
||||
88
skills/app-builder/templates/cli-tool/TEMPLATE.md
Normal file
88
skills/app-builder/templates/cli-tool/TEMPLATE.md
Normal file
@@ -0,0 +1,88 @@
|
||||
---
|
||||
name: cli-tool
|
||||
description: Node.js CLI tool template principles. Commander.js, interactive prompts.
|
||||
---
|
||||
|
||||
# CLI Tool Template
|
||||
|
||||
## Tech Stack
|
||||
|
||||
| Component | Technology |
|
||||
|-----------|------------|
|
||||
| Runtime | Node.js 20+ |
|
||||
| Language | TypeScript |
|
||||
| CLI Framework | Commander.js |
|
||||
| Prompts | Inquirer.js |
|
||||
| Output | chalk + ora |
|
||||
| Config | cosmiconfig |
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
project-name/
|
||||
├── src/
|
||||
│ ├── index.ts # Entry point
|
||||
│ ├── cli.ts # CLI setup
|
||||
│ ├── commands/ # Command handlers
|
||||
│ ├── lib/
|
||||
│ │ ├── config.ts # Config loader
|
||||
│ │ └── logger.ts # Styled output
|
||||
│ └── types/
|
||||
├── bin/
|
||||
│ └── cli.js # Executable
|
||||
└── package.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CLI Design Principles
|
||||
|
||||
| Principle | Description |
|
||||
|-----------|-------------|
|
||||
| Subcommands | Group related actions |
|
||||
| Options | Flags with defaults |
|
||||
| Interactive | Prompts when needed |
|
||||
| Non-interactive | Support --yes flags |
|
||||
|
||||
---
|
||||
|
||||
## Key Components
|
||||
|
||||
| Component | Purpose |
|
||||
|-----------|---------|
|
||||
| Commander | Command parsing |
|
||||
| Inquirer | Interactive prompts |
|
||||
| Chalk | Colored output |
|
||||
| Ora | Spinners/loading |
|
||||
| Cosmiconfig | Config file discovery |
|
||||
|
||||
---
|
||||
|
||||
## Setup Steps
|
||||
|
||||
1. Create project directory
|
||||
2. `npm init -y`
|
||||
3. Install deps: `npm install commander @inquirer/prompts chalk ora cosmiconfig`
|
||||
4. Configure bin in package.json
|
||||
5. `npm link` for local testing
|
||||
|
||||
---
|
||||
|
||||
## Publishing
|
||||
|
||||
```bash
|
||||
npm login
|
||||
npm publish
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Provide helpful error messages
|
||||
- Support both interactive and non-interactive modes
|
||||
- Use consistent output styling
|
||||
- Validate inputs with Zod
|
||||
- Exit with proper codes (0 success, 1 error)
|
||||
88
skills/app-builder/templates/electron-desktop/TEMPLATE.md
Normal file
88
skills/app-builder/templates/electron-desktop/TEMPLATE.md
Normal file
@@ -0,0 +1,88 @@
|
||||
---
|
||||
name: electron-desktop
|
||||
description: Electron desktop app template principles. Cross-platform, React, TypeScript.
|
||||
---
|
||||
|
||||
# Electron Desktop App Template
|
||||
|
||||
## Tech Stack
|
||||
|
||||
| Component | Technology |
|
||||
|-----------|------------|
|
||||
| Framework | Electron 28+ |
|
||||
| UI | React 18 |
|
||||
| Language | TypeScript |
|
||||
| Styling | Tailwind CSS |
|
||||
| Bundler | Vite + electron-builder |
|
||||
| IPC | Type-safe communication |
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
project-name/
|
||||
├── electron/
|
||||
│ ├── main.ts # Main process
|
||||
│ ├── preload.ts # Preload script
|
||||
│ └── ipc/ # IPC handlers
|
||||
├── src/
|
||||
│ ├── App.tsx
|
||||
│ ├── components/
|
||||
│ │ ├── TitleBar.tsx # Custom title bar
|
||||
│ │ └── ...
|
||||
│ └── hooks/
|
||||
├── public/
|
||||
└── package.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Process Model
|
||||
|
||||
| Process | Role |
|
||||
|---------|------|
|
||||
| Main | Node.js, system access |
|
||||
| Renderer | Chromium, React UI |
|
||||
| Preload | Bridge, context isolation |
|
||||
|
||||
---
|
||||
|
||||
## Key Concepts
|
||||
|
||||
| Concept | Purpose |
|
||||
|---------|---------|
|
||||
| contextBridge | Safe API exposure |
|
||||
| ipcMain/ipcRenderer | Process communication |
|
||||
| nodeIntegration: false | Security |
|
||||
| contextIsolation: true | Security |
|
||||
|
||||
---
|
||||
|
||||
## Setup Steps
|
||||
|
||||
1. `npm create vite {{name}} -- --template react-ts`
|
||||
2. Install: `npm install -D electron electron-builder vite-plugin-electron`
|
||||
3. Create electron/ directory
|
||||
4. Configure main process
|
||||
5. `npm run electron:dev`
|
||||
|
||||
---
|
||||
|
||||
## Build Targets
|
||||
|
||||
| Platform | Output |
|
||||
|----------|--------|
|
||||
| Windows | NSIS, Portable |
|
||||
| macOS | DMG, ZIP |
|
||||
| Linux | AppImage, DEB |
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Use preload script for main/renderer bridge
|
||||
- Type-safe IPC with typed handlers
|
||||
- Custom title bar for native feel
|
||||
- Handle window state (maximize, minimize)
|
||||
- Auto-updates with electron-updater
|
||||
83
skills/app-builder/templates/express-api/TEMPLATE.md
Normal file
83
skills/app-builder/templates/express-api/TEMPLATE.md
Normal file
@@ -0,0 +1,83 @@
|
||||
---
|
||||
name: express-api
|
||||
description: Express.js REST API template principles. TypeScript, Prisma, JWT.
|
||||
---
|
||||
|
||||
# Express.js API Template
|
||||
|
||||
## Tech Stack
|
||||
|
||||
| Component | Technology |
|
||||
|-----------|------------|
|
||||
| Runtime | Node.js 20+ |
|
||||
| Framework | Express.js |
|
||||
| Language | TypeScript |
|
||||
| Database | PostgreSQL + Prisma |
|
||||
| Validation | Zod |
|
||||
| Auth | JWT + bcrypt |
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
project-name/
|
||||
├── prisma/
|
||||
│ └── schema.prisma
|
||||
├── src/
|
||||
│ ├── app.ts # Express setup
|
||||
│ ├── config/ # Environment
|
||||
│ ├── routes/ # Route handlers
|
||||
│ ├── controllers/ # Business logic
|
||||
│ ├── services/ # Data access
|
||||
│ ├── middleware/
|
||||
│ │ ├── auth.ts # JWT verify
|
||||
│ │ ├── error.ts # Error handler
|
||||
│ │ └── validate.ts # Zod validation
|
||||
│ ├── schemas/ # Zod schemas
|
||||
│ └── utils/
|
||||
└── package.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Middleware Stack
|
||||
|
||||
| Order | Middleware |
|
||||
|-------|------------|
|
||||
| 1 | helmet (security) |
|
||||
| 2 | cors |
|
||||
| 3 | morgan (logging) |
|
||||
| 4 | body parsing |
|
||||
| 5 | routes |
|
||||
| 6 | error handler |
|
||||
|
||||
---
|
||||
|
||||
## API Response Format
|
||||
|
||||
| Type | Structure |
|
||||
|------|-----------|
|
||||
| Success | `{ success: true, data: {...} }` |
|
||||
| Error | `{ error: "message", details: [...] }` |
|
||||
|
||||
---
|
||||
|
||||
## Setup Steps
|
||||
|
||||
1. Create project directory
|
||||
2. `npm init -y`
|
||||
3. Install deps: `npm install express prisma zod bcrypt jsonwebtoken`
|
||||
4. Configure Prisma
|
||||
5. `npm run db:push`
|
||||
6. `npm run dev`
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Layer architecture (routes → controllers → services)
|
||||
- Validate all inputs with Zod
|
||||
- Centralized error handling
|
||||
- Environment-based config
|
||||
- Use Prisma for type-safe DB access
|
||||
90
skills/app-builder/templates/flutter-app/TEMPLATE.md
Normal file
90
skills/app-builder/templates/flutter-app/TEMPLATE.md
Normal file
@@ -0,0 +1,90 @@
|
||||
---
|
||||
name: flutter-app
|
||||
description: Flutter mobile app template principles. Riverpod, Go Router, clean architecture.
|
||||
---
|
||||
|
||||
# Flutter App Template
|
||||
|
||||
## Tech Stack
|
||||
|
||||
| Component | Technology |
|
||||
|-----------|------------|
|
||||
| Framework | Flutter 3.x |
|
||||
| Language | Dart 3.x |
|
||||
| State | Riverpod 2.0 |
|
||||
| Navigation | Go Router |
|
||||
| HTTP | Dio |
|
||||
| Storage | Hive |
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
project_name/
|
||||
├── lib/
|
||||
│ ├── main.dart
|
||||
│ ├── app.dart
|
||||
│ ├── core/
|
||||
│ │ ├── constants/
|
||||
│ │ ├── theme/
|
||||
│ │ ├── router/
|
||||
│ │ └── utils/
|
||||
│ ├── features/
|
||||
│ │ ├── auth/
|
||||
│ │ │ ├── data/
|
||||
│ │ │ ├── domain/
|
||||
│ │ │ └── presentation/
|
||||
│ │ └── home/
|
||||
│ ├── shared/
|
||||
│ │ ├── widgets/
|
||||
│ │ └── providers/
|
||||
│ └── services/
|
||||
│ ├── api/
|
||||
│ └── storage/
|
||||
├── test/
|
||||
└── pubspec.yaml
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Architecture Layers
|
||||
|
||||
| Layer | Contents |
|
||||
|-------|----------|
|
||||
| Presentation | Screens, Widgets, Providers |
|
||||
| Domain | Entities, Use Cases |
|
||||
| Data | Repositories, Models |
|
||||
|
||||
---
|
||||
|
||||
## Key Packages
|
||||
|
||||
| Package | Purpose |
|
||||
|---------|---------|
|
||||
| flutter_riverpod | State management |
|
||||
| riverpod_annotation | Code generation |
|
||||
| go_router | Navigation |
|
||||
| dio | HTTP client |
|
||||
| freezed | Immutable models |
|
||||
| hive | Local storage |
|
||||
|
||||
---
|
||||
|
||||
## Setup Steps
|
||||
|
||||
1. `flutter create {{name}} --org com.{{bundle}}`
|
||||
2. Update `pubspec.yaml`
|
||||
3. `flutter pub get`
|
||||
4. Run code generation: `dart run build_runner build`
|
||||
5. `flutter run`
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Feature-first folder structure
|
||||
- Riverpod for state, React Query pattern for server state
|
||||
- Freezed for immutable data classes
|
||||
- Go Router for declarative navigation
|
||||
- Material 3 theming
|
||||
90
skills/app-builder/templates/monorepo-turborepo/TEMPLATE.md
Normal file
90
skills/app-builder/templates/monorepo-turborepo/TEMPLATE.md
Normal file
@@ -0,0 +1,90 @@
|
||||
---
|
||||
name: monorepo-turborepo
|
||||
description: Turborepo monorepo template principles. pnpm workspaces, shared packages.
|
||||
---
|
||||
|
||||
# Turborepo Monorepo Template
|
||||
|
||||
## Tech Stack
|
||||
|
||||
| Component | Technology |
|
||||
|-----------|------------|
|
||||
| Build System | Turborepo |
|
||||
| Package Manager | pnpm |
|
||||
| Apps | Next.js, Express |
|
||||
| Packages | Shared UI, Config, Types |
|
||||
| Language | TypeScript |
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
project-name/
|
||||
├── apps/
|
||||
│ ├── web/ # Next.js app
|
||||
│ ├── api/ # Express API
|
||||
│ └── docs/ # Documentation
|
||||
├── packages/
|
||||
│ ├── ui/ # Shared components
|
||||
│ ├── config/ # ESLint, TS, Tailwind
|
||||
│ ├── types/ # Shared types
|
||||
│ └── utils/ # Shared utilities
|
||||
├── turbo.json
|
||||
├── pnpm-workspace.yaml
|
||||
└── package.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Concepts
|
||||
|
||||
| Concept | Description |
|
||||
|---------|-------------|
|
||||
| Workspaces | pnpm-workspace.yaml |
|
||||
| Pipeline | turbo.json task graph |
|
||||
| Caching | Remote/local task caching |
|
||||
| Dependencies | `workspace:*` protocol |
|
||||
|
||||
---
|
||||
|
||||
## Turbo Pipeline
|
||||
|
||||
| Task | Depends On |
|
||||
|------|------------|
|
||||
| build | ^build (dependencies first) |
|
||||
| dev | cache: false, persistent |
|
||||
| lint | ^build |
|
||||
| test | ^build |
|
||||
|
||||
---
|
||||
|
||||
## Setup Steps
|
||||
|
||||
1. Create root directory
|
||||
2. `pnpm init`
|
||||
3. Create pnpm-workspace.yaml
|
||||
4. Create turbo.json
|
||||
5. Add apps and packages
|
||||
6. `pnpm install`
|
||||
7. `pnpm dev`
|
||||
|
||||
---
|
||||
|
||||
## Common Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `pnpm dev` | Run all apps |
|
||||
| `pnpm build` | Build all |
|
||||
| `pnpm --filter @name/web dev` | Run specific app |
|
||||
| `pnpm --filter @name/web add axios` | Add dep to app |
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Shared configs in packages/config
|
||||
- Shared types in packages/types
|
||||
- Internal packages with `workspace:*`
|
||||
- Use Turbo remote caching for CI
|
||||
82
skills/app-builder/templates/nextjs-fullstack/TEMPLATE.md
Normal file
82
skills/app-builder/templates/nextjs-fullstack/TEMPLATE.md
Normal file
@@ -0,0 +1,82 @@
|
||||
---
|
||||
name: nextjs-fullstack
|
||||
description: Next.js full-stack template principles. App Router, Prisma, Tailwind.
|
||||
---
|
||||
|
||||
# Next.js Full-Stack Template
|
||||
|
||||
## Tech Stack
|
||||
|
||||
| Component | Technology |
|
||||
|-----------|------------|
|
||||
| Framework | Next.js 14 (App Router) |
|
||||
| Language | TypeScript |
|
||||
| Database | PostgreSQL + Prisma |
|
||||
| Styling | Tailwind CSS |
|
||||
| Auth | Clerk (optional) |
|
||||
| Validation | Zod |
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
project-name/
|
||||
├── prisma/
|
||||
│ └── schema.prisma
|
||||
├── src/
|
||||
│ ├── app/
|
||||
│ │ ├── layout.tsx
|
||||
│ │ ├── page.tsx
|
||||
│ │ ├── globals.css
|
||||
│ │ └── api/
|
||||
│ ├── components/
|
||||
│ │ └── ui/
|
||||
│ ├── lib/
|
||||
│ │ ├── db.ts # Prisma client
|
||||
│ │ └── utils.ts
|
||||
│ └── types/
|
||||
├── .env.example
|
||||
└── package.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Concepts
|
||||
|
||||
| Concept | Description |
|
||||
|---------|-------------|
|
||||
| Server Components | Default, fetch data |
|
||||
| Server Actions | Form mutations |
|
||||
| Route Handlers | API endpoints |
|
||||
| Prisma | Type-safe ORM |
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Purpose |
|
||||
|----------|---------|
|
||||
| DATABASE_URL | Prisma connection |
|
||||
| NEXT_PUBLIC_APP_URL | Public URL |
|
||||
|
||||
---
|
||||
|
||||
## Setup Steps
|
||||
|
||||
1. `npx create-next-app {{name}} --typescript --tailwind --app`
|
||||
2. `npm install prisma @prisma/client zod`
|
||||
3. `npx prisma init`
|
||||
4. Configure schema
|
||||
5. `npm run db:push`
|
||||
6. `npm run dev`
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Server Components by default
|
||||
- Server Actions for mutations
|
||||
- Prisma for type-safe DB
|
||||
- Zod for validation
|
||||
- Edge runtime where possible
|
||||
100
skills/app-builder/templates/nextjs-saas/TEMPLATE.md
Normal file
100
skills/app-builder/templates/nextjs-saas/TEMPLATE.md
Normal file
@@ -0,0 +1,100 @@
|
||||
---
|
||||
name: nextjs-saas
|
||||
description: Next.js SaaS template principles. Auth, payments, email.
|
||||
---
|
||||
|
||||
# Next.js SaaS Template
|
||||
|
||||
## Tech Stack
|
||||
|
||||
| Component | Technology |
|
||||
|-----------|------------|
|
||||
| Framework | Next.js 14 (App Router) |
|
||||
| Auth | NextAuth.js v5 |
|
||||
| Payments | Stripe |
|
||||
| Database | PostgreSQL + Prisma |
|
||||
| Email | Resend |
|
||||
| UI | Tailwind (ASK USER: shadcn/Headless UI/Custom?) |
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
project-name/
|
||||
├── prisma/
|
||||
├── src/
|
||||
│ ├── app/
|
||||
│ │ ├── (auth)/ # Login, register
|
||||
│ │ ├── (dashboard)/ # Protected routes
|
||||
│ │ ├── (marketing)/ # Landing, pricing
|
||||
│ │ └── api/
|
||||
│ │ ├── auth/[...nextauth]/
|
||||
│ │ └── webhooks/stripe/
|
||||
│ ├── components/
|
||||
│ │ ├── auth/
|
||||
│ │ ├── billing/
|
||||
│ │ └── dashboard/
|
||||
│ ├── lib/
|
||||
│ │ ├── auth.ts # NextAuth config
|
||||
│ │ ├── stripe.ts # Stripe client
|
||||
│ │ └── email.ts # Resend client
|
||||
│ └── config/
|
||||
│ └── subscriptions.ts
|
||||
└── package.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## SaaS Features
|
||||
|
||||
| Feature | Implementation |
|
||||
|---------|---------------|
|
||||
| Auth | NextAuth + OAuth |
|
||||
| Subscriptions | Stripe Checkout |
|
||||
| Billing Portal | Stripe Portal |
|
||||
| Webhooks | Stripe events |
|
||||
| Email | Transactional via Resend |
|
||||
|
||||
---
|
||||
|
||||
## Database Schema
|
||||
|
||||
| Model | Fields |
|
||||
|-------|--------|
|
||||
| User | id, email, stripeCustomerId, subscriptionId |
|
||||
| Account | OAuth provider data |
|
||||
| Session | User sessions |
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Purpose |
|
||||
|----------|---------|
|
||||
| DATABASE_URL | Prisma |
|
||||
| NEXTAUTH_SECRET | Auth |
|
||||
| STRIPE_SECRET_KEY | Payments |
|
||||
| STRIPE_WEBHOOK_SECRET | Webhooks |
|
||||
| RESEND_API_KEY | Email |
|
||||
|
||||
---
|
||||
|
||||
## Setup Steps
|
||||
|
||||
1. `npx create-next-app {{name}} --typescript --tailwind --app`
|
||||
2. Install: `npm install next-auth @auth/prisma-adapter stripe resend`
|
||||
3. Setup Stripe products/prices
|
||||
4. Configure environment
|
||||
5. `npm run db:push`
|
||||
6. `npm run stripe:listen` (webhooks)
|
||||
7. `npm run dev`
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Route groups for layout separation
|
||||
- Stripe webhooks for subscription sync
|
||||
- NextAuth with Prisma adapter
|
||||
- Email templates with React Email
|
||||
106
skills/app-builder/templates/nextjs-static/TEMPLATE.md
Normal file
106
skills/app-builder/templates/nextjs-static/TEMPLATE.md
Normal file
@@ -0,0 +1,106 @@
|
||||
---
|
||||
name: nextjs-static
|
||||
description: Next.js static site template principles. Landing pages, portfolios, marketing.
|
||||
---
|
||||
|
||||
# Next.js Static Site Template
|
||||
|
||||
## Tech Stack
|
||||
|
||||
| Component | Technology |
|
||||
|-----------|------------|
|
||||
| Framework | Next.js 14 (Static Export) |
|
||||
| Language | TypeScript |
|
||||
| Styling | Tailwind CSS |
|
||||
| Animations | Framer Motion |
|
||||
| Icons | Lucide React |
|
||||
| SEO | Next SEO |
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
project-name/
|
||||
├── src/
|
||||
│ ├── app/
|
||||
│ │ ├── layout.tsx
|
||||
│ │ ├── page.tsx # Landing
|
||||
│ │ ├── about/
|
||||
│ │ ├── contact/
|
||||
│ │ └── blog/
|
||||
│ ├── components/
|
||||
│ │ ├── layout/ # Header, Footer
|
||||
│ │ ├── sections/ # Hero, Features, CTA
|
||||
│ │ └── ui/
|
||||
│ └── lib/
|
||||
├── content/ # Markdown content
|
||||
├── public/
|
||||
└── next.config.js
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Static Export Config
|
||||
|
||||
```javascript
|
||||
// next.config.js
|
||||
const nextConfig = {
|
||||
output: 'export',
|
||||
images: { unoptimized: true },
|
||||
trailingSlash: true,
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Landing Page Sections
|
||||
|
||||
| Section | Purpose |
|
||||
|---------|---------|
|
||||
| Hero | Main headline, CTA |
|
||||
| Features | Product benefits |
|
||||
| Testimonials | Social proof |
|
||||
| Pricing | Plans |
|
||||
| CTA | Final conversion |
|
||||
|
||||
---
|
||||
|
||||
## Animation Patterns
|
||||
|
||||
| Pattern | Use |
|
||||
|---------|-----|
|
||||
| Fade up | Content entry |
|
||||
| Stagger | List items |
|
||||
| Scroll reveal | On viewport |
|
||||
| Hover | Interactive feedback |
|
||||
|
||||
---
|
||||
|
||||
## Setup Steps
|
||||
|
||||
1. `npx create-next-app {{name}} --typescript --tailwind --app`
|
||||
2. Install: `npm install framer-motion lucide-react next-seo`
|
||||
3. Configure static export
|
||||
4. Create sections
|
||||
5. `npm run dev`
|
||||
|
||||
---
|
||||
|
||||
## Deployment
|
||||
|
||||
| Platform | Method |
|
||||
|----------|--------|
|
||||
| Vercel | Auto |
|
||||
| Netlify | Auto |
|
||||
| GitHub Pages | gh-pages branch |
|
||||
| Any host | Upload `out` folder |
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Static export for maximum performance
|
||||
- Framer Motion for premium animations
|
||||
- Responsive mobile-first design
|
||||
- SEO metadata on every page
|
||||
101
skills/app-builder/templates/nuxt-app/TEMPLATE.md
Normal file
101
skills/app-builder/templates/nuxt-app/TEMPLATE.md
Normal file
@@ -0,0 +1,101 @@
|
||||
---
|
||||
name: nuxt-app
|
||||
description: Nuxt 3 full-stack template. Vue 3, Pinia, Tailwind, Prisma.
|
||||
---
|
||||
|
||||
# Nuxt 3 Full-Stack Template
|
||||
|
||||
## Tech Stack
|
||||
|
||||
| Component | Technology |
|
||||
|-----------|------------|
|
||||
| Framework | Nuxt 3 |
|
||||
| Language | TypeScript |
|
||||
| UI | Vue 3 (Composition API) |
|
||||
| State | Pinia |
|
||||
| Database | PostgreSQL + Prisma |
|
||||
| Styling | Tailwind CSS |
|
||||
| Validation | Zod |
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
project-name/
|
||||
├── prisma/
|
||||
│ └── schema.prisma
|
||||
├── server/
|
||||
│ ├── api/
|
||||
│ │ └── [resource]/
|
||||
│ │ └── index.ts
|
||||
│ └── utils/
|
||||
│ └── db.ts # Prisma client
|
||||
├── composables/
|
||||
│ └── useAuth.ts
|
||||
├── stores/
|
||||
│ └── user.ts # Pinia store
|
||||
├── components/
|
||||
│ └── ui/
|
||||
├── pages/
|
||||
│ ├── index.vue
|
||||
│ └── [...slug].vue
|
||||
├── layouts/
|
||||
│ └── default.vue
|
||||
├── assets/
|
||||
│ └── css/
|
||||
│ └── main.css
|
||||
├── .env.example
|
||||
├── nuxt.config.ts
|
||||
└── package.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Concepts
|
||||
|
||||
| Concept | Description |
|
||||
|---------|-------------|
|
||||
| Auto-imports | Components, composables, utils |
|
||||
| File-based routing | pages/ → routes |
|
||||
| Server Routes | server/api/ → API endpoints |
|
||||
| Composables | Reusable reactive logic |
|
||||
| Pinia | State management |
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Purpose |
|
||||
|----------|---------|
|
||||
| DATABASE_URL | Prisma connection |
|
||||
| NUXT_PUBLIC_APP_URL | Public URL |
|
||||
|
||||
---
|
||||
|
||||
## Setup Steps
|
||||
|
||||
1. `npx nuxi@latest init {{name}}`
|
||||
2. `cd {{name}}`
|
||||
3. `npm install @pinia/nuxt @prisma/client prisma zod`
|
||||
4. `npm install -D @nuxtjs/tailwindcss`
|
||||
5. Add modules to `nuxt.config.ts`:
|
||||
```ts
|
||||
modules: ['@pinia/nuxt', '@nuxtjs/tailwindcss']
|
||||
```
|
||||
6. `npx prisma init`
|
||||
7. Configure schema
|
||||
8. `npx prisma db push`
|
||||
9. `npm run dev`
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Use `<script setup>` for components
|
||||
- Composables for reusable logic
|
||||
- Pinia stores in `stores/` folder
|
||||
- Server routes for API logic
|
||||
- Auto-import for clean code
|
||||
- TypeScript for type safety
|
||||
- See `@[skills/vue-expert]` for Vue patterns
|
||||
83
skills/app-builder/templates/python-fastapi/TEMPLATE.md
Normal file
83
skills/app-builder/templates/python-fastapi/TEMPLATE.md
Normal file
@@ -0,0 +1,83 @@
|
||||
---
|
||||
name: python-fastapi
|
||||
description: FastAPI REST API template principles. SQLAlchemy, Pydantic, Alembic.
|
||||
---
|
||||
|
||||
# FastAPI API Template
|
||||
|
||||
## Tech Stack
|
||||
|
||||
| Component | Technology |
|
||||
|-----------|------------|
|
||||
| Framework | FastAPI |
|
||||
| Language | Python 3.11+ |
|
||||
| ORM | SQLAlchemy 2.0 |
|
||||
| Validation | Pydantic v2 |
|
||||
| Migrations | Alembic |
|
||||
| Auth | JWT + passlib |
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
project-name/
|
||||
├── alembic/ # Migrations
|
||||
├── app/
|
||||
│ ├── main.py # FastAPI app
|
||||
│ ├── config.py # Settings
|
||||
│ ├── database.py # DB connection
|
||||
│ ├── models/ # SQLAlchemy models
|
||||
│ ├── schemas/ # Pydantic schemas
|
||||
│ ├── routers/ # API routes
|
||||
│ ├── services/ # Business logic
|
||||
│ ├── dependencies/ # DI
|
||||
│ └── utils/
|
||||
├── tests/
|
||||
├── .env.example
|
||||
└── requirements.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Concepts
|
||||
|
||||
| Concept | Description |
|
||||
|---------|-------------|
|
||||
| Async | async/await throughout |
|
||||
| Dependency Injection | FastAPI Depends |
|
||||
| Pydantic v2 | Validation + serialization |
|
||||
| SQLAlchemy 2.0 | Async sessions |
|
||||
|
||||
---
|
||||
|
||||
## API Structure
|
||||
|
||||
| Layer | Responsibility |
|
||||
|-------|---------------|
|
||||
| Routers | HTTP handling |
|
||||
| Dependencies | Auth, validation |
|
||||
| Services | Business logic |
|
||||
| Models | Database entities |
|
||||
| Schemas | Request/response |
|
||||
|
||||
---
|
||||
|
||||
## Setup Steps
|
||||
|
||||
1. `python -m venv venv`
|
||||
2. `source venv/bin/activate`
|
||||
3. `pip install fastapi uvicorn sqlalchemy alembic pydantic`
|
||||
4. Create `.env`
|
||||
5. `alembic upgrade head`
|
||||
6. `uvicorn app.main:app --reload`
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Use async everywhere
|
||||
- Pydantic v2 for validation
|
||||
- SQLAlchemy 2.0 async sessions
|
||||
- Alembic for migrations
|
||||
- pytest-asyncio for tests
|
||||
93
skills/app-builder/templates/react-native-app/TEMPLATE.md
Normal file
93
skills/app-builder/templates/react-native-app/TEMPLATE.md
Normal file
@@ -0,0 +1,93 @@
|
||||
---
|
||||
name: react-native-app
|
||||
description: React Native mobile app template principles. Expo, TypeScript, navigation.
|
||||
---
|
||||
|
||||
# React Native App Template
|
||||
|
||||
## Tech Stack
|
||||
|
||||
| Component | Technology |
|
||||
|-----------|------------|
|
||||
| Framework | React Native + Expo |
|
||||
| Language | TypeScript |
|
||||
| Navigation | Expo Router |
|
||||
| State | Zustand + React Query |
|
||||
| Styling | NativeWind |
|
||||
| Testing | Jest + RNTL |
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
project-name/
|
||||
├── app/ # Expo Router (file-based)
|
||||
│ ├── _layout.tsx # Root layout
|
||||
│ ├── index.tsx # Home
|
||||
│ ├── (tabs)/ # Tab navigation
|
||||
│ └── [id].tsx # Dynamic route
|
||||
├── components/
|
||||
│ ├── ui/ # Reusable
|
||||
│ └── features/
|
||||
├── hooks/
|
||||
├── lib/
|
||||
│ ├── api.ts
|
||||
│ └── storage.ts
|
||||
├── store/
|
||||
├── constants/
|
||||
└── app.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Navigation Patterns
|
||||
|
||||
| Pattern | Use |
|
||||
|---------|-----|
|
||||
| Stack | Page hierarchy |
|
||||
| Tabs | Bottom navigation |
|
||||
| Drawer | Side menu |
|
||||
| Modal | Overlay screens |
|
||||
|
||||
---
|
||||
|
||||
## State Management
|
||||
|
||||
| Type | Tool |
|
||||
|------|------|
|
||||
| Local | Zustand |
|
||||
| Server | React Query |
|
||||
| Forms | React Hook Form |
|
||||
| Storage | Expo SecureStore |
|
||||
|
||||
---
|
||||
|
||||
## Key Packages
|
||||
|
||||
| Package | Purpose |
|
||||
|---------|---------|
|
||||
| expo-router | File-based routing |
|
||||
| zustand | Local state |
|
||||
| @tanstack/react-query | Server state |
|
||||
| nativewind | Tailwind styling |
|
||||
| expo-secure-store | Secure storage |
|
||||
|
||||
---
|
||||
|
||||
## Setup Steps
|
||||
|
||||
1. `npx create-expo-app {{name}} -t expo-template-blank-typescript`
|
||||
2. `npx expo install expo-router react-native-safe-area-context`
|
||||
3. Install state: `npm install zustand @tanstack/react-query`
|
||||
4. `npx expo start`
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Expo Router for navigation
|
||||
- Zustand for local, React Query for server state
|
||||
- NativeWind for consistent styling
|
||||
- Expo SecureStore for tokens
|
||||
- Test on both iOS and Android
|
||||
55
skills/architecture/SKILL.md
Normal file
55
skills/architecture/SKILL.md
Normal file
@@ -0,0 +1,55 @@
|
||||
---
|
||||
name: architecture
|
||||
description: Architectural decision-making framework. Requirements analysis, trade-off evaluation, ADR documentation. Use when making architecture decisions or analyzing system design.
|
||||
allowed-tools: Read, Glob, Grep
|
||||
---
|
||||
|
||||
# Architecture Decision Framework
|
||||
|
||||
> "Requirements drive architecture. Trade-offs inform decisions. ADRs capture rationale."
|
||||
|
||||
## 🎯 Selective Reading Rule
|
||||
|
||||
**Read ONLY files relevant to the request!** Check the content map, find what you need.
|
||||
|
||||
| File | Description | When to Read |
|
||||
|------|-------------|--------------|
|
||||
| `context-discovery.md` | Questions to ask, project classification | Starting architecture design |
|
||||
| `trade-off-analysis.md` | ADR templates, trade-off framework | Documenting decisions |
|
||||
| `pattern-selection.md` | Decision trees, anti-patterns | Choosing patterns |
|
||||
| `examples.md` | MVP, SaaS, Enterprise examples | Reference implementations |
|
||||
| `patterns-reference.md` | Quick lookup for patterns | Pattern comparison |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Related Skills
|
||||
|
||||
| Skill | Use For |
|
||||
|-------|---------|
|
||||
| `@[skills/database-design]` | Database schema design |
|
||||
| `@[skills/api-patterns]` | API design patterns |
|
||||
| `@[skills/deployment-procedures]` | Deployment architecture |
|
||||
|
||||
---
|
||||
|
||||
## Core Principle
|
||||
|
||||
**"Simplicity is the ultimate sophistication."**
|
||||
|
||||
- Start simple
|
||||
- Add complexity ONLY when proven necessary
|
||||
- You can always add patterns later
|
||||
- Removing complexity is MUCH harder than adding it
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
Before finalizing architecture:
|
||||
|
||||
- [ ] Requirements clearly understood
|
||||
- [ ] Constraints identified
|
||||
- [ ] Each decision has trade-off analysis
|
||||
- [ ] Simpler alternatives considered
|
||||
- [ ] ADRs written for significant decisions
|
||||
- [ ] Team expertise matches chosen patterns
|
||||
43
skills/architecture/context-discovery.md
Normal file
43
skills/architecture/context-discovery.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# Context Discovery
|
||||
|
||||
> Before suggesting any architecture, gather context.
|
||||
|
||||
## Question Hierarchy (Ask User FIRST)
|
||||
|
||||
1. **Scale**
|
||||
- How many users? (10, 1K, 100K, 1M+)
|
||||
- Data volume? (MB, GB, TB)
|
||||
- Transaction rate? (per second/minute)
|
||||
|
||||
2. **Team**
|
||||
- Solo developer or team?
|
||||
- Team size and expertise?
|
||||
- Distributed or co-located?
|
||||
|
||||
3. **Timeline**
|
||||
- MVP/Prototype or long-term product?
|
||||
- Time to market pressure?
|
||||
|
||||
4. **Domain**
|
||||
- CRUD-heavy or business logic complex?
|
||||
- Real-time requirements?
|
||||
- Compliance/regulations?
|
||||
|
||||
5. **Constraints**
|
||||
- Budget limitations?
|
||||
- Legacy systems to integrate?
|
||||
- Technology stack preferences?
|
||||
|
||||
## Project Classification Matrix
|
||||
|
||||
```
|
||||
MVP SaaS Enterprise
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Scale │ <1K │ 1K-100K │ 100K+ │
|
||||
│ Team │ Solo │ 2-10 │ 10+ │
|
||||
│ Timeline │ Fast (weeks) │ Medium (months)│ Long (years)│
|
||||
│ Architecture │ Simple │ Modular │ Distributed │
|
||||
│ Patterns │ Minimal │ Selective │ Comprehensive│
|
||||
│ Example │ Next.js API │ NestJS │ Microservices│
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
94
skills/architecture/examples.md
Normal file
94
skills/architecture/examples.md
Normal file
@@ -0,0 +1,94 @@
|
||||
# Architecture Examples
|
||||
|
||||
> Real-world architecture decisions by project type.
|
||||
|
||||
---
|
||||
|
||||
## Example 1: MVP E-commerce (Solo Developer)
|
||||
|
||||
```yaml
|
||||
Requirements:
|
||||
- <1000 users initially
|
||||
- Solo developer
|
||||
- Fast to market (8 weeks)
|
||||
- Budget-conscious
|
||||
|
||||
Architecture Decisions:
|
||||
App Structure: Monolith (simpler for solo)
|
||||
Framework: Next.js (full-stack, fast)
|
||||
Data Layer: Prisma direct (no over-abstraction)
|
||||
Authentication: JWT (simpler than OAuth)
|
||||
Payment: Stripe (hosted solution)
|
||||
Database: PostgreSQL (ACID for orders)
|
||||
|
||||
Trade-offs Accepted:
|
||||
- Monolith → Can't scale independently (team doesn't justify it)
|
||||
- No Repository → Less testable (simple CRUD doesn't need it)
|
||||
- JWT → No social login initially (can add later)
|
||||
|
||||
Future Migration Path:
|
||||
- Users > 10K → Extract payment service
|
||||
- Team > 3 → Add Repository pattern
|
||||
- Social login requested → Add OAuth
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example 2: SaaS Product (5-10 Developers)
|
||||
|
||||
```yaml
|
||||
Requirements:
|
||||
- 1K-100K users
|
||||
- 5-10 developers
|
||||
- Long-term (12+ months)
|
||||
- Multiple domains (billing, users, core)
|
||||
|
||||
Architecture Decisions:
|
||||
App Structure: Modular Monolith (team size optimal)
|
||||
Framework: NestJS (modular by design)
|
||||
Data Layer: Repository pattern (testing, flexibility)
|
||||
Domain Model: Partial DDD (rich entities)
|
||||
Authentication: OAuth + JWT
|
||||
Caching: Redis
|
||||
Database: PostgreSQL
|
||||
|
||||
Trade-offs Accepted:
|
||||
- Modular Monolith → Some module coupling (microservices not justified)
|
||||
- Partial DDD → No full aggregates (no domain experts)
|
||||
- RabbitMQ later → Initial synchronous (add when proven needed)
|
||||
|
||||
Migration Path:
|
||||
- Team > 10 → Consider microservices
|
||||
- Domains conflict → Extract bounded contexts
|
||||
- Read performance issues → Add CQRS
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example 3: Enterprise (100K+ Users)
|
||||
|
||||
```yaml
|
||||
Requirements:
|
||||
- 100K+ users
|
||||
- 10+ developers
|
||||
- Multiple business domains
|
||||
- Different scaling needs
|
||||
- 24/7 availability
|
||||
|
||||
Architecture Decisions:
|
||||
App Structure: Microservices (independent scale)
|
||||
API Gateway: Kong/AWS API GW
|
||||
Domain Model: Full DDD
|
||||
Consistency: Event-driven (eventual OK)
|
||||
Message Bus: Kafka
|
||||
Authentication: OAuth + SAML (enterprise SSO)
|
||||
Database: Polyglot (right tool per job)
|
||||
CQRS: Selected services
|
||||
|
||||
Operational Requirements:
|
||||
- Service mesh (Istio/Linkerd)
|
||||
- Distributed tracing (Jaeger/Tempo)
|
||||
- Centralized logging (ELK/Loki)
|
||||
- Circuit breakers (Resilience4j)
|
||||
- Kubernetes/Helm
|
||||
```
|
||||
68
skills/architecture/pattern-selection.md
Normal file
68
skills/architecture/pattern-selection.md
Normal file
@@ -0,0 +1,68 @@
|
||||
# Pattern Selection Guidelines
|
||||
|
||||
> Decision trees for choosing architectural patterns.
|
||||
|
||||
## Main Decision Tree
|
||||
|
||||
```
|
||||
START: What's your MAIN concern?
|
||||
|
||||
┌─ Data Access Complexity?
|
||||
│ ├─ HIGH (complex queries, testing needed)
|
||||
│ │ → Repository Pattern + Unit of Work
|
||||
│ │ VALIDATE: Will data source change frequently?
|
||||
│ │ ├─ YES → Repository worth the indirection
|
||||
│ │ └─ NO → Consider simpler ORM direct access
|
||||
│ └─ LOW (simple CRUD, single database)
|
||||
│ → ORM directly (Prisma, Drizzle)
|
||||
│ Simpler = Better, Faster
|
||||
│
|
||||
├─ Business Rules Complexity?
|
||||
│ ├─ HIGH (domain logic, rules vary by context)
|
||||
│ │ → Domain-Driven Design
|
||||
│ │ VALIDATE: Do you have domain experts on team?
|
||||
│ │ ├─ YES → Full DDD (Aggregates, Value Objects)
|
||||
│ │ └─ NO → Partial DDD (rich entities, clear boundaries)
|
||||
│ └─ LOW (mostly CRUD, simple validation)
|
||||
│ → Transaction Script pattern
|
||||
│ Simpler = Better, Faster
|
||||
│
|
||||
├─ Independent Scaling Needed?
|
||||
│ ├─ YES (different components scale differently)
|
||||
│ │ → Microservices WORTH the complexity
|
||||
│ │ REQUIREMENTS (ALL must be true):
|
||||
│ │ - Clear domain boundaries
|
||||
│ │ - Team > 10 developers
|
||||
│ │ - Different scaling needs per service
|
||||
│ │ IF NOT ALL MET → Modular Monolith instead
|
||||
│ └─ NO (everything scales together)
|
||||
│ → Modular Monolith
|
||||
│ Can extract services later when proven needed
|
||||
│
|
||||
└─ Real-time Requirements?
|
||||
├─ HIGH (immediate updates, multi-user sync)
|
||||
│ → Event-Driven Architecture
|
||||
│ → Message Queue (RabbitMQ, Redis, Kafka)
|
||||
│ VALIDATE: Can you handle eventual consistency?
|
||||
│ ├─ YES → Event-driven valid
|
||||
│ └─ NO → Synchronous with polling
|
||||
└─ LOW (eventual consistency acceptable)
|
||||
→ Synchronous (REST/GraphQL)
|
||||
Simpler = Better, Faster
|
||||
```
|
||||
|
||||
## The 3 Questions (Before ANY Pattern)
|
||||
|
||||
1. **Problem Solved**: What SPECIFIC problem does this pattern solve?
|
||||
2. **Simpler Alternative**: Is there a simpler solution?
|
||||
3. **Deferred Complexity**: Can we add this LATER when needed?
|
||||
|
||||
## Red Flags (Anti-patterns)
|
||||
|
||||
| Pattern | Anti-pattern | Simpler Alternative |
|
||||
|---------|-------------|-------------------|
|
||||
| Microservices | Premature splitting | Start monolith, extract later |
|
||||
| Clean/Hexagonal | Over-abstraction | Concrete first, interfaces later |
|
||||
| Event Sourcing | Over-engineering | Append-only audit log |
|
||||
| CQRS | Unnecessary complexity | Single model |
|
||||
| Repository | YAGNI for simple CRUD | ORM direct access |
|
||||
50
skills/architecture/patterns-reference.md
Normal file
50
skills/architecture/patterns-reference.md
Normal file
@@ -0,0 +1,50 @@
|
||||
# Architecture Patterns Reference
|
||||
|
||||
> Quick reference for common patterns with usage guidance.
|
||||
|
||||
## Data Access Patterns
|
||||
|
||||
| Pattern | When to Use | When NOT to Use | Complexity |
|
||||
|---------|-------------|-----------------|------------|
|
||||
| **Active Record** | Simple CRUD, rapid prototyping | Complex queries, multiple sources | Low |
|
||||
| **Repository** | Testing needed, multiple sources | Simple CRUD, single database | Medium |
|
||||
| **Unit of Work** | Complex transactions | Simple operations | High |
|
||||
| **Data Mapper** | Complex domain, performance | Simple CRUD, rapid dev | High |
|
||||
|
||||
## Domain Logic Patterns
|
||||
|
||||
| Pattern | When to Use | When NOT to Use | Complexity |
|
||||
|---------|-------------|-----------------|------------|
|
||||
| **Transaction Script** | Simple CRUD, procedural | Complex business rules | Low |
|
||||
| **Table Module** | Record-based logic | Rich behavior needed | Low |
|
||||
| **Domain Model** | Complex business logic | Simple CRUD | Medium |
|
||||
| **DDD (Full)** | Complex domain, domain experts | Simple domain, no experts | High |
|
||||
|
||||
## Distributed System Patterns
|
||||
|
||||
| Pattern | When to Use | When NOT to Use | Complexity |
|
||||
|---------|-------------|-----------------|------------|
|
||||
| **Modular Monolith** | Small teams, unclear boundaries | Clear contexts, different scales | Medium |
|
||||
| **Microservices** | Different scales, large teams | Small teams, simple domain | Very High |
|
||||
| **Event-Driven** | Real-time, loose coupling | Simple workflows, strong consistency | High |
|
||||
| **CQRS** | Read/write performance diverges | Simple CRUD, same model | High |
|
||||
| **Saga** | Distributed transactions | Single database, simple ACID | High |
|
||||
|
||||
## API Patterns
|
||||
|
||||
| Pattern | When to Use | When NOT to Use | Complexity |
|
||||
|---------|-------------|-----------------|------------|
|
||||
| **REST** | Standard CRUD, resources | Real-time, complex queries | Low |
|
||||
| **GraphQL** | Flexible queries, multiple clients | Simple CRUD, caching needs | Medium |
|
||||
| **gRPC** | Internal services, performance | Public APIs, browser clients | Medium |
|
||||
| **WebSocket** | Real-time updates | Simple request/response | Medium |
|
||||
|
||||
---
|
||||
|
||||
## Simplicity Principle
|
||||
|
||||
**"Start simple, add complexity only when proven necessary."**
|
||||
|
||||
- You can always add patterns later
|
||||
- Removing complexity is MUCH harder than adding it
|
||||
- When in doubt, choose simpler option
|
||||
77
skills/architecture/trade-off-analysis.md
Normal file
77
skills/architecture/trade-off-analysis.md
Normal file
@@ -0,0 +1,77 @@
|
||||
# Trade-off Analysis & ADR
|
||||
|
||||
> Document every architectural decision with trade-offs.
|
||||
|
||||
## Decision Framework
|
||||
|
||||
For EACH architectural component, document:
|
||||
|
||||
```markdown
|
||||
## Architecture Decision Record
|
||||
|
||||
### Context
|
||||
- **Problem**: [What problem are we solving?]
|
||||
- **Constraints**: [Team size, scale, timeline, budget]
|
||||
|
||||
### Options Considered
|
||||
|
||||
| Option | Pros | Cons | Complexity | When Valid |
|
||||
|--------|------|------|------------|-----------|
|
||||
| Option A | Benefit 1 | Cost 1 | Low | [Conditions] |
|
||||
| Option B | Benefit 2 | Cost 2 | High | [Conditions] |
|
||||
|
||||
### Decision
|
||||
**Chosen**: [Option B]
|
||||
|
||||
### Rationale
|
||||
1. [Reason 1 - tied to constraints]
|
||||
2. [Reason 2 - tied to requirements]
|
||||
|
||||
### Trade-offs Accepted
|
||||
- [What we're giving up]
|
||||
- [Why this is acceptable]
|
||||
|
||||
### Consequences
|
||||
- **Positive**: [Benefits we gain]
|
||||
- **Negative**: [Costs/risks we accept]
|
||||
- **Mitigation**: [How we'll address negatives]
|
||||
|
||||
### Revisit Trigger
|
||||
- [When to reconsider this decision]
|
||||
```
|
||||
|
||||
## ADR Template
|
||||
|
||||
```markdown
|
||||
# ADR-[XXX]: [Decision Title]
|
||||
|
||||
## Status
|
||||
Proposed | Accepted | Deprecated | Superseded by [ADR-YYY]
|
||||
|
||||
## Context
|
||||
[What problem? What constraints?]
|
||||
|
||||
## Decision
|
||||
[What we chose - be specific]
|
||||
|
||||
## Rationale
|
||||
[Why - tie to requirements and constraints]
|
||||
|
||||
## Trade-offs
|
||||
[What we're giving up - be honest]
|
||||
|
||||
## Consequences
|
||||
- **Positive**: [Benefits]
|
||||
- **Negative**: [Costs]
|
||||
- **Mitigation**: [How to address]
|
||||
```
|
||||
|
||||
## ADR Storage
|
||||
|
||||
```
|
||||
docs/
|
||||
└── architecture/
|
||||
├── adr-001-use-nextjs.md
|
||||
├── adr-002-postgresql-over-mongodb.md
|
||||
└── adr-003-adopt-repository-pattern.md
|
||||
```
|
||||
@@ -1,6 +1,9 @@
|
||||
---
|
||||
name: AWS Penetration Testing
|
||||
description: This skill should be used when the user asks to "pentest AWS", "test AWS security", "enumerate IAM", "exploit cloud infrastructure", "AWS privilege escalation", "S3 bucket testing", "metadata SSRF", "Lambda exploitation", or needs guidance on Amazon Web Services security assessment.
|
||||
metadata:
|
||||
author: zebbern
|
||||
version: "1.1"
|
||||
---
|
||||
|
||||
# AWS Penetration Testing
|
||||
|
||||
199
skills/bash-linux/SKILL.md
Normal file
199
skills/bash-linux/SKILL.md
Normal file
@@ -0,0 +1,199 @@
|
||||
---
|
||||
name: bash-linux
|
||||
description: Bash/Linux terminal patterns. Critical commands, piping, error handling, scripting. Use when working on macOS or Linux systems.
|
||||
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
|
||||
---
|
||||
|
||||
# Bash Linux Patterns
|
||||
|
||||
> Essential patterns for Bash on Linux/macOS.
|
||||
|
||||
---
|
||||
|
||||
## 1. Operator Syntax
|
||||
|
||||
### Chaining Commands
|
||||
|
||||
| Operator | Meaning | Example |
|
||||
|----------|---------|---------|
|
||||
| `;` | Run sequentially | `cmd1; cmd2` |
|
||||
| `&&` | Run if previous succeeded | `npm install && npm run dev` |
|
||||
| `\|\|` | Run if previous failed | `npm test \|\| echo "Tests failed"` |
|
||||
| `\|` | Pipe output | `ls \| grep ".js"` |
|
||||
|
||||
---
|
||||
|
||||
## 2. File Operations
|
||||
|
||||
### Essential Commands
|
||||
|
||||
| Task | Command |
|
||||
|------|---------|
|
||||
| List all | `ls -la` |
|
||||
| Find files | `find . -name "*.js" -type f` |
|
||||
| File content | `cat file.txt` |
|
||||
| First N lines | `head -n 20 file.txt` |
|
||||
| Last N lines | `tail -n 20 file.txt` |
|
||||
| Follow log | `tail -f log.txt` |
|
||||
| Search in files | `grep -r "pattern" --include="*.js"` |
|
||||
| File size | `du -sh *` |
|
||||
| Disk usage | `df -h` |
|
||||
|
||||
---
|
||||
|
||||
## 3. Process Management
|
||||
|
||||
| Task | Command |
|
||||
|------|---------|
|
||||
| List processes | `ps aux` |
|
||||
| Find by name | `ps aux \| grep node` |
|
||||
| Kill by PID | `kill -9 <PID>` |
|
||||
| Find port user | `lsof -i :3000` |
|
||||
| Kill port | `kill -9 $(lsof -t -i :3000)` |
|
||||
| Background | `npm run dev &` |
|
||||
| Jobs | `jobs -l` |
|
||||
| Bring to front | `fg %1` |
|
||||
|
||||
---
|
||||
|
||||
## 4. Text Processing
|
||||
|
||||
### Core Tools
|
||||
|
||||
| Tool | Purpose | Example |
|
||||
|------|---------|---------|
|
||||
| `grep` | Search | `grep -rn "TODO" src/` |
|
||||
| `sed` | Replace | `sed -i 's/old/new/g' file.txt` |
|
||||
| `awk` | Extract columns | `awk '{print $1}' file.txt` |
|
||||
| `cut` | Cut fields | `cut -d',' -f1 data.csv` |
|
||||
| `sort` | Sort lines | `sort -u file.txt` |
|
||||
| `uniq` | Unique lines | `sort file.txt \| uniq -c` |
|
||||
| `wc` | Count | `wc -l file.txt` |
|
||||
|
||||
---
|
||||
|
||||
## 5. Environment Variables
|
||||
|
||||
| Task | Command |
|
||||
|------|---------|
|
||||
| View all | `env` or `printenv` |
|
||||
| View one | `echo $PATH` |
|
||||
| Set temporary | `export VAR="value"` |
|
||||
| Set in script | `VAR="value" command` |
|
||||
| Add to PATH | `export PATH="$PATH:/new/path"` |
|
||||
|
||||
---
|
||||
|
||||
## 6. Network
|
||||
|
||||
| Task | Command |
|
||||
|------|---------|
|
||||
| Download | `curl -O https://example.com/file` |
|
||||
| API request | `curl -X GET https://api.example.com` |
|
||||
| POST JSON | `curl -X POST -H "Content-Type: application/json" -d '{"key":"value"}' URL` |
|
||||
| Check port | `nc -zv localhost 3000` |
|
||||
| Network info | `ifconfig` or `ip addr` |
|
||||
|
||||
---
|
||||
|
||||
## 7. Script Template
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -euo pipefail # Exit on error, undefined var, pipe fail
|
||||
|
||||
# Colors (optional)
|
||||
RED='\033[0;31m'
|
||||
GREEN='\033[0;32m'
|
||||
NC='\033[0m'
|
||||
|
||||
# Script directory
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
|
||||
# Functions
|
||||
log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
|
||||
log_error() { echo -e "${RED}[ERROR]${NC} $1" >&2; }
|
||||
|
||||
# Main
|
||||
main() {
|
||||
log_info "Starting..."
|
||||
# Your logic here
|
||||
log_info "Done!"
|
||||
}
|
||||
|
||||
main "$@"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Common Patterns
|
||||
|
||||
### Check if command exists
|
||||
|
||||
```bash
|
||||
if command -v node &> /dev/null; then
|
||||
echo "Node is installed"
|
||||
fi
|
||||
```
|
||||
|
||||
### Default variable value
|
||||
|
||||
```bash
|
||||
NAME=${1:-"default_value"}
|
||||
```
|
||||
|
||||
### Read file line by line
|
||||
|
||||
```bash
|
||||
while IFS= read -r line; do
|
||||
echo "$line"
|
||||
done < file.txt
|
||||
```
|
||||
|
||||
### Loop over files
|
||||
|
||||
```bash
|
||||
for file in *.js; do
|
||||
echo "Processing $file"
|
||||
done
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Differences from PowerShell
|
||||
|
||||
| Task | PowerShell | Bash |
|
||||
|------|------------|------|
|
||||
| List files | `Get-ChildItem` | `ls -la` |
|
||||
| Find files | `Get-ChildItem -Recurse` | `find . -type f` |
|
||||
| Environment | `$env:VAR` | `$VAR` |
|
||||
| String concat | `"$a$b"` | `"$a$b"` (same) |
|
||||
| Null check | `if ($x)` | `if [ -n "$x" ]` |
|
||||
| Pipeline | Object-based | Text-based |
|
||||
|
||||
---
|
||||
|
||||
## 10. Error Handling
|
||||
|
||||
### Set options
|
||||
|
||||
```bash
|
||||
set -e # Exit on error
|
||||
set -u # Exit on undefined variable
|
||||
set -o pipefail # Exit on pipe failure
|
||||
set -x # Debug: print commands
|
||||
```
|
||||
|
||||
### Trap for cleanup
|
||||
|
||||
```bash
|
||||
cleanup() {
|
||||
echo "Cleaning up..."
|
||||
rm -f /tmp/tempfile
|
||||
}
|
||||
trap cleanup EXIT
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
> **Remember:** Bash is text-based. Use `&&` for success chains, `set -e` for safety, and quote your variables!
|
||||
242
skills/behavioral-modes/SKILL.md
Normal file
242
skills/behavioral-modes/SKILL.md
Normal file
@@ -0,0 +1,242 @@
|
||||
---
|
||||
name: behavioral-modes
|
||||
description: AI operational modes (brainstorm, implement, debug, review, teach, ship, orchestrate). Use to adapt behavior based on task type.
|
||||
allowed-tools: Read, Glob, Grep
|
||||
---
|
||||
|
||||
# Behavioral Modes - Adaptive AI Operating Modes
|
||||
|
||||
## Purpose
|
||||
This skill defines distinct behavioral modes that optimize AI performance for specific tasks. Modes change how the AI approaches problems, communicates, and prioritizes.
|
||||
|
||||
---
|
||||
|
||||
## Available Modes
|
||||
|
||||
### 1. 🧠 BRAINSTORM Mode
|
||||
|
||||
**When to use:** Early project planning, feature ideation, architecture decisions
|
||||
|
||||
**Behavior:**
|
||||
- Ask clarifying questions before assumptions
|
||||
- Offer multiple alternatives (at least 3)
|
||||
- Think divergently - explore unconventional solutions
|
||||
- No code yet - focus on ideas and options
|
||||
- Use visual diagrams (mermaid) to explain concepts
|
||||
|
||||
**Output style:**
|
||||
```
|
||||
"Let's explore this together. Here are some approaches:
|
||||
|
||||
Option A: [description]
|
||||
✅ Pros: ...
|
||||
❌ Cons: ...
|
||||
|
||||
Option B: [description]
|
||||
✅ Pros: ...
|
||||
❌ Cons: ...
|
||||
|
||||
What resonates with you? Or should we explore a different direction?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. ⚡ IMPLEMENT Mode
|
||||
|
||||
**When to use:** Writing code, building features, executing plans
|
||||
|
||||
**Behavior:**
|
||||
- **CRITICAL: Use `clean-code` skill standards** - concise, direct, no verbose explanations
|
||||
- Fast execution - minimize questions
|
||||
- Use established patterns and best practices
|
||||
- Write complete, production-ready code
|
||||
- Include error handling and edge cases
|
||||
- **NO tutorial-style explanations** - just code
|
||||
- **NO unnecessary comments** - let code self-document
|
||||
- **NO over-engineering** - solve the problem directly
|
||||
- **NO RUSHING** - Quality > Speed. Read ALL references before coding.
|
||||
|
||||
**Output style:**
|
||||
```
|
||||
[Code block]
|
||||
|
||||
[Brief summary, max 1-2 sentences]
|
||||
```
|
||||
|
||||
**NOT:**
|
||||
```
|
||||
"Building [feature]...
|
||||
|
||||
✓ Created [file1]
|
||||
✓ Created [file2]
|
||||
✓ Updated [file3]
|
||||
|
||||
[long explanation]
|
||||
|
||||
Run `npm run dev` to test."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. 🔍 DEBUG Mode
|
||||
|
||||
**When to use:** Fixing bugs, troubleshooting errors, investigating issues
|
||||
|
||||
**Behavior:**
|
||||
- Ask for error messages and reproduction steps
|
||||
- Think systematically - check logs, trace data flow
|
||||
- Form hypothesis → test → verify
|
||||
- Explain the root cause, not just the fix
|
||||
- Prevent future occurrences
|
||||
|
||||
**Output style:**
|
||||
```
|
||||
"Investigating...
|
||||
|
||||
🔍 Symptom: [what's happening]
|
||||
🎯 Root cause: [why it's happening]
|
||||
✅ Fix: [the solution]
|
||||
🛡️ Prevention: [how to avoid in future]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. 📋 REVIEW Mode
|
||||
|
||||
**When to use:** Code review, architecture review, security audit
|
||||
|
||||
**Behavior:**
|
||||
- Be thorough but constructive
|
||||
- Categorize by severity (Critical/High/Medium/Low)
|
||||
- Explain the "why" behind suggestions
|
||||
- Offer improved code examples
|
||||
- Acknowledge what's done well
|
||||
|
||||
**Output style:**
|
||||
```
|
||||
## Code Review: [file/feature]
|
||||
|
||||
### 🔴 Critical
|
||||
- [issue with explanation]
|
||||
|
||||
### 🟠 Improvements
|
||||
- [suggestion with example]
|
||||
|
||||
### 🟢 Good
|
||||
- [positive observation]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. 📚 TEACH Mode
|
||||
|
||||
**When to use:** Explaining concepts, documentation, onboarding
|
||||
|
||||
**Behavior:**
|
||||
- Explain from fundamentals
|
||||
- Use analogies and examples
|
||||
- Progress from simple to complex
|
||||
- Include practical exercises
|
||||
- Check understanding
|
||||
|
||||
**Output style:**
|
||||
```
|
||||
## Understanding [Concept]
|
||||
|
||||
### What is it?
|
||||
[Simple explanation with analogy]
|
||||
|
||||
### How it works
|
||||
[Technical explanation with diagram]
|
||||
|
||||
### Example
|
||||
[Code example with comments]
|
||||
|
||||
### Try it yourself
|
||||
[Exercise or task]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. 🚀 SHIP Mode
|
||||
|
||||
**When to use:** Production deployment, final polish, release preparation
|
||||
|
||||
**Behavior:**
|
||||
- Focus on stability over features
|
||||
- Check for missing error handling
|
||||
- Verify environment configs
|
||||
- Run all tests
|
||||
- Create deployment checklist
|
||||
|
||||
**Output style:**
|
||||
```
|
||||
## Pre-Ship Checklist
|
||||
|
||||
### ✅ Code Quality
|
||||
- [ ] No TypeScript errors
|
||||
- [ ] ESLint passing
|
||||
- [ ] All tests passing
|
||||
|
||||
### ✅ Security
|
||||
- [ ] No exposed secrets
|
||||
- [ ] Input validation complete
|
||||
|
||||
### ✅ Performance
|
||||
- [ ] Bundle size acceptable
|
||||
- [ ] No console.logs
|
||||
|
||||
### 🚀 Ready to deploy
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Mode Detection
|
||||
|
||||
The AI should automatically detect the appropriate mode based on:
|
||||
|
||||
| Trigger | Mode |
|
||||
|---------|------|
|
||||
| "what if", "ideas", "options" | BRAINSTORM |
|
||||
| "build", "create", "add" | IMPLEMENT |
|
||||
| "not working", "error", "bug" | DEBUG |
|
||||
| "review", "check", "audit" | REVIEW |
|
||||
| "explain", "how does", "learn" | TEACH |
|
||||
| "deploy", "release", "production" | SHIP |
|
||||
|
||||
---
|
||||
|
||||
## Multi-Agent Collaboration Patterns (2025)
|
||||
|
||||
Modern architectures optimized for agent-to-agent collaboration:
|
||||
|
||||
### 1. 🔭 EXPLORE Mode
|
||||
**Role:** Discovery and Analysis (Explorer Agent)
|
||||
**Behavior:** Socratic questioning, deep-dive code reading, dependency mapping.
|
||||
**Output:** `discovery-report.json`, architectural visualization.
|
||||
|
||||
### 2. 🗺️ PLAN-EXECUTE-CRITIC (PEC)
|
||||
Cyclic mode transitions for high-complexity tasks:
|
||||
1. **Planner:** Decomposes the task into atomic steps (`task.md`).
|
||||
2. **Executor:** Performs the actual coding (`IMPLEMENT`).
|
||||
3. **Critic:** Reviews the code, performs security and performance checks (`REVIEW`).
|
||||
|
||||
### 3. 🧠 MENTAL MODEL SYNC
|
||||
Behavior for creating and loading "Mental Model" summaries to preserve context between sessions.
|
||||
|
||||
---
|
||||
|
||||
## Combining Modes
|
||||
|
||||
---
|
||||
|
||||
## Manual Mode Switching
|
||||
|
||||
Users can explicitly request a mode:
|
||||
|
||||
```
|
||||
/brainstorm new feature ideas
|
||||
/implement the user profile page
|
||||
/debug why login fails
|
||||
/review this pull request
|
||||
```
|
||||
@@ -1,6 +1,9 @@
|
||||
---
|
||||
name: Broken Authentication Testing
|
||||
description: This skill should be used when the user asks to "test for broken authentication vulnerabilities", "assess session management security", "perform credential stuffing tests", "evaluate password policies", "test for session fixation", or "identify authentication bypass flaws". It provides comprehensive techniques for identifying authentication and session management weaknesses in web applications.
|
||||
metadata:
|
||||
author: zebbern
|
||||
version: "1.1"
|
||||
---
|
||||
|
||||
# Broken Authentication Testing
|
||||
|
||||
@@ -1,6 +1,9 @@
|
||||
---
|
||||
name: Burp Suite Web Application Testing
|
||||
description: This skill should be used when the user asks to "intercept HTTP traffic", "modify web requests", "use Burp Suite for testing", "perform web vulnerability scanning", "test with Burp Repeater", "analyze HTTP history", or "configure proxy for web testing". It provides comprehensive guidance for using Burp Suite's core features for web application security testing.
|
||||
metadata:
|
||||
author: zebbern
|
||||
version: "1.1"
|
||||
---
|
||||
|
||||
# Burp Suite Web Application Testing
|
||||
|
||||
584
skills/cc-skill-backend-patterns/SKILL.md
Normal file
584
skills/cc-skill-backend-patterns/SKILL.md
Normal file
@@ -0,0 +1,584 @@
|
||||
---
|
||||
name: backend-patterns
|
||||
description: Backend architecture patterns, API design, database optimization, and server-side best practices for Node.js, Express, and Next.js API routes.
|
||||
author: affaan-m
|
||||
version: "1.0"
|
||||
---
|
||||
|
||||
# Backend Development Patterns
|
||||
|
||||
Backend architecture patterns and best practices for scalable server-side applications.
|
||||
|
||||
## API Design Patterns
|
||||
|
||||
### RESTful API Structure
|
||||
|
||||
```typescript
|
||||
// ✅ Resource-based URLs
|
||||
GET /api/markets # List resources
|
||||
GET /api/markets/:id # Get single resource
|
||||
POST /api/markets # Create resource
|
||||
PUT /api/markets/:id # Replace resource
|
||||
PATCH /api/markets/:id # Update resource
|
||||
DELETE /api/markets/:id # Delete resource
|
||||
|
||||
// ✅ Query parameters for filtering, sorting, pagination
|
||||
GET /api/markets?status=active&sort=volume&limit=20&offset=0
|
||||
```
|
||||
|
||||
### Repository Pattern
|
||||
|
||||
```typescript
|
||||
// Abstract data access logic
|
||||
interface MarketRepository {
|
||||
findAll(filters?: MarketFilters): Promise<Market[]>
|
||||
findById(id: string): Promise<Market | null>
|
||||
create(data: CreateMarketDto): Promise<Market>
|
||||
update(id: string, data: UpdateMarketDto): Promise<Market>
|
||||
delete(id: string): Promise<void>
|
||||
}
|
||||
|
||||
class SupabaseMarketRepository implements MarketRepository {
|
||||
async findAll(filters?: MarketFilters): Promise<Market[]> {
|
||||
let query = supabase.from('markets').select('*')
|
||||
|
||||
if (filters?.status) {
|
||||
query = query.eq('status', filters.status)
|
||||
}
|
||||
|
||||
if (filters?.limit) {
|
||||
query = query.limit(filters.limit)
|
||||
}
|
||||
|
||||
const { data, error } = await query
|
||||
|
||||
if (error) throw new Error(error.message)
|
||||
return data
|
||||
}
|
||||
|
||||
// Other methods...
|
||||
}
|
||||
```
|
||||
|
||||
### Service Layer Pattern
|
||||
|
||||
```typescript
|
||||
// Business logic separated from data access
|
||||
class MarketService {
|
||||
constructor(private marketRepo: MarketRepository) {}
|
||||
|
||||
async searchMarkets(query: string, limit: number = 10): Promise<Market[]> {
|
||||
// Business logic
|
||||
const embedding = await generateEmbedding(query)
|
||||
const results = await this.vectorSearch(embedding, limit)
|
||||
|
||||
// Fetch full data
|
||||
const markets = await this.marketRepo.findByIds(results.map(r => r.id))
|
||||
|
||||
// Sort by similarity
|
||||
return markets.sort((a, b) => {
|
||||
const scoreA = results.find(r => r.id === a.id)?.score || 0
|
||||
const scoreB = results.find(r => r.id === b.id)?.score || 0
|
||||
return scoreA - scoreB
|
||||
})
|
||||
}
|
||||
|
||||
private async vectorSearch(embedding: number[], limit: number) {
|
||||
// Vector search implementation
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Middleware Pattern
|
||||
|
||||
```typescript
|
||||
// Request/response processing pipeline
|
||||
export function withAuth(handler: NextApiHandler): NextApiHandler {
|
||||
return async (req, res) => {
|
||||
const token = req.headers.authorization?.replace('Bearer ', '')
|
||||
|
||||
if (!token) {
|
||||
return res.status(401).json({ error: 'Unauthorized' })
|
||||
}
|
||||
|
||||
try {
|
||||
const user = await verifyToken(token)
|
||||
req.user = user
|
||||
return handler(req, res)
|
||||
} catch (error) {
|
||||
return res.status(401).json({ error: 'Invalid token' })
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Usage
|
||||
export default withAuth(async (req, res) => {
|
||||
// Handler has access to req.user
|
||||
})
|
||||
```
|
||||
|
||||
## Database Patterns
|
||||
|
||||
### Query Optimization
|
||||
|
||||
```typescript
|
||||
// ✅ GOOD: Select only needed columns
|
||||
const { data } = await supabase
|
||||
.from('markets')
|
||||
.select('id, name, status, volume')
|
||||
.eq('status', 'active')
|
||||
.order('volume', { ascending: false })
|
||||
.limit(10)
|
||||
|
||||
// ❌ BAD: Select everything
|
||||
const { data } = await supabase
|
||||
.from('markets')
|
||||
.select('*')
|
||||
```
|
||||
|
||||
### N+1 Query Prevention
|
||||
|
||||
```typescript
|
||||
// ❌ BAD: N+1 query problem
|
||||
const markets = await getMarkets()
|
||||
for (const market of markets) {
|
||||
market.creator = await getUser(market.creator_id) // N queries
|
||||
}
|
||||
|
||||
// ✅ GOOD: Batch fetch
|
||||
const markets = await getMarkets()
|
||||
const creatorIds = markets.map(m => m.creator_id)
|
||||
const creators = await getUsers(creatorIds) // 1 query
|
||||
const creatorMap = new Map(creators.map(c => [c.id, c]))
|
||||
|
||||
markets.forEach(market => {
|
||||
market.creator = creatorMap.get(market.creator_id)
|
||||
})
|
||||
```
|
||||
|
||||
### Transaction Pattern
|
||||
|
||||
```typescript
|
||||
async function createMarketWithPosition(
|
||||
marketData: CreateMarketDto,
|
||||
positionData: CreatePositionDto
|
||||
) {
|
||||
// Use Supabase transaction
|
||||
const { data, error } = await supabase.rpc('create_market_with_position', {
|
||||
market_data: marketData,
|
||||
position_data: positionData
|
||||
})
|
||||
|
||||
if (error) throw new Error('Transaction failed')
|
||||
return data
|
||||
}
|
||||
|
||||
// SQL function in Supabase
|
||||
CREATE OR REPLACE FUNCTION create_market_with_position(
|
||||
market_data jsonb,
|
||||
position_data jsonb
|
||||
)
|
||||
RETURNS jsonb
|
||||
LANGUAGE plpgsql
|
||||
AS $$
|
||||
BEGIN
|
||||
-- Start transaction automatically
|
||||
INSERT INTO markets VALUES (market_data);
|
||||
INSERT INTO positions VALUES (position_data);
|
||||
RETURN jsonb_build_object('success', true);
|
||||
EXCEPTION
|
||||
WHEN OTHERS THEN
|
||||
-- Rollback happens automatically
|
||||
RETURN jsonb_build_object('success', false, 'error', SQLERRM);
|
||||
END;
|
||||
$$;
|
||||
```
|
||||
|
||||
## Caching Strategies
|
||||
|
||||
### Redis Caching Layer
|
||||
|
||||
```typescript
|
||||
class CachedMarketRepository implements MarketRepository {
|
||||
constructor(
|
||||
private baseRepo: MarketRepository,
|
||||
private redis: RedisClient
|
||||
) {}
|
||||
|
||||
async findById(id: string): Promise<Market | null> {
|
||||
// Check cache first
|
||||
const cached = await this.redis.get(`market:${id}`)
|
||||
|
||||
if (cached) {
|
||||
return JSON.parse(cached)
|
||||
}
|
||||
|
||||
// Cache miss - fetch from database
|
||||
const market = await this.baseRepo.findById(id)
|
||||
|
||||
if (market) {
|
||||
// Cache for 5 minutes
|
||||
await this.redis.setex(`market:${id}`, 300, JSON.stringify(market))
|
||||
}
|
||||
|
||||
return market
|
||||
}
|
||||
|
||||
async invalidateCache(id: string): Promise<void> {
|
||||
await this.redis.del(`market:${id}`)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Cache-Aside Pattern
|
||||
|
||||
```typescript
|
||||
async function getMarketWithCache(id: string): Promise<Market> {
|
||||
const cacheKey = `market:${id}`
|
||||
|
||||
// Try cache
|
||||
const cached = await redis.get(cacheKey)
|
||||
if (cached) return JSON.parse(cached)
|
||||
|
||||
// Cache miss - fetch from DB
|
||||
const market = await db.markets.findUnique({ where: { id } })
|
||||
|
||||
if (!market) throw new Error('Market not found')
|
||||
|
||||
// Update cache
|
||||
await redis.setex(cacheKey, 300, JSON.stringify(market))
|
||||
|
||||
return market
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling Patterns
|
||||
|
||||
### Centralized Error Handler
|
||||
|
||||
```typescript
|
||||
class ApiError extends Error {
|
||||
constructor(
|
||||
public statusCode: number,
|
||||
public message: string,
|
||||
public isOperational = true
|
||||
) {
|
||||
super(message)
|
||||
Object.setPrototypeOf(this, ApiError.prototype)
|
||||
}
|
||||
}
|
||||
|
||||
export function errorHandler(error: unknown, req: Request): Response {
|
||||
if (error instanceof ApiError) {
|
||||
return NextResponse.json({
|
||||
success: false,
|
||||
error: error.message
|
||||
}, { status: error.statusCode })
|
||||
}
|
||||
|
||||
if (error instanceof z.ZodError) {
|
||||
return NextResponse.json({
|
||||
success: false,
|
||||
error: 'Validation failed',
|
||||
details: error.errors
|
||||
}, { status: 400 })
|
||||
}
|
||||
|
||||
// Log unexpected errors
|
||||
console.error('Unexpected error:', error)
|
||||
|
||||
return NextResponse.json({
|
||||
success: false,
|
||||
error: 'Internal server error'
|
||||
}, { status: 500 })
|
||||
}
|
||||
|
||||
// Usage
|
||||
export async function GET(request: Request) {
|
||||
try {
|
||||
const data = await fetchData()
|
||||
return NextResponse.json({ success: true, data })
|
||||
} catch (error) {
|
||||
return errorHandler(error, request)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Retry with Exponential Backoff
|
||||
|
||||
```typescript
|
||||
async function fetchWithRetry<T>(
|
||||
fn: () => Promise<T>,
|
||||
maxRetries = 3
|
||||
): Promise<T> {
|
||||
let lastError: Error
|
||||
|
||||
for (let i = 0; i < maxRetries; i++) {
|
||||
try {
|
||||
return await fn()
|
||||
} catch (error) {
|
||||
lastError = error as Error
|
||||
|
||||
if (i < maxRetries - 1) {
|
||||
// Exponential backoff: 1s, 2s, 4s
|
||||
const delay = Math.pow(2, i) * 1000
|
||||
await new Promise(resolve => setTimeout(resolve, delay))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
throw lastError!
|
||||
}
|
||||
|
||||
// Usage
|
||||
const data = await fetchWithRetry(() => fetchFromAPI())
|
||||
```
|
||||
|
||||
## Authentication & Authorization
|
||||
|
||||
### JWT Token Validation
|
||||
|
||||
```typescript
|
||||
import jwt from 'jsonwebtoken'
|
||||
|
||||
interface JWTPayload {
|
||||
userId: string
|
||||
email: string
|
||||
role: 'admin' | 'user'
|
||||
}
|
||||
|
||||
export function verifyToken(token: string): JWTPayload {
|
||||
try {
|
||||
const payload = jwt.verify(token, process.env.JWT_SECRET!) as JWTPayload
|
||||
return payload
|
||||
} catch (error) {
|
||||
throw new ApiError(401, 'Invalid token')
|
||||
}
|
||||
}
|
||||
|
||||
export async function requireAuth(request: Request) {
|
||||
const token = request.headers.get('authorization')?.replace('Bearer ', '')
|
||||
|
||||
if (!token) {
|
||||
throw new ApiError(401, 'Missing authorization token')
|
||||
}
|
||||
|
||||
return verifyToken(token)
|
||||
}
|
||||
|
||||
// Usage in API route
|
||||
export async function GET(request: Request) {
|
||||
const user = await requireAuth(request)
|
||||
|
||||
const data = await getDataForUser(user.userId)
|
||||
|
||||
return NextResponse.json({ success: true, data })
|
||||
}
|
||||
```
|
||||
|
||||
### Role-Based Access Control
|
||||
|
||||
```typescript
|
||||
type Permission = 'read' | 'write' | 'delete' | 'admin'
|
||||
|
||||
interface User {
|
||||
id: string
|
||||
role: 'admin' | 'moderator' | 'user'
|
||||
}
|
||||
|
||||
const rolePermissions: Record<User['role'], Permission[]> = {
|
||||
admin: ['read', 'write', 'delete', 'admin'],
|
||||
moderator: ['read', 'write', 'delete'],
|
||||
user: ['read', 'write']
|
||||
}
|
||||
|
||||
export function hasPermission(user: User, permission: Permission): boolean {
|
||||
return rolePermissions[user.role].includes(permission)
|
||||
}
|
||||
|
||||
export function requirePermission(permission: Permission) {
|
||||
return async (request: Request) => {
|
||||
const user = await requireAuth(request)
|
||||
|
||||
if (!hasPermission(user, permission)) {
|
||||
throw new ApiError(403, 'Insufficient permissions')
|
||||
}
|
||||
|
||||
return user
|
||||
}
|
||||
}
|
||||
|
||||
// Usage
|
||||
export const DELETE = requirePermission('delete')(async (request: Request) => {
|
||||
// Handler with permission check
|
||||
})
|
||||
```
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
### Simple In-Memory Rate Limiter
|
||||
|
||||
```typescript
|
||||
class RateLimiter {
|
||||
private requests = new Map<string, number[]>()
|
||||
|
||||
async checkLimit(
|
||||
identifier: string,
|
||||
maxRequests: number,
|
||||
windowMs: number
|
||||
): Promise<boolean> {
|
||||
const now = Date.now()
|
||||
const requests = this.requests.get(identifier) || []
|
||||
|
||||
// Remove old requests outside window
|
||||
const recentRequests = requests.filter(time => now - time < windowMs)
|
||||
|
||||
if (recentRequests.length >= maxRequests) {
|
||||
return false // Rate limit exceeded
|
||||
}
|
||||
|
||||
// Add current request
|
||||
recentRequests.push(now)
|
||||
this.requests.set(identifier, recentRequests)
|
||||
|
||||
return true
|
||||
}
|
||||
}
|
||||
|
||||
const limiter = new RateLimiter()
|
||||
|
||||
export async function GET(request: Request) {
|
||||
const ip = request.headers.get('x-forwarded-for') || 'unknown'
|
||||
|
||||
const allowed = await limiter.checkLimit(ip, 100, 60000) // 100 req/min
|
||||
|
||||
if (!allowed) {
|
||||
return NextResponse.json({
|
||||
error: 'Rate limit exceeded'
|
||||
}, { status: 429 })
|
||||
}
|
||||
|
||||
// Continue with request
|
||||
}
|
||||
```
|
||||
|
||||
## Background Jobs & Queues
|
||||
|
||||
### Simple Queue Pattern
|
||||
|
||||
```typescript
|
||||
class JobQueue<T> {
|
||||
private queue: T[] = []
|
||||
private processing = false
|
||||
|
||||
async add(job: T): Promise<void> {
|
||||
this.queue.push(job)
|
||||
|
||||
if (!this.processing) {
|
||||
this.process()
|
||||
}
|
||||
}
|
||||
|
||||
private async process(): Promise<void> {
|
||||
this.processing = true
|
||||
|
||||
while (this.queue.length > 0) {
|
||||
const job = this.queue.shift()!
|
||||
|
||||
try {
|
||||
await this.execute(job)
|
||||
} catch (error) {
|
||||
console.error('Job failed:', error)
|
||||
}
|
||||
}
|
||||
|
||||
this.processing = false
|
||||
}
|
||||
|
||||
private async execute(job: T): Promise<void> {
|
||||
// Job execution logic
|
||||
}
|
||||
}
|
||||
|
||||
// Usage for indexing markets
|
||||
interface IndexJob {
|
||||
marketId: string
|
||||
}
|
||||
|
||||
const indexQueue = new JobQueue<IndexJob>()
|
||||
|
||||
export async function POST(request: Request) {
|
||||
const { marketId } = await request.json()
|
||||
|
||||
// Add to queue instead of blocking
|
||||
await indexQueue.add({ marketId })
|
||||
|
||||
return NextResponse.json({ success: true, message: 'Job queued' })
|
||||
}
|
||||
```
|
||||
|
||||
## Logging & Monitoring
|
||||
|
||||
### Structured Logging
|
||||
|
||||
```typescript
|
||||
interface LogContext {
|
||||
userId?: string
|
||||
requestId?: string
|
||||
method?: string
|
||||
path?: string
|
||||
[key: string]: unknown
|
||||
}
|
||||
|
||||
class Logger {
|
||||
log(level: 'info' | 'warn' | 'error', message: string, context?: LogContext) {
|
||||
const entry = {
|
||||
timestamp: new Date().toISOString(),
|
||||
level,
|
||||
message,
|
||||
...context
|
||||
}
|
||||
|
||||
console.log(JSON.stringify(entry))
|
||||
}
|
||||
|
||||
info(message: string, context?: LogContext) {
|
||||
this.log('info', message, context)
|
||||
}
|
||||
|
||||
warn(message: string, context?: LogContext) {
|
||||
this.log('warn', message, context)
|
||||
}
|
||||
|
||||
error(message: string, error: Error, context?: LogContext) {
|
||||
this.log('error', message, {
|
||||
...context,
|
||||
error: error.message,
|
||||
stack: error.stack
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
const logger = new Logger()
|
||||
|
||||
// Usage
|
||||
export async function GET(request: Request) {
|
||||
const requestId = crypto.randomUUID()
|
||||
|
||||
logger.info('Fetching markets', {
|
||||
requestId,
|
||||
method: 'GET',
|
||||
path: '/api/markets'
|
||||
})
|
||||
|
||||
try {
|
||||
const markets = await fetchMarkets()
|
||||
return NextResponse.json({ success: true, data: markets })
|
||||
} catch (error) {
|
||||
logger.error('Failed to fetch markets', error as Error, { requestId })
|
||||
return NextResponse.json({ error: 'Internal error' }, { status: 500 })
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Remember**: Backend patterns enable scalable, maintainable server-side applications. Choose patterns that fit your complexity level.
|
||||
431
skills/cc-skill-clickhouse-io/SKILL.md
Normal file
431
skills/cc-skill-clickhouse-io/SKILL.md
Normal file
@@ -0,0 +1,431 @@
|
||||
---
|
||||
name: clickhouse-io
|
||||
description: ClickHouse database patterns, query optimization, analytics, and data engineering best practices for high-performance analytical workloads.
|
||||
author: affaan-m
|
||||
version: "1.0"
|
||||
---
|
||||
|
||||
# ClickHouse Analytics Patterns
|
||||
|
||||
ClickHouse-specific patterns for high-performance analytics and data engineering.
|
||||
|
||||
## Overview
|
||||
|
||||
ClickHouse is a column-oriented database management system (DBMS) for online analytical processing (OLAP). It's optimized for fast analytical queries on large datasets.
|
||||
|
||||
**Key Features:**
|
||||
- Column-oriented storage
|
||||
- Data compression
|
||||
- Parallel query execution
|
||||
- Distributed queries
|
||||
- Real-time analytics
|
||||
|
||||
## Table Design Patterns
|
||||
|
||||
### MergeTree Engine (Most Common)
|
||||
|
||||
```sql
|
||||
CREATE TABLE markets_analytics (
|
||||
date Date,
|
||||
market_id String,
|
||||
market_name String,
|
||||
volume UInt64,
|
||||
trades UInt32,
|
||||
unique_traders UInt32,
|
||||
avg_trade_size Float64,
|
||||
created_at DateTime
|
||||
) ENGINE = MergeTree()
|
||||
PARTITION BY toYYYYMM(date)
|
||||
ORDER BY (date, market_id)
|
||||
SETTINGS index_granularity = 8192;
|
||||
```
|
||||
|
||||
### ReplacingMergeTree (Deduplication)
|
||||
|
||||
```sql
|
||||
-- For data that may have duplicates (e.g., from multiple sources)
|
||||
CREATE TABLE user_events (
|
||||
event_id String,
|
||||
user_id String,
|
||||
event_type String,
|
||||
timestamp DateTime,
|
||||
properties String
|
||||
) ENGINE = ReplacingMergeTree()
|
||||
PARTITION BY toYYYYMM(timestamp)
|
||||
ORDER BY (user_id, event_id, timestamp)
|
||||
PRIMARY KEY (user_id, event_id);
|
||||
```
|
||||
|
||||
### AggregatingMergeTree (Pre-aggregation)
|
||||
|
||||
```sql
|
||||
-- For maintaining aggregated metrics
|
||||
CREATE TABLE market_stats_hourly (
|
||||
hour DateTime,
|
||||
market_id String,
|
||||
total_volume AggregateFunction(sum, UInt64),
|
||||
total_trades AggregateFunction(count, UInt32),
|
||||
unique_users AggregateFunction(uniq, String)
|
||||
) ENGINE = AggregatingMergeTree()
|
||||
PARTITION BY toYYYYMM(hour)
|
||||
ORDER BY (hour, market_id);
|
||||
|
||||
-- Query aggregated data
|
||||
SELECT
|
||||
hour,
|
||||
market_id,
|
||||
sumMerge(total_volume) AS volume,
|
||||
countMerge(total_trades) AS trades,
|
||||
uniqMerge(unique_users) AS users
|
||||
FROM market_stats_hourly
|
||||
WHERE hour >= toStartOfHour(now() - INTERVAL 24 HOUR)
|
||||
GROUP BY hour, market_id
|
||||
ORDER BY hour DESC;
|
||||
```
|
||||
|
||||
## Query Optimization Patterns
|
||||
|
||||
### Efficient Filtering
|
||||
|
||||
```sql
|
||||
-- ✅ GOOD: Use indexed columns first
|
||||
SELECT *
|
||||
FROM markets_analytics
|
||||
WHERE date >= '2025-01-01'
|
||||
AND market_id = 'market-123'
|
||||
AND volume > 1000
|
||||
ORDER BY date DESC
|
||||
LIMIT 100;
|
||||
|
||||
-- ❌ BAD: Filter on non-indexed columns first
|
||||
SELECT *
|
||||
FROM markets_analytics
|
||||
WHERE volume > 1000
|
||||
AND market_name LIKE '%election%'
|
||||
AND date >= '2025-01-01';
|
||||
```
|
||||
|
||||
### Aggregations
|
||||
|
||||
```sql
|
||||
-- ✅ GOOD: Use ClickHouse-specific aggregation functions
|
||||
SELECT
|
||||
toStartOfDay(created_at) AS day,
|
||||
market_id,
|
||||
sum(volume) AS total_volume,
|
||||
count() AS total_trades,
|
||||
uniq(trader_id) AS unique_traders,
|
||||
avg(trade_size) AS avg_size
|
||||
FROM trades
|
||||
WHERE created_at >= today() - INTERVAL 7 DAY
|
||||
GROUP BY day, market_id
|
||||
ORDER BY day DESC, total_volume DESC;
|
||||
|
||||
-- ✅ Use quantile for percentiles (more efficient than percentile)
|
||||
SELECT
|
||||
quantile(0.50)(trade_size) AS median,
|
||||
quantile(0.95)(trade_size) AS p95,
|
||||
quantile(0.99)(trade_size) AS p99
|
||||
FROM trades
|
||||
WHERE created_at >= now() - INTERVAL 1 HOUR;
|
||||
```
|
||||
|
||||
### Window Functions
|
||||
|
||||
```sql
|
||||
-- Calculate running totals
|
||||
SELECT
|
||||
date,
|
||||
market_id,
|
||||
volume,
|
||||
sum(volume) OVER (
|
||||
PARTITION BY market_id
|
||||
ORDER BY date
|
||||
ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
|
||||
) AS cumulative_volume
|
||||
FROM markets_analytics
|
||||
WHERE date >= today() - INTERVAL 30 DAY
|
||||
ORDER BY market_id, date;
|
||||
```
|
||||
|
||||
## Data Insertion Patterns
|
||||
|
||||
### Bulk Insert (Recommended)
|
||||
|
||||
```typescript
|
||||
import { ClickHouse } from 'clickhouse'
|
||||
|
||||
const clickhouse = new ClickHouse({
|
||||
url: process.env.CLICKHOUSE_URL,
|
||||
port: 8123,
|
||||
basicAuth: {
|
||||
username: process.env.CLICKHOUSE_USER,
|
||||
password: process.env.CLICKHOUSE_PASSWORD
|
||||
}
|
||||
})
|
||||
|
||||
// ✅ Batch insert (efficient)
|
||||
async function bulkInsertTrades(trades: Trade[]) {
|
||||
const values = trades.map(trade => `(
|
||||
'${trade.id}',
|
||||
'${trade.market_id}',
|
||||
'${trade.user_id}',
|
||||
${trade.amount},
|
||||
'${trade.timestamp.toISOString()}'
|
||||
)`).join(',')
|
||||
|
||||
await clickhouse.query(`
|
||||
INSERT INTO trades (id, market_id, user_id, amount, timestamp)
|
||||
VALUES ${values}
|
||||
`).toPromise()
|
||||
}
|
||||
|
||||
// ❌ Individual inserts (slow)
|
||||
async function insertTrade(trade: Trade) {
|
||||
// Don't do this in a loop!
|
||||
await clickhouse.query(`
|
||||
INSERT INTO trades VALUES ('${trade.id}', ...)
|
||||
`).toPromise()
|
||||
}
|
||||
```
|
||||
|
||||
### Streaming Insert
|
||||
|
||||
```typescript
|
||||
// For continuous data ingestion
|
||||
import { createWriteStream } from 'fs'
|
||||
import { pipeline } from 'stream/promises'
|
||||
|
||||
async function streamInserts() {
|
||||
const stream = clickhouse.insert('trades').stream()
|
||||
|
||||
for await (const batch of dataSource) {
|
||||
stream.write(batch)
|
||||
}
|
||||
|
||||
await stream.end()
|
||||
}
|
||||
```
|
||||
|
||||
## Materialized Views
|
||||
|
||||
### Real-time Aggregations
|
||||
|
||||
```sql
|
||||
-- Create materialized view for hourly stats
|
||||
CREATE MATERIALIZED VIEW market_stats_hourly_mv
|
||||
TO market_stats_hourly
|
||||
AS SELECT
|
||||
toStartOfHour(timestamp) AS hour,
|
||||
market_id,
|
||||
sumState(amount) AS total_volume,
|
||||
countState() AS total_trades,
|
||||
uniqState(user_id) AS unique_users
|
||||
FROM trades
|
||||
GROUP BY hour, market_id;
|
||||
|
||||
-- Query the materialized view
|
||||
SELECT
|
||||
hour,
|
||||
market_id,
|
||||
sumMerge(total_volume) AS volume,
|
||||
countMerge(total_trades) AS trades,
|
||||
uniqMerge(unique_users) AS users
|
||||
FROM market_stats_hourly
|
||||
WHERE hour >= now() - INTERVAL 24 HOUR
|
||||
GROUP BY hour, market_id;
|
||||
```
|
||||
|
||||
## Performance Monitoring
|
||||
|
||||
### Query Performance
|
||||
|
||||
```sql
|
||||
-- Check slow queries
|
||||
SELECT
|
||||
query_id,
|
||||
user,
|
||||
query,
|
||||
query_duration_ms,
|
||||
read_rows,
|
||||
read_bytes,
|
||||
memory_usage
|
||||
FROM system.query_log
|
||||
WHERE type = 'QueryFinish'
|
||||
AND query_duration_ms > 1000
|
||||
AND event_time >= now() - INTERVAL 1 HOUR
|
||||
ORDER BY query_duration_ms DESC
|
||||
LIMIT 10;
|
||||
```
|
||||
|
||||
### Table Statistics
|
||||
|
||||
```sql
|
||||
-- Check table sizes
|
||||
SELECT
|
||||
database,
|
||||
table,
|
||||
formatReadableSize(sum(bytes)) AS size,
|
||||
sum(rows) AS rows,
|
||||
max(modification_time) AS latest_modification
|
||||
FROM system.parts
|
||||
WHERE active
|
||||
GROUP BY database, table
|
||||
ORDER BY sum(bytes) DESC;
|
||||
```
|
||||
|
||||
## Common Analytics Queries
|
||||
|
||||
### Time Series Analysis
|
||||
|
||||
```sql
|
||||
-- Daily active users
|
||||
SELECT
|
||||
toDate(timestamp) AS date,
|
||||
uniq(user_id) AS daily_active_users
|
||||
FROM events
|
||||
WHERE timestamp >= today() - INTERVAL 30 DAY
|
||||
GROUP BY date
|
||||
ORDER BY date;
|
||||
|
||||
-- Retention analysis
|
||||
SELECT
|
||||
signup_date,
|
||||
countIf(days_since_signup = 0) AS day_0,
|
||||
countIf(days_since_signup = 1) AS day_1,
|
||||
countIf(days_since_signup = 7) AS day_7,
|
||||
countIf(days_since_signup = 30) AS day_30
|
||||
FROM (
|
||||
SELECT
|
||||
user_id,
|
||||
min(toDate(timestamp)) AS signup_date,
|
||||
toDate(timestamp) AS activity_date,
|
||||
dateDiff('day', signup_date, activity_date) AS days_since_signup
|
||||
FROM events
|
||||
GROUP BY user_id, activity_date
|
||||
)
|
||||
GROUP BY signup_date
|
||||
ORDER BY signup_date DESC;
|
||||
```
|
||||
|
||||
### Funnel Analysis
|
||||
|
||||
```sql
|
||||
-- Conversion funnel
|
||||
SELECT
|
||||
countIf(step = 'viewed_market') AS viewed,
|
||||
countIf(step = 'clicked_trade') AS clicked,
|
||||
countIf(step = 'completed_trade') AS completed,
|
||||
round(clicked / viewed * 100, 2) AS view_to_click_rate,
|
||||
round(completed / clicked * 100, 2) AS click_to_completion_rate
|
||||
FROM (
|
||||
SELECT
|
||||
user_id,
|
||||
session_id,
|
||||
event_type AS step
|
||||
FROM events
|
||||
WHERE event_date = today()
|
||||
)
|
||||
GROUP BY session_id;
|
||||
```
|
||||
|
||||
### Cohort Analysis
|
||||
|
||||
```sql
|
||||
-- User cohorts by signup month
|
||||
SELECT
|
||||
toStartOfMonth(signup_date) AS cohort,
|
||||
toStartOfMonth(activity_date) AS month,
|
||||
dateDiff('month', cohort, month) AS months_since_signup,
|
||||
count(DISTINCT user_id) AS active_users
|
||||
FROM (
|
||||
SELECT
|
||||
user_id,
|
||||
min(toDate(timestamp)) OVER (PARTITION BY user_id) AS signup_date,
|
||||
toDate(timestamp) AS activity_date
|
||||
FROM events
|
||||
)
|
||||
GROUP BY cohort, month, months_since_signup
|
||||
ORDER BY cohort, months_since_signup;
|
||||
```
|
||||
|
||||
## Data Pipeline Patterns
|
||||
|
||||
### ETL Pattern
|
||||
|
||||
```typescript
|
||||
// Extract, Transform, Load
|
||||
async function etlPipeline() {
|
||||
// 1. Extract from source
|
||||
const rawData = await extractFromPostgres()
|
||||
|
||||
// 2. Transform
|
||||
const transformed = rawData.map(row => ({
|
||||
date: new Date(row.created_at).toISOString().split('T')[0],
|
||||
market_id: row.market_slug,
|
||||
volume: parseFloat(row.total_volume),
|
||||
trades: parseInt(row.trade_count)
|
||||
}))
|
||||
|
||||
// 3. Load to ClickHouse
|
||||
await bulkInsertToClickHouse(transformed)
|
||||
}
|
||||
|
||||
// Run periodically
|
||||
setInterval(etlPipeline, 60 * 60 * 1000) // Every hour
|
||||
```
|
||||
|
||||
### Change Data Capture (CDC)
|
||||
|
||||
```typescript
|
||||
// Listen to PostgreSQL changes and sync to ClickHouse
|
||||
import { Client } from 'pg'
|
||||
|
||||
const pgClient = new Client({ connectionString: process.env.DATABASE_URL })
|
||||
|
||||
pgClient.query('LISTEN market_updates')
|
||||
|
||||
pgClient.on('notification', async (msg) => {
|
||||
const update = JSON.parse(msg.payload)
|
||||
|
||||
await clickhouse.insert('market_updates', [
|
||||
{
|
||||
market_id: update.id,
|
||||
event_type: update.operation, // INSERT, UPDATE, DELETE
|
||||
timestamp: new Date(),
|
||||
data: JSON.stringify(update.new_data)
|
||||
}
|
||||
])
|
||||
})
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Partitioning Strategy
|
||||
- Partition by time (usually month or day)
|
||||
- Avoid too many partitions (performance impact)
|
||||
- Use DATE type for partition key
|
||||
|
||||
### 2. Ordering Key
|
||||
- Put most frequently filtered columns first
|
||||
- Consider cardinality (high cardinality first)
|
||||
- Order impacts compression
|
||||
|
||||
### 3. Data Types
|
||||
- Use smallest appropriate type (UInt32 vs UInt64)
|
||||
- Use LowCardinality for repeated strings
|
||||
- Use Enum for categorical data
|
||||
|
||||
### 4. Avoid
|
||||
- SELECT * (specify columns)
|
||||
- FINAL (merge data before query instead)
|
||||
- Too many JOINs (denormalize for analytics)
|
||||
- Small frequent inserts (batch instead)
|
||||
|
||||
### 5. Monitoring
|
||||
- Track query performance
|
||||
- Monitor disk usage
|
||||
- Check merge operations
|
||||
- Review slow query log
|
||||
|
||||
**Remember**: ClickHouse excels at analytical workloads. Design tables for your query patterns, batch inserts, and leverage materialized views for real-time aggregations.
|
||||
522
skills/cc-skill-coding-standards/SKILL.md
Normal file
522
skills/cc-skill-coding-standards/SKILL.md
Normal file
@@ -0,0 +1,522 @@
|
||||
---
|
||||
name: coding-standards
|
||||
description: Universal coding standards, best practices, and patterns for TypeScript, JavaScript, React, and Node.js development.
|
||||
author: affaan-m
|
||||
version: "1.0"
|
||||
---
|
||||
|
||||
# Coding Standards & Best Practices
|
||||
|
||||
Universal coding standards applicable across all projects.
|
||||
|
||||
## Code Quality Principles
|
||||
|
||||
### 1. Readability First
|
||||
- Code is read more than written
|
||||
- Clear variable and function names
|
||||
- Self-documenting code preferred over comments
|
||||
- Consistent formatting
|
||||
|
||||
### 2. KISS (Keep It Simple, Stupid)
|
||||
- Simplest solution that works
|
||||
- Avoid over-engineering
|
||||
- No premature optimization
|
||||
- Easy to understand > clever code
|
||||
|
||||
### 3. DRY (Don't Repeat Yourself)
|
||||
- Extract common logic into functions
|
||||
- Create reusable components
|
||||
- Share utilities across modules
|
||||
- Avoid copy-paste programming
|
||||
|
||||
### 4. YAGNI (You Aren't Gonna Need It)
|
||||
- Don't build features before they're needed
|
||||
- Avoid speculative generality
|
||||
- Add complexity only when required
|
||||
- Start simple, refactor when needed
|
||||
|
||||
## TypeScript/JavaScript Standards
|
||||
|
||||
### Variable Naming
|
||||
|
||||
```typescript
|
||||
// ✅ GOOD: Descriptive names
|
||||
const marketSearchQuery = 'election'
|
||||
const isUserAuthenticated = true
|
||||
const totalRevenue = 1000
|
||||
|
||||
// ❌ BAD: Unclear names
|
||||
const q = 'election'
|
||||
const flag = true
|
||||
const x = 1000
|
||||
```
|
||||
|
||||
### Function Naming
|
||||
|
||||
```typescript
|
||||
// ✅ GOOD: Verb-noun pattern
|
||||
async function fetchMarketData(marketId: string) { }
|
||||
function calculateSimilarity(a: number[], b: number[]) { }
|
||||
function isValidEmail(email: string): boolean { }
|
||||
|
||||
// ❌ BAD: Unclear or noun-only
|
||||
async function market(id: string) { }
|
||||
function similarity(a, b) { }
|
||||
function email(e) { }
|
||||
```
|
||||
|
||||
### Immutability Pattern (CRITICAL)
|
||||
|
||||
```typescript
|
||||
// ✅ ALWAYS use spread operator
|
||||
const updatedUser = {
|
||||
...user,
|
||||
name: 'New Name'
|
||||
}
|
||||
|
||||
const updatedArray = [...items, newItem]
|
||||
|
||||
// ❌ NEVER mutate directly
|
||||
user.name = 'New Name' // BAD
|
||||
items.push(newItem) // BAD
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
```typescript
|
||||
// ✅ GOOD: Comprehensive error handling
|
||||
async function fetchData(url: string) {
|
||||
try {
|
||||
const response = await fetch(url)
|
||||
|
||||
if (!response.ok) {
|
||||
throw new Error(`HTTP ${response.status}: ${response.statusText}`)
|
||||
}
|
||||
|
||||
return await response.json()
|
||||
} catch (error) {
|
||||
console.error('Fetch failed:', error)
|
||||
throw new Error('Failed to fetch data')
|
||||
}
|
||||
}
|
||||
|
||||
// ❌ BAD: No error handling
|
||||
async function fetchData(url) {
|
||||
const response = await fetch(url)
|
||||
return response.json()
|
||||
}
|
||||
```
|
||||
|
||||
### Async/Await Best Practices
|
||||
|
||||
```typescript
|
||||
// ✅ GOOD: Parallel execution when possible
|
||||
const [users, markets, stats] = await Promise.all([
|
||||
fetchUsers(),
|
||||
fetchMarkets(),
|
||||
fetchStats()
|
||||
])
|
||||
|
||||
// ❌ BAD: Sequential when unnecessary
|
||||
const users = await fetchUsers()
|
||||
const markets = await fetchMarkets()
|
||||
const stats = await fetchStats()
|
||||
```
|
||||
|
||||
### Type Safety
|
||||
|
||||
```typescript
|
||||
// ✅ GOOD: Proper types
|
||||
interface Market {
|
||||
id: string
|
||||
name: string
|
||||
status: 'active' | 'resolved' | 'closed'
|
||||
created_at: Date
|
||||
}
|
||||
|
||||
function getMarket(id: string): Promise<Market> {
|
||||
// Implementation
|
||||
}
|
||||
|
||||
// ❌ BAD: Using 'any'
|
||||
function getMarket(id: any): Promise<any> {
|
||||
// Implementation
|
||||
}
|
||||
```
|
||||
|
||||
## React Best Practices
|
||||
|
||||
### Component Structure
|
||||
|
||||
```typescript
|
||||
// ✅ GOOD: Functional component with types
|
||||
interface ButtonProps {
|
||||
children: React.ReactNode
|
||||
onClick: () => void
|
||||
disabled?: boolean
|
||||
variant?: 'primary' | 'secondary'
|
||||
}
|
||||
|
||||
export function Button({
|
||||
children,
|
||||
onClick,
|
||||
disabled = false,
|
||||
variant = 'primary'
|
||||
}: ButtonProps) {
|
||||
return (
|
||||
<button
|
||||
onClick={onClick}
|
||||
disabled={disabled}
|
||||
className={`btn btn-${variant}`}
|
||||
>
|
||||
{children}
|
||||
</button>
|
||||
)
|
||||
}
|
||||
|
||||
// ❌ BAD: No types, unclear structure
|
||||
export function Button(props) {
|
||||
return <button onClick={props.onClick}>{props.children}</button>
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Hooks
|
||||
|
||||
```typescript
|
||||
// ✅ GOOD: Reusable custom hook
|
||||
export function useDebounce<T>(value: T, delay: number): T {
|
||||
const [debouncedValue, setDebouncedValue] = useState<T>(value)
|
||||
|
||||
useEffect(() => {
|
||||
const handler = setTimeout(() => {
|
||||
setDebouncedValue(value)
|
||||
}, delay)
|
||||
|
||||
return () => clearTimeout(handler)
|
||||
}, [value, delay])
|
||||
|
||||
return debouncedValue
|
||||
}
|
||||
|
||||
// Usage
|
||||
const debouncedQuery = useDebounce(searchQuery, 500)
|
||||
```
|
||||
|
||||
### State Management
|
||||
|
||||
```typescript
|
||||
// ✅ GOOD: Proper state updates
|
||||
const [count, setCount] = useState(0)
|
||||
|
||||
// Functional update for state based on previous state
|
||||
setCount(prev => prev + 1)
|
||||
|
||||
// ❌ BAD: Direct state reference
|
||||
setCount(count + 1) // Can be stale in async scenarios
|
||||
```
|
||||
|
||||
### Conditional Rendering
|
||||
|
||||
```typescript
|
||||
// ✅ GOOD: Clear conditional rendering
|
||||
{isLoading && <Spinner />}
|
||||
{error && <ErrorMessage error={error} />}
|
||||
{data && <DataDisplay data={data} />}
|
||||
|
||||
// ❌ BAD: Ternary hell
|
||||
{isLoading ? <Spinner /> : error ? <ErrorMessage error={error} /> : data ? <DataDisplay data={data} /> : null}
|
||||
```
|
||||
|
||||
## API Design Standards
|
||||
|
||||
### REST API Conventions
|
||||
|
||||
```
|
||||
GET /api/markets # List all markets
|
||||
GET /api/markets/:id # Get specific market
|
||||
POST /api/markets # Create new market
|
||||
PUT /api/markets/:id # Update market (full)
|
||||
PATCH /api/markets/:id # Update market (partial)
|
||||
DELETE /api/markets/:id # Delete market
|
||||
|
||||
# Query parameters for filtering
|
||||
GET /api/markets?status=active&limit=10&offset=0
|
||||
```
|
||||
|
||||
### Response Format
|
||||
|
||||
```typescript
|
||||
// ✅ GOOD: Consistent response structure
|
||||
interface ApiResponse<T> {
|
||||
success: boolean
|
||||
data?: T
|
||||
error?: string
|
||||
meta?: {
|
||||
total: number
|
||||
page: number
|
||||
limit: number
|
||||
}
|
||||
}
|
||||
|
||||
// Success response
|
||||
return NextResponse.json({
|
||||
success: true,
|
||||
data: markets,
|
||||
meta: { total: 100, page: 1, limit: 10 }
|
||||
})
|
||||
|
||||
// Error response
|
||||
return NextResponse.json({
|
||||
success: false,
|
||||
error: 'Invalid request'
|
||||
}, { status: 400 })
|
||||
```
|
||||
|
||||
### Input Validation
|
||||
|
||||
```typescript
|
||||
import { z } from 'zod'
|
||||
|
||||
// ✅ GOOD: Schema validation
|
||||
const CreateMarketSchema = z.object({
|
||||
name: z.string().min(1).max(200),
|
||||
description: z.string().min(1).max(2000),
|
||||
endDate: z.string().datetime(),
|
||||
categories: z.array(z.string()).min(1)
|
||||
})
|
||||
|
||||
export async function POST(request: Request) {
|
||||
const body = await request.json()
|
||||
|
||||
try {
|
||||
const validated = CreateMarketSchema.parse(body)
|
||||
// Proceed with validated data
|
||||
} catch (error) {
|
||||
if (error instanceof z.ZodError) {
|
||||
return NextResponse.json({
|
||||
success: false,
|
||||
error: 'Validation failed',
|
||||
details: error.errors
|
||||
}, { status: 400 })
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## File Organization
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── app/ # Next.js App Router
|
||||
│ ├── api/ # API routes
|
||||
│ ├── markets/ # Market pages
|
||||
│ └── (auth)/ # Auth pages (route groups)
|
||||
├── components/ # React components
|
||||
│ ├── ui/ # Generic UI components
|
||||
│ ├── forms/ # Form components
|
||||
│ └── layouts/ # Layout components
|
||||
├── hooks/ # Custom React hooks
|
||||
├── lib/ # Utilities and configs
|
||||
│ ├── api/ # API clients
|
||||
│ ├── utils/ # Helper functions
|
||||
│ └── constants/ # Constants
|
||||
├── types/ # TypeScript types
|
||||
└── styles/ # Global styles
|
||||
```
|
||||
|
||||
### File Naming
|
||||
|
||||
```
|
||||
components/Button.tsx # PascalCase for components
|
||||
hooks/useAuth.ts # camelCase with 'use' prefix
|
||||
lib/formatDate.ts # camelCase for utilities
|
||||
types/market.types.ts # camelCase with .types suffix
|
||||
```
|
||||
|
||||
## Comments & Documentation
|
||||
|
||||
### When to Comment
|
||||
|
||||
```typescript
|
||||
// ✅ GOOD: Explain WHY, not WHAT
|
||||
// Use exponential backoff to avoid overwhelming the API during outages
|
||||
const delay = Math.min(1000 * Math.pow(2, retryCount), 30000)
|
||||
|
||||
// Deliberately using mutation here for performance with large arrays
|
||||
items.push(newItem)
|
||||
|
||||
// ❌ BAD: Stating the obvious
|
||||
// Increment counter by 1
|
||||
count++
|
||||
|
||||
// Set name to user's name
|
||||
name = user.name
|
||||
```
|
||||
|
||||
### JSDoc for Public APIs
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* Searches markets using semantic similarity.
|
||||
*
|
||||
* @param query - Natural language search query
|
||||
* @param limit - Maximum number of results (default: 10)
|
||||
* @returns Array of markets sorted by similarity score
|
||||
* @throws {Error} If OpenAI API fails or Redis unavailable
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const results = await searchMarkets('election', 5)
|
||||
* console.log(results[0].name) // "Trump vs Biden"
|
||||
* ```
|
||||
*/
|
||||
export async function searchMarkets(
|
||||
query: string,
|
||||
limit: number = 10
|
||||
): Promise<Market[]> {
|
||||
// Implementation
|
||||
}
|
||||
```
|
||||
|
||||
## Performance Best Practices
|
||||
|
||||
### Memoization
|
||||
|
||||
```typescript
|
||||
import { useMemo, useCallback } from 'react'
|
||||
|
||||
// ✅ GOOD: Memoize expensive computations
|
||||
const sortedMarkets = useMemo(() => {
|
||||
return markets.sort((a, b) => b.volume - a.volume)
|
||||
}, [markets])
|
||||
|
||||
// ✅ GOOD: Memoize callbacks
|
||||
const handleSearch = useCallback((query: string) => {
|
||||
setSearchQuery(query)
|
||||
}, [])
|
||||
```
|
||||
|
||||
### Lazy Loading
|
||||
|
||||
```typescript
|
||||
import { lazy, Suspense } from 'react'
|
||||
|
||||
// ✅ GOOD: Lazy load heavy components
|
||||
const HeavyChart = lazy(() => import('./HeavyChart'))
|
||||
|
||||
export function Dashboard() {
|
||||
return (
|
||||
<Suspense fallback={<Spinner />}>
|
||||
<HeavyChart />
|
||||
</Suspense>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Database Queries
|
||||
|
||||
```typescript
|
||||
// ✅ GOOD: Select only needed columns
|
||||
const { data } = await supabase
|
||||
.from('markets')
|
||||
.select('id, name, status')
|
||||
.limit(10)
|
||||
|
||||
// ❌ BAD: Select everything
|
||||
const { data } = await supabase
|
||||
.from('markets')
|
||||
.select('*')
|
||||
```
|
||||
|
||||
## Testing Standards
|
||||
|
||||
### Test Structure (AAA Pattern)
|
||||
|
||||
```typescript
|
||||
test('calculates similarity correctly', () => {
|
||||
// Arrange
|
||||
const vector1 = [1, 0, 0]
|
||||
const vector2 = [0, 1, 0]
|
||||
|
||||
// Act
|
||||
const similarity = calculateCosineSimilarity(vector1, vector2)
|
||||
|
||||
// Assert
|
||||
expect(similarity).toBe(0)
|
||||
})
|
||||
```
|
||||
|
||||
### Test Naming
|
||||
|
||||
```typescript
|
||||
// ✅ GOOD: Descriptive test names
|
||||
test('returns empty array when no markets match query', () => { })
|
||||
test('throws error when OpenAI API key is missing', () => { })
|
||||
test('falls back to substring search when Redis unavailable', () => { })
|
||||
|
||||
// ❌ BAD: Vague test names
|
||||
test('works', () => { })
|
||||
test('test search', () => { })
|
||||
```
|
||||
|
||||
## Code Smell Detection
|
||||
|
||||
Watch for these anti-patterns:
|
||||
|
||||
### 1. Long Functions
|
||||
```typescript
|
||||
// ❌ BAD: Function > 50 lines
|
||||
function processMarketData() {
|
||||
// 100 lines of code
|
||||
}
|
||||
|
||||
// ✅ GOOD: Split into smaller functions
|
||||
function processMarketData() {
|
||||
const validated = validateData()
|
||||
const transformed = transformData(validated)
|
||||
return saveData(transformed)
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Deep Nesting
|
||||
```typescript
|
||||
// ❌ BAD: 5+ levels of nesting
|
||||
if (user) {
|
||||
if (user.isAdmin) {
|
||||
if (market) {
|
||||
if (market.isActive) {
|
||||
if (hasPermission) {
|
||||
// Do something
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ✅ GOOD: Early returns
|
||||
if (!user) return
|
||||
if (!user.isAdmin) return
|
||||
if (!market) return
|
||||
if (!market.isActive) return
|
||||
if (!hasPermission) return
|
||||
|
||||
// Do something
|
||||
```
|
||||
|
||||
### 3. Magic Numbers
|
||||
```typescript
|
||||
// ❌ BAD: Unexplained numbers
|
||||
if (retryCount > 3) { }
|
||||
setTimeout(callback, 500)
|
||||
|
||||
// ✅ GOOD: Named constants
|
||||
const MAX_RETRIES = 3
|
||||
const DEBOUNCE_DELAY_MS = 500
|
||||
|
||||
if (retryCount > MAX_RETRIES) { }
|
||||
setTimeout(callback, DEBOUNCE_DELAY_MS)
|
||||
```
|
||||
|
||||
**Remember**: Code quality is not negotiable. Clear, maintainable code enables rapid development and confident refactoring.
|
||||
10
skills/cc-skill-continuous-learning/SKILL.md
Normal file
10
skills/cc-skill-continuous-learning/SKILL.md
Normal file
@@ -0,0 +1,10 @@
|
||||
---
|
||||
name: cc-skill-continuous-learning
|
||||
description: Development skill skill from everything-claude-code
|
||||
author: affaan-m
|
||||
version: "1.0"
|
||||
---
|
||||
|
||||
# cc-skill-continuous-learning
|
||||
|
||||
Development skill skill.
|
||||
18
skills/cc-skill-continuous-learning/config.json
Normal file
18
skills/cc-skill-continuous-learning/config.json
Normal file
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"min_session_length": 10,
|
||||
"extraction_threshold": "medium",
|
||||
"auto_approve": false,
|
||||
"learned_skills_path": "~/.claude/skills/learned/",
|
||||
"patterns_to_detect": [
|
||||
"error_resolution",
|
||||
"user_corrections",
|
||||
"workarounds",
|
||||
"debugging_techniques",
|
||||
"project_specific"
|
||||
],
|
||||
"ignore_patterns": [
|
||||
"simple_typos",
|
||||
"one_time_fixes",
|
||||
"external_api_issues"
|
||||
]
|
||||
}
|
||||
60
skills/cc-skill-continuous-learning/evaluate-session.sh
Executable file
60
skills/cc-skill-continuous-learning/evaluate-session.sh
Executable file
@@ -0,0 +1,60 @@
|
||||
#!/bin/bash
|
||||
# Continuous Learning - Session Evaluator
|
||||
# Runs on Stop hook to extract reusable patterns from Claude Code sessions
|
||||
#
|
||||
# Why Stop hook instead of UserPromptSubmit:
|
||||
# - Stop runs once at session end (lightweight)
|
||||
# - UserPromptSubmit runs every message (heavy, adds latency)
|
||||
#
|
||||
# Hook config (in ~/.claude/settings.json):
|
||||
# {
|
||||
# "hooks": {
|
||||
# "Stop": [{
|
||||
# "matcher": "*",
|
||||
# "hooks": [{
|
||||
# "type": "command",
|
||||
# "command": "~/.claude/skills/continuous-learning/evaluate-session.sh"
|
||||
# }]
|
||||
# }]
|
||||
# }
|
||||
# }
|
||||
#
|
||||
# Patterns to detect: error_resolution, debugging_techniques, workarounds, project_specific
|
||||
# Patterns to ignore: simple_typos, one_time_fixes, external_api_issues
|
||||
# Extracted skills saved to: ~/.claude/skills/learned/
|
||||
|
||||
set -e
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
CONFIG_FILE="$SCRIPT_DIR/config.json"
|
||||
LEARNED_SKILLS_PATH="${HOME}/.claude/skills/learned"
|
||||
MIN_SESSION_LENGTH=10
|
||||
|
||||
# Load config if exists
|
||||
if [ -f "$CONFIG_FILE" ]; then
|
||||
MIN_SESSION_LENGTH=$(jq -r '.min_session_length // 10' "$CONFIG_FILE")
|
||||
LEARNED_SKILLS_PATH=$(jq -r '.learned_skills_path // "~/.claude/skills/learned/"' "$CONFIG_FILE" | sed "s|~|$HOME|")
|
||||
fi
|
||||
|
||||
# Ensure learned skills directory exists
|
||||
mkdir -p "$LEARNED_SKILLS_PATH"
|
||||
|
||||
# Get transcript path from environment (set by Claude Code)
|
||||
transcript_path="${CLAUDE_TRANSCRIPT_PATH:-}"
|
||||
|
||||
if [ -z "$transcript_path" ] || [ ! -f "$transcript_path" ]; then
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Count messages in session
|
||||
message_count=$(grep -c '"type":"user"' "$transcript_path" 2>/dev/null || echo "0")
|
||||
|
||||
# Skip short sessions
|
||||
if [ "$message_count" -lt "$MIN_SESSION_LENGTH" ]; then
|
||||
echo "[ContinuousLearning] Session too short ($message_count messages), skipping" >&2
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Signal to Claude that session should be evaluated for extractable patterns
|
||||
echo "[ContinuousLearning] Session has $message_count messages - evaluate for extractable patterns" >&2
|
||||
echo "[ContinuousLearning] Save learned skills to: $LEARNED_SKILLS_PATH" >&2
|
||||
633
skills/cc-skill-frontend-patterns/SKILL.md
Normal file
633
skills/cc-skill-frontend-patterns/SKILL.md
Normal file
@@ -0,0 +1,633 @@
|
||||
---
|
||||
name: frontend-patterns
|
||||
description: Frontend development patterns for React, Next.js, state management, performance optimization, and UI best practices.
|
||||
author: affaan-m
|
||||
version: "1.0"
|
||||
---
|
||||
|
||||
# Frontend Development Patterns
|
||||
|
||||
Modern frontend patterns for React, Next.js, and performant user interfaces.
|
||||
|
||||
## Component Patterns
|
||||
|
||||
### Composition Over Inheritance
|
||||
|
||||
```typescript
|
||||
// ✅ GOOD: Component composition
|
||||
interface CardProps {
|
||||
children: React.ReactNode
|
||||
variant?: 'default' | 'outlined'
|
||||
}
|
||||
|
||||
export function Card({ children, variant = 'default' }: CardProps) {
|
||||
return <div className={`card card-${variant}`}>{children}</div>
|
||||
}
|
||||
|
||||
export function CardHeader({ children }: { children: React.ReactNode }) {
|
||||
return <div className="card-header">{children}</div>
|
||||
}
|
||||
|
||||
export function CardBody({ children }: { children: React.ReactNode }) {
|
||||
return <div className="card-body">{children}</div>
|
||||
}
|
||||
|
||||
// Usage
|
||||
<Card>
|
||||
<CardHeader>Title</CardHeader>
|
||||
<CardBody>Content</CardBody>
|
||||
</Card>
|
||||
```
|
||||
|
||||
### Compound Components
|
||||
|
||||
```typescript
|
||||
interface TabsContextValue {
|
||||
activeTab: string
|
||||
setActiveTab: (tab: string) => void
|
||||
}
|
||||
|
||||
const TabsContext = createContext<TabsContextValue | undefined>(undefined)
|
||||
|
||||
export function Tabs({ children, defaultTab }: {
|
||||
children: React.ReactNode
|
||||
defaultTab: string
|
||||
}) {
|
||||
const [activeTab, setActiveTab] = useState(defaultTab)
|
||||
|
||||
return (
|
||||
<TabsContext.Provider value={{ activeTab, setActiveTab }}>
|
||||
{children}
|
||||
</TabsContext.Provider>
|
||||
)
|
||||
}
|
||||
|
||||
export function TabList({ children }: { children: React.ReactNode }) {
|
||||
return <div className="tab-list">{children}</div>
|
||||
}
|
||||
|
||||
export function Tab({ id, children }: { id: string, children: React.ReactNode }) {
|
||||
const context = useContext(TabsContext)
|
||||
if (!context) throw new Error('Tab must be used within Tabs')
|
||||
|
||||
return (
|
||||
<button
|
||||
className={context.activeTab === id ? 'active' : ''}
|
||||
onClick={() => context.setActiveTab(id)}
|
||||
>
|
||||
{children}
|
||||
</button>
|
||||
)
|
||||
}
|
||||
|
||||
// Usage
|
||||
<Tabs defaultTab="overview">
|
||||
<TabList>
|
||||
<Tab id="overview">Overview</Tab>
|
||||
<Tab id="details">Details</Tab>
|
||||
</TabList>
|
||||
</Tabs>
|
||||
```
|
||||
|
||||
### Render Props Pattern
|
||||
|
||||
```typescript
|
||||
interface DataLoaderProps<T> {
|
||||
url: string
|
||||
children: (data: T | null, loading: boolean, error: Error | null) => React.ReactNode
|
||||
}
|
||||
|
||||
export function DataLoader<T>({ url, children }: DataLoaderProps<T>) {
|
||||
const [data, setData] = useState<T | null>(null)
|
||||
const [loading, setLoading] = useState(true)
|
||||
const [error, setError] = useState<Error | null>(null)
|
||||
|
||||
useEffect(() => {
|
||||
fetch(url)
|
||||
.then(res => res.json())
|
||||
.then(setData)
|
||||
.catch(setError)
|
||||
.finally(() => setLoading(false))
|
||||
}, [url])
|
||||
|
||||
return <>{children(data, loading, error)}</>
|
||||
}
|
||||
|
||||
// Usage
|
||||
<DataLoader<Market[]> url="/api/markets">
|
||||
{(markets, loading, error) => {
|
||||
if (loading) return <Spinner />
|
||||
if (error) return <Error error={error} />
|
||||
return <MarketList markets={markets!} />
|
||||
}}
|
||||
</DataLoader>
|
||||
```
|
||||
|
||||
## Custom Hooks Patterns
|
||||
|
||||
### State Management Hook
|
||||
|
||||
```typescript
|
||||
export function useToggle(initialValue = false): [boolean, () => void] {
|
||||
const [value, setValue] = useState(initialValue)
|
||||
|
||||
const toggle = useCallback(() => {
|
||||
setValue(v => !v)
|
||||
}, [])
|
||||
|
||||
return [value, toggle]
|
||||
}
|
||||
|
||||
// Usage
|
||||
const [isOpen, toggleOpen] = useToggle()
|
||||
```
|
||||
|
||||
### Async Data Fetching Hook
|
||||
|
||||
```typescript
|
||||
interface UseQueryOptions<T> {
|
||||
onSuccess?: (data: T) => void
|
||||
onError?: (error: Error) => void
|
||||
enabled?: boolean
|
||||
}
|
||||
|
||||
export function useQuery<T>(
|
||||
key: string,
|
||||
fetcher: () => Promise<T>,
|
||||
options?: UseQueryOptions<T>
|
||||
) {
|
||||
const [data, setData] = useState<T | null>(null)
|
||||
const [error, setError] = useState<Error | null>(null)
|
||||
const [loading, setLoading] = useState(false)
|
||||
|
||||
const refetch = useCallback(async () => {
|
||||
setLoading(true)
|
||||
setError(null)
|
||||
|
||||
try {
|
||||
const result = await fetcher()
|
||||
setData(result)
|
||||
options?.onSuccess?.(result)
|
||||
} catch (err) {
|
||||
const error = err as Error
|
||||
setError(error)
|
||||
options?.onError?.(error)
|
||||
} finally {
|
||||
setLoading(false)
|
||||
}
|
||||
}, [fetcher, options])
|
||||
|
||||
useEffect(() => {
|
||||
if (options?.enabled !== false) {
|
||||
refetch()
|
||||
}
|
||||
}, [key, refetch, options?.enabled])
|
||||
|
||||
return { data, error, loading, refetch }
|
||||
}
|
||||
|
||||
// Usage
|
||||
const { data: markets, loading, error, refetch } = useQuery(
|
||||
'markets',
|
||||
() => fetch('/api/markets').then(r => r.json()),
|
||||
{
|
||||
onSuccess: data => console.log('Fetched', data.length, 'markets'),
|
||||
onError: err => console.error('Failed:', err)
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Debounce Hook
|
||||
|
||||
```typescript
|
||||
export function useDebounce<T>(value: T, delay: number): T {
|
||||
const [debouncedValue, setDebouncedValue] = useState<T>(value)
|
||||
|
||||
useEffect(() => {
|
||||
const handler = setTimeout(() => {
|
||||
setDebouncedValue(value)
|
||||
}, delay)
|
||||
|
||||
return () => clearTimeout(handler)
|
||||
}, [value, delay])
|
||||
|
||||
return debouncedValue
|
||||
}
|
||||
|
||||
// Usage
|
||||
const [searchQuery, setSearchQuery] = useState('')
|
||||
const debouncedQuery = useDebounce(searchQuery, 500)
|
||||
|
||||
useEffect(() => {
|
||||
if (debouncedQuery) {
|
||||
performSearch(debouncedQuery)
|
||||
}
|
||||
}, [debouncedQuery])
|
||||
```
|
||||
|
||||
## State Management Patterns
|
||||
|
||||
### Context + Reducer Pattern
|
||||
|
||||
```typescript
|
||||
interface State {
|
||||
markets: Market[]
|
||||
selectedMarket: Market | null
|
||||
loading: boolean
|
||||
}
|
||||
|
||||
type Action =
|
||||
| { type: 'SET_MARKETS'; payload: Market[] }
|
||||
| { type: 'SELECT_MARKET'; payload: Market }
|
||||
| { type: 'SET_LOADING'; payload: boolean }
|
||||
|
||||
function reducer(state: State, action: Action): State {
|
||||
switch (action.type) {
|
||||
case 'SET_MARKETS':
|
||||
return { ...state, markets: action.payload }
|
||||
case 'SELECT_MARKET':
|
||||
return { ...state, selectedMarket: action.payload }
|
||||
case 'SET_LOADING':
|
||||
return { ...state, loading: action.payload }
|
||||
default:
|
||||
return state
|
||||
}
|
||||
}
|
||||
|
||||
const MarketContext = createContext<{
|
||||
state: State
|
||||
dispatch: Dispatch<Action>
|
||||
} | undefined>(undefined)
|
||||
|
||||
export function MarketProvider({ children }: { children: React.ReactNode }) {
|
||||
const [state, dispatch] = useReducer(reducer, {
|
||||
markets: [],
|
||||
selectedMarket: null,
|
||||
loading: false
|
||||
})
|
||||
|
||||
return (
|
||||
<MarketContext.Provider value={{ state, dispatch }}>
|
||||
{children}
|
||||
</MarketContext.Provider>
|
||||
)
|
||||
}
|
||||
|
||||
export function useMarkets() {
|
||||
const context = useContext(MarketContext)
|
||||
if (!context) throw new Error('useMarkets must be used within MarketProvider')
|
||||
return context
|
||||
}
|
||||
```
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Memoization
|
||||
|
||||
```typescript
|
||||
// ✅ useMemo for expensive computations
|
||||
const sortedMarkets = useMemo(() => {
|
||||
return markets.sort((a, b) => b.volume - a.volume)
|
||||
}, [markets])
|
||||
|
||||
// ✅ useCallback for functions passed to children
|
||||
const handleSearch = useCallback((query: string) => {
|
||||
setSearchQuery(query)
|
||||
}, [])
|
||||
|
||||
// ✅ React.memo for pure components
|
||||
export const MarketCard = React.memo<MarketCardProps>(({ market }) => {
|
||||
return (
|
||||
<div className="market-card">
|
||||
<h3>{market.name}</h3>
|
||||
<p>{market.description}</p>
|
||||
</div>
|
||||
)
|
||||
})
|
||||
```
|
||||
|
||||
### Code Splitting & Lazy Loading
|
||||
|
||||
```typescript
|
||||
import { lazy, Suspense } from 'react'
|
||||
|
||||
// ✅ Lazy load heavy components
|
||||
const HeavyChart = lazy(() => import('./HeavyChart'))
|
||||
const ThreeJsBackground = lazy(() => import('./ThreeJsBackground'))
|
||||
|
||||
export function Dashboard() {
|
||||
return (
|
||||
<div>
|
||||
<Suspense fallback={<ChartSkeleton />}>
|
||||
<HeavyChart data={data} />
|
||||
</Suspense>
|
||||
|
||||
<Suspense fallback={null}>
|
||||
<ThreeJsBackground />
|
||||
</Suspense>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Virtualization for Long Lists
|
||||
|
||||
```typescript
|
||||
import { useVirtualizer } from '@tanstack/react-virtual'
|
||||
|
||||
export function VirtualMarketList({ markets }: { markets: Market[] }) {
|
||||
const parentRef = useRef<HTMLDivElement>(null)
|
||||
|
||||
const virtualizer = useVirtualizer({
|
||||
count: markets.length,
|
||||
getScrollElement: () => parentRef.current,
|
||||
estimateSize: () => 100, // Estimated row height
|
||||
overscan: 5 // Extra items to render
|
||||
})
|
||||
|
||||
return (
|
||||
<div ref={parentRef} style={{ height: '600px', overflow: 'auto' }}>
|
||||
<div
|
||||
style={{
|
||||
height: `${virtualizer.getTotalSize()}px`,
|
||||
position: 'relative'
|
||||
}}
|
||||
>
|
||||
{virtualizer.getVirtualItems().map(virtualRow => (
|
||||
<div
|
||||
key={virtualRow.index}
|
||||
style={{
|
||||
position: 'absolute',
|
||||
top: 0,
|
||||
left: 0,
|
||||
width: '100%',
|
||||
height: `${virtualRow.size}px`,
|
||||
transform: `translateY(${virtualRow.start}px)`
|
||||
}}
|
||||
>
|
||||
<MarketCard market={markets[virtualRow.index]} />
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Form Handling Patterns
|
||||
|
||||
### Controlled Form with Validation
|
||||
|
||||
```typescript
|
||||
interface FormData {
|
||||
name: string
|
||||
description: string
|
||||
endDate: string
|
||||
}
|
||||
|
||||
interface FormErrors {
|
||||
name?: string
|
||||
description?: string
|
||||
endDate?: string
|
||||
}
|
||||
|
||||
export function CreateMarketForm() {
|
||||
const [formData, setFormData] = useState<FormData>({
|
||||
name: '',
|
||||
description: '',
|
||||
endDate: ''
|
||||
})
|
||||
|
||||
const [errors, setErrors] = useState<FormErrors>({})
|
||||
|
||||
const validate = (): boolean => {
|
||||
const newErrors: FormErrors = {}
|
||||
|
||||
if (!formData.name.trim()) {
|
||||
newErrors.name = 'Name is required'
|
||||
} else if (formData.name.length > 200) {
|
||||
newErrors.name = 'Name must be under 200 characters'
|
||||
}
|
||||
|
||||
if (!formData.description.trim()) {
|
||||
newErrors.description = 'Description is required'
|
||||
}
|
||||
|
||||
if (!formData.endDate) {
|
||||
newErrors.endDate = 'End date is required'
|
||||
}
|
||||
|
||||
setErrors(newErrors)
|
||||
return Object.keys(newErrors).length === 0
|
||||
}
|
||||
|
||||
const handleSubmit = async (e: React.FormEvent) => {
|
||||
e.preventDefault()
|
||||
|
||||
if (!validate()) return
|
||||
|
||||
try {
|
||||
await createMarket(formData)
|
||||
// Success handling
|
||||
} catch (error) {
|
||||
// Error handling
|
||||
}
|
||||
}
|
||||
|
||||
return (
|
||||
<form onSubmit={handleSubmit}>
|
||||
<input
|
||||
value={formData.name}
|
||||
onChange={e => setFormData(prev => ({ ...prev, name: e.target.value }))}
|
||||
placeholder="Market name"
|
||||
/>
|
||||
{errors.name && <span className="error">{errors.name}</span>}
|
||||
|
||||
{/* Other fields */}
|
||||
|
||||
<button type="submit">Create Market</button>
|
||||
</form>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Error Boundary Pattern
|
||||
|
||||
```typescript
|
||||
interface ErrorBoundaryState {
|
||||
hasError: boolean
|
||||
error: Error | null
|
||||
}
|
||||
|
||||
export class ErrorBoundary extends React.Component<
|
||||
{ children: React.ReactNode },
|
||||
ErrorBoundaryState
|
||||
> {
|
||||
state: ErrorBoundaryState = {
|
||||
hasError: false,
|
||||
error: null
|
||||
}
|
||||
|
||||
static getDerivedStateFromError(error: Error): ErrorBoundaryState {
|
||||
return { hasError: true, error }
|
||||
}
|
||||
|
||||
componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
|
||||
console.error('Error boundary caught:', error, errorInfo)
|
||||
}
|
||||
|
||||
render() {
|
||||
if (this.state.hasError) {
|
||||
return (
|
||||
<div className="error-fallback">
|
||||
<h2>Something went wrong</h2>
|
||||
<p>{this.state.error?.message}</p>
|
||||
<button onClick={() => this.setState({ hasError: false })}>
|
||||
Try again
|
||||
</button>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
return this.props.children
|
||||
}
|
||||
}
|
||||
|
||||
// Usage
|
||||
<ErrorBoundary>
|
||||
<App />
|
||||
</ErrorBoundary>
|
||||
```
|
||||
|
||||
## Animation Patterns
|
||||
|
||||
### Framer Motion Animations
|
||||
|
||||
```typescript
|
||||
import { motion, AnimatePresence } from 'framer-motion'
|
||||
|
||||
// ✅ List animations
|
||||
export function AnimatedMarketList({ markets }: { markets: Market[] }) {
|
||||
return (
|
||||
<AnimatePresence>
|
||||
{markets.map(market => (
|
||||
<motion.div
|
||||
key={market.id}
|
||||
initial={{ opacity: 0, y: 20 }}
|
||||
animate={{ opacity: 1, y: 0 }}
|
||||
exit={{ opacity: 0, y: -20 }}
|
||||
transition={{ duration: 0.3 }}
|
||||
>
|
||||
<MarketCard market={market} />
|
||||
</motion.div>
|
||||
))}
|
||||
</AnimatePresence>
|
||||
)
|
||||
}
|
||||
|
||||
// ✅ Modal animations
|
||||
export function Modal({ isOpen, onClose, children }: ModalProps) {
|
||||
return (
|
||||
<AnimatePresence>
|
||||
{isOpen && (
|
||||
<>
|
||||
<motion.div
|
||||
className="modal-overlay"
|
||||
initial={{ opacity: 0 }}
|
||||
animate={{ opacity: 1 }}
|
||||
exit={{ opacity: 0 }}
|
||||
onClick={onClose}
|
||||
/>
|
||||
<motion.div
|
||||
className="modal-content"
|
||||
initial={{ opacity: 0, scale: 0.9, y: 20 }}
|
||||
animate={{ opacity: 1, scale: 1, y: 0 }}
|
||||
exit={{ opacity: 0, scale: 0.9, y: 20 }}
|
||||
>
|
||||
{children}
|
||||
</motion.div>
|
||||
</>
|
||||
)}
|
||||
</AnimatePresence>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Accessibility Patterns
|
||||
|
||||
### Keyboard Navigation
|
||||
|
||||
```typescript
|
||||
export function Dropdown({ options, onSelect }: DropdownProps) {
|
||||
const [isOpen, setIsOpen] = useState(false)
|
||||
const [activeIndex, setActiveIndex] = useState(0)
|
||||
|
||||
const handleKeyDown = (e: React.KeyboardEvent) => {
|
||||
switch (e.key) {
|
||||
case 'ArrowDown':
|
||||
e.preventDefault()
|
||||
setActiveIndex(i => Math.min(i + 1, options.length - 1))
|
||||
break
|
||||
case 'ArrowUp':
|
||||
e.preventDefault()
|
||||
setActiveIndex(i => Math.max(i - 1, 0))
|
||||
break
|
||||
case 'Enter':
|
||||
e.preventDefault()
|
||||
onSelect(options[activeIndex])
|
||||
setIsOpen(false)
|
||||
break
|
||||
case 'Escape':
|
||||
setIsOpen(false)
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
return (
|
||||
<div
|
||||
role="combobox"
|
||||
aria-expanded={isOpen}
|
||||
aria-haspopup="listbox"
|
||||
onKeyDown={handleKeyDown}
|
||||
>
|
||||
{/* Dropdown implementation */}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Focus Management
|
||||
|
||||
```typescript
|
||||
export function Modal({ isOpen, onClose, children }: ModalProps) {
|
||||
const modalRef = useRef<HTMLDivElement>(null)
|
||||
const previousFocusRef = useRef<HTMLElement | null>(null)
|
||||
|
||||
useEffect(() => {
|
||||
if (isOpen) {
|
||||
// Save currently focused element
|
||||
previousFocusRef.current = document.activeElement as HTMLElement
|
||||
|
||||
// Focus modal
|
||||
modalRef.current?.focus()
|
||||
} else {
|
||||
// Restore focus when closing
|
||||
previousFocusRef.current?.focus()
|
||||
}
|
||||
}, [isOpen])
|
||||
|
||||
return isOpen ? (
|
||||
<div
|
||||
ref={modalRef}
|
||||
role="dialog"
|
||||
aria-modal="true"
|
||||
tabIndex={-1}
|
||||
onKeyDown={e => e.key === 'Escape' && onClose()}
|
||||
>
|
||||
{children}
|
||||
</div>
|
||||
) : null
|
||||
}
|
||||
```
|
||||
|
||||
**Remember**: Modern frontend patterns enable maintainable, performant user interfaces. Choose patterns that fit your project complexity.
|
||||
352
skills/cc-skill-project-guidelines-example/SKILL.md
Normal file
352
skills/cc-skill-project-guidelines-example/SKILL.md
Normal file
@@ -0,0 +1,352 @@
|
||||
---
|
||||
name: cc-skill-project-guidelines-example
|
||||
description: Project Guidelines Skill (Example)
|
||||
author: affaan-m
|
||||
version: "1.0"
|
||||
---
|
||||
|
||||
# Project Guidelines Skill (Example)
|
||||
|
||||
This is an example of a project-specific skill. Use this as a template for your own projects.
|
||||
|
||||
Based on a real production application: [Zenith](https://zenith.chat) - AI-powered customer discovery platform.
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
|
||||
Reference this skill when working on the specific project it's designed for. Project skills contain:
|
||||
- Architecture overview
|
||||
- File structure
|
||||
- Code patterns
|
||||
- Testing requirements
|
||||
- Deployment workflow
|
||||
|
||||
---
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
**Tech Stack:**
|
||||
- **Frontend**: Next.js 15 (App Router), TypeScript, React
|
||||
- **Backend**: FastAPI (Python), Pydantic models
|
||||
- **Database**: Supabase (PostgreSQL)
|
||||
- **AI**: Claude API with tool calling and structured output
|
||||
- **Deployment**: Google Cloud Run
|
||||
- **Testing**: Playwright (E2E), pytest (backend), React Testing Library
|
||||
|
||||
**Services:**
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Frontend │
|
||||
│ Next.js 15 + TypeScript + TailwindCSS │
|
||||
│ Deployed: Vercel / Cloud Run │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Backend │
|
||||
│ FastAPI + Python 3.11 + Pydantic │
|
||||
│ Deployed: Cloud Run │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌───────────────┼───────────────┐
|
||||
▼ ▼ ▼
|
||||
┌──────────┐ ┌──────────┐ ┌──────────┐
|
||||
│ Supabase │ │ Claude │ │ Redis │
|
||||
│ Database │ │ API │ │ Cache │
|
||||
└──────────┘ └──────────┘ └──────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
project/
|
||||
├── frontend/
|
||||
│ └── src/
|
||||
│ ├── app/ # Next.js app router pages
|
||||
│ │ ├── api/ # API routes
|
||||
│ │ ├── (auth)/ # Auth-protected routes
|
||||
│ │ └── workspace/ # Main app workspace
|
||||
│ ├── components/ # React components
|
||||
│ │ ├── ui/ # Base UI components
|
||||
│ │ ├── forms/ # Form components
|
||||
│ │ └── layouts/ # Layout components
|
||||
│ ├── hooks/ # Custom React hooks
|
||||
│ ├── lib/ # Utilities
|
||||
│ ├── types/ # TypeScript definitions
|
||||
│ └── config/ # Configuration
|
||||
│
|
||||
├── backend/
|
||||
│ ├── routers/ # FastAPI route handlers
|
||||
│ ├── models.py # Pydantic models
|
||||
│ ├── main.py # FastAPI app entry
|
||||
│ ├── auth_system.py # Authentication
|
||||
│ ├── database.py # Database operations
|
||||
│ ├── services/ # Business logic
|
||||
│ └── tests/ # pytest tests
|
||||
│
|
||||
├── deploy/ # Deployment configs
|
||||
├── docs/ # Documentation
|
||||
└── scripts/ # Utility scripts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Code Patterns
|
||||
|
||||
### API Response Format (FastAPI)
|
||||
|
||||
```python
|
||||
from pydantic import BaseModel
|
||||
from typing import Generic, TypeVar, Optional
|
||||
|
||||
T = TypeVar('T')
|
||||
|
||||
class ApiResponse(BaseModel, Generic[T]):
|
||||
success: bool
|
||||
data: Optional[T] = None
|
||||
error: Optional[str] = None
|
||||
|
||||
@classmethod
|
||||
def ok(cls, data: T) -> "ApiResponse[T]":
|
||||
return cls(success=True, data=data)
|
||||
|
||||
@classmethod
|
||||
def fail(cls, error: str) -> "ApiResponse[T]":
|
||||
return cls(success=False, error=error)
|
||||
```
|
||||
|
||||
### Frontend API Calls (TypeScript)
|
||||
|
||||
```typescript
|
||||
interface ApiResponse<T> {
|
||||
success: boolean
|
||||
data?: T
|
||||
error?: string
|
||||
}
|
||||
|
||||
async function fetchApi<T>(
|
||||
endpoint: string,
|
||||
options?: RequestInit
|
||||
): Promise<ApiResponse<T>> {
|
||||
try {
|
||||
const response = await fetch(`/api${endpoint}`, {
|
||||
...options,
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
...options?.headers,
|
||||
},
|
||||
})
|
||||
|
||||
if (!response.ok) {
|
||||
return { success: false, error: `HTTP ${response.status}` }
|
||||
}
|
||||
|
||||
return await response.json()
|
||||
} catch (error) {
|
||||
return { success: false, error: String(error) }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Claude AI Integration (Structured Output)
|
||||
|
||||
```python
|
||||
from anthropic import Anthropic
|
||||
from pydantic import BaseModel
|
||||
|
||||
class AnalysisResult(BaseModel):
|
||||
summary: str
|
||||
key_points: list[str]
|
||||
confidence: float
|
||||
|
||||
async def analyze_with_claude(content: str) -> AnalysisResult:
|
||||
client = Anthropic()
|
||||
|
||||
response = client.messages.create(
|
||||
model="claude-sonnet-4-5-20250514",
|
||||
max_tokens=1024,
|
||||
messages=[{"role": "user", "content": content}],
|
||||
tools=[{
|
||||
"name": "provide_analysis",
|
||||
"description": "Provide structured analysis",
|
||||
"input_schema": AnalysisResult.model_json_schema()
|
||||
}],
|
||||
tool_choice={"type": "tool", "name": "provide_analysis"}
|
||||
)
|
||||
|
||||
# Extract tool use result
|
||||
tool_use = next(
|
||||
block for block in response.content
|
||||
if block.type == "tool_use"
|
||||
)
|
||||
|
||||
return AnalysisResult(**tool_use.input)
|
||||
```
|
||||
|
||||
### Custom Hooks (React)
|
||||
|
||||
```typescript
|
||||
import { useState, useCallback } from 'react'
|
||||
|
||||
interface UseApiState<T> {
|
||||
data: T | null
|
||||
loading: boolean
|
||||
error: string | null
|
||||
}
|
||||
|
||||
export function useApi<T>(
|
||||
fetchFn: () => Promise<ApiResponse<T>>
|
||||
) {
|
||||
const [state, setState] = useState<UseApiState<T>>({
|
||||
data: null,
|
||||
loading: false,
|
||||
error: null,
|
||||
})
|
||||
|
||||
const execute = useCallback(async () => {
|
||||
setState(prev => ({ ...prev, loading: true, error: null }))
|
||||
|
||||
const result = await fetchFn()
|
||||
|
||||
if (result.success) {
|
||||
setState({ data: result.data!, loading: false, error: null })
|
||||
} else {
|
||||
setState({ data: null, loading: false, error: result.error! })
|
||||
}
|
||||
}, [fetchFn])
|
||||
|
||||
return { ...state, execute }
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Requirements
|
||||
|
||||
### Backend (pytest)
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
poetry run pytest tests/
|
||||
|
||||
# Run with coverage
|
||||
poetry run pytest tests/ --cov=. --cov-report=html
|
||||
|
||||
# Run specific test file
|
||||
poetry run pytest tests/test_auth.py -v
|
||||
```
|
||||
|
||||
**Test structure:**
|
||||
```python
|
||||
import pytest
|
||||
from httpx import AsyncClient
|
||||
from main import app
|
||||
|
||||
@pytest.fixture
|
||||
async def client():
|
||||
async with AsyncClient(app=app, base_url="http://test") as ac:
|
||||
yield ac
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_health_check(client: AsyncClient):
|
||||
response = await client.get("/health")
|
||||
assert response.status_code == 200
|
||||
assert response.json()["status"] == "healthy"
|
||||
```
|
||||
|
||||
### Frontend (React Testing Library)
|
||||
|
||||
```bash
|
||||
# Run tests
|
||||
npm run test
|
||||
|
||||
# Run with coverage
|
||||
npm run test -- --coverage
|
||||
|
||||
# Run E2E tests
|
||||
npm run test:e2e
|
||||
```
|
||||
|
||||
**Test structure:**
|
||||
```typescript
|
||||
import { render, screen, fireEvent } from '@testing-library/react'
|
||||
import { WorkspacePanel } from './WorkspacePanel'
|
||||
|
||||
describe('WorkspacePanel', () => {
|
||||
it('renders workspace correctly', () => {
|
||||
render(<WorkspacePanel />)
|
||||
expect(screen.getByRole('main')).toBeInTheDocument()
|
||||
})
|
||||
|
||||
it('handles session creation', async () => {
|
||||
render(<WorkspacePanel />)
|
||||
fireEvent.click(screen.getByText('New Session'))
|
||||
expect(await screen.findByText('Session created')).toBeInTheDocument()
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deployment Workflow
|
||||
|
||||
### Pre-Deployment Checklist
|
||||
|
||||
- [ ] All tests passing locally
|
||||
- [ ] `npm run build` succeeds (frontend)
|
||||
- [ ] `poetry run pytest` passes (backend)
|
||||
- [ ] No hardcoded secrets
|
||||
- [ ] Environment variables documented
|
||||
- [ ] Database migrations ready
|
||||
|
||||
### Deployment Commands
|
||||
|
||||
```bash
|
||||
# Build and deploy frontend
|
||||
cd frontend && npm run build
|
||||
gcloud run deploy frontend --source .
|
||||
|
||||
# Build and deploy backend
|
||||
cd backend
|
||||
gcloud run deploy backend --source .
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```bash
|
||||
# Frontend (.env.local)
|
||||
NEXT_PUBLIC_API_URL=https://api.example.com
|
||||
NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
|
||||
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
|
||||
|
||||
# Backend (.env)
|
||||
DATABASE_URL=postgresql://...
|
||||
ANTHROPIC_API_KEY=sk-ant-...
|
||||
SUPABASE_URL=https://xxx.supabase.co
|
||||
SUPABASE_KEY=eyJ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Critical Rules
|
||||
|
||||
1. **No emojis** in code, comments, or documentation
|
||||
2. **Immutability** - never mutate objects or arrays
|
||||
3. **TDD** - write tests before implementation
|
||||
4. **80% coverage** minimum
|
||||
5. **Many small files** - 200-400 lines typical, 800 max
|
||||
6. **No console.log** in production code
|
||||
7. **Proper error handling** with try/catch
|
||||
8. **Input validation** with Pydantic/Zod
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `coding-standards.md` - General coding best practices
|
||||
- `backend-patterns.md` - API and database patterns
|
||||
- `frontend-patterns.md` - React and Next.js patterns
|
||||
- `tdd-workflow/` - Test-driven development methodology
|
||||
496
skills/cc-skill-security-review/SKILL.md
Normal file
496
skills/cc-skill-security-review/SKILL.md
Normal file
@@ -0,0 +1,496 @@
|
||||
---
|
||||
name: security-review
|
||||
description: Use this skill when adding authentication, handling user input, working with secrets, creating API endpoints, or implementing payment/sensitive features. Provides comprehensive security checklist and patterns.
|
||||
author: affaan-m
|
||||
version: "1.0"
|
||||
---
|
||||
|
||||
# Security Review Skill
|
||||
|
||||
This skill ensures all code follows security best practices and identifies potential vulnerabilities.
|
||||
|
||||
## When to Activate
|
||||
|
||||
- Implementing authentication or authorization
|
||||
- Handling user input or file uploads
|
||||
- Creating new API endpoints
|
||||
- Working with secrets or credentials
|
||||
- Implementing payment features
|
||||
- Storing or transmitting sensitive data
|
||||
- Integrating third-party APIs
|
||||
|
||||
## Security Checklist
|
||||
|
||||
### 1. Secrets Management
|
||||
|
||||
#### ❌ NEVER Do This
|
||||
```typescript
|
||||
const apiKey = "sk-proj-xxxxx" // Hardcoded secret
|
||||
const dbPassword = "password123" // In source code
|
||||
```
|
||||
|
||||
#### ✅ ALWAYS Do This
|
||||
```typescript
|
||||
const apiKey = process.env.OPENAI_API_KEY
|
||||
const dbUrl = process.env.DATABASE_URL
|
||||
|
||||
// Verify secrets exist
|
||||
if (!apiKey) {
|
||||
throw new Error('OPENAI_API_KEY not configured')
|
||||
}
|
||||
```
|
||||
|
||||
#### Verification Steps
|
||||
- [ ] No hardcoded API keys, tokens, or passwords
|
||||
- [ ] All secrets in environment variables
|
||||
- [ ] `.env.local` in .gitignore
|
||||
- [ ] No secrets in git history
|
||||
- [ ] Production secrets in hosting platform (Vercel, Railway)
|
||||
|
||||
### 2. Input Validation
|
||||
|
||||
#### Always Validate User Input
|
||||
```typescript
|
||||
import { z } from 'zod'
|
||||
|
||||
// Define validation schema
|
||||
const CreateUserSchema = z.object({
|
||||
email: z.string().email(),
|
||||
name: z.string().min(1).max(100),
|
||||
age: z.number().int().min(0).max(150)
|
||||
})
|
||||
|
||||
// Validate before processing
|
||||
export async function createUser(input: unknown) {
|
||||
try {
|
||||
const validated = CreateUserSchema.parse(input)
|
||||
return await db.users.create(validated)
|
||||
} catch (error) {
|
||||
if (error instanceof z.ZodError) {
|
||||
return { success: false, errors: error.errors }
|
||||
}
|
||||
throw error
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### File Upload Validation
|
||||
```typescript
|
||||
function validateFileUpload(file: File) {
|
||||
// Size check (5MB max)
|
||||
const maxSize = 5 * 1024 * 1024
|
||||
if (file.size > maxSize) {
|
||||
throw new Error('File too large (max 5MB)')
|
||||
}
|
||||
|
||||
// Type check
|
||||
const allowedTypes = ['image/jpeg', 'image/png', 'image/gif']
|
||||
if (!allowedTypes.includes(file.type)) {
|
||||
throw new Error('Invalid file type')
|
||||
}
|
||||
|
||||
// Extension check
|
||||
const allowedExtensions = ['.jpg', '.jpeg', '.png', '.gif']
|
||||
const extension = file.name.toLowerCase().match(/\.[^.]+$/)?.[0]
|
||||
if (!extension || !allowedExtensions.includes(extension)) {
|
||||
throw new Error('Invalid file extension')
|
||||
}
|
||||
|
||||
return true
|
||||
}
|
||||
```
|
||||
|
||||
#### Verification Steps
|
||||
- [ ] All user inputs validated with schemas
|
||||
- [ ] File uploads restricted (size, type, extension)
|
||||
- [ ] No direct use of user input in queries
|
||||
- [ ] Whitelist validation (not blacklist)
|
||||
- [ ] Error messages don't leak sensitive info
|
||||
|
||||
### 3. SQL Injection Prevention
|
||||
|
||||
#### ❌ NEVER Concatenate SQL
|
||||
```typescript
|
||||
// DANGEROUS - SQL Injection vulnerability
|
||||
const query = `SELECT * FROM users WHERE email = '${userEmail}'`
|
||||
await db.query(query)
|
||||
```
|
||||
|
||||
#### ✅ ALWAYS Use Parameterized Queries
|
||||
```typescript
|
||||
// Safe - parameterized query
|
||||
const { data } = await supabase
|
||||
.from('users')
|
||||
.select('*')
|
||||
.eq('email', userEmail)
|
||||
|
||||
// Or with raw SQL
|
||||
await db.query(
|
||||
'SELECT * FROM users WHERE email = $1',
|
||||
[userEmail]
|
||||
)
|
||||
```
|
||||
|
||||
#### Verification Steps
|
||||
- [ ] All database queries use parameterized queries
|
||||
- [ ] No string concatenation in SQL
|
||||
- [ ] ORM/query builder used correctly
|
||||
- [ ] Supabase queries properly sanitized
|
||||
|
||||
### 4. Authentication & Authorization
|
||||
|
||||
#### JWT Token Handling
|
||||
```typescript
|
||||
// ❌ WRONG: localStorage (vulnerable to XSS)
|
||||
localStorage.setItem('token', token)
|
||||
|
||||
// ✅ CORRECT: httpOnly cookies
|
||||
res.setHeader('Set-Cookie',
|
||||
`token=${token}; HttpOnly; Secure; SameSite=Strict; Max-Age=3600`)
|
||||
```
|
||||
|
||||
#### Authorization Checks
|
||||
```typescript
|
||||
export async function deleteUser(userId: string, requesterId: string) {
|
||||
// ALWAYS verify authorization first
|
||||
const requester = await db.users.findUnique({
|
||||
where: { id: requesterId }
|
||||
})
|
||||
|
||||
if (requester.role !== 'admin') {
|
||||
return NextResponse.json(
|
||||
{ error: 'Unauthorized' },
|
||||
{ status: 403 }
|
||||
)
|
||||
}
|
||||
|
||||
// Proceed with deletion
|
||||
await db.users.delete({ where: { id: userId } })
|
||||
}
|
||||
```
|
||||
|
||||
#### Row Level Security (Supabase)
|
||||
```sql
|
||||
-- Enable RLS on all tables
|
||||
ALTER TABLE users ENABLE ROW LEVEL SECURITY;
|
||||
|
||||
-- Users can only view their own data
|
||||
CREATE POLICY "Users view own data"
|
||||
ON users FOR SELECT
|
||||
USING (auth.uid() = id);
|
||||
|
||||
-- Users can only update their own data
|
||||
CREATE POLICY "Users update own data"
|
||||
ON users FOR UPDATE
|
||||
USING (auth.uid() = id);
|
||||
```
|
||||
|
||||
#### Verification Steps
|
||||
- [ ] Tokens stored in httpOnly cookies (not localStorage)
|
||||
- [ ] Authorization checks before sensitive operations
|
||||
- [ ] Row Level Security enabled in Supabase
|
||||
- [ ] Role-based access control implemented
|
||||
- [ ] Session management secure
|
||||
|
||||
### 5. XSS Prevention
|
||||
|
||||
#### Sanitize HTML
|
||||
```typescript
|
||||
import DOMPurify from 'isomorphic-dompurify'
|
||||
|
||||
// ALWAYS sanitize user-provided HTML
|
||||
function renderUserContent(html: string) {
|
||||
const clean = DOMPurify.sanitize(html, {
|
||||
ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p'],
|
||||
ALLOWED_ATTR: []
|
||||
})
|
||||
return <div dangerouslySetInnerHTML={{ __html: clean }} />
|
||||
}
|
||||
```
|
||||
|
||||
#### Content Security Policy
|
||||
```typescript
|
||||
// next.config.js
|
||||
const securityHeaders = [
|
||||
{
|
||||
key: 'Content-Security-Policy',
|
||||
value: `
|
||||
default-src 'self';
|
||||
script-src 'self' 'unsafe-eval' 'unsafe-inline';
|
||||
style-src 'self' 'unsafe-inline';
|
||||
img-src 'self' data: https:;
|
||||
font-src 'self';
|
||||
connect-src 'self' https://api.example.com;
|
||||
`.replace(/\s{2,}/g, ' ').trim()
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
#### Verification Steps
|
||||
- [ ] User-provided HTML sanitized
|
||||
- [ ] CSP headers configured
|
||||
- [ ] No unvalidated dynamic content rendering
|
||||
- [ ] React's built-in XSS protection used
|
||||
|
||||
### 6. CSRF Protection
|
||||
|
||||
#### CSRF Tokens
|
||||
```typescript
|
||||
import { csrf } from '@/lib/csrf'
|
||||
|
||||
export async function POST(request: Request) {
|
||||
const token = request.headers.get('X-CSRF-Token')
|
||||
|
||||
if (!csrf.verify(token)) {
|
||||
return NextResponse.json(
|
||||
{ error: 'Invalid CSRF token' },
|
||||
{ status: 403 }
|
||||
)
|
||||
}
|
||||
|
||||
// Process request
|
||||
}
|
||||
```
|
||||
|
||||
#### SameSite Cookies
|
||||
```typescript
|
||||
res.setHeader('Set-Cookie',
|
||||
`session=${sessionId}; HttpOnly; Secure; SameSite=Strict`)
|
||||
```
|
||||
|
||||
#### Verification Steps
|
||||
- [ ] CSRF tokens on state-changing operations
|
||||
- [ ] SameSite=Strict on all cookies
|
||||
- [ ] Double-submit cookie pattern implemented
|
||||
|
||||
### 7. Rate Limiting
|
||||
|
||||
#### API Rate Limiting
|
||||
```typescript
|
||||
import rateLimit from 'express-rate-limit'
|
||||
|
||||
const limiter = rateLimit({
|
||||
windowMs: 15 * 60 * 1000, // 15 minutes
|
||||
max: 100, // 100 requests per window
|
||||
message: 'Too many requests'
|
||||
})
|
||||
|
||||
// Apply to routes
|
||||
app.use('/api/', limiter)
|
||||
```
|
||||
|
||||
#### Expensive Operations
|
||||
```typescript
|
||||
// Aggressive rate limiting for searches
|
||||
const searchLimiter = rateLimit({
|
||||
windowMs: 60 * 1000, // 1 minute
|
||||
max: 10, // 10 requests per minute
|
||||
message: 'Too many search requests'
|
||||
})
|
||||
|
||||
app.use('/api/search', searchLimiter)
|
||||
```
|
||||
|
||||
#### Verification Steps
|
||||
- [ ] Rate limiting on all API endpoints
|
||||
- [ ] Stricter limits on expensive operations
|
||||
- [ ] IP-based rate limiting
|
||||
- [ ] User-based rate limiting (authenticated)
|
||||
|
||||
### 8. Sensitive Data Exposure
|
||||
|
||||
#### Logging
|
||||
```typescript
|
||||
// ❌ WRONG: Logging sensitive data
|
||||
console.log('User login:', { email, password })
|
||||
console.log('Payment:', { cardNumber, cvv })
|
||||
|
||||
// ✅ CORRECT: Redact sensitive data
|
||||
console.log('User login:', { email, userId })
|
||||
console.log('Payment:', { last4: card.last4, userId })
|
||||
```
|
||||
|
||||
#### Error Messages
|
||||
```typescript
|
||||
// ❌ WRONG: Exposing internal details
|
||||
catch (error) {
|
||||
return NextResponse.json(
|
||||
{ error: error.message, stack: error.stack },
|
||||
{ status: 500 }
|
||||
)
|
||||
}
|
||||
|
||||
// ✅ CORRECT: Generic error messages
|
||||
catch (error) {
|
||||
console.error('Internal error:', error)
|
||||
return NextResponse.json(
|
||||
{ error: 'An error occurred. Please try again.' },
|
||||
{ status: 500 }
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
#### Verification Steps
|
||||
- [ ] No passwords, tokens, or secrets in logs
|
||||
- [ ] Error messages generic for users
|
||||
- [ ] Detailed errors only in server logs
|
||||
- [ ] No stack traces exposed to users
|
||||
|
||||
### 9. Blockchain Security (Solana)
|
||||
|
||||
#### Wallet Verification
|
||||
```typescript
|
||||
import { verify } from '@solana/web3.js'
|
||||
|
||||
async function verifyWalletOwnership(
|
||||
publicKey: string,
|
||||
signature: string,
|
||||
message: string
|
||||
) {
|
||||
try {
|
||||
const isValid = verify(
|
||||
Buffer.from(message),
|
||||
Buffer.from(signature, 'base64'),
|
||||
Buffer.from(publicKey, 'base64')
|
||||
)
|
||||
return isValid
|
||||
} catch (error) {
|
||||
return false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Transaction Verification
|
||||
```typescript
|
||||
async function verifyTransaction(transaction: Transaction) {
|
||||
// Verify recipient
|
||||
if (transaction.to !== expectedRecipient) {
|
||||
throw new Error('Invalid recipient')
|
||||
}
|
||||
|
||||
// Verify amount
|
||||
if (transaction.amount > maxAmount) {
|
||||
throw new Error('Amount exceeds limit')
|
||||
}
|
||||
|
||||
// Verify user has sufficient balance
|
||||
const balance = await getBalance(transaction.from)
|
||||
if (balance < transaction.amount) {
|
||||
throw new Error('Insufficient balance')
|
||||
}
|
||||
|
||||
return true
|
||||
}
|
||||
```
|
||||
|
||||
#### Verification Steps
|
||||
- [ ] Wallet signatures verified
|
||||
- [ ] Transaction details validated
|
||||
- [ ] Balance checks before transactions
|
||||
- [ ] No blind transaction signing
|
||||
|
||||
### 10. Dependency Security
|
||||
|
||||
#### Regular Updates
|
||||
```bash
|
||||
# Check for vulnerabilities
|
||||
npm audit
|
||||
|
||||
# Fix automatically fixable issues
|
||||
npm audit fix
|
||||
|
||||
# Update dependencies
|
||||
npm update
|
||||
|
||||
# Check for outdated packages
|
||||
npm outdated
|
||||
```
|
||||
|
||||
#### Lock Files
|
||||
```bash
|
||||
# ALWAYS commit lock files
|
||||
git add package-lock.json
|
||||
|
||||
# Use in CI/CD for reproducible builds
|
||||
npm ci # Instead of npm install
|
||||
```
|
||||
|
||||
#### Verification Steps
|
||||
- [ ] Dependencies up to date
|
||||
- [ ] No known vulnerabilities (npm audit clean)
|
||||
- [ ] Lock files committed
|
||||
- [ ] Dependabot enabled on GitHub
|
||||
- [ ] Regular security updates
|
||||
|
||||
## Security Testing
|
||||
|
||||
### Automated Security Tests
|
||||
```typescript
|
||||
// Test authentication
|
||||
test('requires authentication', async () => {
|
||||
const response = await fetch('/api/protected')
|
||||
expect(response.status).toBe(401)
|
||||
})
|
||||
|
||||
// Test authorization
|
||||
test('requires admin role', async () => {
|
||||
const response = await fetch('/api/admin', {
|
||||
headers: { Authorization: `Bearer ${userToken}` }
|
||||
})
|
||||
expect(response.status).toBe(403)
|
||||
})
|
||||
|
||||
// Test input validation
|
||||
test('rejects invalid input', async () => {
|
||||
const response = await fetch('/api/users', {
|
||||
method: 'POST',
|
||||
body: JSON.stringify({ email: 'not-an-email' })
|
||||
})
|
||||
expect(response.status).toBe(400)
|
||||
})
|
||||
|
||||
// Test rate limiting
|
||||
test('enforces rate limits', async () => {
|
||||
const requests = Array(101).fill(null).map(() =>
|
||||
fetch('/api/endpoint')
|
||||
)
|
||||
|
||||
const responses = await Promise.all(requests)
|
||||
const tooManyRequests = responses.filter(r => r.status === 429)
|
||||
|
||||
expect(tooManyRequests.length).toBeGreaterThan(0)
|
||||
})
|
||||
```
|
||||
|
||||
## Pre-Deployment Security Checklist
|
||||
|
||||
Before ANY production deployment:
|
||||
|
||||
- [ ] **Secrets**: No hardcoded secrets, all in env vars
|
||||
- [ ] **Input Validation**: All user inputs validated
|
||||
- [ ] **SQL Injection**: All queries parameterized
|
||||
- [ ] **XSS**: User content sanitized
|
||||
- [ ] **CSRF**: Protection enabled
|
||||
- [ ] **Authentication**: Proper token handling
|
||||
- [ ] **Authorization**: Role checks in place
|
||||
- [ ] **Rate Limiting**: Enabled on all endpoints
|
||||
- [ ] **HTTPS**: Enforced in production
|
||||
- [ ] **Security Headers**: CSP, X-Frame-Options configured
|
||||
- [ ] **Error Handling**: No sensitive data in errors
|
||||
- [ ] **Logging**: No sensitive data logged
|
||||
- [ ] **Dependencies**: Up to date, no vulnerabilities
|
||||
- [ ] **Row Level Security**: Enabled in Supabase
|
||||
- [ ] **CORS**: Properly configured
|
||||
- [ ] **File Uploads**: Validated (size, type)
|
||||
- [ ] **Wallet Signatures**: Verified (if blockchain)
|
||||
|
||||
## Resources
|
||||
|
||||
- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
|
||||
- [Next.js Security](https://nextjs.org/docs/security)
|
||||
- [Supabase Security](https://supabase.com/docs/guides/auth)
|
||||
- [Web Security Academy](https://portswigger.net/web-security)
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Security is not optional. One vulnerability can compromise the entire platform. When in doubt, err on the side of caution.
|
||||
10
skills/cc-skill-strategic-compact/SKILL.md
Normal file
10
skills/cc-skill-strategic-compact/SKILL.md
Normal file
@@ -0,0 +1,10 @@
|
||||
---
|
||||
name: cc-skill-strategic-compact
|
||||
description: Development skill skill from everything-claude-code
|
||||
author: affaan-m
|
||||
version: "1.0"
|
||||
---
|
||||
|
||||
# cc-skill-strategic-compact
|
||||
|
||||
Development skill skill.
|
||||
52
skills/cc-skill-strategic-compact/suggest-compact.sh
Executable file
52
skills/cc-skill-strategic-compact/suggest-compact.sh
Executable file
@@ -0,0 +1,52 @@
|
||||
#!/bin/bash
|
||||
# Strategic Compact Suggester
|
||||
# Runs on PreToolUse or periodically to suggest manual compaction at logical intervals
|
||||
#
|
||||
# Why manual over auto-compact:
|
||||
# - Auto-compact happens at arbitrary points, often mid-task
|
||||
# - Strategic compacting preserves context through logical phases
|
||||
# - Compact after exploration, before execution
|
||||
# - Compact after completing a milestone, before starting next
|
||||
#
|
||||
# Hook config (in ~/.claude/settings.json):
|
||||
# {
|
||||
# "hooks": {
|
||||
# "PreToolUse": [{
|
||||
# "matcher": "Edit|Write",
|
||||
# "hooks": [{
|
||||
# "type": "command",
|
||||
# "command": "~/.claude/skills/strategic-compact/suggest-compact.sh"
|
||||
# }]
|
||||
# }]
|
||||
# }
|
||||
# }
|
||||
#
|
||||
# Criteria for suggesting compact:
|
||||
# - Session has been running for extended period
|
||||
# - Large number of tool calls made
|
||||
# - Transitioning from research/exploration to implementation
|
||||
# - Plan has been finalized
|
||||
|
||||
# Track tool call count (increment in a temp file)
|
||||
COUNTER_FILE="/tmp/claude-tool-count-$$"
|
||||
THRESHOLD=${COMPACT_THRESHOLD:-50}
|
||||
|
||||
# Initialize or increment counter
|
||||
if [ -f "$COUNTER_FILE" ]; then
|
||||
count=$(cat "$COUNTER_FILE")
|
||||
count=$((count + 1))
|
||||
echo "$count" > "$COUNTER_FILE"
|
||||
else
|
||||
echo "1" > "$COUNTER_FILE"
|
||||
count=1
|
||||
fi
|
||||
|
||||
# Suggest compact after threshold tool calls
|
||||
if [ "$count" -eq "$THRESHOLD" ]; then
|
||||
echo "[StrategicCompact] $THRESHOLD tool calls reached - consider /compact if transitioning phases" >&2
|
||||
fi
|
||||
|
||||
# Suggest at regular intervals after threshold
|
||||
if [ "$count" -gt "$THRESHOLD" ] && [ $((count % 25)) -eq 0 ]; then
|
||||
echo "[StrategicCompact] $count tool calls - good checkpoint for /compact if context is stale" >&2
|
||||
fi
|
||||
201
skills/clean-code/SKILL.md
Normal file
201
skills/clean-code/SKILL.md
Normal file
@@ -0,0 +1,201 @@
|
||||
---
|
||||
name: clean-code
|
||||
description: Pragmatic coding standards - concise, direct, no over-engineering, no unnecessary comments
|
||||
allowed-tools: Read, Write, Edit
|
||||
version: 2.0
|
||||
priority: CRITICAL
|
||||
---
|
||||
|
||||
# Clean Code - Pragmatic AI Coding Standards
|
||||
|
||||
> **CRITICAL SKILL** - Be **concise, direct, and solution-focused**.
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
| Principle | Rule |
|
||||
|-----------|------|
|
||||
| **SRP** | Single Responsibility - each function/class does ONE thing |
|
||||
| **DRY** | Don't Repeat Yourself - extract duplicates, reuse |
|
||||
| **KISS** | Keep It Simple - simplest solution that works |
|
||||
| **YAGNI** | You Aren't Gonna Need It - don't build unused features |
|
||||
| **Boy Scout** | Leave code cleaner than you found it |
|
||||
|
||||
---
|
||||
|
||||
## Naming Rules
|
||||
|
||||
| Element | Convention |
|
||||
|---------|------------|
|
||||
| **Variables** | Reveal intent: `userCount` not `n` |
|
||||
| **Functions** | Verb + noun: `getUserById()` not `user()` |
|
||||
| **Booleans** | Question form: `isActive`, `hasPermission`, `canEdit` |
|
||||
| **Constants** | SCREAMING_SNAKE: `MAX_RETRY_COUNT` |
|
||||
|
||||
> **Rule:** If you need a comment to explain a name, rename it.
|
||||
|
||||
---
|
||||
|
||||
## Function Rules
|
||||
|
||||
| Rule | Description |
|
||||
|------|-------------|
|
||||
| **Small** | Max 20 lines, ideally 5-10 |
|
||||
| **One Thing** | Does one thing, does it well |
|
||||
| **One Level** | One level of abstraction per function |
|
||||
| **Few Args** | Max 3 arguments, prefer 0-2 |
|
||||
| **No Side Effects** | Don't mutate inputs unexpectedly |
|
||||
|
||||
---
|
||||
|
||||
## Code Structure
|
||||
|
||||
| Pattern | Apply |
|
||||
|---------|-------|
|
||||
| **Guard Clauses** | Early returns for edge cases |
|
||||
| **Flat > Nested** | Avoid deep nesting (max 2 levels) |
|
||||
| **Composition** | Small functions composed together |
|
||||
| **Colocation** | Keep related code close |
|
||||
|
||||
---
|
||||
|
||||
## AI Coding Style
|
||||
|
||||
| Situation | Action |
|
||||
|-----------|--------|
|
||||
| User asks for feature | Write it directly |
|
||||
| User reports bug | Fix it, don't explain |
|
||||
| No clear requirement | Ask, don't assume |
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns (DON'T)
|
||||
|
||||
| ❌ Pattern | ✅ Fix |
|
||||
|-----------|-------|
|
||||
| Comment every line | Delete obvious comments |
|
||||
| Helper for one-liner | Inline the code |
|
||||
| Factory for 2 objects | Direct instantiation |
|
||||
| utils.ts with 1 function | Put code where used |
|
||||
| "First we import..." | Just write code |
|
||||
| Deep nesting | Guard clauses |
|
||||
| Magic numbers | Named constants |
|
||||
| God functions | Split by responsibility |
|
||||
|
||||
---
|
||||
|
||||
## 🔴 Before Editing ANY File (THINK FIRST!)
|
||||
|
||||
**Before changing a file, ask yourself:**
|
||||
|
||||
| Question | Why |
|
||||
|----------|-----|
|
||||
| **What imports this file?** | They might break |
|
||||
| **What does this file import?** | Interface changes |
|
||||
| **What tests cover this?** | Tests might fail |
|
||||
| **Is this a shared component?** | Multiple places affected |
|
||||
|
||||
**Quick Check:**
|
||||
```
|
||||
File to edit: UserService.ts
|
||||
└── Who imports this? → UserController.ts, AuthController.ts
|
||||
└── Do they need changes too? → Check function signatures
|
||||
```
|
||||
|
||||
> 🔴 **Rule:** Edit the file + all dependent files in the SAME task.
|
||||
> 🔴 **Never leave broken imports or missing updates.**
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
| Do | Don't |
|
||||
|----|-------|
|
||||
| Write code directly | Write tutorials |
|
||||
| Let code self-document | Add obvious comments |
|
||||
| Fix bugs immediately | Explain the fix first |
|
||||
| Inline small things | Create unnecessary files |
|
||||
| Name things clearly | Use abbreviations |
|
||||
| Keep functions small | Write 100+ line functions |
|
||||
|
||||
> **Remember: The user wants working code, not a programming lesson.**
|
||||
|
||||
---
|
||||
|
||||
## 🔴 Self-Check Before Completing (MANDATORY)
|
||||
|
||||
**Before saying "task complete", verify:**
|
||||
|
||||
| Check | Question |
|
||||
|-------|----------|
|
||||
| ✅ **Goal met?** | Did I do exactly what user asked? |
|
||||
| ✅ **Files edited?** | Did I modify all necessary files? |
|
||||
| ✅ **Code works?** | Did I test/verify the change? |
|
||||
| ✅ **No errors?** | Lint and TypeScript pass? |
|
||||
| ✅ **Nothing forgotten?** | Any edge cases missed? |
|
||||
|
||||
> 🔴 **Rule:** If ANY check fails, fix it before completing.
|
||||
|
||||
---
|
||||
|
||||
## Verification Scripts (MANDATORY)
|
||||
|
||||
> 🔴 **CRITICAL:** Each agent runs ONLY their own skill's scripts after completing work.
|
||||
|
||||
### Agent → Script Mapping
|
||||
|
||||
| Agent | Script | Command |
|
||||
|-------|--------|---------|
|
||||
| **frontend-specialist** | UX Audit | `python ~/.claude/skills/frontend-design/scripts/ux_audit.py .` |
|
||||
| **frontend-specialist** | A11y Check | `python ~/.claude/skills/frontend-design/scripts/accessibility_checker.py .` |
|
||||
| **backend-specialist** | API Validator | `python ~/.claude/skills/api-patterns/scripts/api_validator.py .` |
|
||||
| **mobile-developer** | Mobile Audit | `python ~/.claude/skills/mobile-design/scripts/mobile_audit.py .` |
|
||||
| **database-architect** | Schema Validate | `python ~/.claude/skills/database-design/scripts/schema_validator.py .` |
|
||||
| **security-auditor** | Security Scan | `python ~/.claude/skills/vulnerability-scanner/scripts/security_scan.py .` |
|
||||
| **seo-specialist** | SEO Check | `python ~/.claude/skills/seo-fundamentals/scripts/seo_checker.py .` |
|
||||
| **seo-specialist** | GEO Check | `python ~/.claude/skills/geo-fundamentals/scripts/geo_checker.py .` |
|
||||
| **performance-optimizer** | Lighthouse | `python ~/.claude/skills/performance-profiling/scripts/lighthouse_audit.py <url>` |
|
||||
| **test-engineer** | Test Runner | `python ~/.claude/skills/testing-patterns/scripts/test_runner.py .` |
|
||||
| **test-engineer** | Playwright | `python ~/.claude/skills/webapp-testing/scripts/playwright_runner.py <url>` |
|
||||
| **Any agent** | Lint Check | `python ~/.claude/skills/lint-and-validate/scripts/lint_runner.py .` |
|
||||
| **Any agent** | Type Coverage | `python ~/.claude/skills/lint-and-validate/scripts/type_coverage.py .` |
|
||||
| **Any agent** | i18n Check | `python ~/.claude/skills/i18n-localization/scripts/i18n_checker.py .` |
|
||||
|
||||
> ❌ **WRONG:** `test-engineer` running `ux_audit.py`
|
||||
> ✅ **CORRECT:** `frontend-specialist` running `ux_audit.py`
|
||||
|
||||
---
|
||||
|
||||
### 🔴 Script Output Handling (READ → SUMMARIZE → ASK)
|
||||
|
||||
**When running a validation script, you MUST:**
|
||||
|
||||
1. **Run the script** and capture ALL output
|
||||
2. **Parse the output** - identify errors, warnings, and passes
|
||||
3. **Summarize to user** in this format:
|
||||
|
||||
```markdown
|
||||
## Script Results: [script_name.py]
|
||||
|
||||
### ❌ Errors Found (X items)
|
||||
- [File:Line] Error description 1
|
||||
- [File:Line] Error description 2
|
||||
|
||||
### ⚠️ Warnings (Y items)
|
||||
- [File:Line] Warning description
|
||||
|
||||
### ✅ Passed (Z items)
|
||||
- Check 1 passed
|
||||
- Check 2 passed
|
||||
|
||||
**Should I fix the X errors?**
|
||||
```
|
||||
|
||||
4. **Wait for user confirmation** before fixing
|
||||
5. **After fixing** → Re-run script to confirm
|
||||
|
||||
> 🔴 **VIOLATION:** Running script and ignoring output = FAILED task.
|
||||
> 🔴 **VIOLATION:** Auto-fixing without asking = Not allowed.
|
||||
> 🔴 **Rule:** Always READ output → SUMMARIZE → ASK → then fix.
|
||||
|
||||
@@ -1,6 +1,9 @@
|
||||
---
|
||||
name: Cloud Penetration Testing
|
||||
description: This skill should be used when the user asks to "perform cloud penetration testing", "assess Azure or AWS or GCP security", "enumerate cloud resources", "exploit cloud misconfigurations", "test O365 security", "extract secrets from cloud environments", or "audit cloud infrastructure". It provides comprehensive techniques for security assessment across major cloud platforms.
|
||||
metadata:
|
||||
author: zebbern
|
||||
version: "1.1"
|
||||
---
|
||||
|
||||
# Cloud Penetration Testing
|
||||
|
||||
109
skills/code-review-checklist/SKILL.md
Normal file
109
skills/code-review-checklist/SKILL.md
Normal file
@@ -0,0 +1,109 @@
|
||||
---
|
||||
name: code-review-checklist
|
||||
description: Code review guidelines covering code quality, security, and best practices.
|
||||
allowed-tools: Read, Glob, Grep
|
||||
---
|
||||
|
||||
# Code Review Checklist
|
||||
|
||||
## Quick Review Checklist
|
||||
|
||||
### Correctness
|
||||
- [ ] Code does what it's supposed to do
|
||||
- [ ] Edge cases handled
|
||||
- [ ] Error handling in place
|
||||
- [ ] No obvious bugs
|
||||
|
||||
### Security
|
||||
- [ ] Input validated and sanitized
|
||||
- [ ] No SQL/NoSQL injection vulnerabilities
|
||||
- [ ] No XSS or CSRF vulnerabilities
|
||||
- [ ] No hardcoded secrets or sensitive credentials
|
||||
- [ ] **AI-Specific:** Protection against Prompt Injection (if applicable)
|
||||
- [ ] **AI-Specific:** Outputs are sanitized before being used in critical sinks
|
||||
|
||||
### Performance
|
||||
- [ ] No N+1 queries
|
||||
- [ ] No unnecessary loops
|
||||
- [ ] Appropriate caching
|
||||
- [ ] Bundle size impact considered
|
||||
|
||||
### Code Quality
|
||||
- [ ] Clear naming
|
||||
- [ ] DRY - no duplicate code
|
||||
- [ ] SOLID principles followed
|
||||
- [ ] Appropriate abstraction level
|
||||
|
||||
### Testing
|
||||
- [ ] Unit tests for new code
|
||||
- [ ] Edge cases tested
|
||||
- [ ] Tests readable and maintainable
|
||||
|
||||
### Documentation
|
||||
- [ ] Complex logic commented
|
||||
- [ ] Public APIs documented
|
||||
- [ ] README updated if needed
|
||||
|
||||
## AI & LLM Review Patterns (2025)
|
||||
|
||||
### Logic & Hallucinations
|
||||
- [ ] **Chain of Thought:** Does the logic follow a verifiable path?
|
||||
- [ ] **Edge Cases:** Did the AI account for empty states, timeouts, and partial failures?
|
||||
- [ ] **External State:** Is the code making safe assumptions about file systems or networks?
|
||||
|
||||
### Prompt Engineering Review
|
||||
```markdown
|
||||
// ❌ Vague prompt in code
|
||||
const response = await ai.generate(userInput);
|
||||
|
||||
// ✅ Structured & Safe prompt
|
||||
const response = await ai.generate({
|
||||
system: "You are a specialized parser...",
|
||||
input: sanitize(userInput),
|
||||
schema: ResponseSchema
|
||||
});
|
||||
```
|
||||
|
||||
## Anti-Patterns to Flag
|
||||
|
||||
```typescript
|
||||
// ❌ Magic numbers
|
||||
if (status === 3) { ... }
|
||||
|
||||
// ✅ Named constants
|
||||
if (status === Status.ACTIVE) { ... }
|
||||
|
||||
// ❌ Deep nesting
|
||||
if (a) { if (b) { if (c) { ... } } }
|
||||
|
||||
// ✅ Early returns
|
||||
if (!a) return;
|
||||
if (!b) return;
|
||||
if (!c) return;
|
||||
// do work
|
||||
|
||||
// ❌ Long functions (100+ lines)
|
||||
// ✅ Small, focused functions
|
||||
|
||||
// ❌ any type
|
||||
const data: any = ...
|
||||
|
||||
// ✅ Proper types
|
||||
const data: UserData = ...
|
||||
```
|
||||
|
||||
## Review Comments Guide
|
||||
|
||||
```
|
||||
// Blocking issues use 🔴
|
||||
🔴 BLOCKING: SQL injection vulnerability here
|
||||
|
||||
// Important suggestions use 🟡
|
||||
🟡 SUGGESTION: Consider using useMemo for performance
|
||||
|
||||
// Minor nits use 🟢
|
||||
🟢 NIT: Prefer const over let for immutable variable
|
||||
|
||||
// Questions use ❓
|
||||
❓ QUESTION: What happens if user is null here?
|
||||
```
|
||||
52
skills/database-design/SKILL.md
Normal file
52
skills/database-design/SKILL.md
Normal file
@@ -0,0 +1,52 @@
|
||||
---
|
||||
name: database-design
|
||||
description: Database design principles and decision-making. Schema design, indexing strategy, ORM selection, serverless databases.
|
||||
allowed-tools: Read, Write, Edit, Glob, Grep
|
||||
---
|
||||
|
||||
# Database Design
|
||||
|
||||
> **Learn to THINK, not copy SQL patterns.**
|
||||
|
||||
## 🎯 Selective Reading Rule
|
||||
|
||||
**Read ONLY files relevant to the request!** Check the content map, find what you need.
|
||||
|
||||
| File | Description | When to Read |
|
||||
|------|-------------|--------------|
|
||||
| `database-selection.md` | PostgreSQL vs Neon vs Turso vs SQLite | Choosing database |
|
||||
| `orm-selection.md` | Drizzle vs Prisma vs Kysely | Choosing ORM |
|
||||
| `schema-design.md` | Normalization, PKs, relationships | Designing schema |
|
||||
| `indexing.md` | Index types, composite indexes | Performance tuning |
|
||||
| `optimization.md` | N+1, EXPLAIN ANALYZE | Query optimization |
|
||||
| `migrations.md` | Safe migrations, serverless DBs | Schema changes |
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Core Principle
|
||||
|
||||
- ASK user for database preferences when unclear
|
||||
- Choose database/ORM based on CONTEXT
|
||||
- Don't default to PostgreSQL for everything
|
||||
|
||||
---
|
||||
|
||||
## Decision Checklist
|
||||
|
||||
Before designing schema:
|
||||
|
||||
- [ ] Asked user about database preference?
|
||||
- [ ] Chosen database for THIS context?
|
||||
- [ ] Considered deployment environment?
|
||||
- [ ] Planned index strategy?
|
||||
- [ ] Defined relationship types?
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
❌ Default to PostgreSQL for simple apps (SQLite may suffice)
|
||||
❌ Skip indexing
|
||||
❌ Use SELECT * in production
|
||||
❌ Store JSON when structured data is better
|
||||
❌ Ignore N+1 queries
|
||||
43
skills/database-design/database-selection.md
Normal file
43
skills/database-design/database-selection.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# Database Selection (2025)
|
||||
|
||||
> Choose database based on context, not default.
|
||||
|
||||
## Decision Tree
|
||||
|
||||
```
|
||||
What are your requirements?
|
||||
│
|
||||
├── Full relational features needed
|
||||
│ ├── Self-hosted → PostgreSQL
|
||||
│ └── Serverless → Neon, Supabase
|
||||
│
|
||||
├── Edge deployment / Ultra-low latency
|
||||
│ └── Turso (edge SQLite)
|
||||
│
|
||||
├── AI / Vector search
|
||||
│ └── PostgreSQL + pgvector
|
||||
│
|
||||
├── Simple / Embedded / Local
|
||||
│ └── SQLite
|
||||
│
|
||||
└── Global distribution
|
||||
└── PlanetScale, CockroachDB, Turso
|
||||
```
|
||||
|
||||
## Comparison
|
||||
|
||||
| Database | Best For | Trade-offs |
|
||||
|----------|----------|------------|
|
||||
| **PostgreSQL** | Full features, complex queries | Needs hosting |
|
||||
| **Neon** | Serverless PG, branching | PG complexity |
|
||||
| **Turso** | Edge, low latency | SQLite limitations |
|
||||
| **SQLite** | Simple, embedded, local | Single-writer |
|
||||
| **PlanetScale** | MySQL, global scale | No foreign keys |
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
1. What's the deployment environment?
|
||||
2. How complex are the queries?
|
||||
3. Is edge/serverless important?
|
||||
4. Vector search needed?
|
||||
5. Global distribution required?
|
||||
39
skills/database-design/indexing.md
Normal file
39
skills/database-design/indexing.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# Indexing Principles
|
||||
|
||||
> When and how to create indexes effectively.
|
||||
|
||||
## When to Create Indexes
|
||||
|
||||
```
|
||||
Index these:
|
||||
├── Columns in WHERE clauses
|
||||
├── Columns in JOIN conditions
|
||||
├── Columns in ORDER BY
|
||||
├── Foreign key columns
|
||||
└── Unique constraints
|
||||
|
||||
Don't over-index:
|
||||
├── Write-heavy tables (slower inserts)
|
||||
├── Low-cardinality columns
|
||||
├── Columns rarely queried
|
||||
```
|
||||
|
||||
## Index Type Selection
|
||||
|
||||
| Type | Use For |
|
||||
|------|---------|
|
||||
| **B-tree** | General purpose, equality & range |
|
||||
| **Hash** | Equality only, faster |
|
||||
| **GIN** | JSONB, arrays, full-text |
|
||||
| **GiST** | Geometric, range types |
|
||||
| **HNSW/IVFFlat** | Vector similarity (pgvector) |
|
||||
|
||||
## Composite Index Principles
|
||||
|
||||
```
|
||||
Order matters for composite indexes:
|
||||
├── Equality columns first
|
||||
├── Range columns last
|
||||
├── Most selective first
|
||||
└── Match query pattern
|
||||
```
|
||||
48
skills/database-design/migrations.md
Normal file
48
skills/database-design/migrations.md
Normal file
@@ -0,0 +1,48 @@
|
||||
# Migration Principles
|
||||
|
||||
> Safe migration strategy for zero-downtime changes.
|
||||
|
||||
## Safe Migration Strategy
|
||||
|
||||
```
|
||||
For zero-downtime changes:
|
||||
│
|
||||
├── Adding column
|
||||
│ └── Add as nullable → backfill → add NOT NULL
|
||||
│
|
||||
├── Removing column
|
||||
│ └── Stop using → deploy → remove column
|
||||
│
|
||||
├── Adding index
|
||||
│ └── CREATE INDEX CONCURRENTLY (non-blocking)
|
||||
│
|
||||
└── Renaming column
|
||||
└── Add new → migrate data → deploy → drop old
|
||||
```
|
||||
|
||||
## Migration Philosophy
|
||||
|
||||
- Never make breaking changes in one step
|
||||
- Test migrations on data copy first
|
||||
- Have rollback plan
|
||||
- Run in transaction when possible
|
||||
|
||||
## Serverless Databases
|
||||
|
||||
### Neon (Serverless PostgreSQL)
|
||||
|
||||
| Feature | Benefit |
|
||||
|---------|---------|
|
||||
| Scale to zero | Cost savings |
|
||||
| Instant branching | Dev/preview |
|
||||
| Full PostgreSQL | Compatibility |
|
||||
| Autoscaling | Traffic handling |
|
||||
|
||||
### Turso (Edge SQLite)
|
||||
|
||||
| Feature | Benefit |
|
||||
|---------|---------|
|
||||
| Edge locations | Ultra-low latency |
|
||||
| SQLite compatible | Simple |
|
||||
| Generous free tier | Cost |
|
||||
| Global distribution | Performance |
|
||||
36
skills/database-design/optimization.md
Normal file
36
skills/database-design/optimization.md
Normal file
@@ -0,0 +1,36 @@
|
||||
# Query Optimization
|
||||
|
||||
> N+1 problem, EXPLAIN ANALYZE, optimization priorities.
|
||||
|
||||
## N+1 Problem
|
||||
|
||||
```
|
||||
What is N+1?
|
||||
├── 1 query to get parent records
|
||||
├── N queries to get related records
|
||||
└── Very slow!
|
||||
|
||||
Solutions:
|
||||
├── JOIN → Single query with all data
|
||||
├── Eager loading → ORM handles JOIN
|
||||
├── DataLoader → Batch and cache (GraphQL)
|
||||
└── Subquery → Fetch related in one query
|
||||
```
|
||||
|
||||
## Query Analysis Mindset
|
||||
|
||||
```
|
||||
Before optimizing:
|
||||
├── EXPLAIN ANALYZE the query
|
||||
├── Look for Seq Scan (full table scan)
|
||||
├── Check actual vs estimated rows
|
||||
└── Identify missing indexes
|
||||
```
|
||||
|
||||
## Optimization Priorities
|
||||
|
||||
1. **Add missing indexes** (most common issue)
|
||||
2. **Select only needed columns** (not SELECT *)
|
||||
3. **Use proper JOINs** (avoid subqueries when possible)
|
||||
4. **Limit early** (pagination at database level)
|
||||
5. **Cache** (when appropriate)
|
||||
30
skills/database-design/orm-selection.md
Normal file
30
skills/database-design/orm-selection.md
Normal file
@@ -0,0 +1,30 @@
|
||||
# ORM Selection (2025)
|
||||
|
||||
> Choose ORM based on deployment and DX needs.
|
||||
|
||||
## Decision Tree
|
||||
|
||||
```
|
||||
What's the context?
|
||||
│
|
||||
├── Edge deployment / Bundle size matters
|
||||
│ └── Drizzle (smallest, SQL-like)
|
||||
│
|
||||
├── Best DX / Schema-first
|
||||
│ └── Prisma (migrations, studio)
|
||||
│
|
||||
├── Maximum control
|
||||
│ └── Raw SQL with query builder
|
||||
│
|
||||
└── Python ecosystem
|
||||
└── SQLAlchemy 2.0 (async support)
|
||||
```
|
||||
|
||||
## Comparison
|
||||
|
||||
| ORM | Best For | Trade-offs |
|
||||
|-----|----------|------------|
|
||||
| **Drizzle** | Edge, TypeScript | Newer, less examples |
|
||||
| **Prisma** | DX, schema management | Heavier, not edge-ready |
|
||||
| **Kysely** | Type-safe SQL builder | Manual migrations |
|
||||
| **Raw SQL** | Complex queries, control | Manual type safety |
|
||||
56
skills/database-design/schema-design.md
Normal file
56
skills/database-design/schema-design.md
Normal file
@@ -0,0 +1,56 @@
|
||||
# Schema Design Principles
|
||||
|
||||
> Normalization, primary keys, timestamps, relationships.
|
||||
|
||||
## Normalization Decision
|
||||
|
||||
```
|
||||
When to normalize (separate tables):
|
||||
├── Data is repeated across rows
|
||||
├── Updates would need multiple changes
|
||||
├── Relationships are clear
|
||||
└── Query patterns benefit
|
||||
|
||||
When to denormalize (embed/duplicate):
|
||||
├── Read performance critical
|
||||
├── Data rarely changes
|
||||
├── Always fetched together
|
||||
└── Simpler queries needed
|
||||
```
|
||||
|
||||
## Primary Key Selection
|
||||
|
||||
| Type | Use When |
|
||||
|------|----------|
|
||||
| **UUID** | Distributed systems, security |
|
||||
| **ULID** | UUID + sortable by time |
|
||||
| **Auto-increment** | Simple apps, single database |
|
||||
| **Natural key** | Rarely (business meaning) |
|
||||
|
||||
## Timestamp Strategy
|
||||
|
||||
```
|
||||
For every table:
|
||||
├── created_at → When created
|
||||
├── updated_at → Last modified
|
||||
└── deleted_at → Soft delete (if needed)
|
||||
|
||||
Use TIMESTAMPTZ (with timezone) not TIMESTAMP
|
||||
```
|
||||
|
||||
## Relationship Types
|
||||
|
||||
| Type | When | Implementation |
|
||||
|------|------|----------------|
|
||||
| **One-to-One** | Extension data | Separate table with FK |
|
||||
| **One-to-Many** | Parent-children | FK on child table |
|
||||
| **Many-to-Many** | Both sides have many | Junction table |
|
||||
|
||||
## Foreign Key ON DELETE
|
||||
|
||||
```
|
||||
├── CASCADE → Delete children with parent
|
||||
├── SET NULL → Children become orphans
|
||||
├── RESTRICT → Prevent delete if children exist
|
||||
└── SET DEFAULT → Children get default value
|
||||
```
|
||||
172
skills/database-design/scripts/schema_validator.py
Normal file
172
skills/database-design/scripts/schema_validator.py
Normal file
@@ -0,0 +1,172 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Schema Validator - Database schema validation
|
||||
Validates Prisma schemas and checks for common issues.
|
||||
|
||||
Usage:
|
||||
python schema_validator.py <project_path>
|
||||
|
||||
Checks:
|
||||
- Prisma schema syntax
|
||||
- Missing relations
|
||||
- Index recommendations
|
||||
- Naming conventions
|
||||
"""
|
||||
|
||||
import sys
|
||||
import json
|
||||
import re
|
||||
from pathlib import Path
|
||||
from datetime import datetime
|
||||
|
||||
# Fix Windows console encoding
|
||||
try:
|
||||
sys.stdout.reconfigure(encoding='utf-8', errors='replace')
|
||||
except:
|
||||
pass
|
||||
|
||||
|
||||
def find_schema_files(project_path: Path) -> list:
|
||||
"""Find database schema files."""
|
||||
schemas = []
|
||||
|
||||
# Prisma schema
|
||||
prisma_files = list(project_path.glob('**/prisma/schema.prisma'))
|
||||
schemas.extend([('prisma', f) for f in prisma_files])
|
||||
|
||||
# Drizzle schema files
|
||||
drizzle_files = list(project_path.glob('**/drizzle/*.ts'))
|
||||
drizzle_files.extend(project_path.glob('**/schema/*.ts'))
|
||||
for f in drizzle_files:
|
||||
if 'schema' in f.name.lower() or 'table' in f.name.lower():
|
||||
schemas.append(('drizzle', f))
|
||||
|
||||
return schemas[:10] # Limit
|
||||
|
||||
|
||||
def validate_prisma_schema(file_path: Path) -> list:
|
||||
"""Validate Prisma schema file."""
|
||||
issues = []
|
||||
|
||||
try:
|
||||
content = file_path.read_text(encoding='utf-8', errors='ignore')
|
||||
|
||||
# Find all models
|
||||
models = re.findall(r'model\s+(\w+)\s*{([^}]+)}', content, re.DOTALL)
|
||||
|
||||
for model_name, model_body in models:
|
||||
# Check naming convention (PascalCase)
|
||||
if not model_name[0].isupper():
|
||||
issues.append(f"Model '{model_name}' should be PascalCase")
|
||||
|
||||
# Check for id field
|
||||
if '@id' not in model_body and 'id' not in model_body.lower():
|
||||
issues.append(f"Model '{model_name}' might be missing @id field")
|
||||
|
||||
# Check for createdAt/updatedAt
|
||||
if 'createdAt' not in model_body and 'created_at' not in model_body:
|
||||
issues.append(f"Model '{model_name}' missing createdAt field (recommended)")
|
||||
|
||||
# Check for @relation without fields
|
||||
relations = re.findall(r'@relation\([^)]*\)', model_body)
|
||||
for rel in relations:
|
||||
if 'fields:' not in rel and 'references:' not in rel:
|
||||
pass # Implicit relation, ok
|
||||
|
||||
# Check for @@index suggestions
|
||||
foreign_keys = re.findall(r'(\w+Id)\s+\w+', model_body)
|
||||
for fk in foreign_keys:
|
||||
if f'@@index([{fk}])' not in content and f'@@index(["{fk}"])' not in content:
|
||||
issues.append(f"Consider adding @@index([{fk}]) for better query performance in {model_name}")
|
||||
|
||||
# Check for enum definitions
|
||||
enums = re.findall(r'enum\s+(\w+)\s*{', content)
|
||||
for enum_name in enums:
|
||||
if not enum_name[0].isupper():
|
||||
issues.append(f"Enum '{enum_name}' should be PascalCase")
|
||||
|
||||
except Exception as e:
|
||||
issues.append(f"Error reading schema: {str(e)[:50]}")
|
||||
|
||||
return issues
|
||||
|
||||
|
||||
def main():
|
||||
project_path = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
|
||||
|
||||
print(f"\n{'='*60}")
|
||||
print(f"[SCHEMA VALIDATOR] Database Schema Validation")
|
||||
print(f"{'='*60}")
|
||||
print(f"Project: {project_path}")
|
||||
print(f"Time: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
|
||||
print("-"*60)
|
||||
|
||||
# Find schema files
|
||||
schemas = find_schema_files(project_path)
|
||||
print(f"Found {len(schemas)} schema files")
|
||||
|
||||
if not schemas:
|
||||
output = {
|
||||
"script": "schema_validator",
|
||||
"project": str(project_path),
|
||||
"schemas_checked": 0,
|
||||
"issues_found": 0,
|
||||
"passed": True,
|
||||
"message": "No schema files found"
|
||||
}
|
||||
print(json.dumps(output, indent=2))
|
||||
sys.exit(0)
|
||||
|
||||
# Validate each schema
|
||||
all_issues = []
|
||||
|
||||
for schema_type, file_path in schemas:
|
||||
print(f"\nValidating: {file_path.name} ({schema_type})")
|
||||
|
||||
if schema_type == 'prisma':
|
||||
issues = validate_prisma_schema(file_path)
|
||||
else:
|
||||
issues = [] # Drizzle validation could be added
|
||||
|
||||
if issues:
|
||||
all_issues.append({
|
||||
"file": str(file_path.name),
|
||||
"type": schema_type,
|
||||
"issues": issues
|
||||
})
|
||||
|
||||
# Summary
|
||||
print("\n" + "="*60)
|
||||
print("SCHEMA ISSUES")
|
||||
print("="*60)
|
||||
|
||||
if all_issues:
|
||||
for item in all_issues:
|
||||
print(f"\n{item['file']} ({item['type']}):")
|
||||
for issue in item["issues"][:5]: # Limit per file
|
||||
print(f" - {issue}")
|
||||
if len(item["issues"]) > 5:
|
||||
print(f" ... and {len(item['issues']) - 5} more issues")
|
||||
else:
|
||||
print("No schema issues found!")
|
||||
|
||||
total_issues = sum(len(item["issues"]) for item in all_issues)
|
||||
# Schema issues are warnings, not failures
|
||||
passed = True
|
||||
|
||||
output = {
|
||||
"script": "schema_validator",
|
||||
"project": str(project_path),
|
||||
"schemas_checked": len(schemas),
|
||||
"issues_found": total_issues,
|
||||
"passed": passed,
|
||||
"issues": all_issues
|
||||
}
|
||||
|
||||
print("\n" + json.dumps(output, indent=2))
|
||||
|
||||
sys.exit(0)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
241
skills/deployment-procedures/SKILL.md
Normal file
241
skills/deployment-procedures/SKILL.md
Normal file
@@ -0,0 +1,241 @@
|
||||
---
|
||||
name: deployment-procedures
|
||||
description: Production deployment principles and decision-making. Safe deployment workflows, rollback strategies, and verification. Teaches thinking, not scripts.
|
||||
allowed-tools: Read, Glob, Grep, Bash
|
||||
---
|
||||
|
||||
# Deployment Procedures
|
||||
|
||||
> Deployment principles and decision-making for safe production releases.
|
||||
> **Learn to THINK, not memorize scripts.**
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ How to Use This Skill
|
||||
|
||||
This skill teaches **deployment principles**, not bash scripts to copy.
|
||||
|
||||
- Every deployment is unique
|
||||
- Understand the WHY behind each step
|
||||
- Adapt procedures to your platform
|
||||
|
||||
---
|
||||
|
||||
## 1. Platform Selection
|
||||
|
||||
### Decision Tree
|
||||
|
||||
```
|
||||
What are you deploying?
|
||||
│
|
||||
├── Static site / JAMstack
|
||||
│ └── Vercel, Netlify, Cloudflare Pages
|
||||
│
|
||||
├── Simple web app
|
||||
│ ├── Managed → Railway, Render, Fly.io
|
||||
│ └── Control → VPS + PM2/Docker
|
||||
│
|
||||
├── Microservices
|
||||
│ └── Container orchestration
|
||||
│
|
||||
└── Serverless
|
||||
└── Edge functions, Lambda
|
||||
```
|
||||
|
||||
### Each Platform Has Different Procedures
|
||||
|
||||
| Platform | Deployment Method |
|
||||
|----------|------------------|
|
||||
| **Vercel/Netlify** | Git push, auto-deploy |
|
||||
| **Railway/Render** | Git push or CLI |
|
||||
| **VPS + PM2** | SSH + manual steps |
|
||||
| **Docker** | Image push + orchestration |
|
||||
| **Kubernetes** | kubectl apply |
|
||||
|
||||
---
|
||||
|
||||
## 2. Pre-Deployment Principles
|
||||
|
||||
### The 4 Verification Categories
|
||||
|
||||
| Category | What to Check |
|
||||
|----------|--------------|
|
||||
| **Code Quality** | Tests passing, linting clean, reviewed |
|
||||
| **Build** | Production build works, no warnings |
|
||||
| **Environment** | Env vars set, secrets current |
|
||||
| **Safety** | Backup done, rollback plan ready |
|
||||
|
||||
### Pre-Deployment Checklist
|
||||
|
||||
- [ ] All tests passing
|
||||
- [ ] Code reviewed and approved
|
||||
- [ ] Production build successful
|
||||
- [ ] Environment variables verified
|
||||
- [ ] Database migrations ready (if any)
|
||||
- [ ] Rollback plan documented
|
||||
- [ ] Team notified
|
||||
- [ ] Monitoring ready
|
||||
|
||||
---
|
||||
|
||||
## 3. Deployment Workflow Principles
|
||||
|
||||
### The 5-Phase Process
|
||||
|
||||
```
|
||||
1. PREPARE
|
||||
└── Verify code, build, env vars
|
||||
|
||||
2. BACKUP
|
||||
└── Save current state before changing
|
||||
|
||||
3. DEPLOY
|
||||
└── Execute with monitoring open
|
||||
|
||||
4. VERIFY
|
||||
└── Health check, logs, key flows
|
||||
|
||||
5. CONFIRM or ROLLBACK
|
||||
└── All good? Confirm. Issues? Rollback.
|
||||
```
|
||||
|
||||
### Phase Principles
|
||||
|
||||
| Phase | Principle |
|
||||
|-------|-----------|
|
||||
| **Prepare** | Never deploy untested code |
|
||||
| **Backup** | Can't rollback without backup |
|
||||
| **Deploy** | Watch it happen, don't walk away |
|
||||
| **Verify** | Trust but verify |
|
||||
| **Confirm** | Have rollback trigger ready |
|
||||
|
||||
---
|
||||
|
||||
## 4. Post-Deployment Verification
|
||||
|
||||
### What to Verify
|
||||
|
||||
| Check | Why |
|
||||
|-------|-----|
|
||||
| **Health endpoint** | Service is running |
|
||||
| **Error logs** | No new errors |
|
||||
| **Key user flows** | Critical features work |
|
||||
| **Performance** | Response times acceptable |
|
||||
|
||||
### Verification Window
|
||||
|
||||
- **First 5 minutes**: Active monitoring
|
||||
- **15 minutes**: Confirm stable
|
||||
- **1 hour**: Final verification
|
||||
- **Next day**: Review metrics
|
||||
|
||||
---
|
||||
|
||||
## 5. Rollback Principles
|
||||
|
||||
### When to Rollback
|
||||
|
||||
| Symptom | Action |
|
||||
|---------|--------|
|
||||
| Service down | Rollback immediately |
|
||||
| Critical errors | Rollback |
|
||||
| Performance >50% degraded | Consider rollback |
|
||||
| Minor issues | Fix forward if quick |
|
||||
|
||||
### Rollback Strategy by Platform
|
||||
|
||||
| Platform | Rollback Method |
|
||||
|----------|----------------|
|
||||
| **Vercel/Netlify** | Redeploy previous commit |
|
||||
| **Railway/Render** | Rollback in dashboard |
|
||||
| **VPS + PM2** | Restore backup, restart |
|
||||
| **Docker** | Previous image tag |
|
||||
| **K8s** | kubectl rollout undo |
|
||||
|
||||
### Rollback Principles
|
||||
|
||||
1. **Speed over perfection**: Rollback first, debug later
|
||||
2. **Don't compound errors**: One rollback, not multiple changes
|
||||
3. **Communicate**: Tell team what happened
|
||||
4. **Post-mortem**: Understand why after stable
|
||||
|
||||
---
|
||||
|
||||
## 6. Zero-Downtime Deployment
|
||||
|
||||
### Strategies
|
||||
|
||||
| Strategy | How It Works |
|
||||
|----------|--------------|
|
||||
| **Rolling** | Replace instances one by one |
|
||||
| **Blue-Green** | Switch traffic between environments |
|
||||
| **Canary** | Gradual traffic shift |
|
||||
|
||||
### Selection Principles
|
||||
|
||||
| Scenario | Strategy |
|
||||
|----------|----------|
|
||||
| Standard release | Rolling |
|
||||
| High-risk change | Blue-green (easy rollback) |
|
||||
| Need validation | Canary (test with real traffic) |
|
||||
|
||||
---
|
||||
|
||||
## 7. Emergency Procedures
|
||||
|
||||
### Service Down Priority
|
||||
|
||||
1. **Assess**: What's the symptom?
|
||||
2. **Quick fix**: Restart if unclear
|
||||
3. **Rollback**: If restart doesn't help
|
||||
4. **Investigate**: After stable
|
||||
|
||||
### Investigation Order
|
||||
|
||||
| Check | Common Issues |
|
||||
|-------|--------------|
|
||||
| **Logs** | Errors, exceptions |
|
||||
| **Resources** | Disk full, memory |
|
||||
| **Network** | DNS, firewall |
|
||||
| **Dependencies** | Database, APIs |
|
||||
|
||||
---
|
||||
|
||||
## 8. Anti-Patterns
|
||||
|
||||
| ❌ Don't | ✅ Do |
|
||||
|----------|-------|
|
||||
| Deploy on Friday | Deploy early in week |
|
||||
| Rush deployment | Follow the process |
|
||||
| Skip staging | Always test first |
|
||||
| Deploy without backup | Backup before deploy |
|
||||
| Walk away after deploy | Monitor for 15+ min |
|
||||
| Multiple changes at once | One change at a time |
|
||||
|
||||
---
|
||||
|
||||
## 9. Decision Checklist
|
||||
|
||||
Before deploying:
|
||||
|
||||
- [ ] **Platform-appropriate procedure?**
|
||||
- [ ] **Backup strategy ready?**
|
||||
- [ ] **Rollback plan documented?**
|
||||
- [ ] **Monitoring configured?**
|
||||
- [ ] **Team notified?**
|
||||
- [ ] **Time to monitor after?**
|
||||
|
||||
---
|
||||
|
||||
## 10. Best Practices
|
||||
|
||||
1. **Small, frequent deploys** over big releases
|
||||
2. **Feature flags** for risky changes
|
||||
3. **Automate** repetitive steps
|
||||
4. **Document** every deployment
|
||||
5. **Review** what went wrong after issues
|
||||
6. **Test rollback** before you need it
|
||||
|
||||
---
|
||||
|
||||
> **Remember:** Every deployment is a risk. Minimize risk through preparation, not speed.
|
||||
409
skills/docker-expert/SKILL.md
Normal file
409
skills/docker-expert/SKILL.md
Normal file
@@ -0,0 +1,409 @@
|
||||
---
|
||||
name: docker-expert
|
||||
description: Docker containerization expert with deep knowledge of multi-stage builds, image optimization, container security, Docker Compose orchestration, and production deployment patterns. Use PROACTIVELY for Dockerfile optimization, container issues, image size problems, security hardening, networking, and orchestration challenges.
|
||||
category: devops
|
||||
color: blue
|
||||
displayName: Docker Expert
|
||||
---
|
||||
|
||||
# Docker Expert
|
||||
|
||||
You are an advanced Docker containerization expert with comprehensive, practical knowledge of container optimization, security hardening, multi-stage builds, orchestration patterns, and production deployment strategies based on current industry best practices.
|
||||
|
||||
## When invoked:
|
||||
|
||||
0. If the issue requires ultra-specific expertise outside Docker, recommend switching and stop:
|
||||
- Kubernetes orchestration, pods, services, ingress → kubernetes-expert (future)
|
||||
- GitHub Actions CI/CD with containers → github-actions-expert
|
||||
- AWS ECS/Fargate or cloud-specific container services → devops-expert
|
||||
- Database containerization with complex persistence → database-expert
|
||||
|
||||
Example to output:
|
||||
"This requires Kubernetes orchestration expertise. Please invoke: 'Use the kubernetes-expert subagent.' Stopping here."
|
||||
|
||||
1. Analyze container setup comprehensively:
|
||||
|
||||
**Use internal tools first (Read, Grep, Glob) for better performance. Shell commands are fallbacks.**
|
||||
|
||||
```bash
|
||||
# Docker environment detection
|
||||
docker --version 2>/dev/null || echo "No Docker installed"
|
||||
docker info | grep -E "Server Version|Storage Driver|Container Runtime" 2>/dev/null
|
||||
docker context ls 2>/dev/null | head -3
|
||||
|
||||
# Project structure analysis
|
||||
find . -name "Dockerfile*" -type f | head -10
|
||||
find . -name "*compose*.yml" -o -name "*compose*.yaml" -type f | head -5
|
||||
find . -name ".dockerignore" -type f | head -3
|
||||
|
||||
# Container status if running
|
||||
docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}" 2>/dev/null | head -10
|
||||
docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}" 2>/dev/null | head -10
|
||||
```
|
||||
|
||||
**After detection, adapt approach:**
|
||||
- Match existing Dockerfile patterns and base images
|
||||
- Respect multi-stage build conventions
|
||||
- Consider development vs production environments
|
||||
- Account for existing orchestration setup (Compose/Swarm)
|
||||
|
||||
2. Identify the specific problem category and complexity level
|
||||
|
||||
3. Apply the appropriate solution strategy from my expertise
|
||||
|
||||
4. Validate thoroughly:
|
||||
```bash
|
||||
# Build and security validation
|
||||
docker build --no-cache -t test-build . 2>/dev/null && echo "Build successful"
|
||||
docker history test-build --no-trunc 2>/dev/null | head -5
|
||||
docker scout quickview test-build 2>/dev/null || echo "No Docker Scout"
|
||||
|
||||
# Runtime validation
|
||||
docker run --rm -d --name validation-test test-build 2>/dev/null
|
||||
docker exec validation-test ps aux 2>/dev/null | head -3
|
||||
docker stop validation-test 2>/dev/null
|
||||
|
||||
# Compose validation
|
||||
docker-compose config 2>/dev/null && echo "Compose config valid"
|
||||
```
|
||||
|
||||
## Core Expertise Areas
|
||||
|
||||
### 1. Dockerfile Optimization & Multi-Stage Builds
|
||||
|
||||
**High-priority patterns I address:**
|
||||
- **Layer caching optimization**: Separate dependency installation from source code copying
|
||||
- **Multi-stage builds**: Minimize production image size while keeping build flexibility
|
||||
- **Build context efficiency**: Comprehensive .dockerignore and build context management
|
||||
- **Base image selection**: Alpine vs distroless vs scratch image strategies
|
||||
|
||||
**Key techniques:**
|
||||
```dockerfile
|
||||
# Optimized multi-stage pattern
|
||||
FROM node:18-alpine AS deps
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN npm ci --only=production && npm cache clean --force
|
||||
|
||||
FROM node:18-alpine AS build
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN npm ci
|
||||
COPY . .
|
||||
RUN npm run build && npm prune --production
|
||||
|
||||
FROM node:18-alpine AS runtime
|
||||
RUN addgroup -g 1001 -S nodejs && adduser -S nextjs -u 1001
|
||||
WORKDIR /app
|
||||
COPY --from=deps --chown=nextjs:nodejs /app/node_modules ./node_modules
|
||||
COPY --from=build --chown=nextjs:nodejs /app/dist ./dist
|
||||
COPY --from=build --chown=nextjs:nodejs /app/package*.json ./
|
||||
USER nextjs
|
||||
EXPOSE 3000
|
||||
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
|
||||
CMD curl -f http://localhost:3000/health || exit 1
|
||||
CMD ["node", "dist/index.js"]
|
||||
```
|
||||
|
||||
### 2. Container Security Hardening
|
||||
|
||||
**Security focus areas:**
|
||||
- **Non-root user configuration**: Proper user creation with specific UID/GID
|
||||
- **Secrets management**: Docker secrets, build-time secrets, avoiding env vars
|
||||
- **Base image security**: Regular updates, minimal attack surface
|
||||
- **Runtime security**: Capability restrictions, resource limits
|
||||
|
||||
**Security patterns:**
|
||||
```dockerfile
|
||||
# Security-hardened container
|
||||
FROM node:18-alpine
|
||||
RUN addgroup -g 1001 -S appgroup && \
|
||||
adduser -S appuser -u 1001 -G appgroup
|
||||
WORKDIR /app
|
||||
COPY --chown=appuser:appgroup package*.json ./
|
||||
RUN npm ci --only=production
|
||||
COPY --chown=appuser:appgroup . .
|
||||
USER 1001
|
||||
# Drop capabilities, set read-only root filesystem
|
||||
```
|
||||
|
||||
### 3. Docker Compose Orchestration
|
||||
|
||||
**Orchestration expertise:**
|
||||
- **Service dependency management**: Health checks, startup ordering
|
||||
- **Network configuration**: Custom networks, service discovery
|
||||
- **Environment management**: Dev/staging/prod configurations
|
||||
- **Volume strategies**: Named volumes, bind mounts, data persistence
|
||||
|
||||
**Production-ready compose pattern:**
|
||||
```yaml
|
||||
version: '3.8'
|
||||
services:
|
||||
app:
|
||||
build:
|
||||
context: .
|
||||
target: production
|
||||
depends_on:
|
||||
db:
|
||||
condition: service_healthy
|
||||
networks:
|
||||
- frontend
|
||||
- backend
|
||||
healthcheck:
|
||||
test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
start_period: 40s
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '0.5'
|
||||
memory: 512M
|
||||
reservations:
|
||||
cpus: '0.25'
|
||||
memory: 256M
|
||||
|
||||
db:
|
||||
image: postgres:15-alpine
|
||||
environment:
|
||||
POSTGRES_DB_FILE: /run/secrets/db_name
|
||||
POSTGRES_USER_FILE: /run/secrets/db_user
|
||||
POSTGRES_PASSWORD_FILE: /run/secrets/db_password
|
||||
secrets:
|
||||
- db_name
|
||||
- db_user
|
||||
- db_password
|
||||
volumes:
|
||||
- postgres_data:/var/lib/postgresql/data
|
||||
networks:
|
||||
- backend
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
|
||||
networks:
|
||||
frontend:
|
||||
driver: bridge
|
||||
backend:
|
||||
driver: bridge
|
||||
internal: true
|
||||
|
||||
volumes:
|
||||
postgres_data:
|
||||
|
||||
secrets:
|
||||
db_name:
|
||||
external: true
|
||||
db_user:
|
||||
external: true
|
||||
db_password:
|
||||
external: true
|
||||
```
|
||||
|
||||
### 4. Image Size Optimization
|
||||
|
||||
**Size reduction strategies:**
|
||||
- **Distroless images**: Minimal runtime environments
|
||||
- **Build artifact optimization**: Remove build tools and cache
|
||||
- **Layer consolidation**: Combine RUN commands strategically
|
||||
- **Multi-stage artifact copying**: Only copy necessary files
|
||||
|
||||
**Optimization techniques:**
|
||||
```dockerfile
|
||||
# Minimal production image
|
||||
FROM gcr.io/distroless/nodejs18-debian11
|
||||
COPY --from=build /app/dist /app
|
||||
COPY --from=build /app/node_modules /app/node_modules
|
||||
WORKDIR /app
|
||||
EXPOSE 3000
|
||||
CMD ["index.js"]
|
||||
```
|
||||
|
||||
### 5. Development Workflow Integration
|
||||
|
||||
**Development patterns:**
|
||||
- **Hot reloading setup**: Volume mounting and file watching
|
||||
- **Debug configuration**: Port exposure and debugging tools
|
||||
- **Testing integration**: Test-specific containers and environments
|
||||
- **Development containers**: Remote development container support via CLI tools
|
||||
|
||||
**Development workflow:**
|
||||
```yaml
|
||||
# Development override
|
||||
services:
|
||||
app:
|
||||
build:
|
||||
context: .
|
||||
target: development
|
||||
volumes:
|
||||
- .:/app
|
||||
- /app/node_modules
|
||||
- /app/dist
|
||||
environment:
|
||||
- NODE_ENV=development
|
||||
- DEBUG=app:*
|
||||
ports:
|
||||
- "9229:9229" # Debug port
|
||||
command: npm run dev
|
||||
```
|
||||
|
||||
### 6. Performance & Resource Management
|
||||
|
||||
**Performance optimization:**
|
||||
- **Resource limits**: CPU, memory constraints for stability
|
||||
- **Build performance**: Parallel builds, cache utilization
|
||||
- **Runtime performance**: Process management, signal handling
|
||||
- **Monitoring integration**: Health checks, metrics exposure
|
||||
|
||||
**Resource management:**
|
||||
```yaml
|
||||
services:
|
||||
app:
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '1.0'
|
||||
memory: 1G
|
||||
reservations:
|
||||
cpus: '0.5'
|
||||
memory: 512M
|
||||
restart_policy:
|
||||
condition: on-failure
|
||||
delay: 5s
|
||||
max_attempts: 3
|
||||
window: 120s
|
||||
```
|
||||
|
||||
## Advanced Problem-Solving Patterns
|
||||
|
||||
### Cross-Platform Builds
|
||||
```bash
|
||||
# Multi-architecture builds
|
||||
docker buildx create --name multiarch-builder --use
|
||||
docker buildx build --platform linux/amd64,linux/arm64 \
|
||||
-t myapp:latest --push .
|
||||
```
|
||||
|
||||
### Build Cache Optimization
|
||||
```dockerfile
|
||||
# Mount build cache for package managers
|
||||
FROM node:18-alpine AS deps
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN --mount=type=cache,target=/root/.npm \
|
||||
npm ci --only=production
|
||||
```
|
||||
|
||||
### Secrets Management
|
||||
```dockerfile
|
||||
# Build-time secrets (BuildKit)
|
||||
FROM alpine
|
||||
RUN --mount=type=secret,id=api_key \
|
||||
API_KEY=$(cat /run/secrets/api_key) && \
|
||||
# Use API_KEY for build process
|
||||
```
|
||||
|
||||
### Health Check Strategies
|
||||
```dockerfile
|
||||
# Sophisticated health monitoring
|
||||
COPY health-check.sh /usr/local/bin/
|
||||
RUN chmod +x /usr/local/bin/health-check.sh
|
||||
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
|
||||
CMD ["/usr/local/bin/health-check.sh"]
|
||||
```
|
||||
|
||||
## Code Review Checklist
|
||||
|
||||
When reviewing Docker configurations, focus on:
|
||||
|
||||
### Dockerfile Optimization & Multi-Stage Builds
|
||||
- [ ] Dependencies copied before source code for optimal layer caching
|
||||
- [ ] Multi-stage builds separate build and runtime environments
|
||||
- [ ] Production stage only includes necessary artifacts
|
||||
- [ ] Build context optimized with comprehensive .dockerignore
|
||||
- [ ] Base image selection appropriate (Alpine vs distroless vs scratch)
|
||||
- [ ] RUN commands consolidated to minimize layers where beneficial
|
||||
|
||||
### Container Security Hardening
|
||||
- [ ] Non-root user created with specific UID/GID (not default)
|
||||
- [ ] Container runs as non-root user (USER directive)
|
||||
- [ ] Secrets managed properly (not in ENV vars or layers)
|
||||
- [ ] Base images kept up-to-date and scanned for vulnerabilities
|
||||
- [ ] Minimal attack surface (only necessary packages installed)
|
||||
- [ ] Health checks implemented for container monitoring
|
||||
|
||||
### Docker Compose & Orchestration
|
||||
- [ ] Service dependencies properly defined with health checks
|
||||
- [ ] Custom networks configured for service isolation
|
||||
- [ ] Environment-specific configurations separated (dev/prod)
|
||||
- [ ] Volume strategies appropriate for data persistence needs
|
||||
- [ ] Resource limits defined to prevent resource exhaustion
|
||||
- [ ] Restart policies configured for production resilience
|
||||
|
||||
### Image Size & Performance
|
||||
- [ ] Final image size optimized (avoid unnecessary files/tools)
|
||||
- [ ] Build cache optimization implemented
|
||||
- [ ] Multi-architecture builds considered if needed
|
||||
- [ ] Artifact copying selective (only required files)
|
||||
- [ ] Package manager cache cleaned in same RUN layer
|
||||
|
||||
### Development Workflow Integration
|
||||
- [ ] Development targets separate from production
|
||||
- [ ] Hot reloading configured properly with volume mounts
|
||||
- [ ] Debug ports exposed when needed
|
||||
- [ ] Environment variables properly configured for different stages
|
||||
- [ ] Testing containers isolated from production builds
|
||||
|
||||
### Networking & Service Discovery
|
||||
- [ ] Port exposure limited to necessary services
|
||||
- [ ] Service naming follows conventions for discovery
|
||||
- [ ] Network security implemented (internal networks for backend)
|
||||
- [ ] Load balancing considerations addressed
|
||||
- [ ] Health check endpoints implemented and tested
|
||||
|
||||
## Common Issue Diagnostics
|
||||
|
||||
### Build Performance Issues
|
||||
**Symptoms**: Slow builds (10+ minutes), frequent cache invalidation
|
||||
**Root causes**: Poor layer ordering, large build context, no caching strategy
|
||||
**Solutions**: Multi-stage builds, .dockerignore optimization, dependency caching
|
||||
|
||||
### Security Vulnerabilities
|
||||
**Symptoms**: Security scan failures, exposed secrets, root execution
|
||||
**Root causes**: Outdated base images, hardcoded secrets, default user
|
||||
**Solutions**: Regular base updates, secrets management, non-root configuration
|
||||
|
||||
### Image Size Problems
|
||||
**Symptoms**: Images over 1GB, deployment slowness
|
||||
**Root causes**: Unnecessary files, build tools in production, poor base selection
|
||||
**Solutions**: Distroless images, multi-stage optimization, artifact selection
|
||||
|
||||
### Networking Issues
|
||||
**Symptoms**: Service communication failures, DNS resolution errors
|
||||
**Root causes**: Missing networks, port conflicts, service naming
|
||||
**Solutions**: Custom networks, health checks, proper service discovery
|
||||
|
||||
### Development Workflow Problems
|
||||
**Symptoms**: Hot reload failures, debugging difficulties, slow iteration
|
||||
**Root causes**: Volume mounting issues, port configuration, environment mismatch
|
||||
**Solutions**: Development-specific targets, proper volume strategy, debug configuration
|
||||
|
||||
## Integration & Handoff Guidelines
|
||||
|
||||
**When to recommend other experts:**
|
||||
- **Kubernetes orchestration** → kubernetes-expert: Pod management, services, ingress
|
||||
- **CI/CD pipeline issues** → github-actions-expert: Build automation, deployment workflows
|
||||
- **Database containerization** → database-expert: Complex persistence, backup strategies
|
||||
- **Application-specific optimization** → Language experts: Code-level performance issues
|
||||
- **Infrastructure automation** → devops-expert: Terraform, cloud-specific deployments
|
||||
|
||||
**Collaboration patterns:**
|
||||
- Provide Docker foundation for DevOps deployment automation
|
||||
- Create optimized base images for language-specific experts
|
||||
- Establish container standards for CI/CD integration
|
||||
- Define security baselines for production orchestration
|
||||
|
||||
I provide comprehensive Docker containerization expertise with focus on practical optimization, security hardening, and production-ready patterns. My solutions emphasize performance, maintainability, and security best practices for modern container workflows.
|
||||
194
skills/documentation-templates/SKILL.md
Normal file
194
skills/documentation-templates/SKILL.md
Normal file
@@ -0,0 +1,194 @@
|
||||
---
|
||||
name: documentation-templates
|
||||
description: Documentation templates and structure guidelines. README, API docs, code comments, and AI-friendly documentation.
|
||||
allowed-tools: Read, Glob, Grep
|
||||
---
|
||||
|
||||
# Documentation Templates
|
||||
|
||||
> Templates and structure guidelines for common documentation types.
|
||||
|
||||
---
|
||||
|
||||
## 1. README Structure
|
||||
|
||||
### Essential Sections (Priority Order)
|
||||
|
||||
| Section | Purpose |
|
||||
|---------|---------|
|
||||
| **Title + One-liner** | What is this? |
|
||||
| **Quick Start** | Running in <5 min |
|
||||
| **Features** | What can I do? |
|
||||
| **Configuration** | How to customize |
|
||||
| **API Reference** | Link to detailed docs |
|
||||
| **Contributing** | How to help |
|
||||
| **License** | Legal |
|
||||
|
||||
### README Template
|
||||
|
||||
```markdown
|
||||
# Project Name
|
||||
|
||||
Brief one-line description.
|
||||
|
||||
## Quick Start
|
||||
|
||||
[Minimum steps to run]
|
||||
|
||||
## Features
|
||||
|
||||
- Feature 1
|
||||
- Feature 2
|
||||
|
||||
## Configuration
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| PORT | Server port | 3000 |
|
||||
|
||||
## Documentation
|
||||
|
||||
- [API Reference](./docs/api.md)
|
||||
- [Architecture](./docs/architecture.md)
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. API Documentation Structure
|
||||
|
||||
### Per-Endpoint Template
|
||||
|
||||
```markdown
|
||||
## GET /users/:id
|
||||
|
||||
Get a user by ID.
|
||||
|
||||
**Parameters:**
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| id | string | Yes | User ID |
|
||||
|
||||
**Response:**
|
||||
- 200: User object
|
||||
- 404: User not found
|
||||
|
||||
**Example:**
|
||||
[Request and response example]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Code Comment Guidelines
|
||||
|
||||
### JSDoc/TSDoc Template
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* Brief description of what the function does.
|
||||
*
|
||||
* @param paramName - Description of parameter
|
||||
* @returns Description of return value
|
||||
* @throws ErrorType - When this error occurs
|
||||
*
|
||||
* @example
|
||||
* const result = functionName(input);
|
||||
*/
|
||||
```
|
||||
|
||||
### When to Comment
|
||||
|
||||
| ✅ Comment | ❌ Don't Comment |
|
||||
|-----------|-----------------|
|
||||
| Why (business logic) | What (obvious) |
|
||||
| Complex algorithms | Every line |
|
||||
| Non-obvious behavior | Self-explanatory code |
|
||||
| API contracts | Implementation details |
|
||||
|
||||
---
|
||||
|
||||
## 4. Changelog Template (Keep a Changelog)
|
||||
|
||||
```markdown
|
||||
# Changelog
|
||||
|
||||
## [Unreleased]
|
||||
### Added
|
||||
- New feature
|
||||
|
||||
## [1.0.0] - 2025-01-01
|
||||
### Added
|
||||
- Initial release
|
||||
### Changed
|
||||
- Updated dependency
|
||||
### Fixed
|
||||
- Bug fix
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Architecture Decision Record (ADR)
|
||||
|
||||
```markdown
|
||||
# ADR-001: [Title]
|
||||
|
||||
## Status
|
||||
Accepted / Deprecated / Superseded
|
||||
|
||||
## Context
|
||||
Why are we making this decision?
|
||||
|
||||
## Decision
|
||||
What did we decide?
|
||||
|
||||
## Consequences
|
||||
What are the trade-offs?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. AI-Friendly Documentation (2025)
|
||||
|
||||
### llms.txt Template
|
||||
|
||||
For AI crawlers and agents:
|
||||
|
||||
```markdown
|
||||
# Project Name
|
||||
> One-line objective.
|
||||
|
||||
## Core Files
|
||||
- [src/index.ts]: Main entry
|
||||
- [src/api/]: API routes
|
||||
- [docs/]: Documentation
|
||||
|
||||
## Key Concepts
|
||||
- Concept 1: Brief explanation
|
||||
- Concept 2: Brief explanation
|
||||
```
|
||||
|
||||
### MCP-Ready Documentation
|
||||
|
||||
For RAG indexing:
|
||||
- Clear H1-H3 hierarchy
|
||||
- JSON/YAML examples for data structures
|
||||
- Mermaid diagrams for flows
|
||||
- Self-contained sections
|
||||
|
||||
---
|
||||
|
||||
## 7. Structure Principles
|
||||
|
||||
| Principle | Why |
|
||||
|-----------|-----|
|
||||
| **Scannable** | Headers, lists, tables |
|
||||
| **Examples first** | Show, don't just tell |
|
||||
| **Progressive detail** | Simple → Complex |
|
||||
| **Up to date** | Outdated = misleading |
|
||||
|
||||
---
|
||||
|
||||
> **Remember:** Templates are starting points. Adapt to your project's needs.
|
||||
@@ -1,6 +1,9 @@
|
||||
---
|
||||
name: Ethical Hacking Methodology
|
||||
description: This skill should be used when the user asks to "learn ethical hacking", "understand penetration testing lifecycle", "perform reconnaissance", "conduct security scanning", "exploit vulnerabilities", or "write penetration test reports". It provides comprehensive ethical hacking methodology and techniques.
|
||||
metadata:
|
||||
author: zebbern
|
||||
version: "1.1"
|
||||
---
|
||||
|
||||
# Ethical Hacking Methodology
|
||||
|
||||
@@ -1,6 +1,9 @@
|
||||
---
|
||||
name: File Path Traversal Testing
|
||||
description: This skill should be used when the user asks to "test for directory traversal", "exploit path traversal vulnerabilities", "read arbitrary files through web applications", "find LFI vulnerabilities", or "access files outside web root". It provides comprehensive file path traversal attack and testing methodologies.
|
||||
metadata:
|
||||
author: zebbern
|
||||
version: "1.1"
|
||||
---
|
||||
|
||||
# File Path Traversal Testing
|
||||
|
||||
119
skills/game-development/2d-games/SKILL.md
Normal file
119
skills/game-development/2d-games/SKILL.md
Normal file
@@ -0,0 +1,119 @@
|
||||
---
|
||||
name: 2d-games
|
||||
description: 2D game development principles. Sprites, tilemaps, physics, camera.
|
||||
allowed-tools: Read, Write, Edit, Glob, Grep
|
||||
---
|
||||
|
||||
# 2D Game Development
|
||||
|
||||
> Principles for 2D game systems.
|
||||
|
||||
---
|
||||
|
||||
## 1. Sprite Systems
|
||||
|
||||
### Sprite Organization
|
||||
|
||||
| Component | Purpose |
|
||||
|-----------|---------|
|
||||
| **Atlas** | Combine textures, reduce draw calls |
|
||||
| **Animation** | Frame sequences |
|
||||
| **Pivot** | Rotation/scale origin |
|
||||
| **Layering** | Z-order control |
|
||||
|
||||
### Animation Principles
|
||||
|
||||
- Frame rate: 8-24 FPS typical
|
||||
- Squash and stretch for impact
|
||||
- Anticipation before action
|
||||
- Follow-through after action
|
||||
|
||||
---
|
||||
|
||||
## 2. Tilemap Design
|
||||
|
||||
### Tile Considerations
|
||||
|
||||
| Factor | Recommendation |
|
||||
|--------|----------------|
|
||||
| **Size** | 16x16, 32x32, 64x64 |
|
||||
| **Auto-tiling** | Use for terrain |
|
||||
| **Collision** | Simplified shapes |
|
||||
|
||||
### Layers
|
||||
|
||||
| Layer | Content |
|
||||
|-------|---------|
|
||||
| Background | Non-interactive scenery |
|
||||
| Terrain | Walkable ground |
|
||||
| Props | Interactive objects |
|
||||
| Foreground | Parallax overlay |
|
||||
|
||||
---
|
||||
|
||||
## 3. 2D Physics
|
||||
|
||||
### Collision Shapes
|
||||
|
||||
| Shape | Use Case |
|
||||
|-------|----------|
|
||||
| Box | Rectangular objects |
|
||||
| Circle | Balls, rounded |
|
||||
| Capsule | Characters |
|
||||
| Polygon | Complex shapes |
|
||||
|
||||
### Physics Considerations
|
||||
|
||||
- Pixel-perfect vs physics-based
|
||||
- Fixed timestep for consistency
|
||||
- Layers for filtering
|
||||
|
||||
---
|
||||
|
||||
## 4. Camera Systems
|
||||
|
||||
### Camera Types
|
||||
|
||||
| Type | Use |
|
||||
|------|-----|
|
||||
| **Follow** | Track player |
|
||||
| **Look-ahead** | Anticipate movement |
|
||||
| **Multi-target** | Two-player |
|
||||
| **Room-based** | Metroidvania |
|
||||
|
||||
### Screen Shake
|
||||
|
||||
- Short duration (50-200ms)
|
||||
- Diminishing intensity
|
||||
- Use sparingly
|
||||
|
||||
---
|
||||
|
||||
## 5. Genre Patterns
|
||||
|
||||
### Platformer
|
||||
|
||||
- Coyote time (leniency after edge)
|
||||
- Jump buffering
|
||||
- Variable jump height
|
||||
|
||||
### Top-down
|
||||
|
||||
- 8-directional or free movement
|
||||
- Aim-based or auto-aim
|
||||
- Consider rotation or not
|
||||
|
||||
---
|
||||
|
||||
## 6. Anti-Patterns
|
||||
|
||||
| ❌ Don't | ✅ Do |
|
||||
|----------|-------|
|
||||
| Separate textures | Use atlases |
|
||||
| Complex collision shapes | Simplified collision |
|
||||
| Jittery camera | Smooth following |
|
||||
| Pixel-perfect on physics | Choose one approach |
|
||||
|
||||
---
|
||||
|
||||
> **Remember:** 2D is about clarity. Every pixel should communicate.
|
||||
135
skills/game-development/3d-games/SKILL.md
Normal file
135
skills/game-development/3d-games/SKILL.md
Normal file
@@ -0,0 +1,135 @@
|
||||
---
|
||||
name: 3d-games
|
||||
description: 3D game development principles. Rendering, shaders, physics, cameras.
|
||||
allowed-tools: Read, Write, Edit, Glob, Grep
|
||||
---
|
||||
|
||||
# 3D Game Development
|
||||
|
||||
> Principles for 3D game systems.
|
||||
|
||||
---
|
||||
|
||||
## 1. Rendering Pipeline
|
||||
|
||||
### Stages
|
||||
|
||||
```
|
||||
1. Vertex Processing → Transform geometry
|
||||
2. Rasterization → Convert to pixels
|
||||
3. Fragment Processing → Color pixels
|
||||
4. Output → To screen
|
||||
```
|
||||
|
||||
### Optimization Principles
|
||||
|
||||
| Technique | Purpose |
|
||||
|-----------|---------|
|
||||
| **Frustum culling** | Don't render off-screen |
|
||||
| **Occlusion culling** | Don't render hidden |
|
||||
| **LOD** | Less detail at distance |
|
||||
| **Batching** | Combine draw calls |
|
||||
|
||||
---
|
||||
|
||||
## 2. Shader Principles
|
||||
|
||||
### Shader Types
|
||||
|
||||
| Type | Purpose |
|
||||
|------|---------|
|
||||
| **Vertex** | Position, normals |
|
||||
| **Fragment/Pixel** | Color, lighting |
|
||||
| **Compute** | General computation |
|
||||
|
||||
### When to Write Custom Shaders
|
||||
|
||||
- Special effects (water, fire, portals)
|
||||
- Stylized rendering (toon, sketch)
|
||||
- Performance optimization
|
||||
- Unique visual identity
|
||||
|
||||
---
|
||||
|
||||
## 3. 3D Physics
|
||||
|
||||
### Collision Shapes
|
||||
|
||||
| Shape | Use Case |
|
||||
|-------|----------|
|
||||
| **Box** | Buildings, crates |
|
||||
| **Sphere** | Balls, quick checks |
|
||||
| **Capsule** | Characters |
|
||||
| **Mesh** | Terrain (expensive) |
|
||||
|
||||
### Principles
|
||||
|
||||
- Simple colliders, complex visuals
|
||||
- Layer-based filtering
|
||||
- Raycasting for line-of-sight
|
||||
|
||||
---
|
||||
|
||||
## 4. Camera Systems
|
||||
|
||||
### Camera Types
|
||||
|
||||
| Type | Use |
|
||||
|------|-----|
|
||||
| **Third-person** | Action, adventure |
|
||||
| **First-person** | Immersive, FPS |
|
||||
| **Isometric** | Strategy, RPG |
|
||||
| **Orbital** | Inspection, editors |
|
||||
|
||||
### Camera Feel
|
||||
|
||||
- Smooth following (lerp)
|
||||
- Collision avoidance
|
||||
- Look-ahead for movement
|
||||
- FOV changes for speed
|
||||
|
||||
---
|
||||
|
||||
## 5. Lighting
|
||||
|
||||
### Light Types
|
||||
|
||||
| Type | Use |
|
||||
|------|-----|
|
||||
| **Directional** | Sun, moon |
|
||||
| **Point** | Lamps, torches |
|
||||
| **Spot** | Flashlight, stage |
|
||||
| **Ambient** | Base illumination |
|
||||
|
||||
### Performance Consideration
|
||||
|
||||
- Real-time shadows are expensive
|
||||
- Bake when possible
|
||||
- Shadow cascades for large worlds
|
||||
|
||||
---
|
||||
|
||||
## 6. Level of Detail (LOD)
|
||||
|
||||
### LOD Strategy
|
||||
|
||||
| Distance | Model |
|
||||
|----------|-------|
|
||||
| Near | Full detail |
|
||||
| Medium | 50% triangles |
|
||||
| Far | 25% or billboard |
|
||||
|
||||
---
|
||||
|
||||
## 7. Anti-Patterns
|
||||
|
||||
| ❌ Don't | ✅ Do |
|
||||
|----------|-------|
|
||||
| Mesh colliders everywhere | Simple shapes |
|
||||
| Real-time shadows on mobile | Baked or blob shadows |
|
||||
| One LOD for all distances | Distance-based LOD |
|
||||
| Unoptimized shaders | Profile and simplify |
|
||||
|
||||
---
|
||||
|
||||
> **Remember:** 3D is about illusion. Create the impression of detail, not the detail itself.
|
||||
167
skills/game-development/SKILL.md
Normal file
167
skills/game-development/SKILL.md
Normal file
@@ -0,0 +1,167 @@
|
||||
---
|
||||
name: game-development
|
||||
description: Game development orchestrator. Routes to platform-specific skills based on project needs.
|
||||
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
|
||||
---
|
||||
|
||||
# Game Development
|
||||
|
||||
> **Orchestrator skill** that provides core principles and routes to specialized sub-skills.
|
||||
|
||||
---
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
You are working on a game development project. This skill teaches the PRINCIPLES of game development and directs you to the right sub-skill based on context.
|
||||
|
||||
---
|
||||
|
||||
## Sub-Skill Routing
|
||||
|
||||
### Platform Selection
|
||||
|
||||
| If the game targets... | Use Sub-Skill |
|
||||
|------------------------|---------------|
|
||||
| Web browsers (HTML5, WebGL) | `game-development/web-games` |
|
||||
| Mobile (iOS, Android) | `game-development/mobile-games` |
|
||||
| PC (Steam, Desktop) | `game-development/pc-games` |
|
||||
| VR/AR headsets | `game-development/vr-ar` |
|
||||
|
||||
### Dimension Selection
|
||||
|
||||
| If the game is... | Use Sub-Skill |
|
||||
|-------------------|---------------|
|
||||
| 2D (sprites, tilemaps) | `game-development/2d-games` |
|
||||
| 3D (meshes, shaders) | `game-development/3d-games` |
|
||||
|
||||
### Specialty Areas
|
||||
|
||||
| If you need... | Use Sub-Skill |
|
||||
|----------------|---------------|
|
||||
| GDD, balancing, player psychology | `game-development/game-design` |
|
||||
| Multiplayer, networking | `game-development/multiplayer` |
|
||||
| Visual style, asset pipeline, animation | `game-development/game-art` |
|
||||
| Sound design, music, adaptive audio | `game-development/game-audio` |
|
||||
|
||||
---
|
||||
|
||||
## Core Principles (All Platforms)
|
||||
|
||||
### 1. The Game Loop
|
||||
|
||||
Every game, regardless of platform, follows this pattern:
|
||||
|
||||
```
|
||||
INPUT → Read player actions
|
||||
UPDATE → Process game logic (fixed timestep)
|
||||
RENDER → Draw the frame (interpolated)
|
||||
```
|
||||
|
||||
**Fixed Timestep Rule:**
|
||||
- Physics/logic: Fixed rate (e.g., 50Hz)
|
||||
- Rendering: As fast as possible
|
||||
- Interpolate between states for smooth visuals
|
||||
|
||||
---
|
||||
|
||||
### 2. Pattern Selection Matrix
|
||||
|
||||
| Pattern | Use When | Example |
|
||||
|---------|----------|---------|
|
||||
| **State Machine** | 3-5 discrete states | Player: Idle→Walk→Jump |
|
||||
| **Object Pooling** | Frequent spawn/destroy | Bullets, particles |
|
||||
| **Observer/Events** | Cross-system communication | Health→UI updates |
|
||||
| **ECS** | Thousands of similar entities | RTS units, particles |
|
||||
| **Command** | Undo, replay, networking | Input recording |
|
||||
| **Behavior Tree** | Complex AI decisions | Enemy AI |
|
||||
|
||||
**Decision Rule:** Start with State Machine. Add ECS only when performance demands.
|
||||
|
||||
---
|
||||
|
||||
### 3. Input Abstraction
|
||||
|
||||
Abstract input into ACTIONS, not raw keys:
|
||||
|
||||
```
|
||||
"jump" → Space, Gamepad A, Touch tap
|
||||
"move" → WASD, Left stick, Virtual joystick
|
||||
```
|
||||
|
||||
**Why:** Enables multi-platform, rebindable controls.
|
||||
|
||||
---
|
||||
|
||||
### 4. Performance Budget (60 FPS = 16.67ms)
|
||||
|
||||
| System | Budget |
|
||||
|--------|--------|
|
||||
| Input | 1ms |
|
||||
| Physics | 3ms |
|
||||
| AI | 2ms |
|
||||
| Game Logic | 4ms |
|
||||
| Rendering | 5ms |
|
||||
| Buffer | 1.67ms |
|
||||
|
||||
**Optimization Priority:**
|
||||
1. Algorithm (O(n²) → O(n log n))
|
||||
2. Batching (reduce draw calls)
|
||||
3. Pooling (avoid GC spikes)
|
||||
4. LOD (detail by distance)
|
||||
5. Culling (skip invisible)
|
||||
|
||||
---
|
||||
|
||||
### 5. AI Selection by Complexity
|
||||
|
||||
| AI Type | Complexity | Use When |
|
||||
|---------|------------|----------|
|
||||
| **FSM** | Simple | 3-5 states, predictable behavior |
|
||||
| **Behavior Tree** | Medium | Modular, designer-friendly |
|
||||
| **GOAP** | High | Emergent, planning-based |
|
||||
| **Utility AI** | High | Scoring-based decisions |
|
||||
|
||||
---
|
||||
|
||||
### 6. Collision Strategy
|
||||
|
||||
| Type | Best For |
|
||||
|------|----------|
|
||||
| **AABB** | Rectangles, fast checks |
|
||||
| **Circle** | Round objects, cheap |
|
||||
| **Spatial Hash** | Many similar-sized objects |
|
||||
| **Quadtree** | Large worlds, varying sizes |
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns (Universal)
|
||||
|
||||
| Don't | Do |
|
||||
|-------|-----|
|
||||
| Update everything every frame | Use events, dirty flags |
|
||||
| Create objects in hot loops | Object pooling |
|
||||
| Cache nothing | Cache references |
|
||||
| Optimize without profiling | Profile first |
|
||||
| Mix input with logic | Abstract input layer |
|
||||
|
||||
---
|
||||
|
||||
## Routing Examples
|
||||
|
||||
### Example 1: "I want to make a browser-based 2D platformer"
|
||||
→ Start with `game-development/web-games` for framework selection
|
||||
→ Then `game-development/2d-games` for sprite/tilemap patterns
|
||||
→ Reference `game-development/game-design` for level design
|
||||
|
||||
### Example 2: "Mobile puzzle game for iOS and Android"
|
||||
→ Start with `game-development/mobile-games` for touch input and stores
|
||||
→ Use `game-development/game-design` for puzzle balancing
|
||||
|
||||
### Example 3: "Multiplayer VR shooter"
|
||||
→ `game-development/vr-ar` for comfort and immersion
|
||||
→ `game-development/3d-games` for rendering
|
||||
→ `game-development/multiplayer` for networking
|
||||
|
||||
---
|
||||
|
||||
> **Remember:** Great games come from iteration, not perfection. Prototype fast, then polish.
|
||||
185
skills/game-development/game-art/SKILL.md
Normal file
185
skills/game-development/game-art/SKILL.md
Normal file
@@ -0,0 +1,185 @@
|
||||
---
|
||||
name: game-art
|
||||
description: Game art principles. Visual style selection, asset pipeline, animation workflow.
|
||||
allowed-tools: Read, Glob, Grep
|
||||
---
|
||||
|
||||
# Game Art Principles
|
||||
|
||||
> Visual design thinking for games - style selection, asset pipelines, and art direction.
|
||||
|
||||
---
|
||||
|
||||
## 1. Art Style Selection
|
||||
|
||||
### Decision Tree
|
||||
|
||||
```
|
||||
What feeling should the game evoke?
|
||||
│
|
||||
├── Nostalgic / Retro
|
||||
│ ├── Limited palette? → Pixel Art
|
||||
│ └── Hand-drawn feel? → Vector / Flash style
|
||||
│
|
||||
├── Realistic / Immersive
|
||||
│ ├── High budget? → PBR 3D
|
||||
│ └── Stylized realism? → Hand-painted textures
|
||||
│
|
||||
├── Approachable / Casual
|
||||
│ ├── Clean shapes? → Flat / Minimalist
|
||||
│ └── Soft feel? → Gradient / Soft shadows
|
||||
│
|
||||
└── Unique / Experimental
|
||||
└── Define custom style guide
|
||||
```
|
||||
|
||||
### Style Comparison Matrix
|
||||
|
||||
| Style | Production Speed | Skill Floor | Scalability | Best For |
|
||||
|-------|------------------|-------------|-------------|----------|
|
||||
| **Pixel Art** | Medium | Medium | Hard to hire | Indie, retro |
|
||||
| **Vector/Flat** | Fast | Low | Easy | Mobile, casual |
|
||||
| **Hand-painted** | Slow | High | Medium | Fantasy, stylized |
|
||||
| **PBR 3D** | Slow | High | AAA pipeline | Realistic games |
|
||||
| **Low-poly** | Fast | Medium | Easy | Indie 3D |
|
||||
| **Cel-shaded** | Medium | Medium | Medium | Anime, cartoon |
|
||||
|
||||
---
|
||||
|
||||
## 2. Asset Pipeline Decisions
|
||||
|
||||
### 2D Pipeline
|
||||
|
||||
| Phase | Tool Options | Output |
|
||||
|-------|--------------|--------|
|
||||
| **Concept** | Paper, Procreate, Photoshop | Reference sheet |
|
||||
| **Creation** | Aseprite, Photoshop, Krita | Individual sprites |
|
||||
| **Atlas** | TexturePacker, Aseprite | Spritesheet |
|
||||
| **Animation** | Spine, DragonBones, Frame-by-frame | Animation data |
|
||||
| **Integration** | Engine import | Game-ready assets |
|
||||
|
||||
### 3D Pipeline
|
||||
|
||||
| Phase | Tool Options | Output |
|
||||
|-------|--------------|--------|
|
||||
| **Concept** | 2D art, Blockout | Reference |
|
||||
| **Modeling** | Blender, Maya, 3ds Max | High-poly mesh |
|
||||
| **Retopology** | Blender, ZBrush | Game-ready mesh |
|
||||
| **UV/Texturing** | Substance Painter, Blender | Texture maps |
|
||||
| **Rigging** | Blender, Maya | Skeletal rig |
|
||||
| **Animation** | Blender, Maya, Mixamo | Animation clips |
|
||||
| **Export** | FBX, glTF | Engine-ready |
|
||||
|
||||
---
|
||||
|
||||
## 3. Color Theory Decisions
|
||||
|
||||
### Palette Selection
|
||||
|
||||
| Goal | Strategy | Example |
|
||||
|------|----------|---------|
|
||||
| **Harmony** | Complementary or analogous | Nature games |
|
||||
| **Contrast** | High saturation differences | Action games |
|
||||
| **Mood** | Warm/cool temperature | Horror, cozy |
|
||||
| **Readability** | Value contrast over hue | Gameplay clarity |
|
||||
|
||||
### Color Principles
|
||||
|
||||
- **Hierarchy:** Important elements should pop
|
||||
- **Consistency:** Same object = same color family
|
||||
- **Context:** Colors read differently on backgrounds
|
||||
- **Accessibility:** Don't rely only on color
|
||||
|
||||
---
|
||||
|
||||
## 4. Animation Principles
|
||||
|
||||
### The 12 Principles (Applied to Games)
|
||||
|
||||
| Principle | Game Application |
|
||||
|-----------|------------------|
|
||||
| **Squash & Stretch** | Jump arcs, impacts |
|
||||
| **Anticipation** | Wind-up before attack |
|
||||
| **Staging** | Clear silhouettes |
|
||||
| **Follow-through** | Hair, capes after movement |
|
||||
| **Slow in/out** | Easing on transitions |
|
||||
| **Arcs** | Natural movement paths |
|
||||
| **Secondary Action** | Breathing, blinking |
|
||||
| **Timing** | Frame count = weight/speed |
|
||||
| **Exaggeration** | Readable from distance |
|
||||
| **Appeal** | Memorable design |
|
||||
|
||||
### Frame Count Guidelines
|
||||
|
||||
| Action Type | Typical Frames | Feel |
|
||||
|-------------|----------------|------|
|
||||
| Idle breathing | 4-8 | Subtle |
|
||||
| Walk cycle | 6-12 | Smooth |
|
||||
| Run cycle | 4-8 | Energetic |
|
||||
| Attack | 3-6 | Snappy |
|
||||
| Death | 8-16 | Dramatic |
|
||||
|
||||
---
|
||||
|
||||
## 5. Resolution & Scale Decisions
|
||||
|
||||
### 2D Resolution by Platform
|
||||
|
||||
| Platform | Base Resolution | Sprite Scale |
|
||||
|----------|-----------------|--------------|
|
||||
| Mobile | 1080p | 64-128px characters |
|
||||
| Desktop | 1080p-4K | 128-256px characters |
|
||||
| Pixel art | 320x180 to 640x360 | 16-32px characters |
|
||||
|
||||
### Consistency Rule
|
||||
|
||||
Choose a base unit and stick to it:
|
||||
- Pixel art: Work at 1x, scale up (never down)
|
||||
- HD art: Define DPI, maintain ratio
|
||||
- 3D: 1 unit = 1 meter (industry standard)
|
||||
|
||||
---
|
||||
|
||||
## 6. Asset Organization
|
||||
|
||||
### Naming Convention
|
||||
|
||||
```
|
||||
[type]_[object]_[variant]_[state].[ext]
|
||||
|
||||
Examples:
|
||||
spr_player_idle_01.png
|
||||
tex_stone_wall_normal.png
|
||||
mesh_tree_oak_lod2.fbx
|
||||
```
|
||||
|
||||
### Folder Structure Principle
|
||||
|
||||
```
|
||||
assets/
|
||||
├── characters/
|
||||
│ ├── player/
|
||||
│ └── enemies/
|
||||
├── environment/
|
||||
│ ├── props/
|
||||
│ └── tiles/
|
||||
├── ui/
|
||||
├── effects/
|
||||
└── audio/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Anti-Patterns
|
||||
|
||||
| Don't | Do |
|
||||
|-------|-----|
|
||||
| Mix art styles randomly | Define and follow style guide |
|
||||
| Work at final resolution only | Create at source resolution |
|
||||
| Ignore silhouette readability | Test at gameplay distance |
|
||||
| Over-detail background | Focus detail on player area |
|
||||
| Skip color testing | Test on target display |
|
||||
|
||||
---
|
||||
|
||||
> **Remember:** Art serves gameplay. If it doesn't help the player, it's decoration.
|
||||
190
skills/game-development/game-audio/SKILL.md
Normal file
190
skills/game-development/game-audio/SKILL.md
Normal file
@@ -0,0 +1,190 @@
|
||||
---
|
||||
name: game-audio
|
||||
description: Game audio principles. Sound design, music integration, adaptive audio systems.
|
||||
allowed-tools: Read, Glob, Grep
|
||||
---
|
||||
|
||||
# Game Audio Principles
|
||||
|
||||
> Sound design and music integration for immersive game experiences.
|
||||
|
||||
---
|
||||
|
||||
## 1. Audio Category System
|
||||
|
||||
### Category Definitions
|
||||
|
||||
| Category | Behavior | Examples |
|
||||
|----------|----------|----------|
|
||||
| **Music** | Looping, crossfade, ducking | BGM, combat music |
|
||||
| **SFX** | One-shot, 3D positioned | Footsteps, impacts |
|
||||
| **Ambient** | Looping, background layer | Wind, crowd, forest |
|
||||
| **UI** | Immediate, non-3D | Button clicks, notifications |
|
||||
| **Voice** | Priority, ducking trigger | Dialogue, announcer |
|
||||
|
||||
### Priority Hierarchy
|
||||
|
||||
```
|
||||
When sounds compete for channels:
|
||||
|
||||
1. Voice (highest - always audible)
|
||||
2. Player SFX (feedback critical)
|
||||
3. Enemy SFX (gameplay important)
|
||||
4. Music (mood, but duckable)
|
||||
5. Ambient (lowest - can drop)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Sound Design Decisions
|
||||
|
||||
### SFX Creation Approach
|
||||
|
||||
| Approach | When to Use | Trade-offs |
|
||||
|----------|-------------|------------|
|
||||
| **Recording** | Realistic needs | High quality, time intensive |
|
||||
| **Synthesis** | Sci-fi, retro, UI | Unique, requires skill |
|
||||
| **Library samples** | Fast production | Common sounds, licensing |
|
||||
| **Layering** | Complex sounds | Best results, more work |
|
||||
|
||||
### Layering Structure
|
||||
|
||||
| Layer | Purpose | Example: Gunshot |
|
||||
|-------|---------|------------------|
|
||||
| **Attack** | Initial transient | Click, snap |
|
||||
| **Body** | Main character | Boom, blast |
|
||||
| **Tail** | Decay, room | Reverb, echo |
|
||||
| **Sweetener** | Special sauce | Shell casing, mechanical |
|
||||
|
||||
---
|
||||
|
||||
## 3. Music Integration
|
||||
|
||||
### Music State System
|
||||
|
||||
```
|
||||
Game State → Music Response
|
||||
│
|
||||
├── Menu → Calm, loopable theme
|
||||
├── Exploration → Ambient, atmospheric
|
||||
├── Combat detected → Transition to tension
|
||||
├── Combat engaged → Full battle music
|
||||
├── Victory → Stinger + calm transition
|
||||
├── Defeat → Somber stinger
|
||||
└── Boss → Unique, multi-phase track
|
||||
```
|
||||
|
||||
### Transition Techniques
|
||||
|
||||
| Technique | Use When | Feel |
|
||||
|-----------|----------|------|
|
||||
| **Crossfade** | Smooth mood shift | Gradual |
|
||||
| **Stinger** | Immediate event | Dramatic |
|
||||
| **Stem mixing** | Dynamic intensity | Seamless |
|
||||
| **Beat-synced** | Rhythmic gameplay | Musical |
|
||||
| **Queue point** | Next natural break | Clean |
|
||||
|
||||
---
|
||||
|
||||
## 4. Adaptive Audio Decisions
|
||||
|
||||
### Intensity Parameters
|
||||
|
||||
| Parameter | Affects | Example |
|
||||
|-----------|---------|---------|
|
||||
| **Threat level** | Music intensity | Enemy count |
|
||||
| **Health** | Filter, reverb | Low health = muffled |
|
||||
| **Speed** | Tempo, energy | Racing speed |
|
||||
| **Environment** | Reverb, EQ | Cave vs outdoor |
|
||||
| **Time of day** | Mood, volume | Night = quieter |
|
||||
|
||||
### Vertical vs Horizontal
|
||||
|
||||
| System | What Changes | Best For |
|
||||
|--------|--------------|----------|
|
||||
| **Vertical (layers)** | Add/remove instrument layers | Intensity scaling |
|
||||
| **Horizontal (segments)** | Different music sections | State changes |
|
||||
| **Combined** | Both | AAA adaptive scores |
|
||||
|
||||
---
|
||||
|
||||
## 5. 3D Audio Decisions
|
||||
|
||||
### Spatialization
|
||||
|
||||
| Element | 3D Positioned? | Reason |
|
||||
|---------|----------------|--------|
|
||||
| Player footsteps | No (or subtle) | Always audible |
|
||||
| Enemy footsteps | Yes | Directional awareness |
|
||||
| Gunfire | Yes | Combat awareness |
|
||||
| Music | No | Mood, non-diegetic |
|
||||
| Ambient zone | Yes (area) | Environmental |
|
||||
| UI sounds | No | Interface feedback |
|
||||
|
||||
### Distance Behavior
|
||||
|
||||
| Distance | Sound Behavior |
|
||||
|----------|----------------|
|
||||
| **Near** | Full volume, full frequency |
|
||||
| **Medium** | Volume falloff, high-freq rolloff |
|
||||
| **Far** | Low volume, low-pass filter |
|
||||
| **Max** | Silent or ambient hint |
|
||||
|
||||
---
|
||||
|
||||
## 6. Platform Considerations
|
||||
|
||||
### Format Selection
|
||||
|
||||
| Platform | Recommended Format | Reason |
|
||||
|----------|-------------------|--------|
|
||||
| PC | OGG Vorbis, WAV | Quality, no licensing |
|
||||
| Console | Platform-specific | Certification |
|
||||
| Mobile | MP3, AAC | Size, compatibility |
|
||||
| Web | WebM/Opus, MP3 fallback | Browser support |
|
||||
|
||||
### Memory Budget
|
||||
|
||||
| Game Type | Audio Budget | Strategy |
|
||||
|-----------|--------------|----------|
|
||||
| Mobile casual | 10-50 MB | Compressed, fewer variants |
|
||||
| PC indie | 100-500 MB | Quality focus |
|
||||
| AAA | 1+ GB | Full quality, many variants |
|
||||
|
||||
---
|
||||
|
||||
## 7. Mix Hierarchy
|
||||
|
||||
### Volume Balance Reference
|
||||
|
||||
| Category | Relative Level | Notes |
|
||||
|----------|----------------|-------|
|
||||
| **Voice** | 0 dB (reference) | Always clear |
|
||||
| **Player SFX** | -3 to -6 dB | Prominent but not harsh |
|
||||
| **Music** | -6 to -12 dB | Foundation, ducks for voice |
|
||||
| **Enemy SFX** | -6 to -9 dB | Important but not dominant |
|
||||
| **Ambient** | -12 to -18 dB | Subtle background |
|
||||
|
||||
### Ducking Rules
|
||||
|
||||
| When | Duck What | Amount |
|
||||
|------|-----------|--------|
|
||||
| Voice plays | Music, Ambient | -6 to -9 dB |
|
||||
| Explosion | All except explosion | Brief duck |
|
||||
| Menu open | Gameplay audio | -3 to -6 dB |
|
||||
|
||||
---
|
||||
|
||||
## 8. Anti-Patterns
|
||||
|
||||
| Don't | Do |
|
||||
|-------|-----|
|
||||
| Play same sound repeatedly | Use variations (3-5 per sound) |
|
||||
| Max volume everything | Use proper mix hierarchy |
|
||||
| Ignore silence | Silence creates contrast |
|
||||
| One music track loops forever | Provide variety, transitions |
|
||||
| Skip audio in prototype | Placeholder audio matters |
|
||||
|
||||
---
|
||||
|
||||
> **Remember:** 50% of the game experience is audio. A muted game loses half its soul.
|
||||
129
skills/game-development/game-design/SKILL.md
Normal file
129
skills/game-development/game-design/SKILL.md
Normal file
@@ -0,0 +1,129 @@
|
||||
---
|
||||
name: game-design
|
||||
description: Game design principles. GDD structure, balancing, player psychology, progression.
|
||||
allowed-tools: Read, Glob, Grep
|
||||
---
|
||||
|
||||
# Game Design Principles
|
||||
|
||||
> Design thinking for engaging games.
|
||||
|
||||
---
|
||||
|
||||
## 1. Core Loop Design
|
||||
|
||||
### The 30-Second Test
|
||||
|
||||
```
|
||||
Every game needs a fun 30-second loop:
|
||||
1. ACTION → Player does something
|
||||
2. FEEDBACK → Game responds
|
||||
3. REWARD → Player feels good
|
||||
4. REPEAT
|
||||
```
|
||||
|
||||
### Loop Examples
|
||||
|
||||
| Genre | Core Loop |
|
||||
|-------|-----------|
|
||||
| Platformer | Run → Jump → Land → Collect |
|
||||
| Shooter | Aim → Shoot → Kill → Loot |
|
||||
| Puzzle | Observe → Think → Solve → Advance |
|
||||
| RPG | Explore → Fight → Level → Gear |
|
||||
|
||||
---
|
||||
|
||||
## 2. Game Design Document (GDD)
|
||||
|
||||
### Essential Sections
|
||||
|
||||
| Section | Content |
|
||||
|---------|---------|
|
||||
| **Pitch** | One-sentence description |
|
||||
| **Core Loop** | 30-second gameplay |
|
||||
| **Mechanics** | How systems work |
|
||||
| **Progression** | How player advances |
|
||||
| **Art Style** | Visual direction |
|
||||
| **Audio** | Sound direction |
|
||||
|
||||
### Principles
|
||||
|
||||
- Keep it living (update regularly)
|
||||
- Visuals help communicate
|
||||
- Less is more (start small)
|
||||
|
||||
---
|
||||
|
||||
## 3. Player Psychology
|
||||
|
||||
### Motivation Types
|
||||
|
||||
| Type | Driven By |
|
||||
|------|-----------|
|
||||
| **Achiever** | Goals, completion |
|
||||
| **Explorer** | Discovery, secrets |
|
||||
| **Socializer** | Interaction, community |
|
||||
| **Killer** | Competition, dominance |
|
||||
|
||||
### Reward Schedules
|
||||
|
||||
| Schedule | Effect | Use |
|
||||
|----------|--------|-----|
|
||||
| **Fixed** | Predictable | Milestone rewards |
|
||||
| **Variable** | Addictive | Loot drops |
|
||||
| **Ratio** | Effort-based | Grind games |
|
||||
|
||||
---
|
||||
|
||||
## 4. Difficulty Balancing
|
||||
|
||||
### Flow State
|
||||
|
||||
```
|
||||
Too Hard → Frustration → Quit
|
||||
Too Easy → Boredom → Quit
|
||||
Just Right → Flow → Engagement
|
||||
```
|
||||
|
||||
### Balancing Strategies
|
||||
|
||||
| Strategy | How |
|
||||
|----------|-----|
|
||||
| **Dynamic** | Adjust to player skill |
|
||||
| **Selection** | Let player choose |
|
||||
| **Accessibility** | Options for all |
|
||||
|
||||
---
|
||||
|
||||
## 5. Progression Design
|
||||
|
||||
### Progression Types
|
||||
|
||||
| Type | Example |
|
||||
|------|---------|
|
||||
| **Skill** | Player gets better |
|
||||
| **Power** | Character gets stronger |
|
||||
| **Content** | New areas unlock |
|
||||
| **Story** | Narrative advances |
|
||||
|
||||
### Pacing Principles
|
||||
|
||||
- Early wins (hook quickly)
|
||||
- Gradually increase challenge
|
||||
- Rest beats between intensity
|
||||
- Meaningful choices
|
||||
|
||||
---
|
||||
|
||||
## 6. Anti-Patterns
|
||||
|
||||
| ❌ Don't | ✅ Do |
|
||||
|----------|-------|
|
||||
| Design in isolation | Playtest constantly |
|
||||
| Polish before fun | Prototype first |
|
||||
| Force one way to play | Allow player expression |
|
||||
| Punish excessively | Reward progress |
|
||||
|
||||
---
|
||||
|
||||
> **Remember:** Fun is discovered through iteration, not designed on paper.
|
||||
108
skills/game-development/mobile-games/SKILL.md
Normal file
108
skills/game-development/mobile-games/SKILL.md
Normal file
@@ -0,0 +1,108 @@
|
||||
---
|
||||
name: mobile-games
|
||||
description: Mobile game development principles. Touch input, battery, performance, app stores.
|
||||
allowed-tools: Read, Write, Edit, Glob, Grep
|
||||
---
|
||||
|
||||
# Mobile Game Development
|
||||
|
||||
> Platform constraints and optimization principles.
|
||||
|
||||
---
|
||||
|
||||
## 1. Platform Considerations
|
||||
|
||||
### Key Constraints
|
||||
|
||||
| Constraint | Strategy |
|
||||
|------------|----------|
|
||||
| **Touch input** | Large hit areas, gestures |
|
||||
| **Battery** | Limit CPU/GPU usage |
|
||||
| **Thermal** | Throttle when hot |
|
||||
| **Screen size** | Responsive UI |
|
||||
| **Interruptions** | Pause on background |
|
||||
|
||||
---
|
||||
|
||||
## 2. Touch Input Principles
|
||||
|
||||
### Touch vs Controller
|
||||
|
||||
| Touch | Desktop/Console |
|
||||
|-------|-----------------|
|
||||
| Imprecise | Precise |
|
||||
| Occludes screen | No occlusion |
|
||||
| Limited buttons | Many buttons |
|
||||
| Gestures available | Buttons/sticks |
|
||||
|
||||
### Best Practices
|
||||
|
||||
- Minimum touch target: 44x44 points
|
||||
- Visual feedback on touch
|
||||
- Avoid precise timing requirements
|
||||
- Support both portrait and landscape
|
||||
|
||||
---
|
||||
|
||||
## 3. Performance Targets
|
||||
|
||||
### Thermal Management
|
||||
|
||||
| Action | Trigger |
|
||||
|--------|---------|
|
||||
| Reduce quality | Device warm |
|
||||
| Limit FPS | Device hot |
|
||||
| Pause effects | Critical temp |
|
||||
|
||||
### Battery Optimization
|
||||
|
||||
- 30 FPS often sufficient
|
||||
- Sleep when paused
|
||||
- Minimize GPS/network
|
||||
- Dark mode saves OLED battery
|
||||
|
||||
---
|
||||
|
||||
## 4. App Store Requirements
|
||||
|
||||
### iOS (App Store)
|
||||
|
||||
| Requirement | Note |
|
||||
|-------------|------|
|
||||
| Privacy labels | Required |
|
||||
| Account deletion | If account creation exists |
|
||||
| Screenshots | For all device sizes |
|
||||
|
||||
### Android (Google Play)
|
||||
|
||||
| Requirement | Note |
|
||||
|-------------|------|
|
||||
| Target API | Current year's SDK |
|
||||
| 64-bit | Required |
|
||||
| App bundles | Recommended |
|
||||
|
||||
---
|
||||
|
||||
## 5. Monetization Models
|
||||
|
||||
| Model | Best For |
|
||||
|-------|----------|
|
||||
| **Premium** | Quality games, loyal audience |
|
||||
| **Free + IAP** | Casual, progression-based |
|
||||
| **Ads** | Hyper-casual, high volume |
|
||||
| **Subscription** | Content updates, multiplayer |
|
||||
|
||||
---
|
||||
|
||||
## 6. Anti-Patterns
|
||||
|
||||
| ❌ Don't | ✅ Do |
|
||||
|----------|-------|
|
||||
| Desktop controls on mobile | Design for touch |
|
||||
| Ignore battery drain | Monitor thermals |
|
||||
| Force landscape | Support player preference |
|
||||
| Always-on network | Cache and sync |
|
||||
|
||||
---
|
||||
|
||||
> **Remember:** Mobile is the most constrained platform. Respect battery and attention.
|
||||
132
skills/game-development/multiplayer/SKILL.md
Normal file
132
skills/game-development/multiplayer/SKILL.md
Normal file
@@ -0,0 +1,132 @@
|
||||
---
|
||||
name: multiplayer
|
||||
description: Multiplayer game development principles. Architecture, networking, synchronization.
|
||||
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
|
||||
---
|
||||
|
||||
# Multiplayer Game Development
|
||||
|
||||
> Networking architecture and synchronization principles.
|
||||
|
||||
---
|
||||
|
||||
## 1. Architecture Selection
|
||||
|
||||
### Decision Tree
|
||||
|
||||
```
|
||||
What type of multiplayer?
|
||||
│
|
||||
├── Competitive / Real-time
|
||||
│ └── Dedicated Server (authoritative)
|
||||
│
|
||||
├── Cooperative / Casual
|
||||
│ └── Host-based (one player is server)
|
||||
│
|
||||
├── Turn-based
|
||||
│ └── Client-server (simple)
|
||||
│
|
||||
└── Massive (MMO)
|
||||
└── Distributed servers
|
||||
```
|
||||
|
||||
### Comparison
|
||||
|
||||
| Architecture | Latency | Cost | Security |
|
||||
|--------------|---------|------|----------|
|
||||
| **Dedicated** | Low | High | Strong |
|
||||
| **P2P** | Variable | Low | Weak |
|
||||
| **Host-based** | Medium | Low | Medium |
|
||||
|
||||
---
|
||||
|
||||
## 2. Synchronization Principles
|
||||
|
||||
### State vs Input
|
||||
|
||||
| Approach | Sync What | Best For |
|
||||
|----------|-----------|----------|
|
||||
| **State Sync** | Game state | Simple, few objects |
|
||||
| **Input Sync** | Player inputs | Action games |
|
||||
| **Hybrid** | Both | Most games |
|
||||
|
||||
### Lag Compensation
|
||||
|
||||
| Technique | Purpose |
|
||||
|-----------|---------|
|
||||
| **Prediction** | Client predicts server |
|
||||
| **Interpolation** | Smooth remote players |
|
||||
| **Reconciliation** | Fix mispredictions |
|
||||
| **Lag compensation** | Rewind for hit detection |
|
||||
|
||||
---
|
||||
|
||||
## 3. Network Optimization
|
||||
|
||||
### Bandwidth Reduction
|
||||
|
||||
| Technique | Savings |
|
||||
|-----------|---------|
|
||||
| **Delta compression** | Send only changes |
|
||||
| **Quantization** | Reduce precision |
|
||||
| **Priority** | Important data first |
|
||||
| **Area of interest** | Only nearby entities |
|
||||
|
||||
### Update Rates
|
||||
|
||||
| Type | Rate |
|
||||
|------|------|
|
||||
| Position | 20-60 Hz |
|
||||
| Health | On change |
|
||||
| Inventory | On change |
|
||||
| Chat | On send |
|
||||
|
||||
---
|
||||
|
||||
## 4. Security Principles
|
||||
|
||||
### Server Authority
|
||||
|
||||
```
|
||||
Client: "I hit the enemy"
|
||||
Server: Validate → did projectile actually hit?
|
||||
→ was player in valid state?
|
||||
→ was timing possible?
|
||||
```
|
||||
|
||||
### Anti-Cheat
|
||||
|
||||
| Cheat | Prevention |
|
||||
|-------|------------|
|
||||
| Speed hack | Server validates movement |
|
||||
| Aimbot | Server validates sight line |
|
||||
| Item dupe | Server owns inventory |
|
||||
| Wall hack | Don't send hidden data |
|
||||
|
||||
---
|
||||
|
||||
## 5. Matchmaking
|
||||
|
||||
### Considerations
|
||||
|
||||
| Factor | Impact |
|
||||
|--------|--------|
|
||||
| **Skill** | Fair matches |
|
||||
| **Latency** | Playable connection |
|
||||
| **Wait time** | Player patience |
|
||||
| **Party size** | Group play |
|
||||
|
||||
---
|
||||
|
||||
## 6. Anti-Patterns
|
||||
|
||||
| ❌ Don't | ✅ Do |
|
||||
|----------|-------|
|
||||
| Trust the client | Server is authority |
|
||||
| Send everything | Send only necessary |
|
||||
| Ignore latency | Design for 100-200ms |
|
||||
| Sync exact positions | Interpolate/predict |
|
||||
|
||||
---
|
||||
|
||||
> **Remember:** Never trust the client. The server is the source of truth.
|
||||
144
skills/game-development/pc-games/SKILL.md
Normal file
144
skills/game-development/pc-games/SKILL.md
Normal file
@@ -0,0 +1,144 @@
|
||||
---
|
||||
name: pc-games
|
||||
description: PC and console game development principles. Engine selection, platform features, optimization strategies.
|
||||
allowed-tools: Read, Write, Edit, Glob, Grep
|
||||
---
|
||||
|
||||
# PC/Console Game Development
|
||||
|
||||
> Engine selection and platform-specific principles.
|
||||
|
||||
---
|
||||
|
||||
## 1. Engine Selection
|
||||
|
||||
### Decision Tree
|
||||
|
||||
```
|
||||
What are you building?
|
||||
│
|
||||
├── 2D Game
|
||||
│ ├── Open source important? → Godot
|
||||
│ └── Large team/assets? → Unity
|
||||
│
|
||||
├── 3D Game
|
||||
│ ├── AAA visual quality? → Unreal
|
||||
│ ├── Cross-platform priority? → Unity
|
||||
│ └── Indie/open source? → Godot 4
|
||||
│
|
||||
└── Specific Needs
|
||||
├── DOTS performance? → Unity
|
||||
├── Nanite/Lumen? → Unreal
|
||||
└── Lightweight? → Godot
|
||||
```
|
||||
|
||||
### Comparison
|
||||
|
||||
| Factor | Unity 6 | Godot 4 | Unreal 5 |
|
||||
|--------|---------|---------|----------|
|
||||
| 2D | Good | Excellent | Limited |
|
||||
| 3D | Good | Good | Excellent |
|
||||
| Learning | Medium | Easy | Hard |
|
||||
| Cost | Revenue share | Free | 5% after $1M |
|
||||
| Team | Any | Solo-Medium | Medium-Large |
|
||||
|
||||
---
|
||||
|
||||
## 2. Platform Features
|
||||
|
||||
### Steam Integration
|
||||
|
||||
| Feature | Purpose |
|
||||
|---------|---------|
|
||||
| Achievements | Player goals |
|
||||
| Cloud Saves | Cross-device progress |
|
||||
| Leaderboards | Competition |
|
||||
| Workshop | User mods |
|
||||
| Rich Presence | Show in-game status |
|
||||
|
||||
### Console Requirements
|
||||
|
||||
| Platform | Certification |
|
||||
|----------|--------------|
|
||||
| PlayStation | TRC compliance |
|
||||
| Xbox | XR compliance |
|
||||
| Nintendo | Lotcheck |
|
||||
|
||||
---
|
||||
|
||||
## 3. Controller Support
|
||||
|
||||
### Input Abstraction
|
||||
|
||||
```
|
||||
Map ACTIONS, not buttons:
|
||||
- "confirm" → A (Xbox), Cross (PS), B (Nintendo)
|
||||
- "cancel" → B (Xbox), Circle (PS), A (Nintendo)
|
||||
```
|
||||
|
||||
### Haptic Feedback
|
||||
|
||||
| Intensity | Use |
|
||||
|-----------|-----|
|
||||
| Light | UI feedback |
|
||||
| Medium | Impacts |
|
||||
| Heavy | Major events |
|
||||
|
||||
---
|
||||
|
||||
## 4. Performance Optimization
|
||||
|
||||
### Profiling First
|
||||
|
||||
| Engine | Tool |
|
||||
|--------|------|
|
||||
| Unity | Profiler Window |
|
||||
| Godot | Debugger → Profiler |
|
||||
| Unreal | Unreal Insights |
|
||||
|
||||
### Common Bottlenecks
|
||||
|
||||
| Bottleneck | Solution |
|
||||
|------------|----------|
|
||||
| Draw calls | Batching, atlases |
|
||||
| GC spikes | Object pooling |
|
||||
| Physics | Simpler colliders |
|
||||
| Shaders | LOD shaders |
|
||||
|
||||
---
|
||||
|
||||
## 5. Engine-Specific Principles
|
||||
|
||||
### Unity 6
|
||||
|
||||
- DOTS for performance-critical systems
|
||||
- Burst compiler for hot paths
|
||||
- Addressables for asset streaming
|
||||
|
||||
### Godot 4
|
||||
|
||||
- GDScript for rapid iteration
|
||||
- C# for complex logic
|
||||
- Signals for decoupling
|
||||
|
||||
### Unreal 5
|
||||
|
||||
- Blueprint for designers
|
||||
- C++ for performance
|
||||
- Nanite for high-poly environments
|
||||
- Lumen for dynamic lighting
|
||||
|
||||
---
|
||||
|
||||
## 6. Anti-Patterns
|
||||
|
||||
| ❌ Don't | ✅ Do |
|
||||
|----------|-------|
|
||||
| Choose engine by hype | Choose by project needs |
|
||||
| Ignore platform guidelines | Study certification requirements |
|
||||
| Hardcode input buttons | Abstract to actions |
|
||||
| Skip profiling | Profile early and often |
|
||||
|
||||
---
|
||||
|
||||
> **Remember:** Engine is a tool. Master the principles, then adapt to any engine.
|
||||
123
skills/game-development/vr-ar/SKILL.md
Normal file
123
skills/game-development/vr-ar/SKILL.md
Normal file
@@ -0,0 +1,123 @@
|
||||
---
|
||||
name: vr-ar
|
||||
description: VR/AR development principles. Comfort, interaction, performance requirements.
|
||||
allowed-tools: Read, Write, Edit, Glob, Grep
|
||||
---
|
||||
|
||||
# VR/AR Development
|
||||
|
||||
> Immersive experience principles.
|
||||
|
||||
---
|
||||
|
||||
## 1. Platform Selection
|
||||
|
||||
### VR Platforms
|
||||
|
||||
| Platform | Use Case |
|
||||
|----------|----------|
|
||||
| **Quest** | Standalone, wireless |
|
||||
| **PCVR** | High fidelity |
|
||||
| **PSVR** | Console market |
|
||||
| **WebXR** | Browser-based |
|
||||
|
||||
### AR Platforms
|
||||
|
||||
| Platform | Use Case |
|
||||
|----------|----------|
|
||||
| **ARKit** | iOS devices |
|
||||
| **ARCore** | Android devices |
|
||||
| **WebXR** | Browser AR |
|
||||
| **HoloLens** | Enterprise |
|
||||
|
||||
---
|
||||
|
||||
## 2. Comfort Principles
|
||||
|
||||
### Motion Sickness Prevention
|
||||
|
||||
| Cause | Solution |
|
||||
|-------|----------|
|
||||
| **Locomotion** | Teleport, snap turn |
|
||||
| **Low FPS** | Maintain 90 FPS |
|
||||
| **Camera shake** | Avoid or minimize |
|
||||
| **Rapid acceleration** | Gradual movement |
|
||||
|
||||
### Comfort Settings
|
||||
|
||||
- Vignette during movement
|
||||
- Snap vs smooth turning
|
||||
- Seated vs standing modes
|
||||
- Height calibration
|
||||
|
||||
---
|
||||
|
||||
## 3. Performance Requirements
|
||||
|
||||
### Target Metrics
|
||||
|
||||
| Platform | FPS | Resolution |
|
||||
|----------|-----|------------|
|
||||
| Quest 2 | 72-90 | 1832x1920 |
|
||||
| Quest 3 | 90-120 | 2064x2208 |
|
||||
| PCVR | 90 | 2160x2160+ |
|
||||
| PSVR2 | 90-120 | 2000x2040 |
|
||||
|
||||
### Frame Budget
|
||||
|
||||
- VR requires consistent frame times
|
||||
- Single dropped frame = visible judder
|
||||
- 90 FPS = 11.11ms budget
|
||||
|
||||
---
|
||||
|
||||
## 4. Interaction Principles
|
||||
|
||||
### Controller Interaction
|
||||
|
||||
| Type | Use |
|
||||
|------|-----|
|
||||
| **Point + click** | UI, distant objects |
|
||||
| **Grab** | Manipulation |
|
||||
| **Gesture** | Magic, special actions |
|
||||
| **Physical** | Throwing, swinging |
|
||||
|
||||
### Hand Tracking
|
||||
|
||||
- More immersive but less precise
|
||||
- Good for: social, casual
|
||||
- Challenging for: action, precision
|
||||
|
||||
---
|
||||
|
||||
## 5. Spatial Design
|
||||
|
||||
### World Scale
|
||||
|
||||
- 1 unit = 1 meter (critical)
|
||||
- Objects must feel right size
|
||||
- Test with real measurements
|
||||
|
||||
### Depth Cues
|
||||
|
||||
| Cue | Importance |
|
||||
|-----|------------|
|
||||
| Stereo | Primary depth |
|
||||
| Motion parallax | Secondary |
|
||||
| Shadows | Grounding |
|
||||
| Occlusion | Layering |
|
||||
|
||||
---
|
||||
|
||||
## 6. Anti-Patterns
|
||||
|
||||
| ❌ Don't | ✅ Do |
|
||||
|----------|-------|
|
||||
| Move camera without player | Player controls camera |
|
||||
| Drop below 90 FPS | Maintain frame rate |
|
||||
| Use tiny UI text | Large, readable text |
|
||||
| Ignore arm length | Scale to player reach |
|
||||
|
||||
---
|
||||
|
||||
> **Remember:** Comfort is not optional. Sick players don't play.
|
||||
150
skills/game-development/web-games/SKILL.md
Normal file
150
skills/game-development/web-games/SKILL.md
Normal file
@@ -0,0 +1,150 @@
|
||||
---
|
||||
name: web-games
|
||||
description: Web browser game development principles. Framework selection, WebGPU, optimization, PWA.
|
||||
allowed-tools: Read, Write, Edit, Glob, Grep
|
||||
---
|
||||
|
||||
# Web Browser Game Development
|
||||
|
||||
> Framework selection and browser-specific principles.
|
||||
|
||||
---
|
||||
|
||||
## 1. Framework Selection
|
||||
|
||||
### Decision Tree
|
||||
|
||||
```
|
||||
What type of game?
|
||||
│
|
||||
├── 2D Game
|
||||
│ ├── Full game engine features? → Phaser
|
||||
│ └── Raw rendering power? → PixiJS
|
||||
│
|
||||
├── 3D Game
|
||||
│ ├── Full engine (physics, XR)? → Babylon.js
|
||||
│ └── Rendering focused? → Three.js
|
||||
│
|
||||
└── Hybrid / Canvas
|
||||
└── Custom → Raw Canvas/WebGL
|
||||
```
|
||||
|
||||
### Comparison (2025)
|
||||
|
||||
| Framework | Type | Best For |
|
||||
|-----------|------|----------|
|
||||
| **Phaser 4** | 2D | Full game features |
|
||||
| **PixiJS 8** | 2D | Rendering, UI |
|
||||
| **Three.js** | 3D | Visualizations, lightweight |
|
||||
| **Babylon.js 7** | 3D | Full engine, XR |
|
||||
|
||||
---
|
||||
|
||||
## 2. WebGPU Adoption
|
||||
|
||||
### Browser Support (2025)
|
||||
|
||||
| Browser | Support |
|
||||
|---------|---------|
|
||||
| Chrome | ✅ Since v113 |
|
||||
| Edge | ✅ Since v113 |
|
||||
| Firefox | ✅ Since v131 |
|
||||
| Safari | ✅ Since 18.0 |
|
||||
| **Total** | **~73%** global |
|
||||
|
||||
### Decision
|
||||
|
||||
- **New projects**: Use WebGPU with WebGL fallback
|
||||
- **Legacy support**: Start with WebGL
|
||||
- **Feature detection**: Check `navigator.gpu`
|
||||
|
||||
---
|
||||
|
||||
## 3. Performance Principles
|
||||
|
||||
### Browser Constraints
|
||||
|
||||
| Constraint | Strategy |
|
||||
|------------|----------|
|
||||
| No local file access | Asset bundling, CDN |
|
||||
| Tab throttling | Pause when hidden |
|
||||
| Mobile data limits | Compress assets |
|
||||
| Audio autoplay | Require user interaction |
|
||||
|
||||
### Optimization Priority
|
||||
|
||||
1. **Asset compression** - KTX2, Draco, WebP
|
||||
2. **Lazy loading** - Load on demand
|
||||
3. **Object pooling** - Avoid GC
|
||||
4. **Draw call batching** - Reduce state changes
|
||||
5. **Web Workers** - Offload heavy computation
|
||||
|
||||
---
|
||||
|
||||
## 4. Asset Strategy
|
||||
|
||||
### Compression Formats
|
||||
|
||||
| Type | Format |
|
||||
|------|--------|
|
||||
| Textures | KTX2 + Basis Universal |
|
||||
| Audio | WebM/Opus (fallback: MP3) |
|
||||
| 3D Models | glTF + Draco/Meshopt |
|
||||
|
||||
### Loading Strategy
|
||||
|
||||
| Phase | Load |
|
||||
|-------|------|
|
||||
| Startup | Core assets, <2MB |
|
||||
| Gameplay | Stream on demand |
|
||||
| Background | Prefetch next level |
|
||||
|
||||
---
|
||||
|
||||
## 5. PWA for Games
|
||||
|
||||
### Benefits
|
||||
|
||||
- Offline play
|
||||
- Install to home screen
|
||||
- Full screen mode
|
||||
- Push notifications
|
||||
|
||||
### Requirements
|
||||
|
||||
- Service worker for caching
|
||||
- Web app manifest
|
||||
- HTTPS
|
||||
|
||||
---
|
||||
|
||||
## 6. Audio Handling
|
||||
|
||||
### Browser Requirements
|
||||
|
||||
- Audio context requires user interaction
|
||||
- Create AudioContext on first click/tap
|
||||
- Resume context if suspended
|
||||
|
||||
### Best Practices
|
||||
|
||||
- Use Web Audio API
|
||||
- Pool audio sources
|
||||
- Preload common sounds
|
||||
- Compress with WebM/Opus
|
||||
|
||||
---
|
||||
|
||||
## 7. Anti-Patterns
|
||||
|
||||
| ❌ Don't | ✅ Do |
|
||||
|----------|-------|
|
||||
| Load all assets upfront | Progressive loading |
|
||||
| Ignore tab visibility | Pause when hidden |
|
||||
| Block on audio load | Lazy load audio |
|
||||
| Skip compression | Compress everything |
|
||||
| Assume fast connection | Handle slow networks |
|
||||
|
||||
---
|
||||
|
||||
> **Remember:** Browser is the most accessible platform. Respect its constraints.
|
||||
156
skills/geo-fundamentals/SKILL.md
Normal file
156
skills/geo-fundamentals/SKILL.md
Normal file
@@ -0,0 +1,156 @@
|
||||
---
|
||||
name: geo-fundamentals
|
||||
description: Generative Engine Optimization for AI search engines (ChatGPT, Claude, Perplexity).
|
||||
allowed-tools: Read, Glob, Grep
|
||||
---
|
||||
|
||||
# GEO Fundamentals
|
||||
|
||||
> Optimization for AI-powered search engines.
|
||||
|
||||
---
|
||||
|
||||
## 1. What is GEO?
|
||||
|
||||
**GEO** = Generative Engine Optimization
|
||||
|
||||
| Goal | Platform |
|
||||
|------|----------|
|
||||
| Be cited in AI responses | ChatGPT, Claude, Perplexity, Gemini |
|
||||
|
||||
### SEO vs GEO
|
||||
|
||||
| Aspect | SEO | GEO |
|
||||
|--------|-----|-----|
|
||||
| Goal | #1 ranking | AI citations |
|
||||
| Platform | Google | AI engines |
|
||||
| Metrics | Rankings, CTR | Citation rate |
|
||||
| Focus | Keywords | Entities, data |
|
||||
|
||||
---
|
||||
|
||||
## 2. AI Engine Landscape
|
||||
|
||||
| Engine | Citation Style | Opportunity |
|
||||
|--------|----------------|-------------|
|
||||
| **Perplexity** | Numbered [1][2] | Highest citation rate |
|
||||
| **ChatGPT** | Inline/footnotes | Custom GPTs |
|
||||
| **Claude** | Contextual | Long-form content |
|
||||
| **Gemini** | Sources section | SEO crossover |
|
||||
|
||||
---
|
||||
|
||||
## 3. RAG Retrieval Factors
|
||||
|
||||
How AI engines select content to cite:
|
||||
|
||||
| Factor | Weight |
|
||||
|--------|--------|
|
||||
| Semantic relevance | ~40% |
|
||||
| Keyword match | ~20% |
|
||||
| Authority signals | ~15% |
|
||||
| Freshness | ~10% |
|
||||
| Source diversity | ~15% |
|
||||
|
||||
---
|
||||
|
||||
## 4. Content That Gets Cited
|
||||
|
||||
| Element | Why It Works |
|
||||
|---------|--------------|
|
||||
| **Original statistics** | Unique, citable data |
|
||||
| **Expert quotes** | Authority transfer |
|
||||
| **Clear definitions** | Easy to extract |
|
||||
| **Step-by-step guides** | Actionable value |
|
||||
| **Comparison tables** | Structured info |
|
||||
| **FAQ sections** | Direct answers |
|
||||
|
||||
---
|
||||
|
||||
## 5. GEO Content Checklist
|
||||
|
||||
### Content Elements
|
||||
|
||||
- [ ] Question-based titles
|
||||
- [ ] Summary/TL;DR at top
|
||||
- [ ] Original data with sources
|
||||
- [ ] Expert quotes (name, title)
|
||||
- [ ] FAQ section (3-5 Q&A)
|
||||
- [ ] Clear definitions
|
||||
- [ ] "Last updated" timestamp
|
||||
- [ ] Author with credentials
|
||||
|
||||
### Technical Elements
|
||||
|
||||
- [ ] Article schema with dates
|
||||
- [ ] Person schema for author
|
||||
- [ ] FAQPage schema
|
||||
- [ ] Fast loading (< 2.5s)
|
||||
- [ ] Clean HTML structure
|
||||
|
||||
---
|
||||
|
||||
## 6. Entity Building
|
||||
|
||||
| Action | Purpose |
|
||||
|--------|---------|
|
||||
| Google Knowledge Panel | Entity recognition |
|
||||
| Wikipedia (if notable) | Authority source |
|
||||
| Consistent info across web | Entity consolidation |
|
||||
| Industry mentions | Authority signals |
|
||||
|
||||
---
|
||||
|
||||
## 7. AI Crawler Access
|
||||
|
||||
### Key AI User-Agents
|
||||
|
||||
| Crawler | Engine |
|
||||
|---------|--------|
|
||||
| GPTBot | ChatGPT/OpenAI |
|
||||
| Claude-Web | Claude |
|
||||
| PerplexityBot | Perplexity |
|
||||
| Googlebot | Gemini (shared) |
|
||||
|
||||
### Access Decision
|
||||
|
||||
| Strategy | When |
|
||||
|----------|------|
|
||||
| Allow all | Want AI citations |
|
||||
| Block GPTBot | Don't want OpenAI training |
|
||||
| Selective | Allow some, block others |
|
||||
|
||||
---
|
||||
|
||||
## 8. Measurement
|
||||
|
||||
| Metric | How to Track |
|
||||
|--------|--------------|
|
||||
| AI citations | Manual monitoring |
|
||||
| "According to [Brand]" mentions | Search in AI |
|
||||
| Competitor citations | Compare share |
|
||||
| AI-referred traffic | UTM parameters |
|
||||
|
||||
---
|
||||
|
||||
## 9. Anti-Patterns
|
||||
|
||||
| ❌ Don't | ✅ Do |
|
||||
|----------|-------|
|
||||
| Publish without dates | Add timestamps |
|
||||
| Vague attributions | Name sources |
|
||||
| Skip author info | Show credentials |
|
||||
| Thin content | Comprehensive coverage |
|
||||
|
||||
---
|
||||
|
||||
> **Remember:** AI cites content that's clear, authoritative, and easy to extract. Be the best answer.
|
||||
|
||||
---
|
||||
|
||||
## Script
|
||||
|
||||
| Script | Purpose | Command |
|
||||
|--------|---------|---------|
|
||||
| `scripts/geo_checker.py` | GEO audit (AI citation readiness) | `python scripts/geo_checker.py <project_path>` |
|
||||
|
||||
289
skills/geo-fundamentals/scripts/geo_checker.py
Normal file
289
skills/geo-fundamentals/scripts/geo_checker.py
Normal file
@@ -0,0 +1,289 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
GEO Checker - Generative Engine Optimization Audit
|
||||
Checks PUBLIC WEB CONTENT for AI citation readiness.
|
||||
|
||||
PURPOSE:
|
||||
- Analyze pages that will be INDEXED by AI engines (ChatGPT, Perplexity, etc.)
|
||||
- Check for structured data, author info, dates, FAQ sections
|
||||
- Help content rank in AI-generated answers
|
||||
|
||||
WHAT IT CHECKS:
|
||||
- HTML files (actual web pages)
|
||||
- JSX/TSX files (React page components)
|
||||
- NOT markdown files (those are developer docs, not public content)
|
||||
|
||||
Usage:
|
||||
python geo_checker.py <project_path>
|
||||
"""
|
||||
import sys
|
||||
import re
|
||||
import json
|
||||
from pathlib import Path
|
||||
|
||||
# Fix Windows console encoding
|
||||
try:
|
||||
sys.stdout.reconfigure(encoding='utf-8', errors='replace')
|
||||
sys.stderr.reconfigure(encoding='utf-8', errors='replace')
|
||||
except AttributeError:
|
||||
pass
|
||||
|
||||
|
||||
# Directories to skip (not public content)
|
||||
SKIP_DIRS = {
|
||||
'node_modules', '.next', 'dist', 'build', '.git', '.github',
|
||||
'__pycache__', '.vscode', '.idea', 'coverage', 'test', 'tests',
|
||||
'__tests__', 'spec', 'docs', 'documentation'
|
||||
}
|
||||
|
||||
# Files to skip (not public pages)
|
||||
SKIP_FILES = {
|
||||
'jest.config', 'webpack.config', 'vite.config', 'tsconfig',
|
||||
'package.json', 'package-lock', 'yarn.lock', '.eslintrc',
|
||||
'tailwind.config', 'postcss.config', 'next.config'
|
||||
}
|
||||
|
||||
|
||||
def is_page_file(file_path: Path) -> bool:
|
||||
"""Check if this file is likely a public-facing page."""
|
||||
name = file_path.stem.lower()
|
||||
|
||||
# Skip config/utility files
|
||||
if any(skip in name for skip in SKIP_FILES):
|
||||
return False
|
||||
|
||||
# Skip test files
|
||||
if name.endswith('.test') or name.endswith('.spec'):
|
||||
return False
|
||||
if name.startswith('test_') or name.startswith('spec_'):
|
||||
return False
|
||||
|
||||
# Likely page indicators
|
||||
page_indicators = ['page', 'index', 'home', 'about', 'contact', 'blog',
|
||||
'post', 'article', 'product', 'service', 'landing']
|
||||
|
||||
# Check if it's in a pages/app directory (Next.js, etc.)
|
||||
parts = [p.lower() for p in file_path.parts]
|
||||
if 'pages' in parts or 'app' in parts or 'routes' in parts:
|
||||
return True
|
||||
|
||||
# Check filename indicators
|
||||
if any(ind in name for ind in page_indicators):
|
||||
return True
|
||||
|
||||
# HTML files are usually pages
|
||||
if file_path.suffix.lower() == '.html':
|
||||
return True
|
||||
|
||||
return False
|
||||
|
||||
|
||||
def find_web_pages(project_path: Path) -> list:
|
||||
"""Find public-facing web pages only."""
|
||||
patterns = ['**/*.html', '**/*.htm', '**/*.jsx', '**/*.tsx']
|
||||
|
||||
files = []
|
||||
for pattern in patterns:
|
||||
for f in project_path.glob(pattern):
|
||||
# Skip excluded directories
|
||||
if any(skip in f.parts for skip in SKIP_DIRS):
|
||||
continue
|
||||
|
||||
# Check if it's likely a page
|
||||
if is_page_file(f):
|
||||
files.append(f)
|
||||
|
||||
return files[:30] # Limit to 30 pages
|
||||
|
||||
|
||||
def check_page(file_path: Path) -> dict:
|
||||
"""Check a single web page for GEO elements."""
|
||||
try:
|
||||
content = file_path.read_text(encoding='utf-8', errors='ignore')
|
||||
except Exception as e:
|
||||
return {'file': str(file_path.name), 'passed': [], 'issues': [f"Error: {e}"], 'score': 0}
|
||||
|
||||
issues = []
|
||||
passed = []
|
||||
|
||||
# 1. JSON-LD Structured Data (Critical for AI)
|
||||
if 'application/ld+json' in content:
|
||||
passed.append("JSON-LD structured data found")
|
||||
if '"@type"' in content:
|
||||
if 'Article' in content:
|
||||
passed.append("Article schema present")
|
||||
if 'FAQPage' in content:
|
||||
passed.append("FAQ schema present")
|
||||
if 'Organization' in content or 'Person' in content:
|
||||
passed.append("Entity schema present")
|
||||
else:
|
||||
issues.append("No JSON-LD structured data (AI engines prefer structured content)")
|
||||
|
||||
# 2. Heading Structure
|
||||
h1_count = len(re.findall(r'<h1[^>]*>', content, re.I))
|
||||
h2_count = len(re.findall(r'<h2[^>]*>', content, re.I))
|
||||
|
||||
if h1_count == 1:
|
||||
passed.append("Single H1 heading (clear topic)")
|
||||
elif h1_count == 0:
|
||||
issues.append("No H1 heading - page topic unclear")
|
||||
else:
|
||||
issues.append(f"Multiple H1 headings ({h1_count}) - confusing for AI")
|
||||
|
||||
if h2_count >= 2:
|
||||
passed.append(f"{h2_count} H2 subheadings (good structure)")
|
||||
else:
|
||||
issues.append("Add more H2 subheadings for scannable content")
|
||||
|
||||
# 3. Author Attribution (E-E-A-T signal)
|
||||
author_patterns = ['author', 'byline', 'written-by', 'contributor', 'rel="author"']
|
||||
has_author = any(p in content.lower() for p in author_patterns)
|
||||
if has_author:
|
||||
passed.append("Author attribution found")
|
||||
else:
|
||||
issues.append("No author info (AI prefers attributed content)")
|
||||
|
||||
# 4. Publication Date (Freshness signal)
|
||||
date_patterns = ['datePublished', 'dateModified', 'datetime=', 'pubdate', 'article:published']
|
||||
has_date = any(re.search(p, content, re.I) for p in date_patterns)
|
||||
if has_date:
|
||||
passed.append("Publication date found")
|
||||
else:
|
||||
issues.append("No publication date (freshness matters for AI)")
|
||||
|
||||
# 5. FAQ Section (Highly citable)
|
||||
faq_patterns = [r'<details', r'faq', r'frequently.?asked', r'"FAQPage"']
|
||||
has_faq = any(re.search(p, content, re.I) for p in faq_patterns)
|
||||
if has_faq:
|
||||
passed.append("FAQ section detected (highly citable)")
|
||||
|
||||
# 6. Lists (Structured content)
|
||||
list_count = len(re.findall(r'<(ul|ol)[^>]*>', content, re.I))
|
||||
if list_count >= 2:
|
||||
passed.append(f"{list_count} lists (structured content)")
|
||||
|
||||
# 7. Tables (Comparison data)
|
||||
table_count = len(re.findall(r'<table[^>]*>', content, re.I))
|
||||
if table_count >= 1:
|
||||
passed.append(f"{table_count} table(s) (comparison data)")
|
||||
|
||||
# 8. Entity Recognition (E-E-A-T signal) - NEW 2025
|
||||
entity_patterns = [
|
||||
r'"@type"\s*:\s*"Organization"',
|
||||
r'"@type"\s*:\s*"LocalBusiness"',
|
||||
r'"@type"\s*:\s*"Brand"',
|
||||
r'itemtype.*schema\.org/(Organization|Person|Brand)',
|
||||
r'rel="author"'
|
||||
]
|
||||
has_entity = any(re.search(p, content, re.I) for p in entity_patterns)
|
||||
if has_entity:
|
||||
passed.append("Entity/Brand recognition (E-E-A-T)")
|
||||
|
||||
# 9. Original Statistics/Data (AI citation magnet) - NEW 2025
|
||||
stat_patterns = [
|
||||
r'\d+%', # Percentages
|
||||
r'\$[\d,]+', # Dollar amounts
|
||||
r'study\s+(shows|found)', # Research citations
|
||||
r'according to', # Source attribution
|
||||
r'data\s+(shows|reveals)', # Data-backed claims
|
||||
r'\d+x\s+(faster|better|more)', # Comparison stats
|
||||
r'(million|billion|trillion)', # Large numbers
|
||||
]
|
||||
stat_matches = sum(1 for p in stat_patterns if re.search(p, content, re.I))
|
||||
if stat_matches >= 2:
|
||||
passed.append("Original statistics/data (citation magnet)")
|
||||
|
||||
# 10. Conversational/Direct answers - NEW 2025
|
||||
direct_answer_patterns = [
|
||||
r'is defined as',
|
||||
r'refers to',
|
||||
r'means that',
|
||||
r'the answer is',
|
||||
r'in short,',
|
||||
r'simply put,',
|
||||
r'<dfn'
|
||||
]
|
||||
has_direct = any(re.search(p, content, re.I) for p in direct_answer_patterns)
|
||||
if has_direct:
|
||||
passed.append("Direct answer patterns (LLM-friendly)")
|
||||
|
||||
# Calculate score
|
||||
total = len(passed) + len(issues)
|
||||
score = (len(passed) / total * 100) if total > 0 else 0
|
||||
|
||||
return {
|
||||
'file': str(file_path.name),
|
||||
'passed': passed,
|
||||
'issues': issues,
|
||||
'score': round(score)
|
||||
}
|
||||
|
||||
|
||||
def main():
|
||||
target = sys.argv[1] if len(sys.argv) > 1 else "."
|
||||
target_path = Path(target).resolve()
|
||||
|
||||
print("\n" + "=" * 60)
|
||||
print(" GEO CHECKER - AI Citation Readiness Audit")
|
||||
print("=" * 60)
|
||||
print(f"Project: {target_path}")
|
||||
print("-" * 60)
|
||||
|
||||
# Find web pages only
|
||||
pages = find_web_pages(target_path)
|
||||
|
||||
if not pages:
|
||||
print("\n[!] No public web pages found.")
|
||||
print(" Looking for: HTML, JSX, TSX files in pages/app directories")
|
||||
print(" Skipping: docs, tests, config files, node_modules")
|
||||
output = {"script": "geo_checker", "pages_found": 0, "passed": True}
|
||||
print("\n" + json.dumps(output, indent=2))
|
||||
sys.exit(0)
|
||||
|
||||
print(f"Found {len(pages)} public pages to analyze\n")
|
||||
|
||||
# Check each page
|
||||
results = []
|
||||
for page in pages:
|
||||
result = check_page(page)
|
||||
results.append(result)
|
||||
|
||||
# Print results
|
||||
for result in results:
|
||||
status = "[OK]" if result['score'] >= 60 else "[!]"
|
||||
print(f"{status} {result['file']}: {result['score']}%")
|
||||
if result['issues'] and result['score'] < 60:
|
||||
for issue in result['issues'][:2]: # Show max 2 issues
|
||||
print(f" - {issue}")
|
||||
|
||||
# Average score
|
||||
avg_score = sum(r['score'] for r in results) / len(results) if results else 0
|
||||
|
||||
print("\n" + "=" * 60)
|
||||
print(f"AVERAGE GEO SCORE: {avg_score:.0f}%")
|
||||
print("=" * 60)
|
||||
|
||||
if avg_score >= 80:
|
||||
print("[OK] Excellent - Content well-optimized for AI citations")
|
||||
elif avg_score >= 60:
|
||||
print("[OK] Good - Some improvements recommended")
|
||||
elif avg_score >= 40:
|
||||
print("[!] Needs work - Add structured elements")
|
||||
else:
|
||||
print("[X] Poor - Content needs GEO optimization")
|
||||
|
||||
# JSON output
|
||||
output = {
|
||||
"script": "geo_checker",
|
||||
"project": str(target_path),
|
||||
"pages_checked": len(results),
|
||||
"average_score": round(avg_score),
|
||||
"passed": avg_score >= 60
|
||||
}
|
||||
print("\n" + json.dumps(output, indent=2))
|
||||
|
||||
sys.exit(0 if avg_score >= 60 else 1)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -1,6 +1,9 @@
|
||||
---
|
||||
name: HTML Injection Testing
|
||||
description: This skill should be used when the user asks to "test for HTML injection", "inject HTML into web pages", "perform HTML injection attacks", "deface web applications", or "test content injection vulnerabilities". It provides comprehensive HTML injection attack techniques and testing methodologies.
|
||||
metadata:
|
||||
author: zebbern
|
||||
version: "1.1"
|
||||
---
|
||||
|
||||
# HTML Injection Testing
|
||||
|
||||
154
skills/i18n-localization/SKILL.md
Normal file
154
skills/i18n-localization/SKILL.md
Normal file
@@ -0,0 +1,154 @@
|
||||
---
|
||||
name: i18n-localization
|
||||
description: Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.
|
||||
allowed-tools: Read, Glob, Grep
|
||||
---
|
||||
|
||||
# i18n & Localization
|
||||
|
||||
> Internationalization (i18n) and Localization (L10n) best practices.
|
||||
|
||||
---
|
||||
|
||||
## 1. Core Concepts
|
||||
|
||||
| Term | Meaning |
|
||||
|------|---------|
|
||||
| **i18n** | Internationalization - making app translatable |
|
||||
| **L10n** | Localization - actual translations |
|
||||
| **Locale** | Language + Region (en-US, tr-TR) |
|
||||
| **RTL** | Right-to-left languages (Arabic, Hebrew) |
|
||||
|
||||
---
|
||||
|
||||
## 2. When to Use i18n
|
||||
|
||||
| Project Type | i18n Needed? |
|
||||
|--------------|--------------|
|
||||
| Public web app | ✅ Yes |
|
||||
| SaaS product | ✅ Yes |
|
||||
| Internal tool | ⚠️ Maybe |
|
||||
| Single-region app | ⚠️ Consider future |
|
||||
| Personal project | ❌ Optional |
|
||||
|
||||
---
|
||||
|
||||
## 3. Implementation Patterns
|
||||
|
||||
### React (react-i18next)
|
||||
|
||||
```tsx
|
||||
import { useTranslation } from 'react-i18next';
|
||||
|
||||
function Welcome() {
|
||||
const { t } = useTranslation();
|
||||
return <h1>{t('welcome.title')}</h1>;
|
||||
}
|
||||
```
|
||||
|
||||
### Next.js (next-intl)
|
||||
|
||||
```tsx
|
||||
import { useTranslations } from 'next-intl';
|
||||
|
||||
export default function Page() {
|
||||
const t = useTranslations('Home');
|
||||
return <h1>{t('title')}</h1>;
|
||||
}
|
||||
```
|
||||
|
||||
### Python (gettext)
|
||||
|
||||
```python
|
||||
from gettext import gettext as _
|
||||
|
||||
print(_("Welcome to our app"))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. File Structure
|
||||
|
||||
```
|
||||
locales/
|
||||
├── en/
|
||||
│ ├── common.json
|
||||
│ ├── auth.json
|
||||
│ └── errors.json
|
||||
├── tr/
|
||||
│ ├── common.json
|
||||
│ ├── auth.json
|
||||
│ └── errors.json
|
||||
└── ar/ # RTL
|
||||
└── ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Best Practices
|
||||
|
||||
### DO ✅
|
||||
|
||||
- Use translation keys, not raw text
|
||||
- Namespace translations by feature
|
||||
- Support pluralization
|
||||
- Handle date/number formats per locale
|
||||
- Plan for RTL from the start
|
||||
- Use ICU message format for complex strings
|
||||
|
||||
### DON'T ❌
|
||||
|
||||
- Hardcode strings in components
|
||||
- Concatenate translated strings
|
||||
- Assume text length (German is 30% longer)
|
||||
- Forget about RTL layout
|
||||
- Mix languages in same file
|
||||
|
||||
---
|
||||
|
||||
## 6. Common Issues
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| Missing translation | Fallback to default language |
|
||||
| Hardcoded strings | Use linter/checker script |
|
||||
| Date format | Use Intl.DateTimeFormat |
|
||||
| Number format | Use Intl.NumberFormat |
|
||||
| Pluralization | Use ICU message format |
|
||||
|
||||
---
|
||||
|
||||
## 7. RTL Support
|
||||
|
||||
```css
|
||||
/* CSS Logical Properties */
|
||||
.container {
|
||||
margin-inline-start: 1rem; /* Not margin-left */
|
||||
padding-inline-end: 1rem; /* Not padding-right */
|
||||
}
|
||||
|
||||
[dir="rtl"] .icon {
|
||||
transform: scaleX(-1);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Checklist
|
||||
|
||||
Before shipping:
|
||||
|
||||
- [ ] All user-facing strings use translation keys
|
||||
- [ ] Locale files exist for all supported languages
|
||||
- [ ] Date/number formatting uses Intl API
|
||||
- [ ] RTL layout tested (if applicable)
|
||||
- [ ] Fallback language configured
|
||||
- [ ] No hardcoded strings in components
|
||||
|
||||
---
|
||||
|
||||
## Script
|
||||
|
||||
| Script | Purpose | Command |
|
||||
|--------|---------|---------|
|
||||
| `scripts/i18n_checker.py` | Detect hardcoded strings & missing translations | `python scripts/i18n_checker.py <project_path>` |
|
||||
241
skills/i18n-localization/scripts/i18n_checker.py
Normal file
241
skills/i18n-localization/scripts/i18n_checker.py
Normal file
@@ -0,0 +1,241 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
i18n Checker - Detects hardcoded strings and missing translations.
|
||||
Scans for untranslated text in React, Vue, and Python files.
|
||||
"""
|
||||
import sys
|
||||
import re
|
||||
import json
|
||||
from pathlib import Path
|
||||
|
||||
# Fix Windows console encoding for Unicode output
|
||||
try:
|
||||
sys.stdout.reconfigure(encoding='utf-8', errors='replace')
|
||||
sys.stderr.reconfigure(encoding='utf-8', errors='replace')
|
||||
except AttributeError:
|
||||
pass # Python < 3.7
|
||||
|
||||
# Patterns that indicate hardcoded strings (should be translated)
|
||||
HARDCODED_PATTERNS = {
|
||||
'jsx': [
|
||||
# Text directly in JSX: <div>Hello World</div>
|
||||
r'>\s*[A-Z][a-zA-Z\s]{3,30}\s*</',
|
||||
# JSX attribute strings: title="Welcome"
|
||||
r'(title|placeholder|label|alt|aria-label)="[A-Z][a-zA-Z\s]{2,}"',
|
||||
# Button/heading text
|
||||
r'<(button|h[1-6]|p|span|label)[^>]*>\s*[A-Z][a-zA-Z\s!?.,]{3,}\s*</',
|
||||
],
|
||||
'vue': [
|
||||
# Vue template text
|
||||
r'>\s*[A-Z][a-zA-Z\s]{3,30}\s*</',
|
||||
r'(placeholder|label|title)="[A-Z][a-zA-Z\s]{2,}"',
|
||||
],
|
||||
'python': [
|
||||
# print/raise with string literals
|
||||
r'(print|raise\s+\w+)\s*\(\s*["\'][A-Z][^"\']{5,}["\']',
|
||||
# Flask flash messages
|
||||
r'flash\s*\(\s*["\'][A-Z][^"\']{5,}["\']',
|
||||
]
|
||||
}
|
||||
|
||||
# Patterns that indicate proper i18n usage
|
||||
I18N_PATTERNS = [
|
||||
r't\(["\']', # t('key') - react-i18next
|
||||
r'useTranslation', # React hook
|
||||
r'\$t\(', # Vue i18n
|
||||
r'_\(["\']', # Python gettext
|
||||
r'gettext\(', # Python gettext
|
||||
r'useTranslations', # next-intl
|
||||
r'FormattedMessage', # react-intl
|
||||
r'i18n\.', # Generic i18n
|
||||
]
|
||||
|
||||
def find_locale_files(project_path: Path) -> list:
|
||||
"""Find translation/locale files."""
|
||||
patterns = [
|
||||
"**/locales/**/*.json",
|
||||
"**/translations/**/*.json",
|
||||
"**/lang/**/*.json",
|
||||
"**/i18n/**/*.json",
|
||||
"**/messages/*.json",
|
||||
"**/*.po", # gettext
|
||||
]
|
||||
|
||||
files = []
|
||||
for pattern in patterns:
|
||||
files.extend(project_path.glob(pattern))
|
||||
|
||||
return [f for f in files if 'node_modules' not in str(f)]
|
||||
|
||||
def check_locale_completeness(locale_files: list) -> dict:
|
||||
"""Check if all locales have the same keys."""
|
||||
issues = []
|
||||
passed = []
|
||||
|
||||
if not locale_files:
|
||||
return {'passed': [], 'issues': ["[!] No locale files found"]}
|
||||
|
||||
# Group by parent folder (language)
|
||||
locales = {}
|
||||
for f in locale_files:
|
||||
if f.suffix == '.json':
|
||||
try:
|
||||
lang = f.parent.name
|
||||
content = json.loads(f.read_text(encoding='utf-8'))
|
||||
if lang not in locales:
|
||||
locales[lang] = {}
|
||||
locales[lang][f.stem] = set(flatten_keys(content))
|
||||
except:
|
||||
continue
|
||||
|
||||
if len(locales) < 2:
|
||||
passed.append(f"[OK] Found {len(locale_files)} locale file(s)")
|
||||
return {'passed': passed, 'issues': issues}
|
||||
|
||||
passed.append(f"[OK] Found {len(locales)} language(s): {', '.join(locales.keys())}")
|
||||
|
||||
# Compare keys across locales
|
||||
all_langs = list(locales.keys())
|
||||
base_lang = all_langs[0]
|
||||
|
||||
for namespace in locales.get(base_lang, {}):
|
||||
base_keys = locales[base_lang].get(namespace, set())
|
||||
|
||||
for lang in all_langs[1:]:
|
||||
other_keys = locales.get(lang, {}).get(namespace, set())
|
||||
|
||||
missing = base_keys - other_keys
|
||||
if missing:
|
||||
issues.append(f"[X] {lang}/{namespace}: Missing {len(missing)} keys")
|
||||
|
||||
extra = other_keys - base_keys
|
||||
if extra:
|
||||
issues.append(f"[!] {lang}/{namespace}: {len(extra)} extra keys")
|
||||
|
||||
if not issues:
|
||||
passed.append("[OK] All locales have matching keys")
|
||||
|
||||
return {'passed': passed, 'issues': issues}
|
||||
|
||||
def flatten_keys(d, prefix=''):
|
||||
"""Flatten nested dict keys."""
|
||||
keys = set()
|
||||
for k, v in d.items():
|
||||
new_key = f"{prefix}.{k}" if prefix else k
|
||||
if isinstance(v, dict):
|
||||
keys.update(flatten_keys(v, new_key))
|
||||
else:
|
||||
keys.add(new_key)
|
||||
return keys
|
||||
|
||||
def check_hardcoded_strings(project_path: Path) -> dict:
|
||||
"""Check for hardcoded strings in code files."""
|
||||
issues = []
|
||||
passed = []
|
||||
|
||||
# Find code files
|
||||
extensions = {
|
||||
'.tsx': 'jsx', '.jsx': 'jsx', '.ts': 'jsx', '.js': 'jsx',
|
||||
'.vue': 'vue',
|
||||
'.py': 'python'
|
||||
}
|
||||
|
||||
code_files = []
|
||||
for ext in extensions:
|
||||
code_files.extend(project_path.rglob(f"*{ext}"))
|
||||
|
||||
code_files = [f for f in code_files if not any(x in str(f) for x in
|
||||
['node_modules', '.git', 'dist', 'build', '__pycache__', 'venv', 'test', 'spec'])]
|
||||
|
||||
if not code_files:
|
||||
return {'passed': ["[!] No code files found"], 'issues': []}
|
||||
|
||||
files_with_i18n = 0
|
||||
files_with_hardcoded = 0
|
||||
hardcoded_examples = []
|
||||
|
||||
for file_path in code_files[:50]: # Limit
|
||||
try:
|
||||
content = file_path.read_text(encoding='utf-8', errors='ignore')
|
||||
ext = file_path.suffix
|
||||
file_type = extensions.get(ext, 'jsx')
|
||||
|
||||
# Check for i18n usage
|
||||
has_i18n = any(re.search(p, content) for p in I18N_PATTERNS)
|
||||
if has_i18n:
|
||||
files_with_i18n += 1
|
||||
|
||||
# Check for hardcoded strings
|
||||
patterns = HARDCODED_PATTERNS.get(file_type, [])
|
||||
hardcoded_found = False
|
||||
|
||||
for pattern in patterns:
|
||||
matches = re.findall(pattern, content)
|
||||
if matches and not has_i18n:
|
||||
hardcoded_found = True
|
||||
if len(hardcoded_examples) < 5:
|
||||
hardcoded_examples.append(f"{file_path.name}: {str(matches[0])[:40]}...")
|
||||
|
||||
if hardcoded_found:
|
||||
files_with_hardcoded += 1
|
||||
|
||||
except:
|
||||
continue
|
||||
|
||||
passed.append(f"[OK] Analyzed {len(code_files)} code files")
|
||||
|
||||
if files_with_i18n > 0:
|
||||
passed.append(f"[OK] {files_with_i18n} files use i18n")
|
||||
|
||||
if files_with_hardcoded > 0:
|
||||
issues.append(f"[X] {files_with_hardcoded} files may have hardcoded strings")
|
||||
for ex in hardcoded_examples:
|
||||
issues.append(f" → {ex}")
|
||||
else:
|
||||
passed.append("[OK] No obvious hardcoded strings detected")
|
||||
|
||||
return {'passed': passed, 'issues': issues}
|
||||
|
||||
def main():
|
||||
target = sys.argv[1] if len(sys.argv) > 1 else "."
|
||||
project_path = Path(target)
|
||||
|
||||
print("\n" + "=" * 60)
|
||||
print(" i18n CHECKER - Internationalization Audit")
|
||||
print("=" * 60 + "\n")
|
||||
|
||||
# Check locale files
|
||||
locale_files = find_locale_files(project_path)
|
||||
locale_result = check_locale_completeness(locale_files)
|
||||
|
||||
# Check hardcoded strings
|
||||
code_result = check_hardcoded_strings(project_path)
|
||||
|
||||
# Print results
|
||||
print("[LOCALE FILES]")
|
||||
print("-" * 40)
|
||||
for item in locale_result['passed']:
|
||||
print(f" {item}")
|
||||
for item in locale_result['issues']:
|
||||
print(f" {item}")
|
||||
|
||||
print("\n[CODE ANALYSIS]")
|
||||
print("-" * 40)
|
||||
for item in code_result['passed']:
|
||||
print(f" {item}")
|
||||
for item in code_result['issues']:
|
||||
print(f" {item}")
|
||||
|
||||
# Summary
|
||||
critical_issues = sum(1 for i in locale_result['issues'] + code_result['issues'] if i.startswith("[X]"))
|
||||
|
||||
print("\n" + "=" * 60)
|
||||
if critical_issues == 0:
|
||||
print("[OK] i18n CHECK: PASSED")
|
||||
sys.exit(0)
|
||||
else:
|
||||
print(f"[X] i18n CHECK: {critical_issues} issues found")
|
||||
sys.exit(1)
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -1,6 +1,9 @@
|
||||
---
|
||||
name: IDOR Vulnerability Testing
|
||||
description: This skill should be used when the user asks to "test for insecure direct object references," "find IDOR vulnerabilities," "exploit broken access control," "enumerate user IDs or object references," or "bypass authorization to access other users' data." It provides comprehensive guidance for detecting, exploiting, and remediating IDOR vulnerabilities in web applications.
|
||||
metadata:
|
||||
author: zebbern
|
||||
version: "1.1"
|
||||
---
|
||||
|
||||
# IDOR Vulnerability Testing
|
||||
|
||||
45
skills/lint-and-validate/SKILL.md
Normal file
45
skills/lint-and-validate/SKILL.md
Normal file
@@ -0,0 +1,45 @@
|
||||
---
|
||||
name: lint-and-validate
|
||||
description: Automatic quality control, linting, and static analysis procedures. Use after every code modification to ensure syntax correctness and project standards. Triggers onKeywords: lint, format, check, validate, types, static analysis.
|
||||
allowed-tools: Read, Glob, Grep, Bash
|
||||
---
|
||||
|
||||
# Lint and Validate Skill
|
||||
|
||||
> **MANDATORY:** Run appropriate validation tools after EVERY code change. Do not finish a task until the code is error-free.
|
||||
|
||||
### Procedures by Ecosystem
|
||||
|
||||
#### Node.js / TypeScript
|
||||
1. **Lint/Fix:** `npm run lint` or `npx eslint "path" --fix`
|
||||
2. **Types:** `npx tsc --noEmit`
|
||||
3. **Security:** `npm audit --audit-level=high`
|
||||
|
||||
#### Python
|
||||
1. **Linter (Ruff):** `ruff check "path" --fix` (Fast & Modern)
|
||||
2. **Security (Bandit):** `bandit -r "path" -ll`
|
||||
3. **Types (MyPy):** `mypy "path"`
|
||||
|
||||
## The Quality Loop
|
||||
1. **Write/Edit Code**
|
||||
2. **Run Audit:** `npm run lint && npx tsc --noEmit`
|
||||
3. **Analyze Report:** Check the "FINAL AUDIT REPORT" section.
|
||||
4. **Fix & Repeat:** Submitting code with "FINAL AUDIT" failures is NOT allowed.
|
||||
|
||||
## Error Handling
|
||||
- If `lint` fails: Fix the style or syntax issues immediately.
|
||||
- If `tsc` fails: Correct type mismatches before proceeding.
|
||||
- If no tool is configured: Check the project root for `.eslintrc`, `tsconfig.json`, `pyproject.toml` and suggest creating one.
|
||||
|
||||
---
|
||||
**Strict Rule:** No code should be committed or reported as "done" without passing these checks.
|
||||
|
||||
---
|
||||
|
||||
## Scripts
|
||||
|
||||
| Script | Purpose | Command |
|
||||
|--------|---------|---------|
|
||||
| `scripts/lint_runner.py` | Unified lint check | `python scripts/lint_runner.py <project_path>` |
|
||||
| `scripts/type_coverage.py` | Type coverage analysis | `python scripts/type_coverage.py <project_path>` |
|
||||
|
||||
172
skills/lint-and-validate/scripts/lint_runner.py
Normal file
172
skills/lint-and-validate/scripts/lint_runner.py
Normal file
@@ -0,0 +1,172 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Lint Runner - Unified linting and type checking
|
||||
Runs appropriate linters based on project type.
|
||||
|
||||
Usage:
|
||||
python lint_runner.py <project_path>
|
||||
|
||||
Supports:
|
||||
- Node.js: npm run lint, npx tsc --noEmit
|
||||
- Python: ruff check, mypy
|
||||
"""
|
||||
|
||||
import subprocess
|
||||
import sys
|
||||
import json
|
||||
from pathlib import Path
|
||||
from datetime import datetime
|
||||
|
||||
# Fix Windows console encoding
|
||||
try:
|
||||
sys.stdout.reconfigure(encoding='utf-8', errors='replace')
|
||||
except:
|
||||
pass
|
||||
|
||||
|
||||
def detect_project_type(project_path: Path) -> dict:
|
||||
"""Detect project type and available linters."""
|
||||
result = {
|
||||
"type": "unknown",
|
||||
"linters": []
|
||||
}
|
||||
|
||||
# Node.js project
|
||||
package_json = project_path / "package.json"
|
||||
if package_json.exists():
|
||||
result["type"] = "node"
|
||||
try:
|
||||
pkg = json.loads(package_json.read_text(encoding='utf-8'))
|
||||
scripts = pkg.get("scripts", {})
|
||||
deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
|
||||
|
||||
# Check for lint script
|
||||
if "lint" in scripts:
|
||||
result["linters"].append({"name": "npm lint", "cmd": ["npm", "run", "lint"]})
|
||||
elif "eslint" in deps:
|
||||
result["linters"].append({"name": "eslint", "cmd": ["npx", "eslint", "."]})
|
||||
|
||||
# Check for TypeScript
|
||||
if "typescript" in deps or (project_path / "tsconfig.json").exists():
|
||||
result["linters"].append({"name": "tsc", "cmd": ["npx", "tsc", "--noEmit"]})
|
||||
|
||||
except:
|
||||
pass
|
||||
|
||||
# Python project
|
||||
if (project_path / "pyproject.toml").exists() or (project_path / "requirements.txt").exists():
|
||||
result["type"] = "python"
|
||||
|
||||
# Check for ruff
|
||||
result["linters"].append({"name": "ruff", "cmd": ["ruff", "check", "."]})
|
||||
|
||||
# Check for mypy
|
||||
if (project_path / "mypy.ini").exists() or (project_path / "pyproject.toml").exists():
|
||||
result["linters"].append({"name": "mypy", "cmd": ["mypy", "."]})
|
||||
|
||||
return result
|
||||
|
||||
|
||||
def run_linter(linter: dict, cwd: Path) -> dict:
|
||||
"""Run a single linter and return results."""
|
||||
result = {
|
||||
"name": linter["name"],
|
||||
"passed": False,
|
||||
"output": "",
|
||||
"error": ""
|
||||
}
|
||||
|
||||
try:
|
||||
proc = subprocess.run(
|
||||
linter["cmd"],
|
||||
cwd=str(cwd),
|
||||
capture_output=True,
|
||||
text=True,
|
||||
encoding='utf-8',
|
||||
errors='replace',
|
||||
timeout=120
|
||||
)
|
||||
|
||||
result["output"] = proc.stdout[:2000] if proc.stdout else ""
|
||||
result["error"] = proc.stderr[:500] if proc.stderr else ""
|
||||
result["passed"] = proc.returncode == 0
|
||||
|
||||
except FileNotFoundError:
|
||||
result["error"] = f"Command not found: {linter['cmd'][0]}"
|
||||
except subprocess.TimeoutExpired:
|
||||
result["error"] = "Timeout after 120s"
|
||||
except Exception as e:
|
||||
result["error"] = str(e)
|
||||
|
||||
return result
|
||||
|
||||
|
||||
def main():
|
||||
project_path = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
|
||||
|
||||
print(f"\n{'='*60}")
|
||||
print(f"[LINT RUNNER] Unified Linting")
|
||||
print(f"{'='*60}")
|
||||
print(f"Project: {project_path}")
|
||||
print(f"Time: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
|
||||
|
||||
# Detect project type
|
||||
project_info = detect_project_type(project_path)
|
||||
print(f"Type: {project_info['type']}")
|
||||
print(f"Linters: {len(project_info['linters'])}")
|
||||
print("-"*60)
|
||||
|
||||
if not project_info["linters"]:
|
||||
print("No linters found for this project type.")
|
||||
output = {
|
||||
"script": "lint_runner",
|
||||
"project": str(project_path),
|
||||
"type": project_info["type"],
|
||||
"checks": [],
|
||||
"passed": True,
|
||||
"message": "No linters configured"
|
||||
}
|
||||
print(json.dumps(output, indent=2))
|
||||
sys.exit(0)
|
||||
|
||||
# Run each linter
|
||||
results = []
|
||||
all_passed = True
|
||||
|
||||
for linter in project_info["linters"]:
|
||||
print(f"\nRunning: {linter['name']}...")
|
||||
result = run_linter(linter, project_path)
|
||||
results.append(result)
|
||||
|
||||
if result["passed"]:
|
||||
print(f" [PASS] {linter['name']}")
|
||||
else:
|
||||
print(f" [FAIL] {linter['name']}")
|
||||
if result["error"]:
|
||||
print(f" Error: {result['error'][:200]}")
|
||||
all_passed = False
|
||||
|
||||
# Summary
|
||||
print("\n" + "="*60)
|
||||
print("SUMMARY")
|
||||
print("="*60)
|
||||
|
||||
for r in results:
|
||||
icon = "[PASS]" if r["passed"] else "[FAIL]"
|
||||
print(f"{icon} {r['name']}")
|
||||
|
||||
output = {
|
||||
"script": "lint_runner",
|
||||
"project": str(project_path),
|
||||
"type": project_info["type"],
|
||||
"checks": results,
|
||||
"passed": all_passed
|
||||
}
|
||||
|
||||
print("\n" + json.dumps(output, indent=2))
|
||||
|
||||
sys.exit(0 if all_passed else 1)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
173
skills/lint-and-validate/scripts/type_coverage.py
Normal file
173
skills/lint-and-validate/scripts/type_coverage.py
Normal file
@@ -0,0 +1,173 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Type Coverage Checker - Measures TypeScript/Python type coverage.
|
||||
Identifies untyped functions, any usage, and type safety issues.
|
||||
"""
|
||||
import sys
|
||||
import re
|
||||
import subprocess
|
||||
from pathlib import Path
|
||||
|
||||
# Fix Windows console encoding for Unicode output
|
||||
try:
|
||||
sys.stdout.reconfigure(encoding='utf-8', errors='replace')
|
||||
sys.stderr.reconfigure(encoding='utf-8', errors='replace')
|
||||
except AttributeError:
|
||||
pass # Python < 3.7
|
||||
|
||||
def check_typescript_coverage(project_path: Path) -> dict:
|
||||
"""Check TypeScript type coverage."""
|
||||
issues = []
|
||||
passed = []
|
||||
stats = {'any_count': 0, 'untyped_functions': 0, 'total_functions': 0}
|
||||
|
||||
ts_files = list(project_path.rglob("*.ts")) + list(project_path.rglob("*.tsx"))
|
||||
ts_files = [f for f in ts_files if 'node_modules' not in str(f) and '.d.ts' not in str(f)]
|
||||
|
||||
if not ts_files:
|
||||
return {'type': 'typescript', 'files': 0, 'passed': [], 'issues': ["[!] No TypeScript files found"], 'stats': stats}
|
||||
|
||||
for file_path in ts_files[:30]: # Limit
|
||||
try:
|
||||
content = file_path.read_text(encoding='utf-8', errors='ignore')
|
||||
|
||||
# Count 'any' usage
|
||||
any_matches = re.findall(r':\s*any\b', content)
|
||||
stats['any_count'] += len(any_matches)
|
||||
|
||||
# Find functions without return types
|
||||
# function name(params) { - no return type
|
||||
untyped = re.findall(r'function\s+\w+\s*\([^)]*\)\s*{', content)
|
||||
# Arrow functions without types: const fn = (x) => or (x) =>
|
||||
untyped += re.findall(r'=\s*\([^:)]*\)\s*=>', content)
|
||||
stats['untyped_functions'] += len(untyped)
|
||||
|
||||
# Count typed functions
|
||||
typed = re.findall(r'function\s+\w+\s*\([^)]*\)\s*:\s*\w+', content)
|
||||
typed += re.findall(r':\s*\([^)]*\)\s*=>\s*\w+', content)
|
||||
stats['total_functions'] += len(typed) + len(untyped)
|
||||
|
||||
except Exception:
|
||||
continue
|
||||
|
||||
# Analyze results
|
||||
if stats['any_count'] == 0:
|
||||
passed.append("[OK] No 'any' types found")
|
||||
elif stats['any_count'] <= 5:
|
||||
issues.append(f"[!] {stats['any_count']} 'any' types found (acceptable)")
|
||||
else:
|
||||
issues.append(f"[X] {stats['any_count']} 'any' types found (too many)")
|
||||
|
||||
if stats['total_functions'] > 0:
|
||||
typed_ratio = (stats['total_functions'] - stats['untyped_functions']) / stats['total_functions'] * 100
|
||||
if typed_ratio >= 80:
|
||||
passed.append(f"[OK] Type coverage: {typed_ratio:.0f}%")
|
||||
elif typed_ratio >= 50:
|
||||
issues.append(f"[!] Type coverage: {typed_ratio:.0f}% (improve)")
|
||||
else:
|
||||
issues.append(f"[X] Type coverage: {typed_ratio:.0f}% (too low)")
|
||||
|
||||
passed.append(f"[OK] Analyzed {len(ts_files)} TypeScript files")
|
||||
|
||||
return {'type': 'typescript', 'files': len(ts_files), 'passed': passed, 'issues': issues, 'stats': stats}
|
||||
|
||||
def check_python_coverage(project_path: Path) -> dict:
|
||||
"""Check Python type hints coverage."""
|
||||
issues = []
|
||||
passed = []
|
||||
stats = {'untyped_functions': 0, 'typed_functions': 0, 'any_count': 0}
|
||||
|
||||
py_files = list(project_path.rglob("*.py"))
|
||||
py_files = [f for f in py_files if not any(x in str(f) for x in ['venv', '__pycache__', '.git', 'node_modules'])]
|
||||
|
||||
if not py_files:
|
||||
return {'type': 'python', 'files': 0, 'passed': [], 'issues': ["[!] No Python files found"], 'stats': stats}
|
||||
|
||||
for file_path in py_files[:30]: # Limit
|
||||
try:
|
||||
content = file_path.read_text(encoding='utf-8', errors='ignore')
|
||||
|
||||
# Count Any usage
|
||||
any_matches = re.findall(r':\s*Any\b', content)
|
||||
stats['any_count'] += len(any_matches)
|
||||
|
||||
# Find functions with type hints
|
||||
typed_funcs = re.findall(r'def\s+\w+\s*\([^)]*:[^)]+\)', content)
|
||||
typed_funcs += re.findall(r'def\s+\w+\s*\([^)]*\)\s*->', content)
|
||||
stats['typed_functions'] += len(typed_funcs)
|
||||
|
||||
# Find functions without type hints
|
||||
all_funcs = re.findall(r'def\s+\w+\s*\(', content)
|
||||
stats['untyped_functions'] += len(all_funcs) - len(typed_funcs)
|
||||
|
||||
except Exception:
|
||||
continue
|
||||
|
||||
total = stats['typed_functions'] + stats['untyped_functions']
|
||||
|
||||
if total > 0:
|
||||
typed_ratio = stats['typed_functions'] / total * 100
|
||||
if typed_ratio >= 70:
|
||||
passed.append(f"[OK] Type hints coverage: {typed_ratio:.0f}%")
|
||||
elif typed_ratio >= 40:
|
||||
issues.append(f"[!] Type hints coverage: {typed_ratio:.0f}%")
|
||||
else:
|
||||
issues.append(f"[X] Type hints coverage: {typed_ratio:.0f}% (add type hints)")
|
||||
|
||||
if stats['any_count'] == 0:
|
||||
passed.append("[OK] No 'Any' types found")
|
||||
elif stats['any_count'] <= 3:
|
||||
issues.append(f"[!] {stats['any_count']} 'Any' types found")
|
||||
else:
|
||||
issues.append(f"[X] {stats['any_count']} 'Any' types found")
|
||||
|
||||
passed.append(f"[OK] Analyzed {len(py_files)} Python files")
|
||||
|
||||
return {'type': 'python', 'files': len(py_files), 'passed': passed, 'issues': issues, 'stats': stats}
|
||||
|
||||
def main():
|
||||
target = sys.argv[1] if len(sys.argv) > 1 else "."
|
||||
project_path = Path(target)
|
||||
|
||||
print("\n" + "=" * 60)
|
||||
print(" TYPE COVERAGE CHECKER")
|
||||
print("=" * 60 + "\n")
|
||||
|
||||
results = []
|
||||
|
||||
# Check TypeScript
|
||||
ts_result = check_typescript_coverage(project_path)
|
||||
if ts_result['files'] > 0:
|
||||
results.append(ts_result)
|
||||
|
||||
# Check Python
|
||||
py_result = check_python_coverage(project_path)
|
||||
if py_result['files'] > 0:
|
||||
results.append(py_result)
|
||||
|
||||
if not results:
|
||||
print("[!] No TypeScript or Python files found.")
|
||||
sys.exit(0)
|
||||
|
||||
# Print results
|
||||
critical_issues = 0
|
||||
for result in results:
|
||||
print(f"\n[{result['type'].upper()}]")
|
||||
print("-" * 40)
|
||||
for item in result['passed']:
|
||||
print(f" {item}")
|
||||
for item in result['issues']:
|
||||
print(f" {item}")
|
||||
if item.startswith("[X]"):
|
||||
critical_issues += 1
|
||||
|
||||
print("\n" + "=" * 60)
|
||||
if critical_issues == 0:
|
||||
print("[OK] TYPE COVERAGE: ACCEPTABLE")
|
||||
sys.exit(0)
|
||||
else:
|
||||
print(f"[X] TYPE COVERAGE: {critical_issues} critical issues")
|
||||
sys.exit(1)
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user