Compare commits
75 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
41309cfd7d | ||
|
|
36107a5cae | ||
|
|
238cfc6933 | ||
|
|
f28591e648 | ||
|
|
d38e2eeab1 | ||
|
|
4fe8a1e6a4 | ||
|
|
1557826c5d | ||
|
|
bec54d7abb | ||
|
|
23f9ad547c | ||
|
|
28def60eec | ||
|
|
902063fd0a | ||
|
|
9ff0cc0b74 | ||
|
|
ae3d038711 | ||
|
|
af57b96721 | ||
|
|
d5d420d2e1 | ||
|
|
e053fd0eb7 | ||
|
|
ee5511fc59 | ||
|
|
f54c340851 | ||
|
|
ad83399403 | ||
|
|
40fd263b4e | ||
|
|
0405d4a577 | ||
|
|
00079b5bff | ||
|
|
27ce8af114 | ||
|
|
5e888ef6bb | ||
|
|
1134e1e735 | ||
|
|
4803af0b95 | ||
|
|
df0f084ac6 | ||
|
|
d962bb21ea | ||
|
|
807f72a5be | ||
|
|
c29f87c2a9 | ||
|
|
06e8811af6 | ||
|
|
afafa37a2e | ||
|
|
c69b033ada | ||
|
|
2f01e2b267 | ||
|
|
91f46351be | ||
|
|
910cbeb8e0 | ||
|
|
2e835b9d66 | ||
|
|
4057e379d9 | ||
|
|
2d5a9a3e85 | ||
|
|
5d01094479 | ||
|
|
3c38ec509d | ||
|
|
4365fba248 | ||
|
|
2885b4ebaa | ||
|
|
63074bc2b7 | ||
|
|
33d8f93c7f | ||
|
|
c688c5e0fa | ||
|
|
590ea1e5b3 | ||
|
|
33908288f1 | ||
|
|
831d87605a | ||
|
|
c6df6cee4c | ||
|
|
8c8bae5e98 | ||
|
|
a10633744d | ||
|
|
10f00a45dd | ||
|
|
29b45dd234 | ||
|
|
81ecf7cec3 | ||
|
|
f6cdf4dc59 | ||
|
|
fef11a8059 | ||
|
|
ebdc51708c | ||
|
|
41fa3734ba | ||
|
|
b64c73015c | ||
|
|
a02afe1d72 | ||
|
|
408f188262 | ||
|
|
23f58f8705 | ||
|
|
90cf84b8bb | ||
|
|
4ee8a0361f | ||
|
|
e0fdc4e263 | ||
|
|
993775eb4d | ||
|
|
d672808990 | ||
|
|
13bdb4970c | ||
|
|
2db2ca8220 | ||
|
|
9720f75ebe | ||
|
|
e56affd8c8 | ||
|
|
518edc9a3c | ||
|
|
57ce2dd084 | ||
|
|
a61c0ed79b |
64
.github/MAINTENANCE.md
vendored
Normal file
64
.github/MAINTENANCE.md
vendored
Normal file
@@ -0,0 +1,64 @@
|
||||
# Repository Maintenance Protocol & Governance
|
||||
|
||||
> [!URGENT]
|
||||
> **READ THIS FIRST**: The single most critical rule of this repository is: **IF YOU DO NOT PUSH YOUR CHANGES, THEY DO NOT EXIST.**
|
||||
>
|
||||
> **ALWAYS** run `git push` immediately after committing. No exceptions.
|
||||
|
||||
## 1. Governance & Roles
|
||||
|
||||
### Maintainers
|
||||
|
||||
- **Core Team**: Responsible for "Official" skills and merging PRs.
|
||||
- **Review Policy**: All PRs must pass the [Quality Bar](../docs/QUALITY_BAR.md) checks.
|
||||
|
||||
### Code of Conduct
|
||||
|
||||
All contributors must adhere to the [Code of Conduct](../CODE_OF_CONDUCT.md).
|
||||
|
||||
## 2. Analysis & Planning (Planner Role)
|
||||
|
||||
1. **Check Duplicates**: `grep -r "search_term" skills_index.json`
|
||||
2. **Consult Quality Bar**: Review `docs/QUALITY_BAR.md` to ensure the plan meets the "Validated" criteria.
|
||||
3. **Risk Assessment**: Determine if the skill is `safe`, `critical`, or `offensive`. (See [Security Guardrails](../docs/SECURITY_GUARDRAILS.md))
|
||||
|
||||
## 3. Implementation Workflow (Executor Role)
|
||||
|
||||
1. **Create Skill**: Follow the standard folder structure `skills/<kebab-name>/`.
|
||||
2. **SKILL.md**: MUST header to the Quality Bar standard.
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: my-skill
|
||||
description: clear description
|
||||
risk: safe
|
||||
source: self
|
||||
---
|
||||
```
|
||||
|
||||
3. **Security Check**: If `risk: offensive`, add the "Authorized Use Only" disclaimer.
|
||||
|
||||
## 4. Validation Chain (MANDATORY)
|
||||
|
||||
Run validation before committing:
|
||||
|
||||
```bash
|
||||
python3 scripts/validate_skills.py
|
||||
python3 scripts/generate_index.py
|
||||
python3 scripts/update_readme.py
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> **Transition Period**: We are currently in a "Soft Launch" phase. Legacy skills may trigger warnings.
|
||||
> **New skills MUST have zero warnings.**
|
||||
|
||||
## 5. Documentation & Credits
|
||||
|
||||
- [ ] **SOURCE.md**: Update the master source list if importing external skills.
|
||||
- [ ] **README.md**: Ensure credits are added in the `Credits` section.
|
||||
|
||||
## 6. Finalization (The "Antigravity" Standard)
|
||||
|
||||
- [ ] **Git Add**: `git add .`
|
||||
- [ ] **Commit**: `git commit -m "feat: add [skill-name] skill"`
|
||||
- [ ] **PUSH NOW**: `git push` (Do not wait).
|
||||
21
.github/PULL_REQUEST_TEMPLATE.md
vendored
21
.github/PULL_REQUEST_TEMPLATE.md
vendored
@@ -1,17 +1,22 @@
|
||||
## Description
|
||||
# Pull Request Description
|
||||
|
||||
Please describe your changes. What skill are you adding or modifying?
|
||||
Please include a summary of the change and which skill is added or fixed.
|
||||
|
||||
## Checklist
|
||||
## Quality Bar Checklist ✅
|
||||
|
||||
- [ ] My skill follows the [creation guidelines](https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/skill-creator)
|
||||
- [ ] I have run `validate_skills.py`
|
||||
- [ ] I have added my name to the credits (if applicable)
|
||||
**All items must be checked before merging.**
|
||||
|
||||
- [ ] **Standards**: I have read `docs/QUALITY_BAR.md` and `docs/SECURITY_GUARDRAILS.md`.
|
||||
- [ ] **Metadata**: The `SKILL.md` frontmatter is valid (checked with `scripts/validate_skills.py`).
|
||||
- [ ] **Risk Label**: I have assigned the correct `risk:` tag (`none`, `safe`, `critical`, `offensive`).
|
||||
- [ ] **Triggers**: The "When to use" section is clear and specific.
|
||||
- [ ] **Security**: If this is an _offensive_ skill, I included the "Authorized Use Only" disclaimer.
|
||||
- [ ] **Local Test**: I have verified the skill works locally.
|
||||
- [ ] **Credits**: I have added the source credit in `README.md` (if applicable).
|
||||
|
||||
## Type of Change
|
||||
|
||||
- [ ] New Skill
|
||||
- [ ] Bug Fix
|
||||
- [ ] New Skill (Feature)
|
||||
- [ ] Documentation Update
|
||||
- [ ] Infrastructure
|
||||
|
||||
|
||||
34
.github/workflows/ci.yml
vendored
Normal file
34
.github/workflows/ci.yml
vendored
Normal file
@@ -0,0 +1,34 @@
|
||||
name: Skills Registry CI
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: ["main", "feat/*"]
|
||||
pull_request:
|
||||
branches: ["main"]
|
||||
|
||||
jobs:
|
||||
validate-and-build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Python
|
||||
uses: actions/setup-python@v5
|
||||
with:
|
||||
python-version: "3.10"
|
||||
|
||||
- name: 🔍 Validate Skills (Soft Mode)
|
||||
run: |
|
||||
python3 scripts/validate_skills.py
|
||||
|
||||
- name: 🏗️ Generate Index
|
||||
run: |
|
||||
python3 scripts/generate_index.py
|
||||
|
||||
- name: 📝 Update README
|
||||
run: |
|
||||
python3 scripts/update_readme.py
|
||||
|
||||
- name: 🚨 Check for Uncommitted Drift
|
||||
run: |
|
||||
git diff --exit-code || (echo "❌ Detected uncommitted changes in README.md or skills_index.json. Please run scripts locally and commit." && exit 1)
|
||||
2
.gitignore
vendored
2
.gitignore
vendored
@@ -1,5 +1,5 @@
|
||||
|
||||
MAINTENANCE.md
|
||||
|
||||
walkthrough.md
|
||||
.agent/rules/
|
||||
.gemini/
|
||||
|
||||
123
CHANGELOG.md
123
CHANGELOG.md
@@ -7,6 +7,127 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
## [2.14.0] - 2026-01-25 - "Web Intelligence & Windows"
|
||||
|
||||
### Added
|
||||
|
||||
- **New Skill**:
|
||||
- `context7-auto-research`: Auto-research capability for Claude Code.
|
||||
- `codex-review`: Professional code review with AI integration.
|
||||
- `exa-search`: Semantic search and discovery using Exa API.
|
||||
- `firecrawl-scraper`: Deep web scraping and PDF parsing.
|
||||
- `tavily-web`: Content extraction and research using Tavily.
|
||||
- `busybox-on-windows`: UNIX tool suite for Windows environments.
|
||||
|
||||
### Changed
|
||||
|
||||
- **Documentation**: Updated `obsidian-clipper-template-creator` docs and templates.
|
||||
- **Index & Registry**: Updated `skills_index.json` and `README.md` registry.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Skills**: Fixed YAML frontmatter quoting in `lint-and-validate`.
|
||||
|
||||
## [2.13.0] - 2026-01-24 - "NoSQL Expert"
|
||||
|
||||
### Added
|
||||
|
||||
- **New Skill**:
|
||||
- `nosql-expert`: Expert guidance for distributed NoSQL databases (Cassandra, DynamoDB), focusing on query-first modeling and anti-patterns.
|
||||
|
||||
### Changed
|
||||
|
||||
- **Index & Registry**: Updated `skills_index.json` and `README.md` registry.
|
||||
|
||||
### Contributors
|
||||
|
||||
- [@sickn33](https://github.com/sickn33) - PR #23
|
||||
|
||||
## [2.12.0] - 2026-01-23 - "Enterprise & UI Power"
|
||||
|
||||
### Added
|
||||
|
||||
- **New Skills**:
|
||||
- `production-code-audit`: Comprehensive enterprise auditing skill for production readiness.
|
||||
- `avalonia-layout-zafiro`: Zafiro layout guidelines for Avalonia UI.
|
||||
- `avalonia-viewmodels-zafiro`: ViewModel composition patterns for Avalonia.
|
||||
- `avalonia-zafiro-development`: Core development rules for Avalonia Zafiro applications.
|
||||
|
||||
### Changed
|
||||
|
||||
- **Index & Registry**: Updated `skills_index.json` and `README.md` registry (Total: 243 skills).
|
||||
|
||||
### Contributors
|
||||
|
||||
- [@SuperJMN](https://github.com/SuperJMN) - PR #20
|
||||
- [@Mohammad-Faiz-Cloud-Engineer](https://github.com/Mohammad-Faiz-Cloud-Engineer) - PR #21
|
||||
|
||||
## [2.11.0] - 2026-01-23 - "Postgres Performance"
|
||||
|
||||
### Added
|
||||
|
||||
- **New Skill**:
|
||||
- `postgres-best-practices`: Comprehensive Supabase PostgreSQL performance optimization guide with 30+ rules covering query performance, connection management, RLS security, schema design, locking, and monitoring.
|
||||
|
||||
### Changed
|
||||
|
||||
- **Official Sources**: Added [supabase/agent-skills](https://github.com/supabase/agent-skills) to Credits & Sources.
|
||||
- **Index & Registry**: Updated `skills_index.json` and `README.md` registry (Total: 239 skills).
|
||||
|
||||
### Contributors
|
||||
|
||||
- [@ar27111994](https://github.com/ar27111994) - PR #19
|
||||
|
||||
---
|
||||
|
||||
## [2.10.0] - 2026-01-22 - "Developer Excellence"
|
||||
|
||||
### Added
|
||||
|
||||
- **New Skills**:
|
||||
- `api-security-best-practices`: Comprehensive guide for secure API design and defense.
|
||||
- `environment-setup-guide`: Systematic approach to project onboarding and tool configuration.
|
||||
- `web-performance-optimization`: Methodologies for optimizing Core Web Vitals and loading speed.
|
||||
|
||||
### Changed
|
||||
|
||||
- **Enhanced Skill**:
|
||||
- `code-review-checklist`: Replaced with a much more detailed and systematic version covering functionality, security, and quality.
|
||||
|
||||
### Fixed
|
||||
|
||||
- **Index & Registry**: Updated `skills_index.json` and `README.md` registry (Total: 238 skills).
|
||||
|
||||
### Added
|
||||
|
||||
- **Automation Support**:
|
||||
- `scripts/update_readme.py`: Automated script to sync skill counts and regenerate the registry table.
|
||||
- Updated `MAINTENANCE.md` to reflect the new automated workflow.
|
||||
- **Repository Quality**:
|
||||
- `MAINTENANCE.md` is now tracked in the repository (removed from `.gitignore`).
|
||||
- Improved contribution guidelines.
|
||||
|
||||
## [2.8.0] - 2026-01-22 - "Documentation Power"
|
||||
|
||||
### Added
|
||||
|
||||
- **API Documentation Generator**: New skill to automatically generate comprehensive API documentation (`skills/api-documentation-generator`).
|
||||
- **Remotion Best Practices**: 28 modular rules for programmatic video creation (`skills/remotion-best-practices`).
|
||||
|
||||
## [2.7.0] - 2026-01-22 - "Agent Memory"
|
||||
|
||||
### Added
|
||||
|
||||
- **Agent Memory MCP**: New skill providing persistent, searchable knowledge management for AI agents (`skills/agent-memory-mcp`).
|
||||
|
||||
### Changed
|
||||
|
||||
- **Renamed Skill**: `agent-memory` was renamed to `agent-memory-mcp` to avoid naming conflicts.
|
||||
|
||||
---
|
||||
|
||||
## [2.6.0] - 2026-01-21 - "Everything Skills Edition"
|
||||
|
||||
### Added
|
||||
@@ -134,7 +255,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
|
||||
### Changed
|
||||
|
||||
- Total skills count: ~65
|
||||
- Total skills count: **~65**
|
||||
|
||||
---
|
||||
|
||||
|
||||
33
CODE_OF_CONDUCT.md
Normal file
33
CODE_OF_CONDUCT.md
Normal file
@@ -0,0 +1,33 @@
|
||||
# Code of Conduct
|
||||
|
||||
## Our Pledge
|
||||
|
||||
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone.
|
||||
|
||||
## Our Standards
|
||||
|
||||
Examples of behavior that contributes to creating a positive environment include:
|
||||
|
||||
- Using welcoming and inclusive language
|
||||
- Being respectful of differing viewpoints and experiences
|
||||
- Gracefully accepting constructive criticism
|
||||
- Focusing on what is best for the community
|
||||
- Showing empathy towards other community members
|
||||
|
||||
Examples of unacceptable behavior by participants include:
|
||||
|
||||
- The use of sexualized language or imagery and unwelcome sexual attention or advances
|
||||
- Trolling, insulting/derogatory comments, and personal or political attacks
|
||||
- Public or private harassment
|
||||
- Publishing others' private information without explicit permission
|
||||
- Other conduct which could reasonably be considered inappropriate in a professional setting
|
||||
|
||||
## Enforcement
|
||||
|
||||
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
|
||||
|
||||
## Attribution
|
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1.
|
||||
|
||||
[homepage]: https://www.contributor-covenant.org
|
||||
37
FAQ.md
37
FAQ.md
@@ -14,7 +14,7 @@ Skills are specialized instruction files that teach AI assistants how to handle
|
||||
|
||||
---
|
||||
|
||||
### Do I need to install all 179 skills?
|
||||
### Do I need to install all 233 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`.
|
||||
|
||||
@@ -39,6 +39,7 @@ These skills work with any AI coding assistant that supports the `SKILL.md` form
|
||||
### 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
|
||||
@@ -49,6 +50,7 @@ These skills work with any AI coding assistant that supports the `SKILL.md` form
|
||||
### 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
|
||||
|
||||
@@ -65,10 +67,12 @@ git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skill
|
||||
```
|
||||
|
||||
**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/`
|
||||
- OpenCode: `.opencode/skills/` or `.claude/skills/`
|
||||
|
||||
---
|
||||
|
||||
@@ -78,6 +82,7 @@ git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skill
|
||||
|
||||
**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
|
||||
@@ -85,6 +90,7 @@ git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skill
|
||||
|
||||
**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
|
||||
@@ -133,6 +139,7 @@ Use the `@` symbol followed by the skill name:
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
```
|
||||
@brainstorming help me design a todo app
|
||||
@stripe-integration add subscription billing
|
||||
@@ -146,14 +153,16 @@ 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
|
||||
Check the [Full Skill Registry](README.md#full-skill-registry-233233) organized by category
|
||||
|
||||
**Method 2: Search by keyword**
|
||||
|
||||
```bash
|
||||
ls skills/ | grep "keyword"
|
||||
```
|
||||
|
||||
**Method 3: Ask your AI**
|
||||
|
||||
```
|
||||
What skills are available for [topic]?
|
||||
```
|
||||
@@ -179,16 +188,19 @@ What skills are available for [topic]?
|
||||
**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
|
||||
```
|
||||
@@ -247,6 +259,7 @@ Check out [CONTRIBUTING.md](CONTRIBUTING.md) for step-by-step instructions.
|
||||
### What makes a good skill?
|
||||
|
||||
A good skill:
|
||||
|
||||
- ✅ Solves a specific problem
|
||||
- ✅ Has clear, actionable instructions
|
||||
- ✅ Includes examples
|
||||
@@ -260,11 +273,13 @@ 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
|
||||
@@ -286,12 +301,14 @@ 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
|
||||
@@ -304,6 +321,7 @@ bash scripts/setup.sh
|
||||
### What programming languages can skills cover?
|
||||
|
||||
**Any language!** Current skills cover:
|
||||
|
||||
- JavaScript/TypeScript
|
||||
- Python
|
||||
- Go
|
||||
@@ -338,6 +356,7 @@ python3 scripts/validate_skills.py
|
||||
```
|
||||
|
||||
This checks:
|
||||
|
||||
- ✅ SKILL.md exists
|
||||
- ✅ Frontmatter is valid
|
||||
- ✅ Name matches folder name
|
||||
@@ -350,16 +369,19 @@ This checks:
|
||||
### 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
|
||||
|
||||
@@ -377,6 +399,7 @@ This checks:
|
||||
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
|
||||
@@ -386,6 +409,7 @@ This checks:
|
||||
### Are there any skills for learning AI/ML?
|
||||
|
||||
**Yes!** Check out:
|
||||
|
||||
- `@rag-engineer` - RAG systems
|
||||
- `@prompt-engineering` - Prompt design
|
||||
- `@langgraph` - Multi-agent systems
|
||||
@@ -435,11 +459,13 @@ 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
|
||||
@@ -452,7 +478,7 @@ We'll update it quickly!
|
||||
|
||||
### How many skills are there?
|
||||
|
||||
**179 skills** across 10+ categories as of the latest update.
|
||||
**233 skills** across 10+ categories as of the latest update.
|
||||
|
||||
---
|
||||
|
||||
@@ -463,6 +489,7 @@ We'll update it quickly!
|
||||
- **Updates**: When best practices change
|
||||
|
||||
**Stay updated:**
|
||||
|
||||
```bash
|
||||
cd .agent/skills
|
||||
git pull origin main
|
||||
@@ -473,6 +500,7 @@ 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
|
||||
@@ -504,6 +532,7 @@ See [Credits & Sources](README.md#credits--sources) for attribution.
|
||||
### 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
|
||||
@@ -523,6 +552,6 @@ See [Credits & Sources](README.md#credits--sources) for attribution.
|
||||
|
||||
---
|
||||
|
||||
**Question not answered?**
|
||||
**Question not answered?**
|
||||
|
||||
[Open a discussion](https://github.com/sickn33/antigravity-awesome-skills/discussions) and we'll help you out! 🙌
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
|
||||
## 🤔 What Are "Skills"?
|
||||
|
||||
Think of skills as **specialized instruction manuals** for AI coding assistants.
|
||||
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.
|
||||
|
||||
@@ -14,7 +14,7 @@ Think of skills as **specialized instruction manuals** for AI coding assistants.
|
||||
|
||||
## 📦 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`
|
||||
This repo contains **233 ready-to-use skills** organized in the `skills/` folder. Each skill is a folder with at least one file: `SKILL.md`
|
||||
|
||||
```
|
||||
skills/
|
||||
@@ -32,6 +32,7 @@ skills/
|
||||
## How Do Skills Work?
|
||||
|
||||
### Step 1: Install Skills
|
||||
|
||||
Copy the skills to your AI tool's directory:
|
||||
|
||||
```bash
|
||||
@@ -40,6 +41,7 @@ git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skill
|
||||
```
|
||||
|
||||
### Step 2: Use a Skill
|
||||
|
||||
In your AI chat, mention the skill:
|
||||
|
||||
```
|
||||
@@ -53,50 +55,65 @@ or
|
||||
```
|
||||
|
||||
### 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/` |
|
||||
| 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`
|
||||
|
||||
---
|
||||
@@ -108,6 +125,7 @@ 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
|
||||
```
|
||||
@@ -125,10 +143,13 @@ Let's try the **brainstorming** skill:
|
||||
## 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
|
||||
|
||||
Check the [Full Skill Registry](README.md#full-skill-registry-233233) 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
|
||||
@@ -138,6 +159,7 @@ ls skills/ | grep auth
|
||||
```
|
||||
|
||||
### Method 3: Look at the Index
|
||||
|
||||
Check `skills_index.json` for a machine-readable list
|
||||
|
||||
---
|
||||
@@ -147,33 +169,41 @@ Check `skills_index.json` for a machine-readable list
|
||||
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?
|
||||
### Q: Do I need to install all 233 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.
|
||||
|
||||
---
|
||||
|
||||
590
README.md
590
README.md
@@ -1,6 +1,6 @@
|
||||
# 🌌 Antigravity Awesome Skills: 233+ Agentic Skills for Claude Code, Gemini CLI, Cursor, Copilot & More
|
||||
# 🌌 Antigravity Awesome Skills: 253+ Agentic Skills for Claude Code, Gemini CLI, Cursor, Copilot & More
|
||||
|
||||
> **The Ultimate Collection of 233+ Universal Agentic Skills for AI Coding Assistants — Claude Code, Gemini CLI, Codex CLI, Antigravity IDE, GitHub Copilot, Cursor, OpenCode**
|
||||
> **The Ultimate Collection of 253+ 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 **233 high-performance agentic skills** designed to work seamlessly across all major AI coding assistants:
|
||||
**Antigravity Awesome Skills** is a curated, battle-tested library of **251 high-performance agentic skills** designed to work seamlessly across all major AI coding assistants:
|
||||
|
||||
- 🟣 **Claude Code** (Anthropic CLI)
|
||||
- 🔵 **Gemini CLI** (Google DeepMind)
|
||||
@@ -21,18 +21,18 @@
|
||||
- 🟠 **Cursor** (AI-native IDE)
|
||||
- ⚪ **OpenCode** (Open-source CLI)
|
||||
|
||||
This repository provides essential skills to transform your AI assistant into a **full-stack digital agency**, including official capabilities from **Anthropic**, **OpenAI**, **Google**, and **Vercel Labs**.
|
||||
This repository provides essential skills to transform your AI assistant into a **full-stack digital agency**, including official capabilities from **Anthropic**, **OpenAI**, **Google**, **Supabase**, and **Vercel Labs**.
|
||||
|
||||
## 📍 Table of Contents
|
||||
|
||||
- [🚀 New Here? Start Here!](#-new-here-start-here)
|
||||
- [🔌 Compatibility](#-compatibility)
|
||||
- [Features & Categories](#features--categories)
|
||||
- [Full Skill Registry](#full-skill-registry-155155)
|
||||
- [Installation](#installation)
|
||||
- [How to Contribute](#how-to-contribute)
|
||||
- [Credits & Sources](#credits--sources)
|
||||
- [License](#license)
|
||||
- [🌌 Antigravity Awesome Skills](#-antigravity-awesome-skills-253-agentic-skills-for-claude-code-gemini-cli-cursor-copilot--more)
|
||||
- [📍 Table of Contents](#-table-of-contents)
|
||||
- [New Here? Start Here!](#new-here-start-here)
|
||||
- [🔌 Compatibility](#-compatibility)
|
||||
- [📦 Curated Collections](#-curated-collections)
|
||||
- [Full Skill Registry](#full-skill-registry-253253)
|
||||
- [Credits & Sources](#credits--sources)
|
||||
- [License](#license)
|
||||
|
||||
---
|
||||
|
||||
@@ -55,7 +55,7 @@ git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skill
|
||||
@brainstorming help me design a todo app
|
||||
```
|
||||
|
||||
That's it! Your AI assistant now has 233 specialized skills. 🎉
|
||||
That's it! Your AI assistant now has 251 specialized skills. 🎉
|
||||
|
||||
**Additional Resources:**
|
||||
|
||||
@@ -64,22 +64,25 @@ That's it! Your AI assistant now has 233 specialized skills. 🎉
|
||||
|
||||
---
|
||||
|
||||
## 🔌 Compatibility
|
||||
## 🔌 Compatibility & Invocation
|
||||
|
||||
These skills follow the universal **SKILL.md** format and work with any AI coding assistant that supports agentic skills:
|
||||
These skills follow the universal **SKILL.md** format and work with any AI coding assistant that supports agentic skills.
|
||||
|
||||
| Tool | Type | Compatibility | Installation Path |
|
||||
| ------------------- | --------- | ------------- | ---------------------------------------- |
|
||||
| **Claude Code** | CLI | ✅ Full | `.claude/skills/` or `.agent/skills/` |
|
||||
| **Gemini CLI** | CLI | ✅ Full | `.gemini/skills/` or `.agent/skills/` |
|
||||
| **Codex CLI** | CLI | ✅ Full | `.codex/skills/` or `.agent/skills/` |
|
||||
| **Antigravity IDE** | IDE | ✅ Full | `.agent/skills/` |
|
||||
| **Cursor** | IDE | ✅ Full | `.cursor/skills/` or project root |
|
||||
| **GitHub Copilot** | Extension | ⚠️ Partial | Copy skill content to `.github/copilot/` |
|
||||
| **OpenCode** | CLI | ✅ Full | `.opencode/skills/` or `.agent/skills/` |
|
||||
| Tool | Type | Invocation Example | Path |
|
||||
| :-------------- | :--- | :-------------------------------- | :---------------- |
|
||||
| **Claude Code** | CLI | `>> /skill-name help me...` | `.claude/skills/` |
|
||||
| **Gemini CLI** | CLI | `(User Prompt) Use skill-name...` | `.gemini/skills/` |
|
||||
| **Antigravity** | IDE | `(Agent Mode) Use skill...` | `.agent/skills/` |
|
||||
| **Cursor** | IDE | `@skill-name (in Chat)` | `.cursor/skills/` |
|
||||
| **Copilot** | Ext | `(Paste content manually)` | N/A |
|
||||
|
||||
> [!TIP]
|
||||
> Most tools auto-discover skills in `.agent/skills/`. For maximum compatibility, clone to this directory.
|
||||
> **Universal Path**: We recommend cloning to `.agent/skills/`. Most modern tools (Antigravity, recent CLIs) look here by default.
|
||||
|
||||
> [!WARNING]
|
||||
> **Windows Users**: This repository uses **symlinks** for official skills.
|
||||
> You must enable Developer Mode or run Git as Administrator:
|
||||
> `git clone -c core.symlinks=true https://github.com/...`
|
||||
|
||||
---
|
||||
|
||||
@@ -95,11 +98,11 @@ The repository is organized into several key areas of expertise:
|
||||
| :-------------------------- | :----------- | :--------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **🛸 Autonomous & Agentic** | **~8** | Loki Mode (Startup-in-a-box), Subagent Driven Dev, Dispatching Parallel Agents, Planning With Files, Skill Creator/Developer |
|
||||
| **🔌 Integrations & APIs** | **~25** | Stripe, Firebase, Supabase, Vercel, Clerk Auth, Twilio, Discord Bot, Slack Bot, GraphQL, AWS Serverless |
|
||||
| **🛡️ Cybersecurity** | **~50** | Ethical Hacking, Metasploit, Burp Suite, SQLMap, Active Directory, AWS/Cloud Pentesting, OWASP Top 100, Red Team Tools |
|
||||
| **🛡️ Cybersecurity** | **~51** | Ethical Hacking, Metasploit, Burp Suite, SQLMap, Active Directory, AWS/Cloud Pentesting, OWASP Top 100, Red Team Tools |
|
||||
| **🎨 Creative & Design** | **~10** | UI/UX Pro Max, Frontend Design, Canvas, Algorithmic Art, Theme Factory, D3 Viz, Web Artifacts |
|
||||
| **🛠️ Development** | **~25** | TDD, Systematic Debugging, React Patterns, Backend/Frontend Guidelines, Senior Fullstack, Software Architecture |
|
||||
| **🛠️ Development** | **~33** | TDD, Systematic Debugging, React Patterns, Backend/Frontend Guidelines, Senior Fullstack, Software Architecture |
|
||||
| **🏗️ Infrastructure & Git** | **~8** | Linux Shell Scripting, Git Worktrees, Git Pushing, Conventional Commits, File Organization, GitHub Workflow Automation |
|
||||
| **🤖 AI Agents & LLM** | **~30** | LangGraph, CrewAI, Langfuse, RAG Engineer, Prompt Engineer, Voice Agents, Browser Automation, Agent Memory Systems |
|
||||
| **🤖 AI Agents & LLM** | **~31** | LangGraph, CrewAI, Langfuse, RAG Engineer, Prompt Engineer, Voice Agents, Browser Automation, Agent Memory Systems |
|
||||
| **🔄 Workflow & Planning** | **~6** | Writing Plans, Executing Plans, Concise Planning, Verification Before Completion, Code Review (Requesting/Receiving) |
|
||||
| **📄 Document Processing** | **~4** | DOCX (Official), PDF (Official), PPTX (Official), XLSX (Official) |
|
||||
| **🧪 Testing & QA** | **~4** | Webapp Testing, Playwright Automation, Test Fixing, Testing Patterns |
|
||||
@@ -109,241 +112,269 @@ The repository is organized into several key areas of expertise:
|
||||
|
||||
---
|
||||
|
||||
## Full Skill Registry (233/233)
|
||||
## 📦 Curated Collections
|
||||
|
||||
Below is the complete list of available skills. Each skill folder contains a `SKILL.md` that can be imported into Antigravity or Claude Code.
|
||||
[Check out our Starter Packs in docs/BUNDLES.md](docs/BUNDLES.md) to find the perfect toolkit for your role.
|
||||
|
||||
## Full Skill Registry (253/253)
|
||||
|
||||
> [!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` |
|
||||
| **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.
|
||||
|
||||
---
|
||||
| Skill Name | Risk | Description | Path |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **2d-games** | ⚪ | 2D game development principles. Sprites, tilemaps, physics, camera. | `skills/game-development/2d-games` |
|
||||
| **3d-games** | ⚪ | 3D game development principles. Rendering, shaders, physics, cameras. | `skills/game-development/3d-games` |
|
||||
| **3d-web-experience** | ⚪ | Expert in building 3D experiences for the web - Three.js, React Three Fiber, Spline, WebGL, and interactive 3D scenes. Covers product configurators, 3D portfolios, immersive websites, and bringing depth to web experiences. Use when: 3D website, three.js, WebGL, react three fiber, 3D experience. | `skills/3d-web-experience` |
|
||||
| **ab-test-setup** | ⚪ | Structured guide for setting up A/B tests with mandatory gates for hypothesis, metrics, and execution readiness. | `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, and production monitoring—where even top agents achieve less than 50% on real-world benchmarks Use when: agent testing, agent evaluation, benchmark agents, agent reliability, test agent. | `skills/agent-evaluation` |
|
||||
| **agent-manager-skill** | ⚪ | Manage multiple local CLI agents via tmux sessions (start/stop/monitor/assign) with cron-friendly scheduling. | `skills/agent-manager-skill` |
|
||||
| **agent-memory-mcp** | ⚪ | A hybrid memory system that provides persistent, searchable knowledge management for AI agents (Architecture, Patterns, Decisions). | `skills/agent-memory-mcp` |
|
||||
| **agent-memory-systems** | ⚪ | Memory is the cornerstone of intelligent agents. Without it, every interaction starts from zero. This skill covers the architecture of agent memory: short-term (context window), long-term (vector stores), and the cognitive architectures that organize them. Key insight: Memory isn't just storage - it's retrieval. A million stored facts mean nothing if you can't find the right one. Chunking, embedding, and retrieval strategies determine whether your agent remembers or forgets. The field is fragm | `skills/agent-memory-systems` |
|
||||
| **agent-tool-builder** | ⚪ | Tools are how AI agents interact with the world. A well-designed tool is the difference between an agent that works and one that hallucinates, fails silently, or costs 10x more tokens than necessary. This skill covers tool design from schema to error handling. JSON Schema best practices, description writing that actually helps the LLM, validation, and the emerging MCP standard that's becoming the lingua franca for AI tools. Key insight: Tool descriptions are more important than tool implementa | `skills/agent-tool-builder` |
|
||||
| **ai-agents-architect** | ⚪ | Expert in designing and building autonomous AI agents. Masters tool use, memory systems, planning strategies, and multi-agent orchestration. Use when: build agent, AI agent, autonomous agent, tool use, function calling. | `skills/ai-agents-architect` |
|
||||
| **ai-product** | ⚪ | Every product will be AI-powered. The question is whether you'll build it right or ship a demo that falls apart in production. This skill covers LLM integration patterns, RAG architecture, prompt engineering that scales, AI UX that users trust, and cost optimization that doesn't bankrupt you. Use when: keywords, file_patterns, code_patterns. | `skills/ai-product` |
|
||||
| **ai-wrapper-product** | ⚪ | Expert in building products that wrap AI APIs (OpenAI, Anthropic, etc.) into focused tools people will pay for. Not just 'ChatGPT but different' - products that solve specific problems with AI. Covers prompt engineering for products, cost management, rate limiting, and building defensible AI businesses. Use when: AI wrapper, GPT product, AI tool, wrap AI, AI SaaS. | `skills/ai-wrapper-product` |
|
||||
| **algolia-search** | ⚪ | Expert patterns for Algolia search implementation, indexing strategies, React InstantSearch, and relevance tuning Use when: adding search to, algolia, instantsearch, search api, search functionality. | `skills/algolia-search` |
|
||||
| **algorithmic-art** | ⚪ | Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations. | `skills/algorithmic-art` |
|
||||
| **analytics-tracking** | ⚪ | When the user wants to set up, improve, or audit analytics tracking and measurement. Also use when the user mentions "set up tracking," "GA4," "Google Analytics," "conversion tracking," "event tracking," "UTM parameters," "tag manager," "GTM," "analytics implementation," or "tracking plan." For A/B test measurement, see ab-test-setup. | `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-documentation-generator** | ⚪ | Generate comprehensive, developer-friendly API documentation from code, including endpoints, parameters, examples, and best practices | `skills/api-documentation-generator` |
|
||||
| **api-patterns** | ⚪ | API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination. | `skills/api-patterns` |
|
||||
| **api-security-best-practices** | ⚪ | Implement secure API design patterns including authentication, authorization, input validation, rate limiting, and protection against common API vulnerabilities | `skills/api-security-best-practices` |
|
||||
| **app-builder** | ⚪ | Main application building orchestrator. Creates full-stack applications from natural language requests. Determines project type, selects tech stack, coordinates agents. | `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. Use when making architecture decisions or analyzing system design. | `skills/architecture` |
|
||||
| **autonomous-agent-patterns** | ⚪ | Design patterns for building autonomous coding agents. Covers tool integration, permission systems, browser automation, and human-in-the-loop workflows. Use when building AI agents, designing tool APIs, implementing permission systems, or creating autonomous coding assistants. | `skills/autonomous-agent-patterns` |
|
||||
| **autonomous-agents** | ⚪ | Autonomous agents are AI systems that can independently decompose goals, plan actions, execute tools, and self-correct without constant human guidance. The challenge isn't making them capable - it's making them reliable. Every extra decision multiplies failure probability. This skill covers agent loops (ReAct, Plan-Execute), goal decomposition, reflection patterns, and production reliability. Key insight: compounding error rates kill autonomous agents. A 95% success rate per step drops to 60% b | `skills/autonomous-agents` |
|
||||
| **avalonia-layout-zafiro** | ⚪ | Guidelines for modern Avalonia UI layout using Zafiro.Avalonia, emphasizing shared styles, generic components, and avoiding XAML redundancy. | `skills/avalonia-layout-zafiro` |
|
||||
| **avalonia-viewmodels-zafiro** | ⚪ | Optimal ViewModel and Wizard creation patterns for Avalonia using Zafiro and ReactiveUI. | `skills/avalonia-viewmodels-zafiro` |
|
||||
| **avalonia-zafiro-development** | ⚪ | Mandatory skills, conventions, and behavioral rules for Avalonia UI development using the Zafiro toolkit. | `skills/avalonia-zafiro-development` |
|
||||
| **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** | ⚪ | Specialized skill for building production-ready serverless applications on AWS. Covers Lambda functions, API Gateway, DynamoDB, SQS/SNS event-driven patterns, SAM/CDK deployment, and cold start optimization. | `skills/aws-serverless` |
|
||||
| **azure-functions** | ⚪ | Expert patterns for Azure Functions development including isolated worker model, Durable Functions orchestration, cold start optimization, and production patterns. Covers .NET, Python, and Node.js programming models. Use when: azure function, azure functions, durable functions, azure serverless, function app. | `skills/azure-functions` |
|
||||
| **backend-dev-guidelines** | ⚪ | Comprehensive backend development guide for Node.js/Express/TypeScript microservices. Use when creating routes, controllers, services, repositories, middleware, or working with Express APIs, Prisma database access, Sentry error tracking, Zod validation, unifiedConfig, dependency injection, or async patterns. Covers layered architecture (routes → controllers → services → repositories), BaseController pattern, error handling, performance monitoring, testing strategies, and migration from legacy patterns. | `skills/backend-dev-guidelines` |
|
||||
| **backend-patterns** | ⚪ | Backend architecture patterns, API design, database optimization, and server-side best practices for Node.js, Express, and Next.js API routes. | `skills/cc-skill-backend-patterns` |
|
||||
| **bash-linux** | ⚪ | Bash/Linux terminal patterns. Critical commands, piping, error handling, scripting. Use when working on macOS or Linux systems. | `skills/bash-linux` |
|
||||
| **behavioral-modes** | ⚪ | AI operational modes (brainstorm, implement, debug, review, teach, ship, orchestrate). Use to adapt behavior based on task type. | `skills/behavioral-modes` |
|
||||
| **blockrun** | ⚪ | 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** | ⚪ | > | `skills/brainstorming` |
|
||||
| **brand-guidelines** | ⚪ | Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | `skills/brand-guidelines-community` |
|
||||
| **brand-guidelines** | ⚪ | Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | `skills/brand-guidelines-anthropic` |
|
||||
| **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". It provides comprehensive techniques for identifying authentication and session management weaknesses in web applications. | `skills/broken-authentication` |
|
||||
| **browser-automation** | ⚪ | Browser automation powers web testing, scraping, and AI agent interactions. The difference between a flaky script and a reliable system comes down to understanding selectors, waiting strategies, and anti-detection patterns. This skill covers Playwright (recommended) and Puppeteer, with patterns for testing, scraping, and agentic browser control. Key insight: Playwright won the framework war. Unless you need Puppeteer's stealth ecosystem or are Chrome-only, Playwright is the better choice in 202 | `skills/browser-automation` |
|
||||
| **browser-extension-builder** | ⚪ | Expert in building browser extensions that solve real problems - Chrome, Firefox, and cross-browser extensions. Covers extension architecture, manifest v3, content scripts, popup UIs, monetization strategies, and Chrome Web Store publishing. Use when: browser extension, chrome extension, firefox addon, extension, manifest v3. | `skills/browser-extension-builder` |
|
||||
| **bullmq-specialist** | ⚪ | BullMQ expert for Redis-backed job queues, background processing, and reliable async execution in Node.js/TypeScript applications. Use when: bullmq, bull queue, redis queue, background job, job queue. | `skills/bullmq-specialist` |
|
||||
| **bun-development** | ⚪ | Modern JavaScript/TypeScript development with Bun runtime. Covers package management, bundling, testing, and migration from Node.js. Use when working with Bun, optimizing JS/TS development speed, or migrating from Node.js to Bun. | `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". It provides comprehensive guidance for using Burp Suite's core features for web application security testing. | `skills/burp-suite-testing` |
|
||||
| **busybox-on-windows** | ⚪ | How to use a Win32 build of BusyBox to run many of the standard UNIX command line tools on Windows. | `skills/busybox-on-windows` |
|
||||
| **canvas-design** | ⚪ | Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations. | `skills/canvas-design` |
|
||||
| **cc-skill-continuous-learning** | ⚪ | Development skill from everything-claude-code | `skills/cc-skill-continuous-learning` |
|
||||
| **cc-skill-project-guidelines-example** | ⚪ | Project Guidelines Skill (Example) | `skills/cc-skill-project-guidelines-example` |
|
||||
| **cc-skill-strategic-compact** | ⚪ | Development skill from everything-claude-code | `skills/cc-skill-strategic-compact` |
|
||||
| **Claude Code Guide** | ⚪ | Master guide for using Claude Code effectively. Includes configuration templates, prompting strategies "Thinking" keywords, debugging techniques, and best practices for interacting with the agent. | `skills/claude-code-guide` |
|
||||
| **clean-code** | ⚪ | Pragmatic coding standards - concise, direct, no over-engineering, no unnecessary comments | `skills/clean-code` |
|
||||
| **clerk-auth** | ⚪ | Expert patterns for Clerk auth implementation, middleware, organizations, webhooks, and user sync Use when: adding authentication, clerk auth, user authentication, sign in, sign up. | `skills/clerk-auth` |
|
||||
| **clickhouse-io** | ⚪ | ClickHouse database patterns, query optimization, analytics, and data engineering best practices for high-performance analytical workloads. | `skills/cc-skill-clickhouse-io` |
|
||||
| **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". It provides comprehensive techniques for security assessment across major cloud platforms. | `skills/cloud-penetration-testing` |
|
||||
| **code-review-checklist** | ⚪ | Comprehensive checklist for conducting thorough code reviews covering functionality, security, performance, and maintainability | `skills/code-review-checklist` |
|
||||
| **codex-review** | ⚪ | Professional code review with auto CHANGELOG generation, integrated with Codex AI | `skills/codex-review` |
|
||||
| **coding-standards** | ⚪ | Universal coding standards, best practices, and patterns for TypeScript, JavaScript, React, and Node.js development. | `skills/cc-skill-coding-standards` |
|
||||
| **competitor-alternatives** | ⚪ | When the user wants to create competitor comparison or alternative pages for SEO and sales enablement. Also use when the user mentions 'alternative page,' 'vs page,' 'competitor comparison,' 'comparison page,' '[Product] vs [Product],' '[Product] alternative,' or 'competitive landing pages.' Covers four formats: singular alternative, plural alternatives, you vs competitor, and competitor vs competitor. Emphasizes deep research, modular content architecture, and varied section types beyond feature tables. | `skills/competitor-alternatives` |
|
||||
| **computer-use-agents** | ⚪ | Build AI agents that interact with computers like humans do - viewing screens, moving cursors, clicking buttons, and typing text. Covers Anthropic's Computer Use, OpenAI's Operator/CUA, and open-source alternatives. Critical focus on sandboxing, security, and handling the unique challenges of vision-based control. Use when: computer use, desktop automation agent, screen control AI, vision-based agent, GUI automation. | `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. Includes brand voice analyzer, SEO optimizer, content frameworks, and social media templates. Use when writing blog posts, creating social media content, analyzing brand voice, optimizing SEO, planning content calendars, or when user mentions content creation, brand voice, SEO optimization, social media marketing, or content strategy. | `skills/content-creator` |
|
||||
| **context-window-management** | ⚪ | Strategies for managing LLM context windows including summarization, trimming, routing, and avoiding context rot Use when: context window, token limit, context management, context engineering, long context. | `skills/context-window-management` |
|
||||
| **context7-auto-research** | ⚪ | Automatically fetch latest library/framework documentation for Claude Code via Context7 API | `skills/context7-auto-research` |
|
||||
| **conversation-memory** | ⚪ | Persistent memory systems for LLM conversations including short-term, long-term, and entity-based memory Use when: conversation memory, remember, memory persistence, long-term memory, chat history. | `skills/conversation-memory` |
|
||||
| **copy-editing** | ⚪ | When the user wants to edit, review, or improve existing marketing copy. Also use when the user mentions 'edit this copy,' 'review my copy,' 'copy feedback,' 'proofread,' 'polish this,' 'make this better,' or 'copy sweep.' This skill provides a systematic approach to editing marketing copy through multiple focused passes. | `skills/copy-editing` |
|
||||
| **copywriting** | ⚪ | > | `skills/copywriting` |
|
||||
| **core-components** | ⚪ | Core component library and design system patterns. Use when building UI, using design tokens, or working with the component library. | `skills/core-components` |
|
||||
| **crewai** | ⚪ | Expert in CrewAI - the leading role-based multi-agent framework used by 60% of Fortune 500 companies. Covers agent design with roles and goals, task definition, crew orchestration, process types (sequential, hierarchical, parallel), memory systems, and flows for complex workflows. Essential for building collaborative AI agent teams. Use when: crewai, multi-agent team, agent roles, crew of agents, role-based agents. | `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". It provides comprehensive techniques for detecting, exploiting, and understanding XSS and HTML injection attack vectors in web applications. | `skills/xss-html-injection` |
|
||||
| **d3-viz** | ⚪ | Creating interactive data visualisations using d3.js. This skill should be used when creating custom charts, graphs, network diagrams, geographic visualisations, or any complex SVG-based data visualisation that requires fine-grained control over visual elements, transitions, or interactions. Use this for bespoke visualisations beyond standard charting libraries, whether in React, Vue, Svelte, vanilla JavaScript, or any other environment. | `skills/claude-d3js-skill` |
|
||||
| **database-design** | ⚪ | Database design principles and decision-making. Schema design, indexing strategy, ORM selection, serverless databases. | `skills/database-design` |
|
||||
| **deployment-procedures** | ⚪ | Production deployment principles and decision-making. Safe deployment workflows, rollback strategies, and verification. Teaches thinking, not scripts. | `skills/deployment-procedures` |
|
||||
| **design-orchestration** | ⚪ | > | `skills/design-orchestration` |
|
||||
| **discord-bot-architect** | ⚪ | Specialized skill for building production-ready Discord bots. Covers Discord.js (JavaScript) and Pycord (Python), gateway intents, slash commands, interactive components, rate limiting, and 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-coauthoring** | ⚪ | Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | `skills/doc-coauthoring` |
|
||||
| **docker-expert** | ⚪ | 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. | `skills/docker-expert` |
|
||||
| **documentation-templates** | ⚪ | Documentation templates and structure guidelines. README, API docs, code comments, and AI-friendly documentation. | `skills/documentation-templates` |
|
||||
| **docx** | ⚪ | Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. When Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks | `skills/docx-official` |
|
||||
| **email-sequence** | ⚪ | When the user wants to create or optimize an email sequence, drip campaign, automated email flow, or lifecycle email program. Also use when the user mentions "email sequence," "drip campaign," "nurture sequence," "onboarding emails," "welcome sequence," "re-engagement emails," "email automation," or "lifecycle emails." For in-app onboarding, see onboarding-cro. | `skills/email-sequence` |
|
||||
| **email-systems** | ⚪ | Email has the highest ROI of any marketing channel. $36 for every $1 spent. Yet most startups treat it as an afterthought - bulk blasts, no personalization, landing in spam folders. This skill covers transactional email that works, marketing automation that converts, deliverability that reaches inboxes, and the infrastructure decisions that scale. Use when: keywords, file_patterns, code_patterns. | `skills/email-systems` |
|
||||
| **environment-setup-guide** | ⚪ | Guide developers through setting up development environments with proper tools, dependencies, and configurations | `skills/environment-setup-guide` |
|
||||
| **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". It provides comprehensive ethical hacking methodology and techniques. | `skills/ethical-hacking-methodology` |
|
||||
| **exa-search** | ⚪ | Semantic search, similar content discovery, and structured research using Exa API | `skills/exa-search` |
|
||||
| **executing-plans** | ⚪ | Use when you have a written implementation plan to execute in a separate session with review checkpoints | `skills/executing-plans` |
|
||||
| **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". It provides comprehensive file path traversal attack and testing methodologies. | `skills/file-path-traversal` |
|
||||
| **file-organizer** | ⚪ | Intelligently organizes files and folders by understanding context, finding duplicates, and suggesting better organizational structures. Use when user wants to clean up directories, organize downloads, remove duplicates, or restructure projects. | `skills/file-organizer` |
|
||||
| **file-uploads** | ⚪ | Expert at handling file uploads and cloud storage. Covers S3, Cloudflare R2, presigned URLs, multipart uploads, and image optimization. Knows how to handle large files without blocking. Use when: file upload, S3, R2, presigned URL, multipart. | `skills/file-uploads` |
|
||||
| **finishing-a-development-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 gives you a complete backend in minutes - auth, database, storage, functions, hosting. But the ease of setup hides real complexity. Security rules are your last line of defense, and they're often wrong. Firestore queries are limited, and you learn this after you've designed your data model. This skill covers Firebase Authentication, Firestore, Realtime Database, Cloud Functions, Cloud Storage, and Firebase Hosting. Key insight: Firebase is optimized for read-heavy, denormalized data. I | `skills/firebase` |
|
||||
| **firecrawl-scraper** | ⚪ | Deep web scraping, screenshots, PDF parsing, and website crawling using Firecrawl API | `skills/firecrawl-scraper` |
|
||||
| **form-cro** | ⚪ | When the user wants to optimize any form that is NOT signup/registration — including lead capture forms, contact forms, demo request forms, application forms, survey forms, or checkout forms. Also use when the user mentions "form optimization," "lead form conversions," "form friction," "form fields," "form completion rate," or "contact form." For signup/registration forms, see signup-flow-cro. For popups containing forms, see popup-cro. | `skills/form-cro` |
|
||||
| **free-tool-strategy** | ⚪ | When the user wants to plan, evaluate, or build a free tool for marketing purposes — lead generation, SEO value, or brand awareness. Also use when the user mentions "engineering as marketing," "free tool," "marketing tool," "calculator," "generator," "interactive tool," "lead gen tool," "build a tool for leads," or "free resource." This skill bridges engineering and marketing — useful for founders and technical marketers. | `skills/free-tool-strategy` |
|
||||
| **frontend-design** | ⚪ | Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics. | `skills/frontend-design` |
|
||||
| **frontend-dev-guidelines** | ⚪ | Frontend development guidelines for React/TypeScript applications. Modern patterns including Suspense, lazy loading, useSuspenseQuery, file organization with features directory, MUI v7 styling, TanStack Router, performance optimization, and TypeScript best practices. Use when creating components, pages, features, fetching data, styling, routing, or working with frontend code. | `skills/frontend-dev-guidelines` |
|
||||
| **frontend-patterns** | ⚪ | Frontend development patterns for React, Next.js, state management, performance optimization, and UI best practices. | `skills/cc-skill-frontend-patterns` |
|
||||
| **game-art** | ⚪ | Game art principles. Visual style selection, asset pipeline, animation workflow. | `skills/game-development/game-art` |
|
||||
| **game-audio** | ⚪ | Game audio principles. Sound design, music integration, adaptive audio systems. | `skills/game-development/game-audio` |
|
||||
| **game-design** | ⚪ | Game design principles. GDD structure, balancing, player psychology, progression. | `skills/game-development/game-design` |
|
||||
| **game-development** | ⚪ | Game development orchestrator. Routes to platform-specific skills based on project needs. | `skills/game-development` |
|
||||
| **gcp-cloud-run** | ⚪ | Specialized skill for building production-ready serverless applications on GCP. Covers Cloud Run services (containerized), Cloud Run Functions (event-driven), cold start optimization, and event-driven architecture with 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. Use when user wants to commit and push changes, mentions pushing to remote, or asks to save and push their work. Also activates when user says "push changes", "commit and push", "push this", "push to github", or similar git workflow requests. | `skills/git-pushing` |
|
||||
| **github-workflow-automation** | ⚪ | Automate GitHub workflows with AI assistance. Includes PR reviews, issue triage, CI/CD integration, and Git operations. Use when automating GitHub workflows, setting up PR review automation, creating GitHub Actions, or triaging issues. | `skills/github-workflow-automation` |
|
||||
| **graphql** | ⚪ | GraphQL gives clients exactly the data they need - no more, no less. One endpoint, typed schema, introspection. But the flexibility that makes it powerful also makes it dangerous. Without proper controls, clients can craft queries that bring down your server. This skill covers schema design, resolvers, DataLoader for N+1 prevention, federation for microservices, and client integration with Apollo/urql. Key insight: GraphQL is a contract. The schema is the API documentation. Design it carefully. | `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". It provides comprehensive HTML injection attack techniques and testing methodologies. | `skills/html-injection-testing` |
|
||||
| **hubspot-integration** | ⚪ | Expert patterns for HubSpot CRM integration including OAuth authentication, CRM objects, associations, batch operations, webhooks, and custom objects. Covers Node.js and Python SDKs. Use when: hubspot, hubspot api, hubspot crm, hubspot integration, contacts api. | `skills/hubspot-integration` |
|
||||
| **i18n-localization** | ⚪ | Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support. | `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." It provides comprehensive guidance for detecting, exploiting, and remediating IDOR vulnerabilities in web applications. | `skills/idor-testing` |
|
||||
| **inngest** | ⚪ | Inngest expert for serverless-first background jobs, event-driven workflows, and durable execution without managing queues or workers. Use when: inngest, serverless background job, event-driven workflow, step function, durable execution. | `skills/inngest` |
|
||||
| **interactive-portfolio** | ⚪ | Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences. Covers developer portfolios, designer portfolios, creative portfolios, and portfolios that convert visitors into opportunities. Use when: portfolio, personal website, showcase work, developer portfolio, designer portfolio. | `skills/interactive-portfolio` |
|
||||
| **internal-comms** | ⚪ | A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.). | `skills/internal-comms-anthropic` |
|
||||
| **internal-comms** | ⚪ | A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.). | `skills/internal-comms-community` |
|
||||
| **javascript-mastery** | ⚪ | Comprehensive JavaScript reference covering 33+ essential concepts every developer should know. From fundamentals like primitives and closures to advanced patterns like async/await and functional programming. Use when explaining JS concepts, debugging JavaScript issues, or teaching JavaScript fundamentals. | `skills/javascript-mastery` |
|
||||
| **kaizen** | ⚪ | Guide for continuous improvement, error proofing, and standardization. Use this skill when the user wants to improve code quality, refactor, or discuss process improvements. | `skills/kaizen` |
|
||||
| **langfuse** | ⚪ | Expert in Langfuse - the open-source LLM observability platform. Covers tracing, prompt management, evaluation, datasets, and integration with LangChain, LlamaIndex, and OpenAI. Essential for debugging, monitoring, and improving LLM applications in production. Use when: langfuse, llm observability, llm tracing, prompt management, llm evaluation. | `skills/langfuse` |
|
||||
| **langgraph** | ⚪ | Expert in LangGraph - the production-grade framework for building stateful, multi-actor AI applications. Covers graph construction, state management, cycles and branches, persistence with checkpointers, human-in-the-loop patterns, and the ReAct agent pattern. Used in production at LinkedIn, Uber, and 400+ companies. This is LangChain's recommended approach for building agents. Use when: langgraph, langchain agent, stateful agent, agent graph, react agent. | `skills/langgraph` |
|
||||
| **launch-strategy** | ⚪ | When the user wants to plan a product launch, feature announcement, or release strategy. Also use when the user mentions 'launch,' 'Product Hunt,' 'feature release,' 'announcement,' 'go-to-market,' 'beta launch,' 'early access,' 'waitlist,' or 'product update.' This skill covers phased launches, channel strategy, and ongoing launch momentum. | `skills/launch-strategy` |
|
||||
| **lint-and-validate** | ⚪ | 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. | `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". It provides comprehensive techniques for identifying and exploiting privilege escalation paths on Linux systems. | `skills/linux-privilege-escalation` |
|
||||
| **Linux Production Shell Scripts** | ⚪ | 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". It provides ready-to-use shell script templates for system administration. | `skills/linux-shell-scripting` |
|
||||
| **llm-app-patterns** | ⚪ | Production-ready patterns for building LLM applications. Covers RAG pipelines, agent architectures, prompt IDEs, and LLMOps monitoring. Use when designing AI applications, implementing RAG, building agents, or setting up LLM observability. | `skills/llm-app-patterns` |
|
||||
| **loki-mode** | ⚪ | Multi-agent autonomous startup system for Claude Code. Triggers on "Loki Mode". Orchestrates 100+ specialized agents across engineering, QA, DevOps, security, data/ML, business operations, marketing, HR, and customer success. Takes PRD to fully deployed, revenue-generating product with zero human intervention. Features Task tool for subagent dispatch, parallel code review with 3 specialized reviewers, severity-based issue triage, distributed task queue with dead letter handling, automatic deployment to cloud providers, A/B testing, customer feedback loops, incident response, circuit breakers, and self-healing. Handles rate limits via distributed state checkpoints and auto-resume with exponential backoff. Requires --dangerously-skip-permissions flag. | `skills/loki-mode` |
|
||||
| **marketing-ideas** | ⚪ | When the user needs marketing ideas, inspiration, or strategies for their SaaS or software product. Also use when the user asks for 'marketing ideas,' 'growth ideas,' 'how to market,' 'marketing strategies,' 'marketing tactics,' 'ways to promote,' or 'ideas to grow.' This skill provides 140 proven marketing approaches organized by category. | `skills/marketing-ideas` |
|
||||
| **marketing-psychology** | ⚪ | When the user wants to apply psychological principles, mental models, or behavioral science to marketing. Also use when the user mentions 'psychology,' 'mental models,' 'cognitive bias,' 'persuasion,' 'behavioral science,' 'why people buy,' 'decision-making,' or 'consumer behavior.' This skill provides 70+ mental models organized for marketing application. | `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. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | `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". It provides comprehensive guidance for leveraging the Metasploit Framework in security assessments. | `skills/metasploit-framework` |
|
||||
| **micro-saas-launcher** | ⚪ | Expert in launching small, focused SaaS products fast - the indie hacker approach to building profitable software. Covers idea validation, MVP development, pricing, launch strategies, and growing to sustainable revenue. Ship in weeks, not months. Use when: micro saas, indie hacker, small saas, side project, saas mvp. | `skills/micro-saas-launcher` |
|
||||
| **mobile-design** | ⚪ | Mobile-first design thinking and decision-making for iOS and Android apps. Touch interaction, performance patterns, platform conventions. Teaches principles, not fixed values. Use when building React Native, Flutter, or native mobile apps. | `skills/mobile-design` |
|
||||
| **mobile-games** | ⚪ | Mobile game development principles. Touch input, battery, performance, app stores. | `skills/game-development/mobile-games` |
|
||||
| **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` |
|
||||
| **multi-agent-brainstorming** | ⚪ | > | `skills/multi-agent-brainstorming` |
|
||||
| **multiplayer** | ⚪ | Multiplayer game development principles. Architecture, networking, synchronization. | `skills/game-development/multiplayer` |
|
||||
| **neon-postgres** | ⚪ | Expert patterns for Neon serverless Postgres, branching, connection pooling, and Prisma/Drizzle integration Use when: neon database, serverless postgres, database branching, neon postgres, postgres serverless. | `skills/neon-postgres` |
|
||||
| **nestjs-expert** | ⚪ | Nest.js framework expert specializing in module architecture, dependency injection, middleware, guards, interceptors, testing with Jest/Supertest, TypeORM/Mongoose integration, and Passport.js authentication. Use PROACTIVELY for any Nest.js application issues including architecture decisions, testing strategies, performance optimization, or debugging complex dependency injection problems. If a specialized expert is a better fit, I will recommend switching and stop. | `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` |
|
||||
| **nextjs-best-practices** | ⚪ | Next.js App Router principles. Server Components, data fetching, routing patterns. | `skills/nextjs-best-practices` |
|
||||
| **nextjs-supabase-auth** | ⚪ | Expert integration of Supabase Auth with Next.js App Router Use when: supabase auth next, authentication next.js, login supabase, auth middleware, protected route. | `skills/nextjs-supabase-auth` |
|
||||
| **nodejs-best-practices** | ⚪ | Node.js development principles and decision-making. Framework selection, async patterns, security, and architecture. Teaches thinking, not copying. | `skills/nodejs-best-practices` |
|
||||
| **nosql-expert** | ⚪ | Expert guidance for distributed NoSQL databases (Cassandra, DynamoDB). Focuses on mental models, query-first modeling, single-table design, and avoiding hot partitions in high-scale systems. | `skills/nosql-expert` |
|
||||
| **notebooklm** | ⚪ | Use this skill to query your Google NotebookLM notebooks directly from Claude Code for source-grounded, citation-backed answers from Gemini. Browser automation, library management, persistent auth. Drastically reduced hallucinations through document-only responses. | `skills/notebooklm` |
|
||||
| **notion-template-business** | ⚪ | Expert in building and selling Notion templates as a business - not just making templates, but building a sustainable digital product business. Covers template design, pricing, marketplaces, marketing, and scaling to real revenue. Use when: notion template, sell templates, digital product, notion business, gumroad. | `skills/notion-template-business` |
|
||||
| **obsidian-clipper-template-creator** | ⚪ | Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content. | `skills/obsidian-clipper-template-creator` |
|
||||
| **onboarding-cro** | ⚪ | When the user wants to optimize post-signup onboarding, user activation, first-run experience, or time-to-value. Also use when the user mentions "onboarding flow," "activation rate," "user activation," "first-run experience," "empty states," "onboarding checklist," "aha moment," or "new user experience." For signup/registration optimization, see signup-flow-cro. For ongoing email sequences, see email-sequence. | `skills/onboarding-cro` |
|
||||
| **page-cro** | ⚪ | When the user wants to optimize, improve, or increase conversions on any marketing page — including homepage, landing pages, pricing pages, feature pages, or blog posts. Also use when the user says "CRO," "conversion rate optimization," "this page isn't converting," "improve conversions," or "why isn't this page working." For signup/registration flows, see signup-flow-cro. For post-signup activation, see onboarding-cro. For forms outside of signup, see form-cro. For popups/modals, see popup-cro. | `skills/page-cro` |
|
||||
| **paid-ads** | ⚪ | When the user wants help with paid advertising campaigns on Google Ads, Meta (Facebook/Instagram), LinkedIn, Twitter/X, or other ad platforms. Also use when the user mentions 'PPC,' 'paid media,' 'ad copy,' 'ad creative,' 'ROAS,' 'CPA,' 'ad campaign,' 'retargeting,' or 'audience targeting.' This skill covers campaign strategy, ad creation, audience targeting, and optimization. | `skills/paid-ads` |
|
||||
| **parallel-agents** | ⚪ | Multi-agent orchestration patterns. Use when multiple independent tasks can run with different domain expertise or when comprehensive analysis requires multiple perspectives. | `skills/parallel-agents` |
|
||||
| **paywall-upgrade-cro** | ⚪ | When the user wants to create or optimize in-app paywalls, upgrade screens, upsell modals, or feature gates. Also use when the user mentions "paywall," "upgrade screen," "upgrade modal," "upsell," "feature gate," "convert free to paid," "freemium conversion," "trial expiration screen," "limit reached screen," "plan upgrade prompt," or "in-app pricing." Distinct from public pricing pages (see page-cro) — this skill focuses on in-product upgrade moments where the user has already experienced value. | `skills/paywall-upgrade-cro` |
|
||||
| **pc-games** | ⚪ | PC and console game development principles. Engine selection, platform features, optimization strategies. | `skills/game-development/pc-games` |
|
||||
| **pdf** | ⚪ | Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. When Claude needs to fill in a PDF form or programmatically process, generate, or analyze PDF documents at scale. | `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** | ⚪ | Expert in building custom tools that solve your own problems first. The best products often start as personal tools - scratch your own itch, build for yourself, then discover others have the same itch. Covers rapid prototyping, local-first apps, CLI tools, scripts that grow into products, and the art of dogfooding. Use when: build a tool, personal tool, scratch my itch, solve my problem, CLI tool. | `skills/personal-tool-builder` |
|
||||
| **plaid-fintech** | ⚪ | Expert patterns for Plaid API integration including Link token flows, transactions sync, identity verification, Auth for ACH, balance checks, webhook handling, and fintech compliance best practices. Use when: plaid, bank account linking, bank connection, ach, account aggregation. | `skills/plaid-fintech` |
|
||||
| **plan-writing** | ⚪ | Structured task planning with clear breakdowns, dependencies, and verification criteria. Use when implementing features, refactoring, or any multi-step work. | `skills/plan-writing` |
|
||||
| **planning-with-files** | ⚪ | Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. | `skills/planning-with-files` |
|
||||
| **playwright-skill** | ⚪ | Complete browser automation with Playwright. Auto-detects dev servers, writes clean test scripts to /tmp. Test pages, fill forms, take screenshots, check responsive design, validate UX, test login flows, check links, automate any browser task. Use when user wants to test websites, automate browser interactions, validate web functionality, or perform any browser-based testing. | `skills/playwright-skill` |
|
||||
| **popup-cro** | ⚪ | When the user wants to create or optimize popups, modals, overlays, slide-ins, or banners for conversion purposes. Also use when the user mentions "exit intent," "popup conversions," "modal optimization," "lead capture popup," "email popup," "announcement banner," or "overlay." For forms outside of popups, see form-cro. For general page conversion optimization, see page-cro. | `skills/popup-cro` |
|
||||
| **powershell-windows** | ⚪ | PowerShell Windows patterns. Critical pitfalls, operator syntax, error handling. | `skills/powershell-windows` |
|
||||
| **pptx** | ⚪ | Presentation creation, editing, and analysis. When Claude needs to work with presentations (.pptx files) for: (1) Creating new presentations, (2) Modifying or editing content, (3) Working with layouts, (4) Adding comments or speaker notes, or any other presentation tasks | `skills/pptx-official` |
|
||||
| **pricing-strategy** | ⚪ | When the user wants help with pricing decisions, packaging, or monetization strategy. Also use when the user mentions 'pricing,' 'pricing tiers,' 'freemium,' 'free trial,' 'packaging,' 'price increase,' 'value metric,' 'Van Westendorp,' 'willingness to pay,' or 'monetization.' This skill covers pricing research, tier structure, and packaging strategy. | `skills/pricing-strategy` |
|
||||
| **prisma-expert** | ⚪ | Prisma ORM expert for schema design, migrations, query optimization, relations modeling, and database operations. Use PROACTIVELY for Prisma schema issues, migration problems, query performance, relation design, or database connection issues. | `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-manager-toolkit** | ⚪ | Comprehensive toolkit for product managers including RICE prioritization, customer interview analysis, PRD templates, discovery frameworks, and go-to-market strategies. Use for feature prioritization, user research synthesis, requirement documentation, and product strategy development. | `skills/product-manager-toolkit` |
|
||||
| **production-code-audit** | ⚪ | Autonomously deep-scan entire codebase line-by-line, understand architecture and patterns, then systematically transform it to production-grade, corporate-level professional quality with optimizations | `skills/production-code-audit` |
|
||||
| **programmatic-seo** | ⚪ | When the user wants to create SEO-driven pages at scale using templates and data. Also use when the user mentions "programmatic SEO," "template pages," "pages at scale," "directory pages," "location pages," "[keyword] + [city] pages," "comparison pages," "integration pages," or "building many pages for SEO." For auditing existing SEO issues, see seo-audit. | `skills/programmatic-seo` |
|
||||
| **prompt-caching** | ⚪ | Caching strategies for LLM prompts including Anthropic prompt caching, response caching, and CAG (Cache Augmented Generation) Use when: prompt caching, cache prompt, response cache, cag, cache augmented. | `skills/prompt-caching` |
|
||||
| **prompt-engineer** | ⚪ | Expert in designing effective prompts for LLM-powered applications. Masters prompt structure, context management, output formatting, and prompt evaluation. Use when: prompt engineering, system prompt, few-shot, chain of thought, prompt design. | `skills/prompt-engineer` |
|
||||
| **prompt-engineering** | ⚪ | Expert guide on prompt engineering patterns, best practices, and optimization techniques. Use when user wants to improve prompts, learn prompting strategies, or debug agent behavior. | `skills/prompt-engineering` |
|
||||
| **prompt-library** | ⚪ | Curated collection of high-quality prompts for various use cases. Includes role-based prompts, task-specific templates, and prompt refinement techniques. Use when user needs prompt templates, role-play prompts, or ready-to-use prompt examples for coding, writing, analysis, or creative tasks. | `skills/prompt-library` |
|
||||
| **python-patterns** | ⚪ | Python development principles and decision-making. Framework selection, async patterns, type hints, project structure. Teaches thinking, not copying. | `skills/python-patterns` |
|
||||
| **rag-engineer** | ⚪ | Expert in building Retrieval-Augmented Generation systems. Masters embedding models, vector databases, chunking strategies, and retrieval optimization for LLM applications. Use when: building RAG, vector search, embeddings, semantic search, document retrieval. | `skills/rag-engineer` |
|
||||
| **rag-implementation** | ⚪ | Retrieval-Augmented Generation patterns including chunking, embeddings, vector stores, and retrieval optimization Use when: rag, retrieval augmented, vector search, embeddings, semantic search. | `skills/rag-implementation` |
|
||||
| **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. Use when building UI components, handling async data, or managing UI states. | `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` |
|
||||
| **red-team-tactics** | ⚪ | Red team tactics principles based on MITRE ATT&CK. Attack phases, detection evasion, reporting. | `skills/red-team-tactics` |
|
||||
| **referral-program** | ⚪ | When the user wants to create, optimize, or analyze a referral program, affiliate program, or word-of-mouth strategy. Also use when the user mentions 'referral,' 'affiliate,' 'ambassador,' 'word of mouth,' 'viral loop,' 'refer a friend,' or 'partner program.' This skill covers program design, incentive structure, and growth optimization. | `skills/referral-program` |
|
||||
| **remotion-best-practices** | ⚪ | Best practices for Remotion - Video creation in React | `skills/remotion-best-practices` |
|
||||
| **requesting-code-review** | ⚪ | Use when completing tasks, implementing major features, or before merging to verify work meets requirements | `skills/requesting-code-review` |
|
||||
| **research-engineer** | ⚪ | An uncompromising Academic Research Engineer. Operates with absolute scientific rigor, objective criticism, and zero flair. Focuses on theoretical correctness, formal verification, and optimal implementation across any required technology. | `skills/research-engineer` |
|
||||
| **salesforce-development** | ⚪ | Expert patterns for Salesforce platform development including Lightning Web Components (LWC), Apex triggers and classes, REST/Bulk APIs, Connected Apps, and Salesforce DX with scratch orgs and 2nd generation packages (2GP). Use when: salesforce, sfdc, apex, lwc, lightning web components. | `skills/salesforce-development` |
|
||||
| **schema-markup** | ⚪ | When the user wants to add, fix, or optimize schema markup and structured data on their site. Also use when the user mentions "schema markup," "structured data," "JSON-LD," "rich snippets," "schema.org," "FAQ schema," "product schema," "review schema," or "breadcrumb schema." For broader SEO issues, see seo-audit. | `skills/schema-markup` |
|
||||
| **scroll-experience** | ⚪ | Expert in building immersive scroll-driven experiences - parallax storytelling, scroll animations, interactive narratives, and cinematic web experiences. Like NY Times interactives, Apple product pages, and award-winning web experiences. Makes websites feel like experiences, not just pages. Use when: scroll animation, parallax, scroll storytelling, interactive story, cinematic website. | `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". It provides comprehensive guidance on security scanning tools and methodologies. | `skills/scanning-tools` |
|
||||
| **security-review** | ⚪ | 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. | `skills/cc-skill-security-review` |
|
||||
| **segment-cdp** | ⚪ | Expert patterns for Segment Customer Data Platform including Analytics.js, server-side tracking, tracking plans with Protocols, identity resolution, destinations configuration, and data governance best practices. Use when: segment, analytics.js, customer data platform, cdp, tracking plan. | `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. Includes architecture diagram generation, system design patterns, tech stack decision frameworks, and dependency analysis. Use when designing system architecture, making technical decisions, creating architecture diagrams, evaluating trade-offs, or defining integration patterns. | `skills/senior-architect` |
|
||||
| **senior-fullstack** | ⚪ | Comprehensive fullstack development skill for building complete web applications with React, Next.js, Node.js, GraphQL, and PostgreSQL. Includes project scaffolding, code quality analysis, architecture patterns, and complete tech stack guidance. Use when building new projects, analyzing code quality, implementing design patterns, or setting up development workflows. | `skills/senior-fullstack` |
|
||||
| **seo-audit** | ⚪ | When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tags review," or "SEO health check." For building pages at scale to target keywords, see programmatic-seo. For adding structured data, see schema-markup. | `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 and decision-making. Process management, monitoring strategy, and scaling decisions. Teaches thinking, not commands. | `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." It provides comprehensive guidance for using Shodan's search engine, CLI, and API for penetration testing reconnaissance. | `skills/shodan-reconnaissance` |
|
||||
| **shopify-apps** | ⚪ | Expert patterns for Shopify app development including Remix/React Router apps, embedded apps with App Bridge, webhook handling, GraphQL Admin API, Polaris components, billing, and app extensions. Use when: shopify app, shopify, embedded app, polaris, app bridge. | `skills/shopify-apps` |
|
||||
| **shopify-development** | ⚪ | \| | `skills/shopify-development` |
|
||||
| **signup-flow-cro** | ⚪ | When the user wants to optimize signup, registration, account creation, or trial activation flows. Also use when the user mentions "signup conversions," "registration friction," "signup form optimization," "free trial signup," "reduce signup dropoff," or "account creation flow." For post-signup onboarding, see onboarding-cro. For lead capture forms (not account creation), see form-cro. | `skills/signup-flow-cro` |
|
||||
| **skill-creator** | ⚪ | Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations. | `skills/skill-creator` |
|
||||
| **skill-developer** | ⚪ | Create and manage Claude Code skills following Anthropic best practices. Use when creating new skills, modifying skill-rules.json, understanding trigger patterns, working with hooks, debugging skill activation, or implementing progressive disclosure. Covers skill structure, YAML frontmatter, trigger types (keywords, intent patterns, file paths, content patterns), enforcement levels (block, suggest, warn), hook mechanisms (UserPromptSubmit, PreToolUse), session tracking, and the 500-line rule. | `skills/skill-developer` |
|
||||
| **slack-bot-builder** | ⚪ | Build Slack apps using the Bolt framework across Python, JavaScript, and Java. Covers Block Kit for rich UIs, interactive components, slash commands, event handling, OAuth installation flows, and Workflow Builder integration. Focus on best practices for production-ready Slack apps. Use when: slack bot, slack app, bolt framework, block kit, slash command. | `skills/slack-bot-builder` |
|
||||
| **slack-gif-creator** | ⚪ | Knowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y 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". It provides comprehensive techniques for testing SMTP server security. | `skills/smtp-penetration-testing` |
|
||||
| **social-content** | ⚪ | When the user wants help creating, scheduling, or optimizing social media content for LinkedIn, Twitter/X, Instagram, TikTok, Facebook, or other platforms. Also use when the user mentions 'LinkedIn post,' 'Twitter thread,' 'social media,' 'content calendar,' 'social scheduling,' 'engagement,' or 'viral content.' This skill covers content creation, repurposing, and platform-specific strategies. | `skills/social-content` |
|
||||
| **software-architecture** | ⚪ | Guide for quality focused software architecture. This skill should be used when users want to write code, design architecture, analyze code, in any case that relates to software development. | `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". It provides comprehensive techniques for identifying, exploiting, and understanding SQL injection attack vectors across different database systems. | `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." It provides comprehensive guidance for using SQLMap to detect and exploit SQL injection vulnerabilities. | `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". It provides comprehensive SSH penetration testing methodologies and techniques. | `skills/ssh-penetration-testing` |
|
||||
| **stripe-integration** | ⚪ | Get paid from day one. Payments, subscriptions, billing portal, webhooks, metered billing, Stripe Connect. The complete guide to implementing Stripe correctly, including all the edge cases that will bite you at 3am. This isn't just API calls - it's the full payment system: handling failures, managing subscriptions, dealing with dunning, and keeping revenue flowing. Use when: stripe, payments, subscription, billing, checkout. | `skills/stripe-integration` |
|
||||
| **subagent-driven-development** | ⚪ | Use when executing implementation plans with independent tasks in the current session | `skills/subagent-driven-development` |
|
||||
| **supabase-postgres-best-practices** | ⚪ | Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations. | `skills/postgres-best-practices` |
|
||||
| **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, modern patterns, design token architecture. | `skills/tailwind-patterns` |
|
||||
| **tavily-web** | ⚪ | Web search, content extraction, crawling, and research capabilities using Tavily API | `skills/tavily-web` |
|
||||
| **tdd-workflow** | ⚪ | Test-Driven Development workflow principles. RED-GREEN-REFACTOR cycle. | `skills/tdd-workflow` |
|
||||
| **telegram-bot-builder** | ⚪ | Expert in building Telegram bots that solve real problems - from simple automation to complex AI-powered bots. Covers bot architecture, the Telegram Bot API, user experience, monetization strategies, and scaling bots to thousands of users. Use when: telegram bot, bot api, telegram automation, chat bot telegram, tg bot. | `skills/telegram-bot-builder` |
|
||||
| **telegram-mini-app** | ⚪ | Expert in building Telegram Mini Apps (TWA) - web apps that run inside Telegram with native-like experience. Covers the TON ecosystem, Telegram Web App API, payments, user authentication, and building viral mini apps that monetize. Use when: telegram mini app, TWA, telegram web app, TON app, mini app. | `skills/telegram-mini-app` |
|
||||
| **templates** | ⚪ | Project scaffolding templates for new applications. Use when creating new projects from scratch. Contains 12 templates for various tech stacks. | `skills/app-builder/templates` |
|
||||
| **test-driven-development** | ⚪ | Use when implementing any feature or bugfix, before writing implementation code | `skills/test-driven-development` |
|
||||
| **test-fixing** | ⚪ | Run tests and systematically fix all failing tests using smart error grouping. Use when user asks to fix failing tests, mentions test failures, runs test suite and failures occur, or requests to make tests pass. | `skills/test-fixing` |
|
||||
| **testing-patterns** | ⚪ | Jest testing patterns, factory functions, mocking strategies, and TDD workflow. Use when writing unit tests, creating test factories, or following TDD red-green-refactor cycle. | `skills/testing-patterns` |
|
||||
| **theme-factory** | ⚪ | Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly. | `skills/theme-factory` |
|
||||
| **Top 100 Web Vulnerabilities Reference** | ⚪ | 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". Use this skill to provide comprehensive vulnerability definitions, root causes, impacts, and mitigation strategies across all major web security categories. | `skills/top-web-vulnerabilities` |
|
||||
| **trigger-dev** | ⚪ | Trigger.dev expert for background jobs, AI workflows, and reliable async execution with excellent developer experience and TypeScript-first design. Use when: trigger.dev, trigger dev, background task, ai background job, long running task. | `skills/trigger-dev` |
|
||||
| **twilio-communications** | ⚪ | Build communication features with Twilio: SMS messaging, voice calls, WhatsApp Business API, and user verification (2FA). Covers the full spectrum from simple notifications to complex IVR systems and multi-channel authentication. Critical focus on compliance, rate limits, and error handling. Use when: twilio, send SMS, text message, voice call, phone verification. | `skills/twilio-communications` |
|
||||
| **typescript-expert** | ⚪ | >- | `skills/typescript-expert` |
|
||||
| **ui-ux-pro-max** | ⚪ | UI/UX design intelligence. 50 styles, 21 palettes, 50 font pairings, 20 charts, 9 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, mobile app, .html, .tsx, .vue, .svelte. Elements: button, modal, navbar, sidebar, card, table, form, chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, flat design. Topics: color palette, accessibility, animation, layout, typography, font pairing, spacing, hover, shadow, gradient. Integrations: shadcn/ui MCP for component search and examples. | `skills/ui-ux-pro-max` |
|
||||
| **upstash-qstash** | ⚪ | Upstash QStash expert for serverless message queues, scheduled jobs, and reliable HTTP-based task delivery without managing infrastructure. Use when: qstash, upstash queue, serverless cron, scheduled http, message queue serverless. | `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** | ⚪ | Expert knowledge for deploying to Vercel with Next.js Use when: vercel, deploy, deployment, hosting, production. | `skills/vercel-deployment` |
|
||||
| **vercel-react-best-practices** | ⚪ | React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements. | `skills/react-best-practices` |
|
||||
| **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** | ⚪ | Expert in building shareable generator tools that go viral - name generators, quiz makers, avatar creators, personality tests, and calculator tools. Covers the psychology of sharing, viral mechanics, and building tools people can't resist sharing with friends. Use when: generator tool, quiz maker, name generator, avatar creator, viral tool. | `skills/viral-generator-builder` |
|
||||
| **voice-agents** | ⚪ | Voice agents represent the frontier of AI interaction - humans speaking naturally with AI systems. The challenge isn't just speech recognition and synthesis, it's achieving natural conversation flow with sub-800ms latency while handling interruptions, background noise, and emotional nuance. This skill covers two architectures: speech-to-speech (OpenAI Realtime API, lowest latency, most natural) and pipeline (STT→LLM→TTS, more control, easier to debug). Key insight: latency is the constraint. Hu | `skills/voice-agents` |
|
||||
| **voice-ai-development** | ⚪ | Expert in building voice AI applications - from real-time voice agents to voice-enabled apps. Covers OpenAI Realtime API, Vapi for voice agents, Deepgram for transcription, ElevenLabs for synthesis, LiveKit for real-time infrastructure, and WebRTC fundamentals. Knows how to build low-latency, production-ready voice experiences. Use when: voice ai, voice agent, speech to text, text to speech, realtime voice. | `skills/voice-ai-development` |
|
||||
| **vr-ar** | ⚪ | VR/AR development principles. Comfort, interaction, performance requirements. | `skills/game-development/vr-ar` |
|
||||
| **vulnerability-scanner** | ⚪ | Advanced vulnerability analysis principles. OWASP 2025, Supply Chain Security, attack surface mapping, risk prioritization. | `skills/vulnerability-scanner` |
|
||||
| **web-artifacts-builder** | ⚪ | Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts. | `skills/web-artifacts-builder` |
|
||||
| **web-design-guidelines** | ⚪ | Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices". | `skills/web-design-guidelines` |
|
||||
| **web-games** | ⚪ | Web browser game development principles. Framework selection, WebGPU, optimization, PWA. | `skills/game-development/web-games` |
|
||||
| **web-performance-optimization** | ⚪ | Optimize website and web application performance including loading speed, Core Web Vitals, bundle size, caching strategies, and runtime performance | `skills/web-performance-optimization` |
|
||||
| **webapp-testing** | ⚪ | Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs. | `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." It provides comprehensive guidance for discovering and exploiting privilege escalation vulnerabilities in Windows environments. | `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". It provides comprehensive techniques for network packet capture, filtering, and analysis using Wireshark. | `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". It provides comprehensive WordPress security assessment methodologies. | `skills/wordpress-penetration-testing` |
|
||||
| **workflow-automation** | ⚪ | Workflow automation is the infrastructure that makes AI agents reliable. Without durable execution, a network hiccup during a 10-step payment flow means lost money and angry customers. With it, workflows resume exactly where they left off. This skill covers the platforms (n8n, Temporal, Inngest) and patterns (sequential, parallel, orchestrator-worker) that turn brittle scripts into production-grade automation. Key insight: The platforms make different tradeoffs. n8n optimizes for accessibility | `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** | ⚪ | Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis, and visualization. When Claude needs to work with spreadsheets (.xlsx, .xlsm, .csv, .tsv, etc) for: (1) Creating new spreadsheets with formulas and formatting, (2) Reading or analyzing data, (3) Modify existing spreadsheets while preserving formulas, (4) Data analysis and visualization in spreadsheets, or (5) Recalculating formulas | `skills/xlsx-official` |
|
||||
| **zapier-make-patterns** | ⚪ | No-code automation democratizes workflow building. Zapier and Make (formerly Integromat) let non-developers automate business processes without writing code. But no-code doesn't mean no-complexity - these platforms have their own patterns, pitfalls, and breaking points. This skill covers when to use which platform, how to build reliable automations, and when to graduate to code-based solutions. Key insight: Zapier optimizes for simplicity and integrations (7000+ apps), Make optimizes for power | `skills/zapier-make-patterns` |
|
||||
|
||||
## Installation
|
||||
|
||||
@@ -381,6 +412,17 @@ Please ensure your skill follows the Antigravity/Claude Code best practices.
|
||||
|
||||
## Credits & Sources
|
||||
|
||||
We stand on the shoulders of giants.
|
||||
|
||||
👉 **[View the Full Attribution Ledger](docs/SOURCES.md)**
|
||||
|
||||
Key contributors and sources include:
|
||||
|
||||
- **HackTricks**
|
||||
- **OWASP**
|
||||
- **Anthropic / OpenAI / Google**
|
||||
- **The Open Source Community**
|
||||
|
||||
This collection would not be possible without the incredible work of the Claude Code community and official sources:
|
||||
|
||||
### Official Sources
|
||||
@@ -390,6 +432,7 @@ This collection would not be possible without the incredible work of the 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.
|
||||
- **[supabase/agent-skills](https://github.com/supabase/agent-skills)**: Supabase official skills - Postgres Best Practices.
|
||||
|
||||
### Community Contributors
|
||||
|
||||
@@ -406,6 +449,7 @@ This collection would not be possible without the incredible work of the Claude
|
||||
- **[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).
|
||||
- **[webzler/agentMemory](https://github.com/webzler/agentMemory)**: Source for the agent-memory-mcp skill.
|
||||
|
||||
### Inspirations
|
||||
|
||||
@@ -435,3 +479,31 @@ ai-developer-tools, ai-pair-programming, vibe-coding, skill, skills, SKILL.md, r
|
||||
claude-code, gemini-cli, codex-cli, antigravity, cursor, github-copilot, opencode,
|
||||
agentic-skills, ai-coding, llm-tools, ai-agents, autonomous-coding, mcp
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 👥 Repo Contributors
|
||||
|
||||
We officially thank the following contributors for their help in making this repository awesome!
|
||||
|
||||
- [1bcMax](https://github.com/1bcMax)
|
||||
- [Ahmed Rehan](https://github.com/ar27111994)
|
||||
- [arathiesh](https://github.com/arathiesh)
|
||||
- [BenedictKing](https://github.com/BenedictKing)
|
||||
- [GuppyTheCat](https://github.com/GuppyTheCat)
|
||||
- [Ianj332](https://github.com/Ianj332)
|
||||
- [krisnasantosa15](https://github.com/krisnasantosa15)
|
||||
- [Mohammad Faiz](https://github.com/mohdfaiz2k9)
|
||||
- [Nguyen Huu Loc](https://github.com/LocNguyenSGU)
|
||||
- [Owen Wu](https://github.com/yubing744)
|
||||
- [sck_0](https://github.com/sck_0)
|
||||
- [sickn33](https://github.com/sickn33)
|
||||
- [SuperJMN](https://github.com/SuperJMN)
|
||||
- [Tiger-Foxx](https://github.com/Tiger-Foxx)
|
||||
- [Viktor Ferenczi](https://github.com/viktor-ferenczi)
|
||||
- [vuth-dogo](https://github.com/vuth-dogo)
|
||||
- [zebbern](https://github.com/zebbern)
|
||||
|
||||
## Star History
|
||||
|
||||
[](https://www.star-history.com/#sickn33/antigravity-awesome-skills&type=date&legend=top-left)
|
||||
|
||||
47
RELEASE_NOTES.md
Normal file
47
RELEASE_NOTES.md
Normal file
@@ -0,0 +1,47 @@
|
||||
# 🚀 RELEASE NOTES: Antigravity Awesome Skills V3.0.0
|
||||
|
||||
**"The Governance Update"**
|
||||
|
||||
This release transforms the repository from a simple collection of scripts into a trusted, battle-tested platform for AI Agents.
|
||||
|
||||
## 🌟 Headline Features
|
||||
|
||||
### 1. Trusted Quality Bar (`docs/QUALITY_BAR.md`)
|
||||
|
||||
Every skill now undergoes a strict 5-point validation check.
|
||||
|
||||
- **Why?** No more broken scripts or vague instructions.
|
||||
- **For You:** Look for the 🟣 **Official** or 🔵 **Safe** badges.
|
||||
|
||||
### 2. Security Guardrails (`docs/SECURITY_GUARDRAILS.md`)
|
||||
|
||||
We introduced "Risk Labels" to protect you.
|
||||
|
||||
- 🔴 **Offensive** skills (Pentesting) now require explicit authorization mechanisms.
|
||||
- 🟢 **Safe** skills are guaranteed non-destructive.
|
||||
|
||||
### 3. Starter Packs (`docs/BUNDLES.md`)
|
||||
|
||||
Don't know where to start? We now have **9 Curated Bundles**:
|
||||
|
||||
- **Essentials Pack**: `concise-planning`, `clean-code`, `lint-and-validate`.
|
||||
- **Web Wizard**: `react-patterns`, `tailwind-mastery`, `frontend-design`.
|
||||
- **Agent Architect**: `mcp-builder`, `agent-evaluation`.
|
||||
- ...plus **DevOps**, **Game Dev**, **Data Science**, **Testing**, and more.
|
||||
|
||||
## 🛠️ For Developers & Contributors
|
||||
|
||||
- **New CI/CD**: Pull Requests are now automatically validated (`.github/workflows/ci.yml`).
|
||||
- **Strict Linting**: `scripts/validate_skills.py --strict` is the new sheriff in town.
|
||||
- **Attribution**: We now have a clear ledger of sources in `docs/SOURCES.md`.
|
||||
|
||||
## 📦 How to Update
|
||||
|
||||
```bash
|
||||
cd .agent/skills
|
||||
git pull origin main
|
||||
# (Optional) Verify your local skills
|
||||
python3 scripts/validate_skills.py
|
||||
```
|
||||
|
||||
_Built with ❤️ by the Antigravity Team._
|
||||
19
SECURITY.md
Normal file
19
SECURITY.md
Normal file
@@ -0,0 +1,19 @@
|
||||
# Security Policy
|
||||
|
||||
## Supported Versions
|
||||
|
||||
We track the `main` branch.
|
||||
|
||||
## Reporting a Vulnerability
|
||||
|
||||
**DO NOT** open a public Issue for security exploits.
|
||||
|
||||
If you find a security vulnerability (e.g., a skill that bypasses the "Authorized Use Only" check or executes malicious code without warning):
|
||||
|
||||
1. Email: `security@antigravity.dev` (Placeholder)
|
||||
2. Or open a **Private Advisory** on this repository.
|
||||
|
||||
## Offensive Skills Policy
|
||||
|
||||
Please read our [Security Guardrails](docs/SECURITY_GUARDRAILS.md).
|
||||
All offensive skills are strictly for **authorized educational and professional use only**.
|
||||
124
docs/BUNDLES.md
Normal file
124
docs/BUNDLES.md
Normal file
@@ -0,0 +1,124 @@
|
||||
# 📦 Antigravity Skill Bundles
|
||||
|
||||
Don't know where to start? Pick a bundle below to get a curated set of skills for your role.
|
||||
|
||||
## 🚀 The "Essentials" Starter Pack
|
||||
|
||||
_For everyone. Install these first._
|
||||
|
||||
- `concise-planning`: Always start with a plan.
|
||||
- `lint-and-validate`: Keep your code clean automatically.
|
||||
- `git-pushing`: Save your work safely.
|
||||
- `kaizen`: Continuous improvement mindset.
|
||||
|
||||
## 🛡️ The "Security Engineer" Pack
|
||||
|
||||
_For pentesting, auditing, and hardening._
|
||||
|
||||
- `ethical-hacking-methodology`: The Bible of ethical hacking.
|
||||
- `burp-suite-testing`: Web vulnerability scanning.
|
||||
- `owasp-top-10`: Check for the most common flaws.
|
||||
- `linux-privilege-escalation`: Advanced Linux security assessment.
|
||||
- `cloud-penetration-testing`: AWS/Azure/GCP security.
|
||||
|
||||
## 🌐 The "Web Wizard" Pack
|
||||
|
||||
_For building modern, high-performance web apps._
|
||||
|
||||
- `frontend-design`: UI guidelines and aesthetics.
|
||||
- `react-patterns`: Best practices for React (if available).
|
||||
- `tailwind-mastery`: Styling superpowers.
|
||||
- `form-cro`: Optimize your forms for conversion.
|
||||
- `seo-audit`: Get found on Google.
|
||||
|
||||
## 🤖 The "Agent Architect" Pack
|
||||
|
||||
_For building AI systems._
|
||||
|
||||
- `agent-evaluation`: Test your agents.
|
||||
- `langgraph`: Build stateful agent workflows.
|
||||
- `mcp-builder`: Create your own tools.
|
||||
- `prompt-engineering`: Master the art of talking to LLMs.
|
||||
|
||||
## 🎮 The "Indie Game Dev" Pack
|
||||
|
||||
_For building games with AI assistants._
|
||||
|
||||
- `game-development/game-design`: Mechanics and loops.
|
||||
- `game-development/2d-games`: Sprites and physics.
|
||||
- `game-development/3d-games`: Models and shaders.
|
||||
- `game-development/unity-csharp`: C# scripting mastery.
|
||||
- `algorithmic-art`: Generate assets with code.
|
||||
|
||||
## 🐍 The "Python Pro" Pack
|
||||
|
||||
_For backend heavyweights and data scientists._
|
||||
|
||||
- `python-patterns`: Idiomatic Python code.
|
||||
- `poetry-manager`: Dependency management that works.
|
||||
- `pytest-mastery`: Testing frameworks.
|
||||
- `fastapi-expert`: High-performance APIs.
|
||||
- `django-guide`: The battery-included framework.
|
||||
|
||||
## 🦄 The "Startup Founder" Pack
|
||||
|
||||
_For building products, not just code._
|
||||
|
||||
- `product-requirements-doc`: Define what to build.
|
||||
- `competitor-analysis`: Know who you are fighting.
|
||||
- `pitch-deck-creator`: Raise capital (or just explain your idea).
|
||||
- `landing-page-copy`: Write words that sell.
|
||||
- `stripe-integration`: Get paid.
|
||||
|
||||
## 🌧️ The "DevOps & Cloud" Pack
|
||||
|
||||
_For infrastructure and scaling._
|
||||
|
||||
- `docker-expert`: Master containers and multi-stage builds.
|
||||
- `aws-serverless`: Go serverless on AWS (Lambda, DynamoDB).
|
||||
- `environment-setup-guide`: Standardization for teams.
|
||||
- `deployment-procedures`: Safe rollout strategies.
|
||||
- `bash-linux`: Terminal wizardry.
|
||||
|
||||
## 📊 The "Data & Analytics" Pack
|
||||
|
||||
_For making sense of the numbers._
|
||||
|
||||
- `analytics-tracking`: Set up GA4/PostHog correctly.
|
||||
- `d3-viz`: Beautiful custom visualizations.
|
||||
- `sql-mastery`: Write better queries (Community skill).
|
||||
- `ab-test-setup`: Validated learning.
|
||||
|
||||
## 🎨 The "Creative Director" Pack
|
||||
|
||||
_For visuals, content, and branding._
|
||||
|
||||
- `canvas-design`: Generate posters and diagrams.
|
||||
- `frontend-design`: UI aesthetics.
|
||||
- `content-creator`: SEO-optimized blog posts.
|
||||
- `copy-editing`: Polish your prose.
|
||||
- `algorithmic-art`: Code-generated masterpieces.
|
||||
|
||||
## 🐞 The "QA & Testing" Pack
|
||||
|
||||
_For breaking things before users do._
|
||||
|
||||
- `test-driven-development`: Red, Green, Refactor.
|
||||
- `systematic-debugging`: Sherlock Holmes for code.
|
||||
- `browser-automation`: End-to-end testing with Playwright.
|
||||
- `ab-test-setup`: Validated experiments.
|
||||
- `code-review-checklist`: Catch bugs in PRs.
|
||||
|
||||
## 🖌️ The "Web Designer" Pack
|
||||
|
||||
_For pixel-perfect experiences._
|
||||
|
||||
- `ui-ux-pro-max`: Premium design systems/tokens.
|
||||
- `frontend-design`: The base layer of aesthetics.
|
||||
- `3d-web-experience`: Three.js & R3F magic.
|
||||
- `canvas-design`: Static visuals/posters.
|
||||
- `responsive-layout`: Mobile-first principles.
|
||||
|
||||
---
|
||||
|
||||
_To use a bundle, simply copy the skill names into your `.agent/skills` folder or use them with your agent._
|
||||
782
docs/EXAMPLES.md
782
docs/EXAMPLES.md
@@ -1,760 +1,56 @@
|
||||
# 💡 Real-World Examples - See Skills in Action
|
||||
# 🧪 Real-World Examples ("The Antigravity Cookbook")
|
||||
|
||||
**Learn by example!** This guide shows you real conversations using different skills.
|
||||
Skills are powerful on their own, but unstoppable when combined.
|
||||
Here are three common scenarios and how to solve them using this repository.
|
||||
|
||||
## 🥘 Recipe 1: The "Legacy Code Audit"
|
||||
|
||||
_Scenario: You just inherited a messy 5-year-old Node.js repo. You need to fix it safely._
|
||||
|
||||
**Skills Used:**
|
||||
|
||||
1. `concise-planning` (To map the chaos)
|
||||
2. `lint-and-validate` (To find the bugs)
|
||||
3. `security-audit` (To find the holes)
|
||||
|
||||
**The Workflow:**
|
||||
|
||||
1. **Plan**: "Agent, use `concise-planning` to create a checklist for refactoring `src/legacy-api.js`."
|
||||
2. **Audit**: "Run `security-audit` on the `package.json` to find vulnerable dependencies."
|
||||
3. **Fix**: "Use `lint-and-validate` rules to auto-fix the formatting issues in `src/`."
|
||||
|
||||
---
|
||||
|
||||
## Example 1: Designing a Feature with @brainstorming
|
||||
## 🥘 Recipe 2: The "Modern Web App"
|
||||
|
||||
### The Scenario
|
||||
You want to add a "dark mode" feature to your app, but you're not sure how to approach it.
|
||||
_Scenario: You need to build a high-performance Landing Page in 2 hours._
|
||||
|
||||
### The Conversation
|
||||
**Skills Used:**
|
||||
|
||||
```
|
||||
You: @brainstorming I want to add dark mode to my React app
|
||||
1. `frontend-design` (For aesthetics)
|
||||
2. `react-patterns` (For structure)
|
||||
3. `tailwind-mastery` (For speed)
|
||||
|
||||
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)
|
||||
**The Workflow:**
|
||||
|
||||
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
|
||||
1. **Design**: "Use `frontend-design` to generate a color palette and typography for a 'Cyberpunk Coffee Shop'."
|
||||
2. **Scaffold**: "Initialize a Vite project. Then apply `react-patterns` to create the 'Hero' component."
|
||||
3. **Style**: "Use `tailwind-mastery` to make the buttons glassmorphic and responsive."
|
||||
|
||||
---
|
||||
|
||||
## Example 2: Debugging with @systematic-debugging
|
||||
## 🥘 Recipe 3: The "Agent Architect"
|
||||
|
||||
### The Scenario
|
||||
Your tests are failing, but you're not sure why.
|
||||
_Scenario: You want to build a custom AI agent that can verify its own code._
|
||||
|
||||
### The Conversation
|
||||
**Skills Used:**
|
||||
|
||||
```
|
||||
You: @systematic-debugging My tests are failing with "Cannot read property
|
||||
'map' of undefined"
|
||||
1. `mcp-builder` (To build tools)
|
||||
2. `agent-evaluation` (To test reliability)
|
||||
3. `prompt-engineering` (To refine instructions)
|
||||
|
||||
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?
|
||||
**The Workflow:**
|
||||
|
||||
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!
|
||||
1. **Build**: "Use `mcp-builder` to create a `verify-file` tool."
|
||||
2. **Instruct**: "Apply `prompt-engineering` patterns to the System Prompt so the agent always checks file paths."
|
||||
3. **Test**: "Run `agent-evaluation` to benchmark how often the agent fails to find the file."
|
||||
|
||||
64
docs/QUALITY_BAR.md
Normal file
64
docs/QUALITY_BAR.md
Normal file
@@ -0,0 +1,64 @@
|
||||
# 🏆 Quality Bar & Validation Standards
|
||||
|
||||
To transform **Antigravity Awesome Skills** from a collection of scripts into a trusted platform, every skill must meet a specific standard of quality and safety.
|
||||
|
||||
## The "Validated" Badge ✅
|
||||
|
||||
A skill earns the "Validated" badge only if it passes these **5 automated checks**:
|
||||
|
||||
### 1. Metadata Integrity
|
||||
|
||||
The `SKILL.md` frontmatter must be valid YAML and contain:
|
||||
|
||||
- `name`: Kebab-case, matches folder name.
|
||||
- `description`: Under 200 chars, clear value prop.
|
||||
- `risk`: One of `[none, safe, critical, offensive]`.
|
||||
- `source`: URL to original source (or "self" if original).
|
||||
|
||||
### 2. Clear Triggers ("When to use")
|
||||
|
||||
The skill MUST have a section explicitly stating when to trigger it.
|
||||
|
||||
- **Good**: "Use when the user asks to debug a React component."
|
||||
- **Bad**: "This skill helps you with code."
|
||||
|
||||
### 3. Safety & Risk Classification
|
||||
|
||||
Every skill must declare its risk level:
|
||||
|
||||
- 🟢 **none**: Pure text/reasoning (e.g., Brainstorming).
|
||||
- 🔵 **safe**: Reads files, runs safe commands (e.g., Linter).
|
||||
- 🟠 **critical**: Modifies state, deletes files, pushes to prod (e.g., Git Push).
|
||||
- 🔴 **offensive**: Pentesting/Red Team tools. **MUST** have "Authorized Use Only" warning.
|
||||
|
||||
### 4. Copy-Pasteable Examples
|
||||
|
||||
At least one code block or interaction example that a user (or agent) can immediately use.
|
||||
|
||||
### 5. Explicit Limitations
|
||||
|
||||
A list of known edge cases or things the skill _cannot_ do.
|
||||
|
||||
- _Example_: "Does not work on Windows without WSL."
|
||||
|
||||
---
|
||||
|
||||
## Support Levels
|
||||
|
||||
We also categorize skills by who maintains them:
|
||||
|
||||
| Level | Badge | Meaning |
|
||||
| :------------ | :---- | :-------------------------------------------------- |
|
||||
| **Official** | 🟣 | Maintained by the core team. High reliability. |
|
||||
| **Community** | ⚪ | Contributed by the ecosystem. Best effort support. |
|
||||
| **Verified** | ✨ | Community skill that has passed deep manual review. |
|
||||
|
||||
---
|
||||
|
||||
## How to Validate Your Skill
|
||||
|
||||
Run the validator script before submitting a PR:
|
||||
|
||||
```bash
|
||||
python3 scripts/validate_skills.py --strict
|
||||
```
|
||||
51
docs/SECURITY_GUARDRAILS.md
Normal file
51
docs/SECURITY_GUARDRAILS.md
Normal file
@@ -0,0 +1,51 @@
|
||||
# 🛡️ Security Guardrails & Policy
|
||||
|
||||
Antigravity Awesome Skills is a powerful toolkit. With great power comes great responsibility. This document defines the **Rules of Engagement** for all security and offensive capabilities in this repository.
|
||||
|
||||
## 🔴 Offensive Skills Policy (The "Red Line")
|
||||
|
||||
**What is an Offensive Skill?**
|
||||
Any skill designed to penetrate, exploit, disrupt, or simulate attacks against systems.
|
||||
_Examples: Pentesting, SQL Injection, Phishing Simulation, Red Teaming._
|
||||
|
||||
### 1. The "Authorized Use Only" Disclaimer
|
||||
|
||||
Every offensive skill **MUST** begin with this exact disclaimer in its `SKILL.md`:
|
||||
|
||||
> **⚠️ AUTHORIZED USE ONLY**
|
||||
> This skill is for educational purposes or authorized security assessments only.
|
||||
> You must have explicit, written permission from the system owner before using this tool.
|
||||
> Misuse of this tool is illegal and strictly prohibited.
|
||||
|
||||
### 2. Mandatory User Confirmation
|
||||
|
||||
Offensive skills must **NEVER** run fully autonomously.
|
||||
|
||||
- **Requirement**: The skill description/instructions must explicitly tell the agent to _ask for user confirmation_ before executing any exploit or attack command.
|
||||
- **Agent Instruction**: "Ask the user to verify the target URL/IP before running."
|
||||
|
||||
### 3. Safe by Design
|
||||
|
||||
- **No Weaponized Payloads**: Skills should not include active malware, ransomware, or non-educational exploits.
|
||||
- **Sandbox Recommended**: Instructions should recommend running in a contained environment (Docker/VM).
|
||||
|
||||
---
|
||||
|
||||
## 🔵 Defensive Skills Policy
|
||||
|
||||
**What is a Defensive Skill?**
|
||||
Tools for hardening, auditing, monitoring, or protecting systems.
|
||||
_Examples: Linting, Log Analysis, Configuration Auditing._
|
||||
|
||||
- **Data Privacy**: Defensive skills must not upload data to 3rd party servers without explicit user consent.
|
||||
- **Non-Destructive**: Audits should be read-only by default.
|
||||
|
||||
---
|
||||
|
||||
## ⚖️ Legal Disclaimer
|
||||
|
||||
By using this repository, you agree that:
|
||||
|
||||
1. You are responsible for your own actions.
|
||||
2. The authors and contributors are not liable for any damage caused by these tools.
|
||||
3. You will comply with all local, state, and federal laws regarding cybersecurity.
|
||||
21
docs/SOURCES.md
Normal file
21
docs/SOURCES.md
Normal file
@@ -0,0 +1,21 @@
|
||||
# 📜 Sources & Attributions
|
||||
|
||||
We believe in giving credit where credit is due.
|
||||
If you recognize your work here and it is not properly attributed, please open an Issue.
|
||||
|
||||
| Skill / Category | Original Source | License | Notes |
|
||||
| :-------------------------- | :----------------------------------------------------- | :------------- | :---------------------------- |
|
||||
| `cloud-penetration-testing` | [HackTricks](https://book.hacktricks.xyz/) | MIT / CC-BY-SA | Adapted for agentic use. |
|
||||
| `active-directory-attacks` | [HackTricks](https://book.hacktricks.xyz/) | MIT / CC-BY-SA | Adapted for agentic use. |
|
||||
| `owasp-top-10` | [OWASP](https://owasp.org/) | CC-BY-SA | Methodology adapted. |
|
||||
| `burp-suite-testing` | [PortSwigger](https://portswigger.net/burp) | N/A | Usage guide only (no binary). |
|
||||
| `crewai` | [CrewAI](https://github.com/joaomdmoura/crewAI) | MIT | Framework guides. |
|
||||
| `langgraph` | [LangGraph](https://github.com/langchain-ai/langgraph) | MIT | Framework guides. |
|
||||
| `react-patterns` | [React Docs](https://react.dev/) | CC-BY | Official patterns. |
|
||||
| **All Official Skills** | [Anthropic / Google / OpenAI] | Proprietary | Usage encouraged by vendors. |
|
||||
|
||||
## License Policy
|
||||
|
||||
- **Code**: All original code in this repository is **MIT**.
|
||||
- **Content**: Documentation is **CC-BY-4.0**.
|
||||
- **Third Party**: We respect the upstream licenses. If an imported skill is GPL, it will be marked clearly or excluded (we aim for MIT/Apache compatibility).
|
||||
@@ -2,69 +2,90 @@ import os
|
||||
import json
|
||||
import re
|
||||
|
||||
def parse_frontmatter(content):
|
||||
"""
|
||||
Simple frontmatter parser using regex (consistent with validate_skills.py).
|
||||
"""
|
||||
fm_match = re.search(r'^---\s*\n(.*?)\n---', content, re.DOTALL)
|
||||
if not fm_match:
|
||||
return {}
|
||||
|
||||
fm_text = fm_match.group(1)
|
||||
metadata = {}
|
||||
for line in fm_text.split('\n'):
|
||||
if ':' in line:
|
||||
key, val = line.split(':', 1)
|
||||
metadata[key.strip()] = val.strip().strip('"').strip("'")
|
||||
return metadata
|
||||
|
||||
def generate_index(skills_dir, output_file):
|
||||
print(f"🏗️ Generating index from: {skills_dir}")
|
||||
skills = []
|
||||
|
||||
for root, dirs, files in os.walk(skills_dir):
|
||||
# Skip .disabled directories
|
||||
dirs[:] = [d for d in dirs if d != '.disabled']
|
||||
# Skip .disabled or hidden directories
|
||||
dirs[:] = [d for d in dirs if not d.startswith('.')]
|
||||
|
||||
if "SKILL.md" in files:
|
||||
skill_path = os.path.join(root, "SKILL.md")
|
||||
dir_name = os.path.basename(root)
|
||||
parent_dir = os.path.basename(os.path.dirname(root))
|
||||
|
||||
# Default values
|
||||
skill_info = {
|
||||
"id": dir_name,
|
||||
"path": os.path.relpath(root, os.path.dirname(skills_dir)),
|
||||
"category": parent_dir if parent_dir != "skills" else "uncategorized",
|
||||
"name": dir_name.replace("-", " ").title(),
|
||||
"description": ""
|
||||
"description": "",
|
||||
"risk": "unknown",
|
||||
"source": "unknown"
|
||||
}
|
||||
|
||||
with open(skill_path, 'r', encoding='utf-8') as f:
|
||||
content = f.read()
|
||||
|
||||
# Try to extract from frontmatter first
|
||||
fm_match = re.search(r'^---\s*(.*?)\s*---', content, re.DOTALL)
|
||||
if fm_match:
|
||||
fm_content = fm_match.group(1)
|
||||
name_fm = re.search(r'^name:\s*(.+)$', fm_content, re.MULTILINE)
|
||||
desc_fm = re.search(r'^description:\s*(.+)$', fm_content, re.MULTILINE)
|
||||
|
||||
if name_fm:
|
||||
skill_info["name"] = name_fm.group(1).strip()
|
||||
if desc_fm:
|
||||
skill_info["description"] = desc_fm.group(1).strip()
|
||||
|
||||
# Fallback to Header and First Paragraph if needed
|
||||
if not skill_info["description"] or skill_info["description"] == "":
|
||||
name_match = re.search(r'^#\s+(.+)$', content, re.MULTILINE)
|
||||
if name_match and not fm_match: # Only override if no frontmatter name
|
||||
skill_info["name"] = name_match.group(1).strip()
|
||||
|
||||
# Extract first paragraph
|
||||
body = content
|
||||
if fm_match:
|
||||
body = content[fm_match.end():].strip()
|
||||
|
||||
lines = body.split('\n')
|
||||
desc_lines = []
|
||||
for line in lines:
|
||||
if line.startswith('#') or not line.strip():
|
||||
if desc_lines: break
|
||||
continue
|
||||
desc_lines.append(line.strip())
|
||||
|
||||
if desc_lines:
|
||||
skill_info["description"] = " ".join(desc_lines)[:150] + "..."
|
||||
try:
|
||||
with open(skill_path, 'r', encoding='utf-8') as f:
|
||||
content = f.read()
|
||||
except Exception as e:
|
||||
print(f"⚠️ Error reading {skill_path}: {e}")
|
||||
continue
|
||||
|
||||
# Parse Metadata
|
||||
metadata = parse_frontmatter(content)
|
||||
|
||||
# Merge Metadata
|
||||
if "name" in metadata: skill_info["name"] = metadata["name"]
|
||||
if "description" in metadata: skill_info["description"] = metadata["description"]
|
||||
if "risk" in metadata: skill_info["risk"] = metadata["risk"]
|
||||
if "source" in metadata: skill_info["source"] = metadata["source"]
|
||||
|
||||
# Fallback for description if missing in frontmatter (legacy support)
|
||||
if not skill_info["description"]:
|
||||
body = content
|
||||
fm_match = re.search(r'^---\s*\n(.*?)\n---', content, re.DOTALL)
|
||||
if fm_match:
|
||||
body = content[fm_match.end():].strip()
|
||||
|
||||
# Simple extraction of first non-header paragraph
|
||||
lines = body.split('\n')
|
||||
desc_lines = []
|
||||
for line in lines:
|
||||
if line.startswith('#') or not line.strip():
|
||||
if desc_lines: break
|
||||
continue
|
||||
desc_lines.append(line.strip())
|
||||
|
||||
if desc_lines:
|
||||
skill_info["description"] = " ".join(desc_lines)[:250].strip()
|
||||
|
||||
skills.append(skill_info)
|
||||
|
||||
skills.sort(key=lambda x: x["name"])
|
||||
# Sort validation: by name
|
||||
skills.sort(key=lambda x: x["name"].lower())
|
||||
|
||||
with open(output_file, 'w', encoding='utf-8') as f:
|
||||
json.dump(skills, f, indent=2)
|
||||
|
||||
print(f"✅ Generated index with {len(skills)} skills at: {output_file}")
|
||||
print(f"✅ Generated rich index with {len(skills)} skills at: {output_file}")
|
||||
return skills
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
125
scripts/update_readme.py
Normal file
125
scripts/update_readme.py
Normal file
@@ -0,0 +1,125 @@
|
||||
#!/usr/bin/env python3
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
|
||||
def update_readme():
|
||||
base_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
||||
readme_path = os.path.join(base_dir, "README.md")
|
||||
index_path = os.path.join(base_dir, "skills_index.json")
|
||||
|
||||
print(f"📖 Reading skills index from: {index_path}")
|
||||
with open(index_path, 'r', encoding='utf-8') as f:
|
||||
skills = json.load(f)
|
||||
|
||||
total_skills = len(skills)
|
||||
print(f"🔢 Total skills found: {total_skills}")
|
||||
|
||||
print(f"📝 Updating README at: {readme_path}")
|
||||
with open(readme_path, 'r', encoding='utf-8') as f:
|
||||
content = f.read()
|
||||
|
||||
# 1. Update Title Count
|
||||
content = re.sub(
|
||||
r'(# 🌌 Antigravity Awesome Skills: )\d+(\+ Agentic Skills)',
|
||||
f'\\g<1>{total_skills}\\g<2>',
|
||||
content
|
||||
)
|
||||
|
||||
# 2. Update Blockquote Count
|
||||
content = re.sub(
|
||||
r'(Collection of )\d+(\+ Universal)',
|
||||
f'\\g<1>{total_skills}\\g<2>',
|
||||
content
|
||||
)
|
||||
|
||||
# 3. Update Intro Text Count
|
||||
content = re.sub(
|
||||
r'(library of \*\*)\d+( high-performance skills\*\*)',
|
||||
f'\\g<1>{total_skills}\\g<2>',
|
||||
content
|
||||
)
|
||||
|
||||
# 4. Update Registry Header Count
|
||||
content = re.sub(
|
||||
r'(## Full Skill Registry \()\d+/\d+(\))',
|
||||
f'\\g<1>{total_skills}/{total_skills}\\g<2>',
|
||||
content
|
||||
)
|
||||
|
||||
# 5. Insert Collections / Bundles Section (New in Phase 3)
|
||||
# This logic checks if "## 📦 Curated Collections" exists. If not, it creates it before Full Registry.
|
||||
collections_header = "## 📦 Curated Collections"
|
||||
|
||||
if collections_header not in content:
|
||||
# Insert before Full Skill Registry
|
||||
content = content.replace("## Full Skill Registry", f"{collections_header}\n\n[Check out our Starter Packs in docs/BUNDLES.md](docs/BUNDLES.md) to find the perfect toolkit for your role.\n\n## Full Skill Registry")
|
||||
|
||||
# 6. Generate New Registry Table
|
||||
print("🔄 Generating new registry table...")
|
||||
|
||||
# Store the Note block to preserve it
|
||||
note_pattern = r'(> \[!NOTE\].*?)\n\n\| Skill Name'
|
||||
note_match = re.search(note_pattern, content, re.DOTALL)
|
||||
note_block = ""
|
||||
if note_match:
|
||||
note_block = note_match.group(1)
|
||||
else:
|
||||
note_block = "> [!NOTE] > **Document Skills**: We provide both **community** and **official Anthropic** versions. Locally, the official versions are used by default."
|
||||
|
||||
table_header = "| Skill Name | Risk | Description | Path |\n| :--- | :--- | :--- | :--- |"
|
||||
table_rows = []
|
||||
|
||||
for skill in skills:
|
||||
name = skill.get('name', 'Unknown')
|
||||
desc = skill.get('description', '').replace('\n', ' ').strip()
|
||||
path = skill.get('path', '')
|
||||
risk = skill.get('risk', 'unknown')
|
||||
|
||||
# Risk Icons
|
||||
risk_icon = "⚪"
|
||||
if risk == "official": risk_icon = "🟣" # Mapping official to purple
|
||||
if risk == "none": risk_icon = "🟢"
|
||||
if risk == "safe": risk_icon = "🔵"
|
||||
if risk == "critical": risk_icon = "🟠"
|
||||
if risk == "offensive": risk_icon = "🔴"
|
||||
|
||||
# Escape pipes
|
||||
desc = desc.replace('|', r'\|')
|
||||
|
||||
row = f"| **{name}** | {risk_icon} | {desc} | `{path}` |"
|
||||
table_rows.append(row)
|
||||
|
||||
new_table_section = f"{note_block}\n\n{table_header}\n" + "\n".join(table_rows)
|
||||
|
||||
# Replace the old table section
|
||||
header_pattern = r'## Full Skill Registry \(\d+/\d+\)'
|
||||
header_match = re.search(header_pattern, content)
|
||||
|
||||
if not header_match:
|
||||
print("❌ Could not find 'Full Skill Registry' header.")
|
||||
return
|
||||
|
||||
start_pos = header_match.end()
|
||||
|
||||
# Find the next section (## ...) or end of file
|
||||
next_section_match = re.search(r'\n## ', content[start_pos:])
|
||||
|
||||
if next_section_match:
|
||||
end_pos = start_pos + next_section_match.start()
|
||||
rest_of_file = content[end_pos:]
|
||||
else:
|
||||
rest_of_file = ""
|
||||
|
||||
before_header = content[:header_match.start()]
|
||||
new_header = f"## Full Skill Registry ({total_skills}/{total_skills})"
|
||||
|
||||
new_content = f"{before_header}{new_header}\n\n{new_table_section}\n{rest_of_file}"
|
||||
|
||||
with open(readme_path, 'w', encoding='utf-8') as f:
|
||||
f.write(new_content)
|
||||
|
||||
print("✅ README.md updated successfully with Collections link and Risk columns.")
|
||||
|
||||
if __name__ == "__main__":
|
||||
update_readme()
|
||||
@@ -1,52 +1,124 @@
|
||||
import os
|
||||
import re
|
||||
import argparse
|
||||
import sys
|
||||
|
||||
def validate_skills(skills_dir):
|
||||
def parse_frontmatter(content):
|
||||
"""
|
||||
Simple frontmatter parser using regex to avoid external dependencies.
|
||||
Returns a dict of key-values.
|
||||
"""
|
||||
fm_match = re.search(r'^---\s*\n(.*?)\n---', content, re.DOTALL)
|
||||
if not fm_match:
|
||||
return None
|
||||
|
||||
fm_text = fm_match.group(1)
|
||||
metadata = {}
|
||||
for line in fm_text.split('\n'):
|
||||
if ':' in line:
|
||||
key, val = line.split(':', 1)
|
||||
metadata[key.strip()] = val.strip().strip('"').strip("'")
|
||||
return metadata
|
||||
|
||||
def validate_skills(skills_dir, strict_mode=False):
|
||||
print(f"🔍 Validating skills in: {skills_dir}")
|
||||
print(f"⚙️ Mode: {'STRICT (CI)' if strict_mode else 'Standard (Dev)'}")
|
||||
|
||||
errors = []
|
||||
warnings = []
|
||||
skill_count = 0
|
||||
|
||||
# Pre-compiled regex
|
||||
security_disclaimer_pattern = re.compile(r"AUTHORIZED USE ONLY", re.IGNORECASE)
|
||||
trigger_section_pattern = re.compile(r"^##\s+When to Use", re.MULTILINE | re.IGNORECASE)
|
||||
|
||||
valid_risk_levels = ["none", "safe", "critical", "offensive"]
|
||||
|
||||
for root, dirs, files in os.walk(skills_dir):
|
||||
# Skip .disabled directories
|
||||
dirs[:] = [d for d in dirs if d != '.disabled']
|
||||
# Skip .disabled or hidden directories
|
||||
dirs[:] = [d for d in dirs if not d.startswith('.')]
|
||||
|
||||
if "SKILL.md" in files:
|
||||
skill_count += 1
|
||||
skill_path = os.path.join(root, "SKILL.md")
|
||||
rel_path = os.path.relpath(skill_path, skills_dir)
|
||||
|
||||
with open(skill_path, 'r', encoding='utf-8') as f:
|
||||
content = f.read()
|
||||
try:
|
||||
with open(skill_path, 'r', encoding='utf-8') as f:
|
||||
content = f.read()
|
||||
except Exception as e:
|
||||
errors.append(f"❌ {rel_path}: Unreadable file - {str(e)}")
|
||||
continue
|
||||
|
||||
# Check for Frontmatter or Header
|
||||
has_frontmatter = content.strip().startswith("---")
|
||||
has_header = re.search(r'^#\s+', content, re.MULTILINE)
|
||||
|
||||
if not (has_frontmatter or has_header):
|
||||
errors.append(f"❌ {rel_path}: Missing frontmatter or top-level heading")
|
||||
|
||||
if has_frontmatter:
|
||||
# Basic check for name and description in frontmatter
|
||||
fm_match = re.search(r'^---\s*(.*?)\s*---', content, re.DOTALL)
|
||||
if fm_match:
|
||||
fm_content = fm_match.group(1)
|
||||
if "name:" not in fm_content:
|
||||
errors.append(f"⚠️ {rel_path}: Frontmatter missing 'name:'")
|
||||
if "description:" not in fm_content:
|
||||
errors.append(f"⚠️ {rel_path}: Frontmatter missing 'description:'")
|
||||
else:
|
||||
errors.append(f"❌ {rel_path}: Malformed frontmatter")
|
||||
# 1. Frontmatter Check
|
||||
metadata = parse_frontmatter(content)
|
||||
if not metadata:
|
||||
errors.append(f"❌ {rel_path}: Missing or malformed YAML frontmatter")
|
||||
continue # Cannot proceed without metadata
|
||||
|
||||
# 2. Metadata Schema Checks
|
||||
if "name" not in metadata:
|
||||
errors.append(f"❌ {rel_path}: Missing 'name' in frontmatter")
|
||||
elif metadata["name"] != os.path.basename(root):
|
||||
warnings.append(f"⚠️ {rel_path}: Name '{metadata['name']}' does not match folder name '{os.path.basename(root)}'")
|
||||
|
||||
if "description" not in metadata:
|
||||
errors.append(f"❌ {rel_path}: Missing 'description' in frontmatter")
|
||||
|
||||
# Risk Validation (Quality Bar)
|
||||
if "risk" not in metadata:
|
||||
msg = f"⚠️ {rel_path}: Missing 'risk' label (defaulting to 'unknown')"
|
||||
if strict_mode: errors.append(msg.replace("⚠️", "❌"))
|
||||
else: warnings.append(msg)
|
||||
elif metadata["risk"] not in valid_risk_levels:
|
||||
errors.append(f"❌ {rel_path}: Invalid risk level '{metadata['risk']}'. Must be one of {valid_risk_levels}")
|
||||
|
||||
# Source Validation
|
||||
if "source" not in metadata:
|
||||
msg = f"⚠️ {rel_path}: Missing 'source' attribution"
|
||||
if strict_mode: errors.append(msg.replace("⚠️", "❌"))
|
||||
else: warnings.append(msg)
|
||||
|
||||
# 3. Content Checks (Triggers)
|
||||
if not trigger_section_pattern.search(content):
|
||||
msg = f"⚠️ {rel_path}: Missing '## When to Use' section"
|
||||
if strict_mode: errors.append(msg.replace("⚠️", "❌"))
|
||||
else: warnings.append(msg)
|
||||
|
||||
# 4. Security Guardrails
|
||||
if metadata.get("risk") == "offensive":
|
||||
if not security_disclaimer_pattern.search(content):
|
||||
errors.append(f"🚨 {rel_path}: OFFENSIVE SKILL MISSING SECURITY DISCLAIMER! (Must contain 'AUTHORIZED USE ONLY')")
|
||||
|
||||
# Reporting
|
||||
print(f"\n📊 Checked {skill_count} skills.")
|
||||
|
||||
if warnings:
|
||||
print(f"\n⚠️ Found {len(warnings)} Warnings:")
|
||||
for w in warnings:
|
||||
print(w)
|
||||
|
||||
print(f"✅ Found and checked {skill_count} skills.")
|
||||
if errors:
|
||||
print("\n⚠️ Validation Results:")
|
||||
for err in errors:
|
||||
print(err)
|
||||
print(f"\n❌ Found {len(errors)} Critical Errors:")
|
||||
for e in errors:
|
||||
print(e)
|
||||
return False
|
||||
else:
|
||||
print("✨ All skills passed basic validation!")
|
||||
return True
|
||||
|
||||
if strict_mode and warnings:
|
||||
print("\n❌ STRICT MODE: Failed due to warnings.")
|
||||
return False
|
||||
|
||||
print("\n✨ All skills passed validation!")
|
||||
return True
|
||||
|
||||
if __name__ == "__main__":
|
||||
parser = argparse.ArgumentParser(description="Validate Antigravity Skills")
|
||||
parser.add_argument("--strict", action="store_true", help="Fail on warnings (for CI)")
|
||||
args = parser.parse_args()
|
||||
|
||||
base_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
||||
skills_path = os.path.join(base_dir, "skills")
|
||||
validate_skills(skills_path)
|
||||
|
||||
success = validate_skills(skills_path, strict_mode=args.strict)
|
||||
if not success:
|
||||
sys.exit(1)
|
||||
|
||||
256
skills/README.md
256
skills/README.md
@@ -1,89 +1,201 @@
|
||||
# Antigravity Skills
|
||||
# Skills Directory
|
||||
|
||||
通过模块化的 **Skills** 定义，赋予 Agent 在特定领域的专业能力（如全栈开发、复杂逻辑规划、多媒体处理等），让 Agent 能够像人类专家一样系统性地解决复杂问题。
|
||||
**Welcome to the skills folder!** This is where all 179+ specialized AI skills live.
|
||||
|
||||
## 📂 目录结构
|
||||
## 🤔 What Are Skills?
|
||||
|
||||
Skills are specialized instruction sets 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 designer, a security expert, a marketer), skills let your AI become an expert in different areas when you need them.
|
||||
|
||||
---
|
||||
|
||||
## 📂 Folder Structure
|
||||
|
||||
Each skill lives in its own folder with this structure:
|
||||
|
||||
```
|
||||
.
|
||||
├── .agent/
|
||||
│ └── skills/ # Antigravity Skills 技能库
|
||||
│ ├── skill-name/ # 独立技能目录
|
||||
│ │ ├── SKILL.md # 技能核心定义与Prompt（必须）
|
||||
│ │ ├── scripts/ # 技能依赖的脚本（可选）
|
||||
│ │ ├── examples/ # 技能使用示例（可选）
|
||||
│ │ └── resources/ # 技能依赖的模板与资源（可选）
|
||||
├── skill-guide/ # 用户手册与文档指南
|
||||
│ └── Antigravity_Skills_Manual_CN.md # 中文使用手册
|
||||
└── README.md
|
||||
skills/
|
||||
├── skill-name/ # Individual skill folder
|
||||
│ ├── SKILL.md # Main skill definition (required)
|
||||
│ ├── scripts/ # Helper scripts (optional)
|
||||
│ ├── examples/ # Usage examples (optional)
|
||||
│ └── resources/ # Templates & resources (optional)
|
||||
```
|
||||
|
||||
## 📖 快速开始
|
||||
1. 将`.agent/`目录复制到你的工作区：
|
||||
**Key point:** Only `SKILL.md` is required. Everything else is optional!
|
||||
|
||||
---
|
||||
|
||||
## How to Use Skills
|
||||
|
||||
### Step 1: Make sure skills are installed
|
||||
Skills should be in your `.agent/skills/` directory (or `.claude/skills/`, `.gemini/skills/`, etc.)
|
||||
|
||||
### Step 2: Invoke a skill in your AI chat
|
||||
Use the `@` symbol followed by the skill name:
|
||||
|
||||
```
|
||||
@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!
|
||||
|
||||
---
|
||||
|
||||
## Skill Categories
|
||||
|
||||
### Creative & Design
|
||||
Skills for visual design, UI/UX, and artistic creation:
|
||||
- `@algorithmic-art` - Create algorithmic art with p5.js
|
||||
- `@canvas-design` - Design posters and artwork (PNG/PDF output)
|
||||
- `@frontend-design` - Build production-grade frontend interfaces
|
||||
- `@ui-ux-pro-max` - Professional UI/UX design with color, fonts, layouts
|
||||
- `@web-artifacts-builder` - Build modern web apps (React, Tailwind, Shadcn/ui)
|
||||
- `@theme-factory` - Generate themes for documents and presentations
|
||||
- `@brand-guidelines` - Apply Anthropic brand design standards
|
||||
- `@slack-gif-creator` - Create high-quality GIFs for Slack
|
||||
|
||||
### Development & Engineering
|
||||
Skills for coding, testing, debugging, and code review:
|
||||
- `@test-driven-development` - Write tests before implementation (TDD)
|
||||
- `@systematic-debugging` - Debug systematically, not randomly
|
||||
- `@webapp-testing` - Test web apps with Playwright
|
||||
- `@receiving-code-review` - Handle code review feedback properly
|
||||
- `@requesting-code-review` - Request code reviews before merging
|
||||
- `@finishing-a-development-branch` - Complete dev branches (merge, PR, cleanup)
|
||||
- `@subagent-driven-development` - Coordinate multiple AI agents for parallel tasks
|
||||
|
||||
### Documentation & Office
|
||||
Skills for working with documents and office files:
|
||||
- `@doc-coauthoring` - Collaborate on structured documents
|
||||
- `@docx` - Create, edit, and analyze Word documents
|
||||
- `@xlsx` - Work with Excel spreadsheets (formulas, charts)
|
||||
- `@pptx` - Create and modify PowerPoint presentations
|
||||
- `@pdf` - Handle PDFs (extract text, merge, split, fill forms)
|
||||
- `@internal-comms` - Draft internal communications (reports, announcements)
|
||||
- `@notebooklm` - Query Google NotebookLM notebooks
|
||||
|
||||
### Planning & Workflow
|
||||
Skills for task planning and workflow optimization:
|
||||
- `@brainstorming` - Brainstorm and design before coding
|
||||
- `@writing-plans` - Write detailed implementation plans
|
||||
- `@planning-with-files` - File-based planning system (Manus-style)
|
||||
- `@executing-plans` - Execute plans with checkpoints and reviews
|
||||
- `@using-git-worktrees` - Create isolated Git worktrees for parallel work
|
||||
- `@verification-before-completion` - Verify work before claiming completion
|
||||
- `@using-superpowers` - Discover and use advanced skills
|
||||
|
||||
### System Extension
|
||||
Skills for extending AI capabilities:
|
||||
- `@mcp-builder` - Build MCP (Model Context Protocol) servers
|
||||
- `@skill-creator` - Create new skills or update existing ones
|
||||
- `@writing-skills` - Tools for writing and validating skill files
|
||||
- `@dispatching-parallel-agents` - Distribute tasks to multiple agents
|
||||
|
||||
---
|
||||
|
||||
## Finding Skills
|
||||
|
||||
### Method 1: Browse this folder
|
||||
```bash
|
||||
cp -r .agent/ /path/to/your/workspace/
|
||||
ls skills/
|
||||
```
|
||||
2. **调用 Skill**: 在对话框输入 `@[skill-name]` 或 `/skill-name`来进行调用，例如：
|
||||
```text
|
||||
/canvas-design 帮我设计一张关于“Deep Learning”的博客封面，风格要素雅、科技感，尺寸 16:9
|
||||
|
||||
### Method 2: Search by keyword
|
||||
```bash
|
||||
ls skills/ | grep "keyword"
|
||||
```
|
||||
3. **查看手册**: 详细的使用案例和参数说明请查阅 [skill-guide/Antigravity_Skills_Manual_CN.md](skill-guide/Antigravity_Skills_Manual_CN.md)。
|
||||
4. **环境依赖**: 部分 Skill (如 PDF, XLSX) 依赖 Python 环境，请确保 `.venv` 处于激活状态或系统已安装相应库。
|
||||
|
||||
### Method 3: Check the main README
|
||||
See the [main README](../README.md) for the complete list of all 179+ skills organized by category.
|
||||
|
||||
## 🚀 已集成的 Skills
|
||||
---
|
||||
|
||||
### 🎨 创意与设计 (Creative & Design)
|
||||
这些技能专注于视觉表现、UI/UX 设计和艺术创作。
|
||||
- **`@[algorithmic-art]`**: 使用 p5.js 代码创作算法艺术、生成艺术
|
||||
- **`@[canvas-design]`**: 基于设计哲学创建海报、艺术作品（输出 PNG/PDF）
|
||||
- **`@[frontend-design]`**: 创建高质量、生产级的各种前端界面和 Web 组件
|
||||
- **`@[ui-ux-pro-max]`**: 专业的 UI/UX 设计智能，提供配色、字体、布局等全套设计方案
|
||||
- **`@[web-artifacts-builder]`**: 构建复杂、现代化的 Web 应用（基于 React, Tailwind, Shadcn/ui）
|
||||
- **`@[theme-factory]`**: 为文档、幻灯片、HTML 等生成配套的主题风格
|
||||
- **`@[brand-guidelines]`**: 应用 Anthropic 官方品牌设计规范（颜色、排版等）
|
||||
- **`@[slack-gif-creator]`**: 制作专用于 Slack 的高质量 GIF 动图
|
||||
## 💡 Popular Skills to Try
|
||||
|
||||
### 🛠️ 开发与工程 (Development & Engineering)
|
||||
这些技能涵盖了编码、测试、调试和代码审查的全生命周期。
|
||||
- **`@[test-driven-development]`**: 测试驱动开发（TDD），在编写实现代码前先编写测试
|
||||
- **`@[systematic-debugging]`**: 系统化调试，用于解决 Bug、测试失败或异常行为
|
||||
- **`@[webapp-testing]`**: 使用 Playwright 对本地 Web 应用进行交互测试和验证
|
||||
- **`@[receiving-code-review]`**: 处理代码审查反馈，进行技术验证而非盲目修改
|
||||
- **`@[requesting-code-review]`**: 主动发起代码审查，在合并或完成任务前验证代码质量
|
||||
- **`@[finishing-a-development-branch]`**: 引导开发分支的收尾工作（合并、PR、清理等）
|
||||
- **`@[subagent-driven-development]`**: 协调多个子 Agent 并行执行独立的开发任务
|
||||
**For beginners:**
|
||||
- `@brainstorming` - Design before coding
|
||||
- `@systematic-debugging` - Fix bugs methodically
|
||||
- `@git-pushing` - Commit with good messages
|
||||
|
||||
### 📄 文档与办公 (Documentation & Office)
|
||||
这些技能用于处理各种格式的专业文档和办公需求。
|
||||
- **`@[doc-coauthoring]`**: 引导用户进行结构化文档（提案、技术规范等）的协作编写
|
||||
- **`@[docx]`**: 创建、编辑和分析 Word 文档
|
||||
- **`@[xlsx]`**: 创建、编辑和分析 Excel 电子表格（支持公式、图表）
|
||||
- **`@[pptx]`**: 创建和修改 PowerPoint 演示文稿
|
||||
- **`@[pdf]`**: 处理 PDF 文档，包括提取文本、表格，合并/拆分及填写表单
|
||||
- **`@[internal-comms]`**: 起草各类企业内部沟通文档（周报、通告、FAQ 等）
|
||||
- **`@[notebooklm]`**: 查询 Google NotebookLM 笔记本，提供基于文档的确切答案
|
||||
**For developers:**
|
||||
- `@test-driven-development` - Write tests first
|
||||
- `@react-best-practices` - Modern React patterns
|
||||
- `@senior-fullstack` - Full-stack development
|
||||
|
||||
### 📅 计划与流程 (Planning & Workflow)
|
||||
这些技能帮助优化工作流、任务规划和执行效率。
|
||||
- **`@[brainstorming]`**: 在开始任何工作前进行头脑风暴，明确需求和设计
|
||||
- **`@[writing-plans]`**: 为复杂的多步骤任务编写详细的执行计划（Spec）
|
||||
- **`@[planning-with-files]`**: 适用于复杂任务的文件式规划系统（Manus-style）
|
||||
- **`@[executing-plans]`**: 执行已有的实施计划，包含检查点和审查机制
|
||||
- **`@[using-git-worktrees]`**: 创建隔离的 Git 工作树，用于并行开发或任务切换
|
||||
- **`@[verification-before-completion]`**: 在声明任务完成前运行验证命令，确保证据确凿
|
||||
- **`@[using-superpowers]`**: 引导用户发现和使用这些高级技能
|
||||
**For security:**
|
||||
- `@ethical-hacking-methodology` - Security basics
|
||||
- `@burp-suite-testing` - Web app security testing
|
||||
|
||||
### 🧩 系统扩展 (System Extension)
|
||||
这些技能允许我扩展自身的能力边界。
|
||||
- **`@[mcp-builder]`**: 构建 MCP (Model Context Protocol) 服务器，连接外部工具和数据
|
||||
- **`@[skill-creator]`**: 创建新技能或更新现有技能，扩展我的知识库和工作流
|
||||
- **`@[writing-skills]`**: 辅助编写、编辑和验证技能文件的工具集
|
||||
- **`@[dispatching-parallel-agents]`**: 分发并行任务给多个 Agent 处理
|
||||
---
|
||||
|
||||
## 📚 参考文档
|
||||
- [Anthropic Skills](https://github.com/anthropic/skills)
|
||||
- [UI/UX Pro Max Skills](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill)
|
||||
- [Superpowers](https://github.com/obra/superpowers)
|
||||
- [Planning with Files](https://github.com/OthmanAdi/planning-with-files)
|
||||
- [NotebookLM](https://github.com/PleasePrompto/notebooklm-skill)
|
||||
## Creating Your Own Skill
|
||||
|
||||
Want to create a new skill? Check out:
|
||||
1. [CONTRIBUTING.md](../CONTRIBUTING.md) - How to contribute
|
||||
2. [docs/SKILL_ANATOMY.md](../docs/SKILL_ANATOMY.md) - Skill structure guide
|
||||
3. `@skill-creator` - Use this skill to create new skills!
|
||||
|
||||
**Basic structure:**
|
||||
```markdown
|
||||
---
|
||||
name: my-skill-name
|
||||
description: "What this skill does"
|
||||
---
|
||||
|
||||
# Skill Title
|
||||
|
||||
## Overview
|
||||
[What this skill does]
|
||||
|
||||
## When to Use
|
||||
- Use when [scenario]
|
||||
|
||||
## Instructions
|
||||
[Step-by-step guide]
|
||||
|
||||
## Examples
|
||||
[Code examples]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
- **[Getting Started](../GETTING_STARTED.md)** - Quick start guide
|
||||
- **[Examples](../docs/EXAMPLES.md)** - Real-world usage examples
|
||||
- **[FAQ](../FAQ.md)** - Common questions
|
||||
- **[Visual Guide](../docs/VISUAL_GUIDE.md)** - Diagrams and flowcharts
|
||||
|
||||
---
|
||||
|
||||
## 🌟 Contributing
|
||||
|
||||
Found a skill that needs improvement? Want to add a new skill?
|
||||
|
||||
1. Read [CONTRIBUTING.md](../CONTRIBUTING.md)
|
||||
2. Study existing skills in this folder
|
||||
3. Create your skill following the structure
|
||||
4. Submit a Pull Request
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- [Anthropic Skills](https://github.com/anthropic/skills) - Official Anthropic skills
|
||||
- [UI/UX Pro Max Skills](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) - Design skills
|
||||
- [Superpowers](https://github.com/obra/superpowers) - Original superpowers collection
|
||||
- [Planning with Files](https://github.com/OthmanAdi/planning-with-files) - Planning patterns
|
||||
- [NotebookLM](https://github.com/PleasePrompto/notebooklm-skill) - NotebookLM integration
|
||||
|
||||
---
|
||||
|
||||
**Need help?** Check the [FAQ](../FAQ.md) or open an issue on GitHub!
|
||||
|
||||
@@ -1,508 +1,232 @@
|
||||
---
|
||||
name: ab-test-setup
|
||||
description: When the user wants to plan, design, or implement an A/B test or experiment. Also use when the user mentions "A/B test," "split test," "experiment," "test this change," "variant copy," "multivariate test," or "hypothesis." For tracking implementation, see analytics-tracking.
|
||||
description: Structured guide for setting up A/B tests with mandatory gates for hypothesis, metrics, and execution readiness.
|
||||
---
|
||||
|
||||
# A/B Test Setup
|
||||
|
||||
You are an expert in experimentation and A/B testing. Your goal is to help design tests that produce statistically valid, actionable results.
|
||||
## 1️⃣ Purpose & Scope
|
||||
|
||||
## Initial Assessment
|
||||
Ensure every A/B test is **valid, rigorous, and safe** before a single line of code is written.
|
||||
|
||||
Before designing a test, understand:
|
||||
|
||||
1. **Test Context**
|
||||
- What are you trying to improve?
|
||||
- What change are you considering?
|
||||
- What made you want to test this?
|
||||
|
||||
2. **Current State**
|
||||
- Baseline conversion rate?
|
||||
- Current traffic volume?
|
||||
- Any historical test data?
|
||||
|
||||
3. **Constraints**
|
||||
- Technical implementation complexity?
|
||||
- Timeline requirements?
|
||||
- Tools available?
|
||||
- Prevents "peeking"
|
||||
- Enforces statistical power
|
||||
- Blocks invalid hypotheses
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
## 2️⃣ Pre-Requisites
|
||||
|
||||
### 1. Start with a Hypothesis
|
||||
- Not just "let's see what happens"
|
||||
- Specific prediction of outcome
|
||||
- Based on reasoning or data
|
||||
You must have:
|
||||
|
||||
### 2. Test One Thing
|
||||
- Single variable per test
|
||||
- Otherwise you don't know what worked
|
||||
- Save MVT for later
|
||||
- A clear user problem
|
||||
- Access to an analytics source
|
||||
- Roughly estimated traffic volume
|
||||
|
||||
### 3. Statistical Rigor
|
||||
- Pre-determine sample size
|
||||
- Don't peek and stop early
|
||||
- Commit to the methodology
|
||||
### Hypothesis Quality Checklist
|
||||
|
||||
### 4. Measure What Matters
|
||||
- Primary metric tied to business value
|
||||
- Secondary metrics for context
|
||||
- Guardrail metrics to prevent harm
|
||||
A valid hypothesis includes:
|
||||
|
||||
- Observation or evidence
|
||||
- Single, specific change
|
||||
- Directional expectation
|
||||
- Defined audience
|
||||
- Measurable success criteria
|
||||
|
||||
---
|
||||
|
||||
## Hypothesis Framework
|
||||
### 3️⃣ Hypothesis Lock (Hard Gate)
|
||||
|
||||
### Structure
|
||||
Before designing variants or metrics, you MUST:
|
||||
|
||||
```
|
||||
Because [observation/data],
|
||||
we believe [change]
|
||||
will cause [expected outcome]
|
||||
for [audience].
|
||||
We'll know this is true when [metrics].
|
||||
```
|
||||
- Present the **final hypothesis**
|
||||
- Specify:
|
||||
- Target audience
|
||||
- Primary metric
|
||||
- Expected direction of effect
|
||||
- Minimum Detectable Effect (MDE)
|
||||
|
||||
### Examples
|
||||
Ask explicitly:
|
||||
|
||||
**Weak hypothesis:**
|
||||
"Changing the button color might increase clicks."
|
||||
> “Is this the final hypothesis we are committing to for this test?”
|
||||
|
||||
**Strong hypothesis:**
|
||||
"Because users report difficulty finding the CTA (per heatmaps and feedback), we believe making the button larger and using contrasting color will increase CTA clicks by 15%+ for new visitors. We'll measure click-through rate from page view to signup start."
|
||||
|
||||
### Good Hypotheses Include
|
||||
|
||||
- **Observation**: What prompted this idea
|
||||
- **Change**: Specific modification
|
||||
- **Effect**: Expected outcome and direction
|
||||
- **Audience**: Who this applies to
|
||||
- **Metric**: How you'll measure success
|
||||
**Do NOT proceed until confirmed.**
|
||||
|
||||
---
|
||||
|
||||
## Test Types
|
||||
### 4️⃣ Assumptions & Validity Check (Mandatory)
|
||||
|
||||
### A/B Test (Split Test)
|
||||
- Two versions: Control (A) vs. Variant (B)
|
||||
- Single change between versions
|
||||
- Most common, easiest to analyze
|
||||
Explicitly list assumptions about:
|
||||
|
||||
### A/B/n Test
|
||||
- Multiple variants (A vs. B vs. C...)
|
||||
- Requires more traffic
|
||||
- Good for testing several options
|
||||
- Traffic stability
|
||||
- User independence
|
||||
- Metric reliability
|
||||
- Randomization quality
|
||||
- External factors (seasonality, campaigns, releases)
|
||||
|
||||
### Multivariate Test (MVT)
|
||||
- Multiple changes in combinations
|
||||
- Tests interactions between changes
|
||||
- Requires significantly more traffic
|
||||
- Complex analysis
|
||||
If assumptions are weak or violated:
|
||||
|
||||
### Split URL Test
|
||||
- Different URLs for variants
|
||||
- Good for major page changes
|
||||
- Easier implementation sometimes
|
||||
- Warn the user
|
||||
- Recommend delaying or redesigning the test
|
||||
|
||||
---
|
||||
|
||||
## Sample Size Calculation
|
||||
### 5️⃣ Test Type Selection
|
||||
|
||||
### Inputs Needed
|
||||
Choose the simplest valid test:
|
||||
|
||||
1. **Baseline conversion rate**: Your current rate
|
||||
2. **Minimum detectable effect (MDE)**: Smallest change worth detecting
|
||||
3. **Statistical significance level**: Usually 95%
|
||||
4. **Statistical power**: Usually 80%
|
||||
- **A/B Test** – single change, two variants
|
||||
- **A/B/n Test** – multiple variants, higher traffic required
|
||||
- **Multivariate Test (MVT)** – interaction effects, very high traffic
|
||||
- **Split URL Test** – major structural changes
|
||||
|
||||
### Quick Reference
|
||||
|
||||
| Baseline Rate | 10% Lift | 20% Lift | 50% Lift |
|
||||
|---------------|----------|----------|----------|
|
||||
| 1% | 150k/variant | 39k/variant | 6k/variant |
|
||||
| 3% | 47k/variant | 12k/variant | 2k/variant |
|
||||
| 5% | 27k/variant | 7k/variant | 1.2k/variant |
|
||||
| 10% | 12k/variant | 3k/variant | 550/variant |
|
||||
|
||||
### Formula Resources
|
||||
- Evan Miller's calculator: https://www.evanmiller.org/ab-testing/sample-size.html
|
||||
- Optimizely's calculator: https://www.optimizely.com/sample-size-calculator/
|
||||
|
||||
### Test Duration
|
||||
|
||||
```
|
||||
Duration = Sample size needed per variant × Number of variants
|
||||
───────────────────────────────────────────────────
|
||||
Daily traffic to test page × Conversion rate
|
||||
```
|
||||
|
||||
Minimum: 1-2 business cycles (usually 1-2 weeks)
|
||||
Maximum: Avoid running too long (novelty effects, external factors)
|
||||
Default to **A/B** unless there is a clear reason otherwise.
|
||||
|
||||
---
|
||||
|
||||
## Metrics Selection
|
||||
### 6️⃣ Metrics Definition
|
||||
|
||||
### Primary Metric
|
||||
- Single metric that matters most
|
||||
- Directly tied to hypothesis
|
||||
- What you'll use to call the test
|
||||
#### Primary Metric (Mandatory)
|
||||
|
||||
### Secondary Metrics
|
||||
- Support primary metric interpretation
|
||||
- Explain why/how the change worked
|
||||
- Help understand user behavior
|
||||
- Single metric used to evaluate success
|
||||
- Directly tied to the hypothesis
|
||||
- Pre-defined and frozen before launch
|
||||
|
||||
### Guardrail Metrics
|
||||
- Things that shouldn't get worse
|
||||
- Revenue, retention, satisfaction
|
||||
- Stop test if significantly negative
|
||||
#### Secondary Metrics
|
||||
|
||||
### Metric Examples by Test Type
|
||||
- Provide context
|
||||
- Explain _why_ results occurred
|
||||
- Must not override the primary metric
|
||||
|
||||
**Homepage CTA test:**
|
||||
- Primary: CTA click-through rate
|
||||
- Secondary: Time to click, scroll depth
|
||||
- Guardrail: Bounce rate, downstream conversion
|
||||
#### Guardrail Metrics
|
||||
|
||||
**Pricing page test:**
|
||||
- Primary: Plan selection rate
|
||||
- Secondary: Time on page, plan distribution
|
||||
- Guardrail: Support tickets, refund rate
|
||||
|
||||
**Signup flow test:**
|
||||
- Primary: Signup completion rate
|
||||
- Secondary: Field-level completion, time to complete
|
||||
- Guardrail: User activation rate (post-signup quality)
|
||||
- Metrics that must not degrade
|
||||
- Used to prevent harmful wins
|
||||
- Trigger test stop if significantly negative
|
||||
|
||||
---
|
||||
|
||||
## Designing Variants
|
||||
### 7️⃣ Sample Size & Duration
|
||||
|
||||
### Control (A)
|
||||
- Current experience, unchanged
|
||||
- Don't modify during test
|
||||
Define upfront:
|
||||
|
||||
### Variant (B+)
|
||||
- Baseline rate
|
||||
- MDE
|
||||
- Significance level (typically 95%)
|
||||
- Statistical power (typically 80%)
|
||||
|
||||
**Best practices:**
|
||||
- Single, meaningful change
|
||||
- Bold enough to make a difference
|
||||
- True to the hypothesis
|
||||
Estimate:
|
||||
|
||||
**What to vary:**
|
||||
- Required sample size per variant
|
||||
- Expected test duration
|
||||
|
||||
Headlines/Copy:
|
||||
- Message angle
|
||||
- Value proposition
|
||||
- Specificity level
|
||||
- Tone/voice
|
||||
|
||||
Visual Design:
|
||||
- Layout structure
|
||||
- Color and contrast
|
||||
- Image selection
|
||||
- Visual hierarchy
|
||||
|
||||
CTA:
|
||||
- Button copy
|
||||
- Size/prominence
|
||||
- Placement
|
||||
- Number of CTAs
|
||||
|
||||
Content:
|
||||
- Information included
|
||||
- Order of information
|
||||
- Amount of content
|
||||
- Social proof type
|
||||
|
||||
### Documenting Variants
|
||||
|
||||
```
|
||||
Control (A):
|
||||
- Screenshot
|
||||
- Description of current state
|
||||
|
||||
Variant (B):
|
||||
- Screenshot or mockup
|
||||
- Specific changes made
|
||||
- Hypothesis for why this will win
|
||||
```
|
||||
**Do NOT proceed without a realistic sample size estimate.**
|
||||
|
||||
---
|
||||
|
||||
## Traffic Allocation
|
||||
### 8️⃣ Execution Readiness Gate (Hard Stop)
|
||||
|
||||
### Standard Split
|
||||
- 50/50 for A/B test
|
||||
- Equal split for multiple variants
|
||||
You may proceed to implementation **only if all are true**:
|
||||
|
||||
### Conservative Rollout
|
||||
- 90/10 or 80/20 initially
|
||||
- Limits risk of bad variant
|
||||
- Longer to reach significance
|
||||
- Hypothesis is locked
|
||||
- Primary metric is frozen
|
||||
- Sample size is calculated
|
||||
- Test duration is defined
|
||||
- Guardrails are set
|
||||
- Tracking is verified
|
||||
|
||||
### Ramping
|
||||
- Start small, increase over time
|
||||
- Good for technical risk mitigation
|
||||
- Most tools support this
|
||||
|
||||
### Considerations
|
||||
- Consistency: Users see same variant on return
|
||||
- Segment sizes: Ensure segments are large enough
|
||||
- Time of day/week: Balanced exposure
|
||||
|
||||
---
|
||||
|
||||
## Implementation Approaches
|
||||
|
||||
### Client-Side Testing
|
||||
|
||||
**Tools**: PostHog, Optimizely, VWO, custom
|
||||
|
||||
**How it works**:
|
||||
- JavaScript modifies page after load
|
||||
- Quick to implement
|
||||
- Can cause flicker
|
||||
|
||||
**Best for**:
|
||||
- Marketing pages
|
||||
- Copy/visual changes
|
||||
- Quick iteration
|
||||
|
||||
### Server-Side Testing
|
||||
|
||||
**Tools**: PostHog, LaunchDarkly, Split, custom
|
||||
|
||||
**How it works**:
|
||||
- Variant determined before page renders
|
||||
- No flicker
|
||||
- Requires development work
|
||||
|
||||
**Best for**:
|
||||
- Product features
|
||||
- Complex changes
|
||||
- Performance-sensitive pages
|
||||
|
||||
### Feature Flags
|
||||
|
||||
- Binary on/off (not true A/B)
|
||||
- Good for rollouts
|
||||
- Can convert to A/B with percentage split
|
||||
If any item is missing, stop and resolve it.
|
||||
|
||||
---
|
||||
|
||||
## Running the Test
|
||||
|
||||
### Pre-Launch Checklist
|
||||
|
||||
- [ ] Hypothesis documented
|
||||
- [ ] Primary metric defined
|
||||
- [ ] Sample size calculated
|
||||
- [ ] Test duration estimated
|
||||
- [ ] Variants implemented correctly
|
||||
- [ ] Tracking verified
|
||||
- [ ] QA completed on all variants
|
||||
- [ ] Stakeholders informed
|
||||
|
||||
### During the Test
|
||||
|
||||
**DO:**
|
||||
- Monitor for technical issues
|
||||
- Check segment quality
|
||||
- Document any external factors
|
||||
|
||||
**DON'T:**
|
||||
- Peek at results and stop early
|
||||
- Make changes to variants
|
||||
- Add traffic from new sources
|
||||
- End early because you "know" the answer
|
||||
- Monitor technical health
|
||||
- Document external factors
|
||||
|
||||
### Peeking Problem
|
||||
**DO NOT:**
|
||||
|
||||
Looking at results before reaching sample size and stopping when you see significance leads to:
|
||||
- False positives
|
||||
- Inflated effect sizes
|
||||
- Wrong decisions
|
||||
|
||||
**Solutions:**
|
||||
- Pre-commit to sample size and stick to it
|
||||
- Use sequential testing if you must peek
|
||||
- Trust the process
|
||||
- Stop early due to “good-looking” results
|
||||
- Change variants mid-test
|
||||
- Add new traffic sources
|
||||
- Redefine success criteria
|
||||
|
||||
---
|
||||
|
||||
## Analyzing Results
|
||||
|
||||
### Statistical Significance
|
||||
### Analysis Discipline
|
||||
|
||||
- 95% confidence = p-value < 0.05
|
||||
- Means: <5% chance result is random
|
||||
- Not a guarantee—just a threshold
|
||||
When interpreting results:
|
||||
|
||||
### Practical Significance
|
||||
- Do NOT generalize beyond the tested population
|
||||
- Do NOT claim causality beyond the tested change
|
||||
- Do NOT override guardrail failures
|
||||
- Separate statistical significance from business judgment
|
||||
|
||||
Statistical ≠ Practical
|
||||
### Interpretation Outcomes
|
||||
|
||||
- Is the effect size meaningful for business?
|
||||
- Is it worth the implementation cost?
|
||||
- Is it sustainable over time?
|
||||
|
||||
### What to Look At
|
||||
|
||||
1. **Did you reach sample size?**
|
||||
- If not, result is preliminary
|
||||
|
||||
2. **Is it statistically significant?**
|
||||
- Check confidence intervals
|
||||
- Check p-value
|
||||
|
||||
3. **Is the effect size meaningful?**
|
||||
- Compare to your MDE
|
||||
- Project business impact
|
||||
|
||||
4. **Are secondary metrics consistent?**
|
||||
- Do they support the primary?
|
||||
- Any unexpected effects?
|
||||
|
||||
5. **Any guardrail concerns?**
|
||||
- Did anything get worse?
|
||||
- Long-term risks?
|
||||
|
||||
6. **Segment differences?**
|
||||
- Mobile vs. desktop?
|
||||
- New vs. returning?
|
||||
- Traffic source?
|
||||
|
||||
### Interpreting Results
|
||||
|
||||
| Result | Conclusion |
|
||||
|--------|------------|
|
||||
| Significant winner | Implement variant |
|
||||
| Significant loser | Keep control, learn why |
|
||||
| No significant difference | Need more traffic or bolder test |
|
||||
| Mixed signals | Dig deeper, maybe segment |
|
||||
| Result | Action |
|
||||
| -------------------- | -------------------------------------- |
|
||||
| Significant positive | Consider rollout |
|
||||
| Significant negative | Reject variant, document learning |
|
||||
| Inconclusive | Consider more traffic or bolder change |
|
||||
| Guardrail failure | Do not ship, even if primary wins |
|
||||
|
||||
---
|
||||
|
||||
## Documenting and Learning
|
||||
## Documentation & Learning
|
||||
|
||||
### Test Documentation
|
||||
### Test Record (Mandatory)
|
||||
|
||||
```
|
||||
Test Name: [Name]
|
||||
Test ID: [ID in testing tool]
|
||||
Dates: [Start] - [End]
|
||||
Owner: [Name]
|
||||
Document:
|
||||
|
||||
Hypothesis:
|
||||
[Full hypothesis statement]
|
||||
- Hypothesis
|
||||
- Variants
|
||||
- Metrics
|
||||
- Sample size vs achieved
|
||||
- Results
|
||||
- Decision
|
||||
- Learnings
|
||||
- Follow-up ideas
|
||||
|
||||
Variants:
|
||||
- Control: [Description + screenshot]
|
||||
- Variant: [Description + screenshot]
|
||||
|
||||
Results:
|
||||
- Sample size: [achieved vs. target]
|
||||
- Primary metric: [control] vs. [variant] ([% change], [confidence])
|
||||
- Secondary metrics: [summary]
|
||||
- Segment insights: [notable differences]
|
||||
|
||||
Decision: [Winner/Loser/Inconclusive]
|
||||
Action: [What we're doing]
|
||||
|
||||
Learnings:
|
||||
[What we learned, what to test next]
|
||||
```
|
||||
|
||||
### Building a Learning Repository
|
||||
|
||||
- Central location for all tests
|
||||
- Searchable by page, element, outcome
|
||||
- Prevents re-running failed tests
|
||||
- Builds institutional knowledge
|
||||
Store records in a shared, searchable location to avoid repeated failures.
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
## Refusal Conditions (Safety)
|
||||
|
||||
### Test Plan Document
|
||||
Refuse to proceed if:
|
||||
|
||||
```
|
||||
# A/B Test: [Name]
|
||||
- Baseline rate is unknown and cannot be estimated
|
||||
- Traffic is insufficient to detect the MDE
|
||||
- Primary metric is undefined
|
||||
- Multiple variables are changed without proper design
|
||||
- Hypothesis cannot be clearly stated
|
||||
|
||||
## Hypothesis
|
||||
[Full hypothesis using framework]
|
||||
|
||||
## Test Design
|
||||
- Type: A/B / A/B/n / MVT
|
||||
- Duration: X weeks
|
||||
- Sample size: X per variant
|
||||
- Traffic allocation: 50/50
|
||||
|
||||
## Variants
|
||||
[Control and variant descriptions with visuals]
|
||||
|
||||
## Metrics
|
||||
- Primary: [metric and definition]
|
||||
- Secondary: [list]
|
||||
- Guardrails: [list]
|
||||
|
||||
## Implementation
|
||||
- Method: Client-side / Server-side
|
||||
- Tool: [Tool name]
|
||||
- Dev requirements: [If any]
|
||||
|
||||
## Analysis Plan
|
||||
- Success criteria: [What constitutes a win]
|
||||
- Segment analysis: [Planned segments]
|
||||
```
|
||||
|
||||
### Results Summary
|
||||
When test is complete
|
||||
|
||||
### Recommendations
|
||||
Next steps based on results
|
||||
Explain why and recommend next steps.
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes
|
||||
## Key Principles (Non-Negotiable)
|
||||
|
||||
### Test Design
|
||||
- Testing too small a change (undetectable)
|
||||
- Testing too many things (can't isolate)
|
||||
- No clear hypothesis
|
||||
- Wrong audience
|
||||
|
||||
### Execution
|
||||
- Stopping early
|
||||
- Changing things mid-test
|
||||
- Not checking implementation
|
||||
- Uneven traffic allocation
|
||||
|
||||
### Analysis
|
||||
- Ignoring confidence intervals
|
||||
- Cherry-picking segments
|
||||
- Over-interpreting inconclusive results
|
||||
- Not considering practical significance
|
||||
- One hypothesis per test
|
||||
- One primary metric
|
||||
- Commit before launch
|
||||
- No peeking
|
||||
- Learning over winning
|
||||
- Statistical rigor first
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask
|
||||
## Final Reminder
|
||||
|
||||
If you need more context:
|
||||
1. What's your current conversion rate?
|
||||
2. How much traffic does this page get?
|
||||
3. What change are you considering and why?
|
||||
4. What's the smallest improvement worth detecting?
|
||||
5. What tools do you have for testing?
|
||||
6. Have you tested this area before?
|
||||
A/B testing is not about proving ideas right.
|
||||
It is about **learning the truth with confidence**.
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **page-cro**: For generating test ideas based on CRO principles
|
||||
- **analytics-tracking**: For setting up test measurement
|
||||
- **copywriting**: For creating variant copy
|
||||
If you feel tempted to rush, simplify, or “just try it” —
|
||||
that is the signal to **slow down and re-check the design**.
|
||||
|
||||
82
skills/agent-memory-mcp/SKILL.md
Normal file
82
skills/agent-memory-mcp/SKILL.md
Normal file
@@ -0,0 +1,82 @@
|
||||
---
|
||||
name: agent-memory-mcp
|
||||
author: Amit Rathiesh
|
||||
description: A hybrid memory system that provides persistent, searchable knowledge management for AI agents (Architecture, Patterns, Decisions).
|
||||
---
|
||||
|
||||
# Agent Memory Skill
|
||||
|
||||
This skill provides a persistent, searchable memory bank that automatically syncs with project documentation. It runs as an MCP server to allow reading/writing/searching of long-term memories.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node.js (v18+)
|
||||
|
||||
## Setup
|
||||
|
||||
1. **Clone the Repository**:
|
||||
Clone the `agentMemory` project into your agent's workspace or a parallel directory:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/webzler/agentMemory.git .agent/skills/agent-memory
|
||||
```
|
||||
|
||||
2. **Install Dependencies**:
|
||||
|
||||
```bash
|
||||
cd .agent/skills/agent-memory
|
||||
npm install
|
||||
npm run compile
|
||||
```
|
||||
|
||||
3. **Start the MCP Server**:
|
||||
Use the helper script to activate the memory bank for your current project:
|
||||
|
||||
```bash
|
||||
npm run start-server <project_id> <absolute_path_to_target_workspace>
|
||||
```
|
||||
|
||||
_Example for current directory:_
|
||||
|
||||
```bash
|
||||
npm run start-server my-project $(pwd)
|
||||
```
|
||||
|
||||
## Capabilities (MCP Tools)
|
||||
|
||||
### `memory_search`
|
||||
|
||||
Search for memories by query, type, or tags.
|
||||
|
||||
- **Args**: `query` (string), `type?` (string), `tags?` (string[])
|
||||
- **Usage**: "Find all authentication patterns" -> `memory_search({ query: "authentication", type: "pattern" })`
|
||||
|
||||
### `memory_write`
|
||||
|
||||
Record new knowledge or decisions.
|
||||
|
||||
- **Args**: `key` (string), `type` (string), `content` (string), `tags?` (string[])
|
||||
- **Usage**: "Save this architecture decision" -> `memory_write({ key: "auth-v1", type: "decision", content: "..." })`
|
||||
|
||||
### `memory_read`
|
||||
|
||||
Retrieve specific memory content by key.
|
||||
|
||||
- **Args**: `key` (string)
|
||||
- **Usage**: "Get the auth design" -> `memory_read({ key: "auth-v1" })`
|
||||
|
||||
### `memory_stats`
|
||||
|
||||
View analytics on memory usage.
|
||||
|
||||
- **Usage**: "Show memory statistics" -> `memory_stats({})`
|
||||
|
||||
## Dashboard
|
||||
|
||||
This skill includes a standalone dashboard to visualize memory usage.
|
||||
|
||||
```bash
|
||||
npm run start-dashboard <absolute_path_to_target_workspace>
|
||||
```
|
||||
|
||||
Access at: `http://localhost:3333`
|
||||
484
skills/api-documentation-generator/SKILL.md
Normal file
484
skills/api-documentation-generator/SKILL.md
Normal file
@@ -0,0 +1,484 @@
|
||||
---
|
||||
name: api-documentation-generator
|
||||
description: "Generate comprehensive, developer-friendly API documentation from code, including endpoints, parameters, examples, and best practices"
|
||||
---
|
||||
|
||||
# API Documentation Generator
|
||||
|
||||
## Overview
|
||||
|
||||
Automatically generate clear, comprehensive API documentation from your codebase. This skill helps you create professional documentation that includes endpoint descriptions, request/response examples, authentication details, error handling, and usage guidelines.
|
||||
|
||||
Perfect for REST APIs, GraphQL APIs, and WebSocket APIs.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
- Use when you need to document a new API
|
||||
- Use when updating existing API documentation
|
||||
- Use when your API lacks clear documentation
|
||||
- Use when onboarding new developers to your API
|
||||
- Use when preparing API documentation for external users
|
||||
- Use when creating OpenAPI/Swagger specifications
|
||||
|
||||
## How It Works
|
||||
|
||||
### Step 1: Analyze the API Structure
|
||||
|
||||
First, I'll examine your API codebase to understand:
|
||||
- Available endpoints and routes
|
||||
- HTTP methods (GET, POST, PUT, DELETE, etc.)
|
||||
- Request parameters and body structure
|
||||
- Response formats and status codes
|
||||
- Authentication and authorization requirements
|
||||
- Error handling patterns
|
||||
|
||||
### Step 2: Generate Endpoint Documentation
|
||||
|
||||
For each endpoint, I'll create documentation including:
|
||||
|
||||
**Endpoint Details:**
|
||||
- HTTP method and URL path
|
||||
- Brief description of what it does
|
||||
- Authentication requirements
|
||||
- Rate limiting information (if applicable)
|
||||
|
||||
**Request Specification:**
|
||||
- Path parameters
|
||||
- Query parameters
|
||||
- Request headers
|
||||
- Request body schema (with types and validation rules)
|
||||
|
||||
**Response Specification:**
|
||||
- Success response (status code + body structure)
|
||||
- Error responses (all possible error codes)
|
||||
- Response headers
|
||||
|
||||
**Code Examples:**
|
||||
- cURL command
|
||||
- JavaScript/TypeScript (fetch/axios)
|
||||
- Python (requests)
|
||||
- Other languages as needed
|
||||
|
||||
### Step 3: Add Usage Guidelines
|
||||
|
||||
I'll include:
|
||||
- Getting started guide
|
||||
- Authentication setup
|
||||
- Common use cases
|
||||
- Best practices
|
||||
- Rate limiting details
|
||||
- Pagination patterns
|
||||
- Filtering and sorting options
|
||||
|
||||
### Step 4: Document Error Handling
|
||||
|
||||
Clear error documentation including:
|
||||
- All possible error codes
|
||||
- Error message formats
|
||||
- Troubleshooting guide
|
||||
- Common error scenarios and solutions
|
||||
|
||||
### Step 5: Create Interactive Examples
|
||||
|
||||
Where possible, I'll provide:
|
||||
- Postman collection
|
||||
- OpenAPI/Swagger specification
|
||||
- Interactive code examples
|
||||
- Sample responses
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: REST API Endpoint Documentation
|
||||
|
||||
```markdown
|
||||
## Create User
|
||||
|
||||
Creates a new user account.
|
||||
|
||||
**Endpoint:** `POST /api/v1/users`
|
||||
|
||||
**Authentication:** Required (Bearer token)
|
||||
|
||||
**Request Body:**
|
||||
\`\`\`json
|
||||
{
|
||||
"email": "user@example.com", // Required: Valid email address
|
||||
"password": "SecurePass123!", // Required: Min 8 chars, 1 uppercase, 1 number
|
||||
"name": "John Doe", // Required: 2-50 characters
|
||||
"role": "user" // Optional: "user" or "admin" (default: "user")
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
**Success Response (201 Created):**
|
||||
\`\`\`json
|
||||
{
|
||||
"id": "usr_1234567890",
|
||||
"email": "user@example.com",
|
||||
"name": "John Doe",
|
||||
"role": "user",
|
||||
"createdAt": "2026-01-20T10:30:00Z",
|
||||
"emailVerified": false
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
**Error Responses:**
|
||||
|
||||
- `400 Bad Request` - Invalid input data
|
||||
\`\`\`json
|
||||
{
|
||||
"error": "VALIDATION_ERROR",
|
||||
"message": "Invalid email format",
|
||||
"field": "email"
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
- `409 Conflict` - Email already exists
|
||||
\`\`\`json
|
||||
{
|
||||
"error": "EMAIL_EXISTS",
|
||||
"message": "An account with this email already exists"
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
- `401 Unauthorized` - Missing or invalid authentication token
|
||||
|
||||
**Example Request (cURL):**
|
||||
\`\`\`bash
|
||||
curl -X POST https://api.example.com/api/v1/users \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"email": "user@example.com",
|
||||
"password": "SecurePass123!",
|
||||
"name": "John Doe"
|
||||
}'
|
||||
\`\`\`
|
||||
|
||||
**Example Request (JavaScript):**
|
||||
\`\`\`javascript
|
||||
const response = await fetch('https://api.example.com/api/v1/users', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Authorization': `Bearer ${token}`,
|
||||
'Content-Type': 'application/json'
|
||||
},
|
||||
body: JSON.stringify({
|
||||
email: 'user@example.com',
|
||||
password: 'SecurePass123!',
|
||||
name: 'John Doe'
|
||||
})
|
||||
});
|
||||
|
||||
const user = await response.json();
|
||||
console.log(user);
|
||||
\`\`\`
|
||||
|
||||
**Example Request (Python):**
|
||||
\`\`\`python
|
||||
import requests
|
||||
|
||||
response = requests.post(
|
||||
'https://api.example.com/api/v1/users',
|
||||
headers={
|
||||
'Authorization': f'Bearer {token}',
|
||||
'Content-Type': 'application/json'
|
||||
},
|
||||
json={
|
||||
'email': 'user@example.com',
|
||||
'password': 'SecurePass123!',
|
||||
'name': 'John Doe'
|
||||
}
|
||||
)
|
||||
|
||||
user = response.json()
|
||||
print(user)
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### Example 2: GraphQL API Documentation
|
||||
|
||||
```markdown
|
||||
## User Query
|
||||
|
||||
Fetch user information by ID.
|
||||
|
||||
**Query:**
|
||||
\`\`\`graphql
|
||||
query GetUser($id: ID!) {
|
||||
user(id: $id) {
|
||||
id
|
||||
email
|
||||
name
|
||||
role
|
||||
createdAt
|
||||
posts {
|
||||
id
|
||||
title
|
||||
publishedAt
|
||||
}
|
||||
}
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
**Variables:**
|
||||
\`\`\`json
|
||||
{
|
||||
"id": "usr_1234567890"
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
**Response:**
|
||||
\`\`\`json
|
||||
{
|
||||
"data": {
|
||||
"user": {
|
||||
"id": "usr_1234567890",
|
||||
"email": "user@example.com",
|
||||
"name": "John Doe",
|
||||
"role": "user",
|
||||
"createdAt": "2026-01-20T10:30:00Z",
|
||||
"posts": [
|
||||
{
|
||||
"id": "post_123",
|
||||
"title": "My First Post",
|
||||
"publishedAt": "2026-01-21T14:00:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
**Errors:**
|
||||
\`\`\`json
|
||||
{
|
||||
"errors": [
|
||||
{
|
||||
"message": "User not found",
|
||||
"extensions": {
|
||||
"code": "USER_NOT_FOUND",
|
||||
"userId": "usr_1234567890"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### Example 3: Authentication Documentation
|
||||
|
||||
```markdown
|
||||
## Authentication
|
||||
|
||||
All API requests require authentication using Bearer tokens.
|
||||
|
||||
### Getting a Token
|
||||
|
||||
**Endpoint:** `POST /api/v1/auth/login`
|
||||
|
||||
**Request:**
|
||||
\`\`\`json
|
||||
{
|
||||
"email": "user@example.com",
|
||||
"password": "your-password"
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
**Response:**
|
||||
\`\`\`json
|
||||
{
|
||||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"expiresIn": 3600,
|
||||
"refreshToken": "refresh_token_here"
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
### Using the Token
|
||||
|
||||
Include the token in the Authorization header:
|
||||
|
||||
\`\`\`
|
||||
Authorization: Bearer YOUR_TOKEN
|
||||
\`\`\`
|
||||
|
||||
### Token Expiration
|
||||
|
||||
Tokens expire after 1 hour. Use the refresh token to get a new access token:
|
||||
|
||||
**Endpoint:** `POST /api/v1/auth/refresh`
|
||||
|
||||
**Request:**
|
||||
\`\`\`json
|
||||
{
|
||||
"refreshToken": "refresh_token_here"
|
||||
}
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### ✅ Do This
|
||||
|
||||
- **Be Consistent** - Use the same format for all endpoints
|
||||
- **Include Examples** - Provide working code examples in multiple languages
|
||||
- **Document Errors** - List all possible error codes and their meanings
|
||||
- **Show Real Data** - Use realistic example data, not "foo" and "bar"
|
||||
- **Explain Parameters** - Describe what each parameter does and its constraints
|
||||
- **Version Your API** - Include version numbers in URLs (/api/v1/)
|
||||
- **Add Timestamps** - Show when documentation was last updated
|
||||
- **Link Related Endpoints** - Help users discover related functionality
|
||||
- **Include Rate Limits** - Document any rate limiting policies
|
||||
- **Provide Postman Collection** - Make it easy to test your API
|
||||
|
||||
### ❌ Don't Do This
|
||||
|
||||
- **Don't Skip Error Cases** - Users need to know what can go wrong
|
||||
- **Don't Use Vague Descriptions** - "Gets data" is not helpful
|
||||
- **Don't Forget Authentication** - Always document auth requirements
|
||||
- **Don't Ignore Edge Cases** - Document pagination, filtering, sorting
|
||||
- **Don't Leave Examples Broken** - Test all code examples
|
||||
- **Don't Use Outdated Info** - Keep documentation in sync with code
|
||||
- **Don't Overcomplicate** - Keep it simple and scannable
|
||||
- **Don't Forget Response Headers** - Document important headers
|
||||
|
||||
## Documentation Structure
|
||||
|
||||
### Recommended Sections
|
||||
|
||||
1. **Introduction**
|
||||
- What the API does
|
||||
- Base URL
|
||||
- API version
|
||||
- Support contact
|
||||
|
||||
2. **Authentication**
|
||||
- How to authenticate
|
||||
- Token management
|
||||
- Security best practices
|
||||
|
||||
3. **Quick Start**
|
||||
- Simple example to get started
|
||||
- Common use case walkthrough
|
||||
|
||||
4. **Endpoints**
|
||||
- Organized by resource
|
||||
- Full details for each endpoint
|
||||
|
||||
5. **Data Models**
|
||||
- Schema definitions
|
||||
- Field descriptions
|
||||
- Validation rules
|
||||
|
||||
6. **Error Handling**
|
||||
- Error code reference
|
||||
- Error response format
|
||||
- Troubleshooting guide
|
||||
|
||||
7. **Rate Limiting**
|
||||
- Limits and quotas
|
||||
- Headers to check
|
||||
- Handling rate limit errors
|
||||
|
||||
8. **Changelog**
|
||||
- API version history
|
||||
- Breaking changes
|
||||
- Deprecation notices
|
||||
|
||||
9. **SDKs and Tools**
|
||||
- Official client libraries
|
||||
- Postman collection
|
||||
- OpenAPI specification
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
### Problem: Documentation Gets Out of Sync
|
||||
**Symptoms:** Examples don't work, parameters are wrong, endpoints return different data
|
||||
**Solution:**
|
||||
- Generate docs from code comments/annotations
|
||||
- Use tools like Swagger/OpenAPI
|
||||
- Add API tests that validate documentation
|
||||
- Review docs with every API change
|
||||
|
||||
### Problem: Missing Error Documentation
|
||||
**Symptoms:** Users don't know how to handle errors, support tickets increase
|
||||
**Solution:**
|
||||
- Document every possible error code
|
||||
- Provide clear error messages
|
||||
- Include troubleshooting steps
|
||||
- Show example error responses
|
||||
|
||||
### Problem: Examples Don't Work
|
||||
**Symptoms:** Users can't get started, frustration increases
|
||||
**Solution:**
|
||||
- Test every code example
|
||||
- Use real, working endpoints
|
||||
- Include complete examples (not fragments)
|
||||
- Provide a sandbox environment
|
||||
|
||||
### Problem: Unclear Parameter Requirements
|
||||
**Symptoms:** Users send invalid requests, validation errors
|
||||
**Solution:**
|
||||
- Mark required vs optional clearly
|
||||
- Document data types and formats
|
||||
- Show validation rules
|
||||
- Provide example values
|
||||
|
||||
## Tools and Formats
|
||||
|
||||
### OpenAPI/Swagger
|
||||
Generate interactive documentation:
|
||||
```yaml
|
||||
openapi: 3.0.0
|
||||
info:
|
||||
title: My API
|
||||
version: 1.0.0
|
||||
paths:
|
||||
/users:
|
||||
post:
|
||||
summary: Create a new user
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CreateUserRequest'
|
||||
```
|
||||
|
||||
### Postman Collection
|
||||
Export collection for easy testing:
|
||||
```json
|
||||
{
|
||||
"info": {
|
||||
"name": "My API",
|
||||
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
|
||||
},
|
||||
"item": [
|
||||
{
|
||||
"name": "Create User",
|
||||
"request": {
|
||||
"method": "POST",
|
||||
"url": "{{baseUrl}}/api/v1/users"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `@doc-coauthoring` - For collaborative documentation writing
|
||||
- `@copywriting` - For clear, user-friendly descriptions
|
||||
- `@test-driven-development` - For ensuring API behavior matches docs
|
||||
- `@systematic-debugging` - For troubleshooting API issues
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [OpenAPI Specification](https://swagger.io/specification/)
|
||||
- [REST API Best Practices](https://restfulapi.net/)
|
||||
- [GraphQL Documentation](https://graphql.org/learn/)
|
||||
- [API Design Patterns](https://www.apiguide.com/)
|
||||
- [Postman Documentation](https://learning.postman.com/docs/)
|
||||
|
||||
---
|
||||
|
||||
**Pro Tip:** Keep your API documentation as close to your code as possible. Use tools that generate docs from code comments to ensure they stay in sync!
|
||||
907
skills/api-security-best-practices/SKILL.md
Normal file
907
skills/api-security-best-practices/SKILL.md
Normal file
@@ -0,0 +1,907 @@
|
||||
---
|
||||
name: api-security-best-practices
|
||||
description: "Implement secure API design patterns including authentication, authorization, input validation, rate limiting, and protection against common API vulnerabilities"
|
||||
---
|
||||
|
||||
# API Security Best Practices
|
||||
|
||||
## Overview
|
||||
|
||||
Guide developers in building secure APIs by implementing authentication, authorization, input validation, rate limiting, and protection against common vulnerabilities. This skill covers security patterns for REST, GraphQL, and WebSocket APIs.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
- Use when designing new API endpoints
|
||||
- Use when securing existing APIs
|
||||
- Use when implementing authentication and authorization
|
||||
- Use when protecting against API attacks (injection, DDoS, etc.)
|
||||
- Use when conducting API security reviews
|
||||
- Use when preparing for security audits
|
||||
- Use when implementing rate limiting and throttling
|
||||
- Use when handling sensitive data in APIs
|
||||
|
||||
## How It Works
|
||||
|
||||
### Step 1: Authentication & Authorization
|
||||
|
||||
I'll help you implement secure authentication:
|
||||
- Choose authentication method (JWT, OAuth 2.0, API keys)
|
||||
- Implement token-based authentication
|
||||
- Set up role-based access control (RBAC)
|
||||
- Secure session management
|
||||
- Implement multi-factor authentication (MFA)
|
||||
|
||||
### Step 2: Input Validation & Sanitization
|
||||
|
||||
Protect against injection attacks:
|
||||
- Validate all input data
|
||||
- Sanitize user inputs
|
||||
- Use parameterized queries
|
||||
- Implement request schema validation
|
||||
- Prevent SQL injection, XSS, and command injection
|
||||
|
||||
### Step 3: Rate Limiting & Throttling
|
||||
|
||||
Prevent abuse and DDoS attacks:
|
||||
- Implement rate limiting per user/IP
|
||||
- Set up API throttling
|
||||
- Configure request quotas
|
||||
- Handle rate limit errors gracefully
|
||||
- Monitor for suspicious activity
|
||||
|
||||
### Step 4: Data Protection
|
||||
|
||||
Secure sensitive data:
|
||||
- Encrypt data in transit (HTTPS/TLS)
|
||||
- Encrypt sensitive data at rest
|
||||
- Implement proper error handling (no data leaks)
|
||||
- Sanitize error messages
|
||||
- Use secure headers
|
||||
|
||||
### Step 5: API Security Testing
|
||||
|
||||
Verify security implementation:
|
||||
- Test authentication and authorization
|
||||
- Perform penetration testing
|
||||
- Check for common vulnerabilities (OWASP API Top 10)
|
||||
- Validate input handling
|
||||
- Test rate limiting
|
||||
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Implementing JWT Authentication
|
||||
|
||||
```markdown
|
||||
## Secure JWT Authentication Implementation
|
||||
|
||||
### Authentication Flow
|
||||
|
||||
1. User logs in with credentials
|
||||
2. Server validates credentials
|
||||
3. Server generates JWT token
|
||||
4. Client stores token securely
|
||||
5. Client sends token with each request
|
||||
6. Server validates token
|
||||
|
||||
### Implementation
|
||||
|
||||
#### 1. Generate Secure JWT Tokens
|
||||
|
||||
\`\`\`javascript
|
||||
// auth.js
|
||||
const jwt = require('jsonwebtoken');
|
||||
const bcrypt = require('bcrypt');
|
||||
|
||||
// Login endpoint
|
||||
app.post('/api/auth/login', async (req, res) => {
|
||||
try {
|
||||
const { email, password } = req.body;
|
||||
|
||||
// Validate input
|
||||
if (!email || !password) {
|
||||
return res.status(400).json({
|
||||
error: 'Email and password are required'
|
||||
});
|
||||
}
|
||||
|
||||
// Find user
|
||||
const user = await db.user.findUnique({
|
||||
where: { email }
|
||||
});
|
||||
|
||||
if (!user) {
|
||||
// Don't reveal if user exists
|
||||
return res.status(401).json({
|
||||
error: 'Invalid credentials'
|
||||
});
|
||||
}
|
||||
|
||||
// Verify password
|
||||
const validPassword = await bcrypt.compare(
|
||||
password,
|
||||
user.passwordHash
|
||||
);
|
||||
|
||||
if (!validPassword) {
|
||||
return res.status(401).json({
|
||||
error: 'Invalid credentials'
|
||||
});
|
||||
}
|
||||
|
||||
// Generate JWT token
|
||||
const token = jwt.sign(
|
||||
{
|
||||
userId: user.id,
|
||||
email: user.email,
|
||||
role: user.role
|
||||
},
|
||||
process.env.JWT_SECRET,
|
||||
{
|
||||
expiresIn: '1h',
|
||||
issuer: 'your-app',
|
||||
audience: 'your-app-users'
|
||||
}
|
||||
);
|
||||
|
||||
// Generate refresh token
|
||||
const refreshToken = jwt.sign(
|
||||
{ userId: user.id },
|
||||
process.env.JWT_REFRESH_SECRET,
|
||||
{ expiresIn: '7d' }
|
||||
);
|
||||
|
||||
// Store refresh token in database
|
||||
await db.refreshToken.create({
|
||||
data: {
|
||||
token: refreshToken,
|
||||
userId: user.id,
|
||||
expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)
|
||||
}
|
||||
});
|
||||
|
||||
res.json({
|
||||
token,
|
||||
refreshToken,
|
||||
expiresIn: 3600
|
||||
});
|
||||
|
||||
} catch (error) {
|
||||
console.error('Login error:', error);
|
||||
res.status(500).json({
|
||||
error: 'An error occurred during login'
|
||||
});
|
||||
}
|
||||
});
|
||||
\`\`\`
|
||||
|
||||
#### 2. Verify JWT Tokens (Middleware)
|
||||
|
||||
\`\`\`javascript
|
||||
// middleware/auth.js
|
||||
const jwt = require('jsonwebtoken');
|
||||
|
||||
function authenticateToken(req, res, next) {
|
||||
// Get token from header
|
||||
const authHeader = req.headers['authorization'];
|
||||
const token = authHeader && authHeader.split(' ')[1]; // Bearer TOKEN
|
||||
|
||||
if (!token) {
|
||||
return res.status(401).json({
|
||||
error: 'Access token required'
|
||||
});
|
||||
}
|
||||
|
||||
// Verify token
|
||||
jwt.verify(
|
||||
token,
|
||||
process.env.JWT_SECRET,
|
||||
{
|
||||
issuer: 'your-app',
|
||||
audience: 'your-app-users'
|
||||
},
|
||||
(err, user) => {
|
||||
if (err) {
|
||||
if (err.name === 'TokenExpiredError') {
|
||||
return res.status(401).json({
|
||||
error: 'Token expired'
|
||||
});
|
||||
}
|
||||
return res.status(403).json({
|
||||
error: 'Invalid token'
|
||||
});
|
||||
}
|
||||
|
||||
// Attach user to request
|
||||
req.user = user;
|
||||
next();
|
||||
}
|
||||
);
|
||||
}
|
||||
|
||||
module.exports = { authenticateToken };
|
||||
\`\`\`
|
||||
|
||||
#### 3. Protect Routes
|
||||
|
||||
\`\`\`javascript
|
||||
const { authenticateToken } = require('./middleware/auth');
|
||||
|
||||
// Protected route
|
||||
app.get('/api/user/profile', authenticateToken, async (req, res) => {
|
||||
try {
|
||||
const user = await db.user.findUnique({
|
||||
where: { id: req.user.userId },
|
||||
select: {
|
||||
id: true,
|
||||
email: true,
|
||||
name: true,
|
||||
// Don't return passwordHash
|
||||
}
|
||||
});
|
||||
|
||||
res.json(user);
|
||||
} catch (error) {
|
||||
res.status(500).json({ error: 'Server error' });
|
||||
}
|
||||
});
|
||||
\`\`\`
|
||||
|
||||
#### 4. Implement Token Refresh
|
||||
|
||||
\`\`\`javascript
|
||||
app.post('/api/auth/refresh', async (req, res) => {
|
||||
const { refreshToken } = req.body;
|
||||
|
||||
if (!refreshToken) {
|
||||
return res.status(401).json({
|
||||
error: 'Refresh token required'
|
||||
});
|
||||
}
|
||||
|
||||
try {
|
||||
// Verify refresh token
|
||||
const decoded = jwt.verify(
|
||||
refreshToken,
|
||||
process.env.JWT_REFRESH_SECRET
|
||||
);
|
||||
|
||||
// Check if refresh token exists in database
|
||||
const storedToken = await db.refreshToken.findFirst({
|
||||
where: {
|
||||
token: refreshToken,
|
||||
userId: decoded.userId,
|
||||
expiresAt: { gt: new Date() }
|
||||
}
|
||||
});
|
||||
|
||||
if (!storedToken) {
|
||||
return res.status(403).json({
|
||||
error: 'Invalid refresh token'
|
||||
});
|
||||
}
|
||||
|
||||
// Generate new access token
|
||||
const user = await db.user.findUnique({
|
||||
where: { id: decoded.userId }
|
||||
});
|
||||
|
||||
const newToken = jwt.sign(
|
||||
{
|
||||
userId: user.id,
|
||||
email: user.email,
|
||||
role: user.role
|
||||
},
|
||||
process.env.JWT_SECRET,
|
||||
{ expiresIn: '1h' }
|
||||
);
|
||||
|
||||
res.json({
|
||||
token: newToken,
|
||||
expiresIn: 3600
|
||||
});
|
||||
|
||||
} catch (error) {
|
||||
res.status(403).json({
|
||||
error: 'Invalid refresh token'
|
||||
});
|
||||
}
|
||||
});
|
||||
\`\`\`
|
||||
|
||||
### Security Best Practices
|
||||
|
||||
- ✅ Use strong JWT secrets (256-bit minimum)
|
||||
- ✅ Set short expiration times (1 hour for access tokens)
|
||||
- ✅ Implement refresh tokens for long-lived sessions
|
||||
- ✅ Store refresh tokens in database (can be revoked)
|
||||
- ✅ Use HTTPS only
|
||||
- ✅ Don't store sensitive data in JWT payload
|
||||
- ✅ Validate token issuer and audience
|
||||
- ✅ Implement token blacklisting for logout
|
||||
```
|
||||
|
||||
|
||||
### Example 2: Input Validation and SQL Injection Prevention
|
||||
|
||||
```markdown
|
||||
## Preventing SQL Injection and Input Validation
|
||||
|
||||
### The Problem
|
||||
|
||||
**❌ Vulnerable Code:**
|
||||
\`\`\`javascript
|
||||
// NEVER DO THIS - SQL Injection vulnerability
|
||||
app.get('/api/users/:id', async (req, res) => {
|
||||
const userId = req.params.id;
|
||||
|
||||
// Dangerous: User input directly in query
|
||||
const query = \`SELECT * FROM users WHERE id = '\${userId}'\`;
|
||||
const user = await db.query(query);
|
||||
|
||||
res.json(user);
|
||||
});
|
||||
|
||||
// Attack example:
|
||||
// GET /api/users/1' OR '1'='1
|
||||
// Returns all users!
|
||||
\`\`\`
|
||||
|
||||
### The Solution
|
||||
|
||||
#### 1. Use Parameterized Queries
|
||||
|
||||
\`\`\`javascript
|
||||
// ✅ Safe: Parameterized query
|
||||
app.get('/api/users/:id', async (req, res) => {
|
||||
const userId = req.params.id;
|
||||
|
||||
// Validate input first
|
||||
if (!userId || !/^\d+$/.test(userId)) {
|
||||
return res.status(400).json({
|
||||
error: 'Invalid user ID'
|
||||
});
|
||||
}
|
||||
|
||||
// Use parameterized query
|
||||
const user = await db.query(
|
||||
'SELECT id, email, name FROM users WHERE id = $1',
|
||||
[userId]
|
||||
);
|
||||
|
||||
if (!user) {
|
||||
return res.status(404).json({
|
||||
error: 'User not found'
|
||||
});
|
||||
}
|
||||
|
||||
res.json(user);
|
||||
});
|
||||
\`\`\`
|
||||
|
||||
#### 2. Use ORM with Proper Escaping
|
||||
|
||||
\`\`\`javascript
|
||||
// ✅ Safe: Using Prisma ORM
|
||||
app.get('/api/users/:id', async (req, res) => {
|
||||
const userId = parseInt(req.params.id);
|
||||
|
||||
if (isNaN(userId)) {
|
||||
return res.status(400).json({
|
||||
error: 'Invalid user ID'
|
||||
});
|
||||
}
|
||||
|
||||
const user = await prisma.user.findUnique({
|
||||
where: { id: userId },
|
||||
select: {
|
||||
id: true,
|
||||
email: true,
|
||||
name: true,
|
||||
// Don't select sensitive fields
|
||||
}
|
||||
});
|
||||
|
||||
if (!user) {
|
||||
return res.status(404).json({
|
||||
error: 'User not found'
|
||||
});
|
||||
}
|
||||
|
||||
res.json(user);
|
||||
});
|
||||
\`\`\`
|
||||
|
||||
#### 3. Implement Request Validation with Zod
|
||||
|
||||
\`\`\`javascript
|
||||
const { z } = require('zod');
|
||||
|
||||
// Define validation schema
|
||||
const createUserSchema = z.object({
|
||||
email: z.string().email('Invalid email format'),
|
||||
password: z.string()
|
||||
.min(8, 'Password must be at least 8 characters')
|
||||
.regex(/[A-Z]/, 'Password must contain uppercase letter')
|
||||
.regex(/[a-z]/, 'Password must contain lowercase letter')
|
||||
.regex(/[0-9]/, 'Password must contain number'),
|
||||
name: z.string()
|
||||
.min(2, 'Name must be at least 2 characters')
|
||||
.max(100, 'Name too long'),
|
||||
age: z.number()
|
||||
.int('Age must be an integer')
|
||||
.min(18, 'Must be 18 or older')
|
||||
.max(120, 'Invalid age')
|
||||
.optional()
|
||||
});
|
||||
|
||||
// Validation middleware
|
||||
function validateRequest(schema) {
|
||||
return (req, res, next) => {
|
||||
try {
|
||||
schema.parse(req.body);
|
||||
next();
|
||||
} catch (error) {
|
||||
res.status(400).json({
|
||||
error: 'Validation failed',
|
||||
details: error.errors
|
||||
});
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
// Use validation
|
||||
app.post('/api/users',
|
||||
validateRequest(createUserSchema),
|
||||
async (req, res) => {
|
||||
// Input is validated at this point
|
||||
const { email, password, name, age } = req.body;
|
||||
|
||||
// Hash password
|
||||
const passwordHash = await bcrypt.hash(password, 10);
|
||||
|
||||
// Create user
|
||||
const user = await prisma.user.create({
|
||||
data: {
|
||||
email,
|
||||
passwordHash,
|
||||
name,
|
||||
age
|
||||
}
|
||||
});
|
||||
|
||||
// Don't return password hash
|
||||
const { passwordHash: _, ...userWithoutPassword } = user;
|
||||
res.status(201).json(userWithoutPassword);
|
||||
}
|
||||
);
|
||||
\`\`\`
|
||||
|
||||
#### 4. Sanitize Output to Prevent XSS
|
||||
|
||||
\`\`\`javascript
|
||||
const DOMPurify = require('isomorphic-dompurify');
|
||||
|
||||
app.post('/api/comments', authenticateToken, async (req, res) => {
|
||||
const { content } = req.body;
|
||||
|
||||
// Validate
|
||||
if (!content || content.length > 1000) {
|
||||
return res.status(400).json({
|
||||
error: 'Invalid comment content'
|
||||
});
|
||||
}
|
||||
|
||||
// Sanitize HTML to prevent XSS
|
||||
const sanitizedContent = DOMPurify.sanitize(content, {
|
||||
ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'a'],
|
||||
ALLOWED_ATTR: ['href']
|
||||
});
|
||||
|
||||
const comment = await prisma.comment.create({
|
||||
data: {
|
||||
content: sanitizedContent,
|
||||
userId: req.user.userId
|
||||
}
|
||||
});
|
||||
|
||||
res.status(201).json(comment);
|
||||
});
|
||||
\`\`\`
|
||||
|
||||
### Validation Checklist
|
||||
|
||||
- [ ] Validate all user inputs
|
||||
- [ ] Use parameterized queries or ORM
|
||||
- [ ] Validate data types (string, number, email, etc.)
|
||||
- [ ] Validate data ranges (min/max length, value ranges)
|
||||
- [ ] Sanitize HTML content
|
||||
- [ ] Escape special characters
|
||||
- [ ] Validate file uploads (type, size, content)
|
||||
- [ ] Use allowlists, not blocklists
|
||||
```
|
||||
|
||||
|
||||
### Example 3: Rate Limiting and DDoS Protection
|
||||
|
||||
```markdown
|
||||
## Implementing Rate Limiting
|
||||
|
||||
### Why Rate Limiting?
|
||||
|
||||
- Prevent brute force attacks
|
||||
- Protect against DDoS
|
||||
- Prevent API abuse
|
||||
- Ensure fair usage
|
||||
- Reduce server costs
|
||||
|
||||
### Implementation with Express Rate Limit
|
||||
|
||||
\`\`\`javascript
|
||||
const rateLimit = require('express-rate-limit');
|
||||
const RedisStore = require('rate-limit-redis');
|
||||
const Redis = require('ioredis');
|
||||
|
||||
// Create Redis client
|
||||
const redis = new Redis({
|
||||
host: process.env.REDIS_HOST,
|
||||
port: process.env.REDIS_PORT
|
||||
});
|
||||
|
||||
// General API rate limit
|
||||
const apiLimiter = rateLimit({
|
||||
store: new RedisStore({
|
||||
client: redis,
|
||||
prefix: 'rl:api:'
|
||||
}),
|
||||
windowMs: 15 * 60 * 1000, // 15 minutes
|
||||
max: 100, // 100 requests per window
|
||||
message: {
|
||||
error: 'Too many requests, please try again later',
|
||||
retryAfter: 900 // seconds
|
||||
},
|
||||
standardHeaders: true, // Return rate limit info in headers
|
||||
legacyHeaders: false,
|
||||
// Custom key generator (by user ID or IP)
|
||||
keyGenerator: (req) => {
|
||||
return req.user?.userId || req.ip;
|
||||
}
|
||||
});
|
||||
|
||||
// Strict rate limit for authentication endpoints
|
||||
const authLimiter = rateLimit({
|
||||
store: new RedisStore({
|
||||
client: redis,
|
||||
prefix: 'rl:auth:'
|
||||
}),
|
||||
windowMs: 15 * 60 * 1000, // 15 minutes
|
||||
max: 5, // Only 5 login attempts per 15 minutes
|
||||
skipSuccessfulRequests: true, // Don't count successful logins
|
||||
message: {
|
||||
error: 'Too many login attempts, please try again later',
|
||||
retryAfter: 900
|
||||
}
|
||||
});
|
||||
|
||||
// Apply rate limiters
|
||||
app.use('/api/', apiLimiter);
|
||||
app.use('/api/auth/login', authLimiter);
|
||||
app.use('/api/auth/register', authLimiter);
|
||||
|
||||
// Custom rate limiter for expensive operations
|
||||
const expensiveLimiter = rateLimit({
|
||||
windowMs: 60 * 60 * 1000, // 1 hour
|
||||
max: 10, // 10 requests per hour
|
||||
message: {
|
||||
error: 'Rate limit exceeded for this operation'
|
||||
}
|
||||
});
|
||||
|
||||
app.post('/api/reports/generate',
|
||||
authenticateToken,
|
||||
expensiveLimiter,
|
||||
async (req, res) => {
|
||||
// Expensive operation
|
||||
}
|
||||
);
|
||||
\`\`\`
|
||||
|
||||
### Advanced: Per-User Rate Limiting
|
||||
|
||||
\`\`\`javascript
|
||||
// Different limits based on user tier
|
||||
function createTieredRateLimiter() {
|
||||
const limits = {
|
||||
free: { windowMs: 60 * 60 * 1000, max: 100 },
|
||||
pro: { windowMs: 60 * 60 * 1000, max: 1000 },
|
||||
enterprise: { windowMs: 60 * 60 * 1000, max: 10000 }
|
||||
};
|
||||
|
||||
return async (req, res, next) => {
|
||||
const user = req.user;
|
||||
const tier = user?.tier || 'free';
|
||||
const limit = limits[tier];
|
||||
|
||||
const key = \`rl:user:\${user.userId}\`;
|
||||
const current = await redis.incr(key);
|
||||
|
||||
if (current === 1) {
|
||||
await redis.expire(key, limit.windowMs / 1000);
|
||||
}
|
||||
|
||||
if (current > limit.max) {
|
||||
return res.status(429).json({
|
||||
error: 'Rate limit exceeded',
|
||||
limit: limit.max,
|
||||
remaining: 0,
|
||||
reset: await redis.ttl(key)
|
||||
});
|
||||
}
|
||||
|
||||
// Set rate limit headers
|
||||
res.set({
|
||||
'X-RateLimit-Limit': limit.max,
|
||||
'X-RateLimit-Remaining': limit.max - current,
|
||||
'X-RateLimit-Reset': await redis.ttl(key)
|
||||
});
|
||||
|
||||
next();
|
||||
};
|
||||
}
|
||||
|
||||
app.use('/api/', authenticateToken, createTieredRateLimiter());
|
||||
\`\`\`
|
||||
|
||||
### DDoS Protection with Helmet
|
||||
|
||||
\`\`\`javascript
|
||||
const helmet = require('helmet');
|
||||
|
||||
app.use(helmet({
|
||||
// Content Security Policy
|
||||
contentSecurityPolicy: {
|
||||
directives: {
|
||||
defaultSrc: ["'self'"],
|
||||
styleSrc: ["'self'", "'unsafe-inline'"],
|
||||
scriptSrc: ["'self'"],
|
||||
imgSrc: ["'self'", 'data:', 'https:']
|
||||
}
|
||||
},
|
||||
// Prevent clickjacking
|
||||
frameguard: { action: 'deny' },
|
||||
// Hide X-Powered-By header
|
||||
hidePoweredBy: true,
|
||||
// Prevent MIME type sniffing
|
||||
noSniff: true,
|
||||
// Enable HSTS
|
||||
hsts: {
|
||||
maxAge: 31536000,
|
||||
includeSubDomains: true,
|
||||
preload: true
|
||||
}
|
||||
}));
|
||||
\`\`\`
|
||||
|
||||
### Rate Limit Response Headers
|
||||
|
||||
\`\`\`
|
||||
X-RateLimit-Limit: 100
|
||||
X-RateLimit-Remaining: 87
|
||||
X-RateLimit-Reset: 1640000000
|
||||
Retry-After: 900
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### ✅ Do This
|
||||
|
||||
- **Use HTTPS Everywhere** - Never send sensitive data over HTTP
|
||||
- **Implement Authentication** - Require authentication for protected endpoints
|
||||
- **Validate All Inputs** - Never trust user input
|
||||
- **Use Parameterized Queries** - Prevent SQL injection
|
||||
- **Implement Rate Limiting** - Protect against brute force and DDoS
|
||||
- **Hash Passwords** - Use bcrypt with salt rounds >= 10
|
||||
- **Use Short-Lived Tokens** - JWT access tokens should expire quickly
|
||||
- **Implement CORS Properly** - Only allow trusted origins
|
||||
- **Log Security Events** - Monitor for suspicious activity
|
||||
- **Keep Dependencies Updated** - Regularly update packages
|
||||
- **Use Security Headers** - Implement Helmet.js
|
||||
- **Sanitize Error Messages** - Don't leak sensitive information
|
||||
|
||||
### ❌ Don't Do This
|
||||
|
||||
- **Don't Store Passwords in Plain Text** - Always hash passwords
|
||||
- **Don't Use Weak Secrets** - Use strong, random JWT secrets
|
||||
- **Don't Trust User Input** - Always validate and sanitize
|
||||
- **Don't Expose Stack Traces** - Hide error details in production
|
||||
- **Don't Use String Concatenation for SQL** - Use parameterized queries
|
||||
- **Don't Store Sensitive Data in JWT** - JWTs are not encrypted
|
||||
- **Don't Ignore Security Updates** - Update dependencies regularly
|
||||
- **Don't Use Default Credentials** - Change all default passwords
|
||||
- **Don't Disable CORS Completely** - Configure it properly instead
|
||||
- **Don't Log Sensitive Data** - Sanitize logs
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
### Problem: JWT Secret Exposed in Code
|
||||
**Symptoms:** JWT secret hardcoded or committed to Git
|
||||
**Solution:**
|
||||
\`\`\`javascript
|
||||
// ❌ Bad
|
||||
const JWT_SECRET = 'my-secret-key';
|
||||
|
||||
// ✅ Good
|
||||
const JWT_SECRET = process.env.JWT_SECRET;
|
||||
if (!JWT_SECRET) {
|
||||
throw new Error('JWT_SECRET environment variable is required');
|
||||
}
|
||||
|
||||
// Generate strong secret
|
||||
// node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
|
||||
\`\`\`
|
||||
|
||||
### Problem: Weak Password Requirements
|
||||
**Symptoms:** Users can set weak passwords like "password123"
|
||||
**Solution:**
|
||||
\`\`\`javascript
|
||||
const passwordSchema = z.string()
|
||||
.min(12, 'Password must be at least 12 characters')
|
||||
.regex(/[A-Z]/, 'Must contain uppercase letter')
|
||||
.regex(/[a-z]/, 'Must contain lowercase letter')
|
||||
.regex(/[0-9]/, 'Must contain number')
|
||||
.regex(/[^A-Za-z0-9]/, 'Must contain special character');
|
||||
|
||||
// Or use a password strength library
|
||||
const zxcvbn = require('zxcvbn');
|
||||
const result = zxcvbn(password);
|
||||
if (result.score < 3) {
|
||||
return res.status(400).json({
|
||||
error: 'Password too weak',
|
||||
suggestions: result.feedback.suggestions
|
||||
});
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
### Problem: Missing Authorization Checks
|
||||
**Symptoms:** Users can access resources they shouldn't
|
||||
**Solution:**
|
||||
\`\`\`javascript
|
||||
// ❌ Bad: Only checks authentication
|
||||
app.delete('/api/posts/:id', authenticateToken, async (req, res) => {
|
||||
await prisma.post.delete({ where: { id: req.params.id } });
|
||||
res.json({ success: true });
|
||||
});
|
||||
|
||||
// ✅ Good: Checks both authentication and authorization
|
||||
app.delete('/api/posts/:id', authenticateToken, async (req, res) => {
|
||||
const post = await prisma.post.findUnique({
|
||||
where: { id: req.params.id }
|
||||
});
|
||||
|
||||
if (!post) {
|
||||
return res.status(404).json({ error: 'Post not found' });
|
||||
}
|
||||
|
||||
// Check if user owns the post or is admin
|
||||
if (post.userId !== req.user.userId && req.user.role !== 'admin') {
|
||||
return res.status(403).json({
|
||||
error: 'Not authorized to delete this post'
|
||||
});
|
||||
}
|
||||
|
||||
await prisma.post.delete({ where: { id: req.params.id } });
|
||||
res.json({ success: true });
|
||||
});
|
||||
\`\`\`
|
||||
|
||||
### Problem: Verbose Error Messages
|
||||
**Symptoms:** Error messages reveal system details
|
||||
**Solution:**
|
||||
\`\`\`javascript
|
||||
// ❌ Bad: Exposes database details
|
||||
app.post('/api/users', async (req, res) => {
|
||||
try {
|
||||
const user = await prisma.user.create({ data: req.body });
|
||||
res.json(user);
|
||||
} catch (error) {
|
||||
res.status(500).json({ error: error.message });
|
||||
// Error: "Unique constraint failed on the fields: (`email`)"
|
||||
}
|
||||
});
|
||||
|
||||
// ✅ Good: Generic error message
|
||||
app.post('/api/users', async (req, res) => {
|
||||
try {
|
||||
const user = await prisma.user.create({ data: req.body });
|
||||
res.json(user);
|
||||
} catch (error) {
|
||||
console.error('User creation error:', error); // Log full error
|
||||
|
||||
if (error.code === 'P2002') {
|
||||
return res.status(400).json({
|
||||
error: 'Email already exists'
|
||||
});
|
||||
}
|
||||
|
||||
res.status(500).json({
|
||||
error: 'An error occurred while creating user'
|
||||
});
|
||||
}
|
||||
});
|
||||
\`\`\`
|
||||
|
||||
## Security Checklist
|
||||
|
||||
### Authentication & Authorization
|
||||
- [ ] Implement strong authentication (JWT, OAuth 2.0)
|
||||
- [ ] Use HTTPS for all endpoints
|
||||
- [ ] Hash passwords with bcrypt (salt rounds >= 10)
|
||||
- [ ] Implement token expiration
|
||||
- [ ] Add refresh token mechanism
|
||||
- [ ] Verify user authorization for each request
|
||||
- [ ] Implement role-based access control (RBAC)
|
||||
|
||||
### Input Validation
|
||||
- [ ] Validate all user inputs
|
||||
- [ ] Use parameterized queries or ORM
|
||||
- [ ] Sanitize HTML content
|
||||
- [ ] Validate file uploads
|
||||
- [ ] Implement request schema validation
|
||||
- [ ] Use allowlists, not blocklists
|
||||
|
||||
### Rate Limiting & DDoS Protection
|
||||
- [ ] Implement rate limiting per user/IP
|
||||
- [ ] Add stricter limits for auth endpoints
|
||||
- [ ] Use Redis for distributed rate limiting
|
||||
- [ ] Return proper rate limit headers
|
||||
- [ ] Implement request throttling
|
||||
|
||||
### Data Protection
|
||||
- [ ] Use HTTPS/TLS for all traffic
|
||||
- [ ] Encrypt sensitive data at rest
|
||||
- [ ] Don't store sensitive data in JWT
|
||||
- [ ] Sanitize error messages
|
||||
- [ ] Implement proper CORS configuration
|
||||
- [ ] Use security headers (Helmet.js)
|
||||
|
||||
### Monitoring & Logging
|
||||
- [ ] Log security events
|
||||
- [ ] Monitor for suspicious activity
|
||||
- [ ] Set up alerts for failed auth attempts
|
||||
- [ ] Track API usage patterns
|
||||
- [ ] Don't log sensitive data
|
||||
|
||||
## OWASP API Security Top 10
|
||||
|
||||
1. **Broken Object Level Authorization** - Always verify user can access resource
|
||||
2. **Broken Authentication** - Implement strong authentication mechanisms
|
||||
3. **Broken Object Property Level Authorization** - Validate which properties user can access
|
||||
4. **Unrestricted Resource Consumption** - Implement rate limiting and quotas
|
||||
5. **Broken Function Level Authorization** - Verify user role for each function
|
||||
6. **Unrestricted Access to Sensitive Business Flows** - Protect critical workflows
|
||||
7. **Server Side Request Forgery (SSRF)** - Validate and sanitize URLs
|
||||
8. **Security Misconfiguration** - Use security best practices and headers
|
||||
9. **Improper Inventory Management** - Document and secure all API endpoints
|
||||
10. **Unsafe Consumption of APIs** - Validate data from third-party APIs
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `@ethical-hacking-methodology` - Security testing perspective
|
||||
- `@sql-injection-testing` - Testing for SQL injection
|
||||
- `@xss-html-injection` - Testing for XSS vulnerabilities
|
||||
- `@broken-authentication` - Authentication vulnerabilities
|
||||
- `@backend-dev-guidelines` - Backend development standards
|
||||
- `@systematic-debugging` - Debug security issues
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [OWASP API Security Top 10](https://owasp.org/www-project-api-security/)
|
||||
- [JWT Best Practices](https://tools.ietf.org/html/rfc8725)
|
||||
- [Express Security Best Practices](https://expressjs.com/en/advanced/best-practice-security.html)
|
||||
- [Node.js Security Checklist](https://blog.risingstack.com/node-js-security-checklist/)
|
||||
- [API Security Checklist](https://github.com/shieldfy/API-Security-Checklist)
|
||||
|
||||
---
|
||||
|
||||
**Pro Tip:** Security is not a one-time task - regularly audit your APIs, keep dependencies updated, and stay informed about new vulnerabilities!
|
||||
59
skills/avalonia-layout-zafiro/SKILL.md
Normal file
59
skills/avalonia-layout-zafiro/SKILL.md
Normal file
@@ -0,0 +1,59 @@
|
||||
---
|
||||
name: avalonia-layout-zafiro
|
||||
description: Guidelines for modern Avalonia UI layout using Zafiro.Avalonia, emphasizing shared styles, generic components, and avoiding XAML redundancy.
|
||||
allowed-tools: Read, Write, Edit, Glob, Grep
|
||||
---
|
||||
|
||||
# Avalonia Layout with Zafiro.Avalonia
|
||||
|
||||
> Master modern, clean, and maintainable Avalonia UI layouts.
|
||||
> **Focus on semantic containers, shared styles, and minimal XAML.**
|
||||
|
||||
## 🎯 Selective Reading Rule
|
||||
|
||||
**Read ONLY files relevant to the layout challenge!**
|
||||
|
||||
---
|
||||
|
||||
## 📑 Content Map
|
||||
|
||||
| File | Description | When to Read |
|
||||
|------|-------------|--------------|
|
||||
| `themes.md` | Theme organization and shared styles | Setting up or refining app themes |
|
||||
| `containers.md` | Semantic containers (`HeaderedContainer`, `EdgePanel`, `Card`) | Structuring views and layouts |
|
||||
| `icons.md` | Icon usage with `IconExtension` and `IconOptions` | Adding and customizing icons |
|
||||
| `behaviors.md` | `Xaml.Interaction.Behaviors` and avoiding Converters | Implementing complex interactions |
|
||||
| `components.md` | Generic components and avoiding nesting | Creating reusable UI elements |
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Related Project (Exemplary Implementation)
|
||||
|
||||
For a real-world example, refer to the **Angor** project:
|
||||
`/mnt/fast/Repos/angor/src/Angor/Avalonia/Angor.Avalonia.sln`
|
||||
|
||||
---
|
||||
|
||||
## ✅ Checklist for Clean Layouts
|
||||
|
||||
- [ ] **Used semantic containers?** (e.g., `HeaderedContainer` instead of `Border` with manual header)
|
||||
- [ ] **Avoided redundant properties?** Use shared styles in `axaml` files.
|
||||
- [ ] **Minimized nesting?** Flatten layouts using `EdgePanel` or generic components.
|
||||
- [ ] **Icons via extension?** Use `{Icon fa-name}` and `IconOptions` for styling.
|
||||
- [ ] **Behaviors over code-behind?** Use `Interaction.Behaviors` for UI-logic.
|
||||
- [ ] **Avoided Converters?** Prefer ViewModel properties or Behaviors unless necessary.
|
||||
|
||||
---
|
||||
|
||||
## ❌ Anti-Patterns
|
||||
|
||||
**DON'T:**
|
||||
- Use hardcoded colors or sizes (literals) in views.
|
||||
- Create deep nesting of `Grid` and `StackPanel`.
|
||||
- Repeat visual properties across multiple elements (use Styles).
|
||||
- Use `IValueConverter` for simple logic that belongs in the ViewModel.
|
||||
|
||||
**DO:**
|
||||
- Use `DynamicResource` for colors and brushes.
|
||||
- Extract repeated layouts into generic components.
|
||||
- Leverage `Zafiro.Avalonia` specific panels like `EdgePanel` for common UI patterns.
|
||||
35
skills/avalonia-layout-zafiro/behaviors.md
Normal file
35
skills/avalonia-layout-zafiro/behaviors.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# Interactions and Logic
|
||||
|
||||
To keep XAML clean and maintainable, minimize logic in views and avoid excessive use of converters.
|
||||
|
||||
## 🎭 Xaml.Interaction.Behaviors
|
||||
|
||||
Use `Interaction.Behaviors` to handle UI-related logic that doesn't belong in the ViewModel, such as focus management, animations, or specialized event handling.
|
||||
|
||||
```xml
|
||||
<TextBox Text="{Binding Address}">
|
||||
<Interaction.Behaviors>
|
||||
<UntouchedClassBehavior />
|
||||
</Interaction.Behaviors>
|
||||
</TextBox>
|
||||
```
|
||||
|
||||
### Why use Behaviors?
|
||||
- **Encapsulation**: UI logic is contained in a reusable behavior class.
|
||||
- **Clean XAML**: Avoids code-behind and complex XAML triggers.
|
||||
- **Testability**: Behaviors can be tested independently of the View.
|
||||
|
||||
## 🚫 Avoiding Converters
|
||||
|
||||
Converters often lead to "magical" logic hidden in XAML. Whenever possible, prefer:
|
||||
|
||||
1. **ViewModel Properties**: Let the ViewModel provide the final data format (e.g., a `string` formatted for display).
|
||||
2. **MultiBinding**: Use for simple logic combinations (And/Or) directly in XAML.
|
||||
3. **Behaviors**: For more complex interactions that involve state or events.
|
||||
|
||||
### When to use Converters?
|
||||
Only use them when the conversion is purely visual and highly reusable across different contexts (e.g., `BoolToOpacityConverter`).
|
||||
|
||||
## 🧩 Simplified Interactions
|
||||
|
||||
If you find yourself needing a complex converter or behavior, consider if the component can be simplified or if the data model can be adjusted to make the view binding more direct.
|
||||
41
skills/avalonia-layout-zafiro/components.md
Normal file
41
skills/avalonia-layout-zafiro/components.md
Normal file
@@ -0,0 +1,41 @@
|
||||
# Building Generic Components
|
||||
|
||||
Reducing nesting and complexity is achieved by breaking down views into generic, reusable components.
|
||||
|
||||
## 🧊 Generic Components
|
||||
|
||||
Instead of building large, complex views, extract recurring patterns into small `UserControl`s.
|
||||
|
||||
### Example: A generic "Summary Item"
|
||||
Instead of repeating a `Grid` with labels and values:
|
||||
|
||||
```xml
|
||||
<!-- ❌ BAD: Repeated Grid -->
|
||||
<Grid ColumnDefinitions="*,Auto">
|
||||
<TextBlock Text="Total:" />
|
||||
<TextBlock Grid.Column="1" Text="{Binding Total}" />
|
||||
</Grid>
|
||||
```
|
||||
|
||||
Create a generic component (or use `EdgePanel` with a Style):
|
||||
|
||||
```xml
|
||||
<!-- ✅ GOOD: Use a specialized control or style -->
|
||||
<EdgePanel StartContent="Total:" EndContent="{Binding Total}" Classes="SummaryItem" />
|
||||
```
|
||||
|
||||
## 📉 Flattening Layouts
|
||||
|
||||
Avoid deep nesting. Deeply nested XAML is hard to read and can impact performance.
|
||||
|
||||
- **StackPanel vs Grid**: Use `StackPanel` (with `Spacing`) for simple linear layouts.
|
||||
- **EdgePanel**: Great for "Label - Value" or "Icon - Text - Action" rows.
|
||||
- **UniformGrid**: Use for grids where all cells are the same size.
|
||||
|
||||
## 🔧 Component Granularity
|
||||
|
||||
- **Atomical**: Small controls like custom buttons or icons.
|
||||
- **Molecular**: Groups of atoms like a `HeaderedContainer` with specific content.
|
||||
- **Organisms**: Higher-level sections of a page.
|
||||
|
||||
Aim for components that are generic enough to be reused but specific enough to simplify the parent view significantly.
|
||||
50
skills/avalonia-layout-zafiro/containers.md
Normal file
50
skills/avalonia-layout-zafiro/containers.md
Normal file
@@ -0,0 +1,50 @@
|
||||
# Semantic Containers
|
||||
|
||||
Using the right container for the data type simplifies XAML and improves maintainability. `Zafiro.Avalonia` provides specialized controls for common layout patterns.
|
||||
|
||||
## 📦 HeaderedContainer
|
||||
|
||||
Prefer `HeaderedContainer` over a `Border` or `Grid` when a section needs a title or header.
|
||||
|
||||
```xml
|
||||
<HeaderedContainer Header="Security Settings" Classes="WizardSection">
|
||||
<StackPanel>
|
||||
<!-- Content here -->
|
||||
</StackPanel>
|
||||
</HeaderedContainer>
|
||||
```
|
||||
|
||||
### Key Properties:
|
||||
- `Header`: The content or string for the header.
|
||||
- `HeaderBackground`: Brush for the header area.
|
||||
- `ContentPadding`: Padding for the content area.
|
||||
|
||||
## ↔️ EdgePanel
|
||||
|
||||
Use `EdgePanel` to position elements at the edges of a container without complex `Grid` definitions.
|
||||
|
||||
```xml
|
||||
<EdgePanel StartContent="{Icon fa-wallet}"
|
||||
Content="Wallet Balance"
|
||||
EndContent="$1,234.00" />
|
||||
```
|
||||
|
||||
### Slots:
|
||||
- `StartContent`: Aligned to the left (or beginning).
|
||||
- `Content`: Fills the remaining space in the middle.
|
||||
- `EndContent`: Aligned to the right (or end).
|
||||
|
||||
## 📇 Card
|
||||
|
||||
A simple container for grouping related information, often used inside `HeaderedContainer` or as a standalone element in a list.
|
||||
|
||||
```xml
|
||||
<Card Header="Enter recipient address:">
|
||||
<TextBox Text="{Binding Address}" />
|
||||
</Card>
|
||||
```
|
||||
|
||||
## 📐 Best Practices
|
||||
|
||||
- Use `Classes` to apply themed variants (e.g., `Classes="Section"`, `Classes="Highlight"`).
|
||||
- Customize internal parts of the containers using templates in your styles when necessary, rather than nesting more controls.
|
||||
53
skills/avalonia-layout-zafiro/icons.md
Normal file
53
skills/avalonia-layout-zafiro/icons.md
Normal file
@@ -0,0 +1,53 @@
|
||||
# Icon Usage
|
||||
|
||||
`Zafiro.Avalonia` simplifies icon management using a specialized markup extension and styling options.
|
||||
|
||||
## 🛠️ IconExtension
|
||||
|
||||
Use the `{Icon}` markup extension to easily include icons from libraries like FontAwesome.
|
||||
|
||||
```xml
|
||||
<!-- Positional parameter -->
|
||||
<Button Content="{Icon fa-wallet}" />
|
||||
|
||||
<!-- Named parameter -->
|
||||
<ContentControl Content="{Icon Source=fa-gear}" />
|
||||
```
|
||||
|
||||
## 🎨 IconOptions
|
||||
|
||||
`IconOptions` allows you to customize icons without manually wrapping them in other controls. It's often used in styles to provide a consistent look.
|
||||
|
||||
```xml
|
||||
<Style Selector="HeaderedContainer /template/ ContentPresenter#Header EdgePanel /template/ ContentControl#StartContent">
|
||||
<Setter Property="IconOptions.Size" Value="20" />
|
||||
<Setter Property="IconOptions.Fill" Value="{DynamicResource Accent}" />
|
||||
<Setter Property="IconOptions.Padding" Value="10" />
|
||||
<Setter Property="IconOptions.CornerRadius" Value="10" />
|
||||
</Style>
|
||||
```
|
||||
|
||||
### Common Properties:
|
||||
- `IconOptions.Size`: Sets the width and height of the icon.
|
||||
- `IconOptions.Fill`: The color/brush of the icon.
|
||||
- `IconOptions.Background`: Background brush for the icon container.
|
||||
- `IconOptions.Padding`: Padding inside the icon container.
|
||||
- `IconOptions.CornerRadius`: Corner radius if a background is used.
|
||||
|
||||
## 📁 Shared Icon Resources
|
||||
|
||||
Define icons as resources for reuse across the application.
|
||||
|
||||
```xml
|
||||
<ResourceDictionary xmlns="https://github.com/avaloniaui">
|
||||
<Icon x:Key="fa-wallet" Source="fa-wallet" />
|
||||
</ResourceDictionary>
|
||||
```
|
||||
|
||||
Then use them with `StaticResource` if they are already defined:
|
||||
|
||||
```xml
|
||||
<Button Content="{StaticResource fa-wallet}" />
|
||||
```
|
||||
|
||||
However, the `{Icon ...}` extension is usually preferred for its brevity and ability to create new icon instances on the fly.
|
||||
51
skills/avalonia-layout-zafiro/themes.md
Normal file
51
skills/avalonia-layout-zafiro/themes.md
Normal file
@@ -0,0 +1,51 @@
|
||||
# Theme Organization and Shared Styles
|
||||
|
||||
Efficient theme organization is key to avoiding redundant XAML and ensuring visual consistency.
|
||||
|
||||
## 🏗️ Structure
|
||||
|
||||
Follow the pattern from Angor:
|
||||
|
||||
1. **Colors & Brushes**: Define in a dedicated `Colors.axaml`. Use `DynamicResource` to support theme switching.
|
||||
2. **Styles**: Group styles by category (e.g., `Buttons.axaml`, `Containers.axaml`, `Typography.axaml`).
|
||||
3. **App-wide Theme**: Aggregate all styles in a main `Theme.axaml`.
|
||||
|
||||
## 🎨 Avoiding Redundancy
|
||||
|
||||
Instead of setting properties directly on elements:
|
||||
|
||||
```xml
|
||||
<!-- ❌ BAD: Redundant properties -->
|
||||
<HeaderedContainer CornerRadius="10" BorderThickness="1" BorderBrush="Blue" Background="LightBlue" />
|
||||
<HeaderedContainer CornerRadius="10" BorderThickness="1" BorderBrush="Blue" Background="LightBlue" />
|
||||
|
||||
<!-- ✅ GOOD: Use Classes and Styles -->
|
||||
<HeaderedContainer Classes="BlueSection" />
|
||||
<HeaderedContainer Classes="BlueSection" />
|
||||
```
|
||||
|
||||
Define the style in a shared `axaml` file:
|
||||
|
||||
```xml
|
||||
<Style Selector="HeaderedContainer.BlueSection">
|
||||
<Setter Property="CornerRadius" Value="10" />
|
||||
<Setter Property="BorderThickness" Value="1" />
|
||||
<Setter Property="BorderBrush" Value="{DynamicResource Accent}" />
|
||||
<Setter Property="Background" Value="{DynamicResource SurfaceSubtle}" />
|
||||
</Style>
|
||||
```
|
||||
|
||||
## 🧩 Shared Icons and Resources
|
||||
|
||||
Centralize icon definitions and other shared resources in `Icons.axaml` and include them in the `MergedDictionaries` of your theme or `App.axaml`.
|
||||
|
||||
```xml
|
||||
<Application.Resources>
|
||||
<ResourceDictionary>
|
||||
<ResourceDictionary.MergedDictionaries>
|
||||
<MergeResourceInclude Source="UI/Themes/Styles/Containers.axaml" />
|
||||
<MergeResourceInclude Source="UI/Shared/Resources/Icons.axaml" />
|
||||
</ResourceDictionary.MergedDictionaries>
|
||||
</ResourceDictionary>
|
||||
</Application.Resources>
|
||||
```
|
||||
29
skills/avalonia-viewmodels-zafiro/SKILL.md
Normal file
29
skills/avalonia-viewmodels-zafiro/SKILL.md
Normal file
@@ -0,0 +1,29 @@
|
||||
---
|
||||
name: avalonia-viewmodels-zafiro
|
||||
description: Optimal ViewModel and Wizard creation patterns for Avalonia using Zafiro and ReactiveUI.
|
||||
---
|
||||
|
||||
# Avalonia ViewModels with Zafiro
|
||||
|
||||
This skill provides a set of best practices and patterns for creating ViewModels, Wizards, and managing navigation in Avalonia applications, leveraging the power of **ReactiveUI** and the **Zafiro** toolkit.
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **Functional-Reactive Approach**: Use ReactiveUI (`ReactiveObject`, `WhenAnyValue`, etc.) to handle state and logic.
|
||||
2. **Enhanced Commands**: Utilize `IEnhancedCommand` for better command management, including progress reporting and name/text attributes.
|
||||
3. **Wizard Pattern**: Implement complex flows using `SlimWizard` and `WizardBuilder` for a declarative and maintainable approach.
|
||||
4. **Automatic Section Discovery**: Use the `[Section]` attribute to register and discover UI sections automatically.
|
||||
5. **Clean Composition**: map ViewModels to Views using `DataTypeViewLocator` and manage dependencies in the `CompositionRoot`.
|
||||
|
||||
## Guides
|
||||
|
||||
- [ViewModels & Commands](viewmodels.md): Creating robust ViewModels and handling commands.
|
||||
- [Wizards & Flows](wizards.md): Building multi-step wizards with `SlimWizard`.
|
||||
- [Navigation & Sections](navigation_sections.md): Managing navigation and section-based UIs.
|
||||
- [Composition & Mapping](composition.md): Best practices for View-ViewModel wiring and DI.
|
||||
|
||||
## Example Reference
|
||||
|
||||
For real-world implementations, refer to the **Angor** project:
|
||||
- `CreateProjectFlowV2.cs`: Excellent example of complex Wizard building.
|
||||
- `HomeViewModel.cs`: Simple section ViewModel using functional-reactive commands.
|
||||
75
skills/avalonia-viewmodels-zafiro/composition.md
Normal file
75
skills/avalonia-viewmodels-zafiro/composition.md
Normal file
@@ -0,0 +1,75 @@
|
||||
# Composition & Mapping
|
||||
|
||||
Ensuring your ViewModels are correctly instantiated and mapped to their corresponding Views is crucial for a maintainable application.
|
||||
|
||||
## ViewModel-to-View Mapping
|
||||
|
||||
Zafiro uses the `DataTypeViewLocator` to automatically map ViewModels to Views based on their data type.
|
||||
|
||||
### Integration in App.axaml
|
||||
|
||||
Register the `DataTypeViewLocator` in your application's data templates:
|
||||
|
||||
```xml
|
||||
<Application.DataTemplates>
|
||||
<DataTypeViewLocator />
|
||||
<DataTemplateInclude Source="avares://Zafiro.Avalonia/DataTemplates.axaml" />
|
||||
</Application.DataTemplates>
|
||||
```
|
||||
|
||||
### Registration
|
||||
|
||||
Mappings can be registered globally or locally. Common practice in Zafiro projects is to use naming conventions or explicit registrations made by source generators.
|
||||
|
||||
## Composition Root
|
||||
|
||||
Use a central `CompositionRoot` to manage dependency injection and service registration.
|
||||
|
||||
```csharp
|
||||
public static class CompositionRoot
|
||||
{
|
||||
public static IShellViewModel CreateMainViewModel(Control topLevelView)
|
||||
{
|
||||
var services = new ServiceCollection();
|
||||
|
||||
services
|
||||
.AddViewModels()
|
||||
.AddUIServices(topLevelView);
|
||||
|
||||
var serviceProvider = services.BuildServiceProvider();
|
||||
return serviceProvider.GetRequiredService<IShellViewModel>();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Registering ViewModels
|
||||
|
||||
Register ViewModels with appropriate scopes (Transient, Scoped, or Singleton).
|
||||
|
||||
```csharp
|
||||
public static IServiceCollection AddViewModels(this IServiceCollection services)
|
||||
{
|
||||
return services
|
||||
.AddTransient<IHomeSectionViewModel, HomeSectionSectionViewModel>()
|
||||
.AddSingleton<IShellViewModel, ShellViewModel>();
|
||||
}
|
||||
```
|
||||
|
||||
## View Injection
|
||||
|
||||
Use the `Connect` helper (if available) or manual instantiation in `OnFrameworkInitializationCompleted`:
|
||||
|
||||
```csharp
|
||||
public override void OnFrameworkInitializationCompleted()
|
||||
{
|
||||
this.Connect(
|
||||
() => new ShellView(),
|
||||
view => CompositionRoot.CreateMainViewModel(view),
|
||||
() => new MainWindow());
|
||||
|
||||
base.OnFrameworkInitializationCompleted();
|
||||
}
|
||||
```
|
||||
|
||||
> [!TIP]
|
||||
> Use `ActivatorUtilities.CreateInstance` when you need to manually instantiate a class while still resolving its dependencies from the `IServiceProvider`.
|
||||
53
skills/avalonia-viewmodels-zafiro/navigation_sections.md
Normal file
53
skills/avalonia-viewmodels-zafiro/navigation_sections.md
Normal file
@@ -0,0 +1,53 @@
|
||||
# Navigation & Sections
|
||||
|
||||
Zafiro provides powerful abstractions for managing application-wide navigation and modular UI sections.
|
||||
|
||||
## Navigation with INavigator
|
||||
|
||||
The `INavigator` interface is used to switch between different views or viewmodels.
|
||||
|
||||
```csharp
|
||||
public class MyViewModel(INavigator navigator)
|
||||
{
|
||||
public async Task GoToDetails()
|
||||
{
|
||||
await navigator.Navigate(() => new DetailsViewModel());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## UI Sections
|
||||
|
||||
Sections are modular parts of the UI (like tabs or sidebar items) that can be automatically registered.
|
||||
|
||||
### The [Section] Attribute
|
||||
|
||||
ViewModels intended to be sections should be marked with the `[Section]` attribute.
|
||||
|
||||
```csharp
|
||||
[Section("Wallet", icon: "fa-wallet")]
|
||||
public class WalletSectionViewModel : IWalletSectionViewModel
|
||||
{
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### Automatic Registration
|
||||
|
||||
In the `CompositionRoot`, sections can be automatically registered:
|
||||
|
||||
```csharp
|
||||
services.AddAnnotatedSections(logger);
|
||||
services.AddSectionsFromAttributes(logger);
|
||||
```
|
||||
|
||||
### Switching Sections
|
||||
|
||||
You can switch the current active section via the `IShellViewModel`:
|
||||
|
||||
```csharp
|
||||
shellViewModel.SetSection("Browse");
|
||||
```
|
||||
|
||||
> [!IMPORTANT]
|
||||
> The `icon` parameter in the `[Section]` attribute supports FontAwesome icons (e.g., `fa-home`) when configured with `ProjektankerIconControlProvider`.
|
||||
68
skills/avalonia-viewmodels-zafiro/viewmodels.md
Normal file
68
skills/avalonia-viewmodels-zafiro/viewmodels.md
Normal file
@@ -0,0 +1,68 @@
|
||||
# ViewModels & Commands
|
||||
|
||||
In a Zafiro-based application, ViewModels should be functional, reactive, and resilient.
|
||||
|
||||
## Reactive ViewModels
|
||||
|
||||
Use `ReactiveObject` as the base class. Properties should be defined using the `[Reactive]` attribute (from ReactiveUI.SourceGenerators) for brevity.
|
||||
|
||||
```csharp
|
||||
public partial class MyViewModel : ReactiveObject
|
||||
{
|
||||
[Reactive] private string name;
|
||||
[Reactive] private bool isBusy;
|
||||
}
|
||||
```
|
||||
|
||||
### Observation and Transformation
|
||||
|
||||
Use `WhenAnyValue` to react to property changes:
|
||||
|
||||
```csharp
|
||||
this.WhenAnyValue(x => x.Name)
|
||||
.Select(name => !string.IsNullOrEmpty(name))
|
||||
.ToPropertyEx(this, x => x.CanSubmit);
|
||||
```
|
||||
|
||||
## Enhanced Commands
|
||||
|
||||
Zafiro uses `IEnhancedCommand`, which extends `ICommand` and `IReactiveCommand` with additional metadata like `Name` and `Text`.
|
||||
|
||||
### Creating a Command
|
||||
|
||||
Use `ReactiveCommand.Create` or `ReactiveCommand.CreateFromTask` and then `Enhance()` it.
|
||||
|
||||
```csharp
|
||||
public IEnhancedCommand Submit { get; }
|
||||
|
||||
public MyViewModel()
|
||||
{
|
||||
Submit = ReactiveCommand.CreateFromTask(OnSubmit, canSubmit)
|
||||
.Enhance(text: "Submit Data", name: "SubmitCommand");
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
Use `HandleErrorsWith` to automatically channel command errors to the `NotificationService`.
|
||||
|
||||
```csharp
|
||||
Submit.HandleErrorsWith(uiServices.NotificationService, "Submission Failed")
|
||||
.DisposeWith(disposable);
|
||||
```
|
||||
|
||||
## Disposables
|
||||
|
||||
Always use a `CompositeDisposable` to manage subscriptions and command lifetimes.
|
||||
|
||||
```csharp
|
||||
public class MyViewModel : ReactiveObject, IDisposable
|
||||
{
|
||||
private readonly CompositeDisposable disposables = new();
|
||||
|
||||
public void Dispose() => disposables.Dispose();
|
||||
}
|
||||
```
|
||||
|
||||
> [!TIP]
|
||||
> Use `.DisposeWith(disposables)` on any observable subscription or command to ensure proper cleanup.
|
||||
47
skills/avalonia-viewmodels-zafiro/wizards.md
Normal file
47
skills/avalonia-viewmodels-zafiro/wizards.md
Normal file
@@ -0,0 +1,47 @@
|
||||
# Wizards & Flows
|
||||
|
||||
Complex multi-step processes are handled using the `SlimWizard` pattern. This provides a declarative way to define steps, navigation logic, and final results.
|
||||
|
||||
## Defining a Wizard
|
||||
|
||||
Use `WizardBuilder` to define the steps. Each step corresponds to a ViewModel.
|
||||
|
||||
```csharp
|
||||
SlimWizard<string> wizard = WizardBuilder
|
||||
.StartWith(() => new Step1ViewModel(data))
|
||||
.NextUnit()
|
||||
.WhenValid()
|
||||
.Then(prevResult => new Step2ViewModel(prevResult))
|
||||
.NextCommand(vm => vm.CustomNextCommand)
|
||||
.Then(result => new SuccessViewModel("Done!"))
|
||||
.Next((_, s) => s, "Finish")
|
||||
.WithCompletionFinalStep();
|
||||
```
|
||||
|
||||
### Navigation Rules
|
||||
|
||||
- **NextUnit()**: Advances when a simple signal is emitted.
|
||||
- **NextCommand()**: Advances when a specific command in the ViewModel execution successfully.
|
||||
- **WhenValid()**: Wait until the current ViewModel's validation passes before allowing navigation.
|
||||
- **Always()**: Navigation is always allowed.
|
||||
|
||||
## Navigation Integration
|
||||
|
||||
The wizard is navigated using an `INavigator`:
|
||||
|
||||
```csharp
|
||||
public async Task CreateSomething()
|
||||
{
|
||||
var wizard = BuildWizard();
|
||||
var result = await wizard.Navigate(navigator);
|
||||
// Handle result
|
||||
}
|
||||
```
|
||||
|
||||
## Step Configuration
|
||||
|
||||
- **WithCompletionFinalStep()**: Marks the wizard as finished when the last step completes.
|
||||
- **WithCommitFinalStep()**: Typically used for wizards that perform a final "Save" or "Deploy" action.
|
||||
|
||||
> [!NOTE]
|
||||
> The `SlimWizard` handles the "Back" command automatically, providing a consistent user experience across different flows.
|
||||
29
skills/avalonia-zafiro-development/SKILL.md
Normal file
29
skills/avalonia-zafiro-development/SKILL.md
Normal file
@@ -0,0 +1,29 @@
|
||||
---
|
||||
name: avalonia-zafiro-development
|
||||
description: Mandatory skills, conventions, and behavioral rules for Avalonia UI development using the Zafiro toolkit.
|
||||
---
|
||||
|
||||
# Avalonia Zafiro Development
|
||||
|
||||
This skill defines the mandatory conventions and behavioral rules for developing cross-platform applications with Avalonia UI and the Zafiro toolkit. These rules prioritize maintainability, correctness, and a functional-reactive approach.
|
||||
|
||||
## Core Pillars
|
||||
|
||||
1. **Functional-Reactive MVVM**: Pure MVVM logic using DynamicData and ReactiveUI.
|
||||
2. **Safety & Predictability**: Explicit error handling with `Result` types and avoidance of exceptions for flow control.
|
||||
3. **Cross-Platform Excellence**: Strictly Avalonia-independent ViewModels and composition-over-inheritance.
|
||||
4. **Zafiro First**: Leverage existing Zafiro abstractions and helpers to avoid redundancy.
|
||||
|
||||
## Guides
|
||||
|
||||
- [Core Technical Skills & Architecture](core-technical-skills.md): Fundamental skills and architectural principles.
|
||||
- [Naming & Coding Standards](naming-standards.md): Rules for naming, fields, and error handling.
|
||||
- [Avalonia, Zafiro & Reactive Rules](avalonia-reactive-rules.md): Specific guidelines for UI, Zafiro integration, and DynamicData pipelines.
|
||||
- [Zafiro Shortcuts](zafiro-shortcuts.md): Concise mappings for common Rx/Zafiro operations.
|
||||
- [Common Patterns](patterns.md): Advanced patterns like `RefreshableCollection` and Validation.
|
||||
|
||||
## Procedure Before Writing Code
|
||||
|
||||
1. **Search First**: Search the codebase for similar implementations or existing Zafiro helpers.
|
||||
2. **Reusable Extensions**: If a helper is missing, propose a new reusable extension method instead of inlining complex logic.
|
||||
3. **Reactive Pipelines**: Ensure DynamicData operators are used instead of plain Rx where applicable.
|
||||
@@ -0,0 +1,49 @@
|
||||
# Avalonia, Zafiro & Reactive Rules
|
||||
|
||||
## Avalonia UI Rules
|
||||
|
||||
- **Strict Avalonia**: Never use `System.Drawing`; always use Avalonia types.
|
||||
- **Pure ViewModels**: ViewModels must **never** reference Avalonia types.
|
||||
- **Bindings Over Code-Behind**: Logic should be driven by bindings.
|
||||
- **DataTemplates**: Prefer explicit `DataTemplate`s and typed `DataContext`s.
|
||||
- **VisualStates**: Avoid using `VisualStates` unless absolutely required.
|
||||
|
||||
## Zafiro Guidelines
|
||||
|
||||
- **Prefer Abstractions**: Always look for existing Zafiro helpers, extension methods, and abstractions before re-implementing logic.
|
||||
- **Validation**: Use Zafiro's `ValidationRule` and validation extensions instead of ad-hoc reactive logic.
|
||||
|
||||
## DynamicData & Reactive Rules
|
||||
|
||||
### The Mandatory Approach
|
||||
|
||||
- **Operator Preference**: Always prefer **DynamicData** operators (`Connect`, `Filter`, `Transform`, `Sort`, `Bind`, `DisposeMany`) over plain Rx operators when working with collections.
|
||||
- **Readable Pipelines**: Build and maintain pipelines as a single, readable chain.
|
||||
- **Lifecycle**: Use `DisposeWith` for lifecycle management.
|
||||
- **Minimal Subscriptions**: Subscriptions should be minimal, centralized, and strictly for side-effects.
|
||||
|
||||
### Forbidden Anti-Patterns
|
||||
|
||||
- **Ad-hoc Sources**: Do NOT create new `SourceList` / `SourceCache` on the fly for local problems.
|
||||
- **Logic in Subscribe**: Do NOT place business logic inside `Subscribe`.
|
||||
- **Operator Mismatch**: Do NOT use `System.Reactive` operators if a DynamicData equivalent exists.
|
||||
|
||||
### Canonical Patterns
|
||||
|
||||
**Validation of Dynamic Collections:**
|
||||
```csharp
|
||||
this.ValidationRule(
|
||||
StagesSource
|
||||
.Connect()
|
||||
.FilterOnObservable(stage => stage.IsValid)
|
||||
.IsEmpty(),
|
||||
b => !b,
|
||||
_ => "Stages are not valid")
|
||||
.DisposeWith(Disposables);
|
||||
```
|
||||
|
||||
**Filtering Nulls:**
|
||||
Use `WhereNotNull()` in reactive pipelines.
|
||||
```csharp
|
||||
this.WhenAnyValue(x => x.DurationPreset).WhereNotNull()
|
||||
```
|
||||
19
skills/avalonia-zafiro-development/core-technical-skills.md
Normal file
19
skills/avalonia-zafiro-development/core-technical-skills.md
Normal file
@@ -0,0 +1,19 @@
|
||||
# Core Technical Skills & Architecture
|
||||
|
||||
## Mandatory Expertise
|
||||
|
||||
The developer must possess strong expertise in:
|
||||
- **C# and modern .NET**: Utilizing the latest features of the language and framework.
|
||||
- **Avalonia UI**: For cross-platform UI development.
|
||||
- **MVVM Architecture**: Maintaining strict separation between UI and business logic.
|
||||
- **Clean Code & Clean Architecture**: Focusing on maintainability and inward dependency flow.
|
||||
- **Functional Programming in C#**: Embracing immutability and functional patterns.
|
||||
- **Reactive Programming**: Expertise in DynamicData and System.Reactive.
|
||||
|
||||
## Architectural Principles
|
||||
|
||||
- **Pure MVVM**: Mandatory for all UI code. Logic must be independent of UI concerns.
|
||||
- **Composition over Inheritance**: Favor modular building blocks over deep inheritance hierarchies.
|
||||
- **Inward Dependency Flow**: Abstractions must not depend on implementations.
|
||||
- **Immutability**: Prefer immutable structures where practical to ensure predictability.
|
||||
- **Stable Public APIs**: Design APIs carefully to ensure long-term stability and clarity.
|
||||
15
skills/avalonia-zafiro-development/naming-standards.md
Normal file
15
skills/avalonia-zafiro-development/naming-standards.md
Normal file
@@ -0,0 +1,15 @@
|
||||
# Naming & Coding Standards
|
||||
|
||||
## General Standards
|
||||
|
||||
- **Explicit Names**: Favor clarity over cleverness.
|
||||
- **Async Suffix**: Do **NOT** use the `Async` suffix in method names, even if they return `Task`.
|
||||
- **Private Fields**: Do **NOT** use the `_` prefix for private fields.
|
||||
- **Static State**: Avoid static state unless explicitly justified and documented.
|
||||
- **Method Design**: Keep methods small, expressive, and with low cyclomatic complexity.
|
||||
|
||||
## Error Handling
|
||||
|
||||
- **Result & Maybe**: Use types from **CSharpFunctionalExtensions** for flow control and error handling.
|
||||
- **Exceptions**: Reserved strictly for truly exceptional, unrecoverable situations.
|
||||
- **Boundaries**: Never allow exceptions to leak across architectural boundaries.
|
||||
45
skills/avalonia-zafiro-development/patterns.md
Normal file
45
skills/avalonia-zafiro-development/patterns.md
Normal file
@@ -0,0 +1,45 @@
|
||||
# Common Patterns in Angor/Zafiro
|
||||
|
||||
## Refreshable Collections
|
||||
|
||||
The `RefreshableCollection` pattern is used to manage lists that can be refreshed via a command, maintaining an internal `SourceCache`/`SourceList` and exposing a `ReadOnlyObservableCollection`.
|
||||
|
||||
### Implementation
|
||||
|
||||
```csharp
|
||||
var refresher = RefreshableCollection.Create(
|
||||
() => GetDataTask(),
|
||||
model => model.Id)
|
||||
.DisposeWith(disposable);
|
||||
|
||||
LoadData = refresher.Refresh;
|
||||
Items = refresher.Items;
|
||||
```
|
||||
|
||||
### Benefits
|
||||
- **Automatic Loading**: Handles the command execution and results.
|
||||
- **Efficient Updates**: Uses `EditDiff` internally to update items without clearing the list.
|
||||
- **UI Friendly**: Exposes `Items` as a `ReadOnlyObservableCollection` suitable for binding.
|
||||
|
||||
## Mandatory Validation Pattern
|
||||
|
||||
When validating dynamic collections, always use the Zafiro validation extension:
|
||||
|
||||
```csharp
|
||||
this.ValidationRule(
|
||||
StagesSource
|
||||
.Connect()
|
||||
.FilterOnObservable(stage => stage.IsValid)
|
||||
.IsEmpty(),
|
||||
b => !b,
|
||||
_ => "Stages are not valid")
|
||||
.DisposeWith(Disposables);
|
||||
```
|
||||
|
||||
## Error Handling Pipeline
|
||||
|
||||
Instead of manual `Subscribe`, use `HandleErrorsWith` to pipe errors directly to the user:
|
||||
|
||||
```csharp
|
||||
LoadProjects.HandleErrorsWith(uiServices.NotificationService, "Could not load projects");
|
||||
```
|
||||
43
skills/avalonia-zafiro-development/zafiro-shortcuts.md
Normal file
43
skills/avalonia-zafiro-development/zafiro-shortcuts.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# Zafiro Reactive Shortcuts
|
||||
|
||||
Use these Zafiro extension methods to replace standard, more verbose Reactive and DynamicData patterns.
|
||||
|
||||
## General Observable Helpers
|
||||
|
||||
| Standard Pattern | Zafiro Shortcut |
|
||||
| :--- | :--- |
|
||||
| `Replay(1).RefCount()` | `ReplayLastActive()` |
|
||||
| `Select(_ => Unit.Default)` | `ToSignal()` |
|
||||
| `Select(b => !b)` | `Not()` |
|
||||
| `Where(b => b).ToSignal()` | `Trues()` |
|
||||
| `Where(b => !b).ToSignal()` | `Falses()` |
|
||||
| `Select(x => x is null)` | `Null()` |
|
||||
| `Select(x => x is not null)` | `NotNull()` |
|
||||
| `Select(string.IsNullOrWhiteSpace)` | `NullOrWhitespace()` |
|
||||
| `Select(s => !string.IsNullOrWhiteSpace(s))` | `NotNullOrEmpty()` |
|
||||
|
||||
## Result & Maybe Extensions
|
||||
|
||||
| Standard Pattern | Zafiro Shortcut |
|
||||
| :--- | :--- |
|
||||
| `Where(r => r.IsSuccess).Select(r => r.Value)` | `Successes()` |
|
||||
| `Where(r => r.IsFailure).Select(r => r.Error)` | `Failures()` |
|
||||
| `Where(m => m.HasValue).Select(m => m.Value)` | `Values()` |
|
||||
| `Where(m => !m.HasValue).ToSignal()` | `Empties()` |
|
||||
|
||||
## Lifecycle Management
|
||||
|
||||
| Description | Method |
|
||||
| :--- | :--- |
|
||||
| Dispose previous item before emitting new one | `DisposePrevious()` |
|
||||
| Manage lifecycle within a disposable | `DisposeWith(disposables)` |
|
||||
|
||||
## Command & Interaction
|
||||
|
||||
| Description | Method |
|
||||
| :--- | :--- |
|
||||
| Add metadata/text to a ReactiveCommand | `Enhance(text, name)` |
|
||||
| Automatically show errors in UI | `HandleErrorsWith(notificationService)` |
|
||||
|
||||
> [!TIP]
|
||||
> Always check `Zafiro.Reactive.ObservableMixin` and `Zafiro.CSharpFunctionalExtensions.ObservableExtensions` before writing custom Rx logic.
|
||||
@@ -1,54 +1,230 @@
|
||||
---
|
||||
name: brainstorming
|
||||
description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
|
||||
description: >
|
||||
Use this skill before any creative or constructive work
|
||||
(features, components, architecture, behavior changes, or functionality).
|
||||
This skill transforms vague ideas into validated designs through
|
||||
disciplined, incremental reasoning and collaboration.
|
||||
---
|
||||
|
||||
# Brainstorming Ideas Into Designs
|
||||
|
||||
## Overview
|
||||
## Purpose
|
||||
|
||||
Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
|
||||
Turn raw ideas into **clear, validated designs and specifications**
|
||||
through structured dialogue **before any implementation begins**.
|
||||
|
||||
Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.
|
||||
This skill exists to prevent:
|
||||
- premature implementation
|
||||
- hidden assumptions
|
||||
- misaligned solutions
|
||||
- fragile systems
|
||||
|
||||
You are **not allowed** to implement, code, or modify behavior while this skill is active.
|
||||
|
||||
---
|
||||
|
||||
## Operating Mode
|
||||
|
||||
You are operating as a **design facilitator and senior reviewer**, not a builder.
|
||||
|
||||
- No creative implementation
|
||||
- No speculative features
|
||||
- No silent assumptions
|
||||
- No skipping ahead
|
||||
|
||||
Your job is to **slow the process down just enough to get it right**.
|
||||
|
||||
---
|
||||
|
||||
## The Process
|
||||
|
||||
**Understanding the idea:**
|
||||
- Check out the current project state first (files, docs, recent commits)
|
||||
- Ask questions one at a time to refine the idea
|
||||
- Prefer multiple choice questions when possible, but open-ended is fine too
|
||||
- Only one question per message - if a topic needs more exploration, break it into multiple questions
|
||||
- Focus on understanding: purpose, constraints, success criteria
|
||||
### 1️⃣ Understand the Current Context (Mandatory First Step)
|
||||
|
||||
**Exploring approaches:**
|
||||
- Propose 2-3 different approaches with trade-offs
|
||||
- Present options conversationally with your recommendation and reasoning
|
||||
- Lead with your recommended option and explain why
|
||||
Before asking any questions:
|
||||
|
||||
**Presenting the design:**
|
||||
- Once you believe you understand what you're building, present the design
|
||||
- Break it into sections of 200-300 words
|
||||
- Ask after each section whether it looks right so far
|
||||
- Cover: architecture, components, data flow, error handling, testing
|
||||
- Be ready to go back and clarify if something doesn't make sense
|
||||
- Review the current project state (if available):
|
||||
- files
|
||||
- documentation
|
||||
- plans
|
||||
- prior decisions
|
||||
- Identify what already exists vs. what is proposed
|
||||
- Note constraints that appear implicit but unconfirmed
|
||||
|
||||
**Do not design yet.**
|
||||
|
||||
---
|
||||
|
||||
### 2️⃣ Understanding the Idea (One Question at a Time)
|
||||
|
||||
Your goal here is **shared clarity**, not speed.
|
||||
|
||||
**Rules:**
|
||||
|
||||
- Ask **one question per message**
|
||||
- Prefer **multiple-choice questions** when possible
|
||||
- Use open-ended questions only when necessary
|
||||
- If a topic needs depth, split it into multiple questions
|
||||
|
||||
Focus on understanding:
|
||||
|
||||
- purpose
|
||||
- target users
|
||||
- constraints
|
||||
- success criteria
|
||||
- explicit non-goals
|
||||
|
||||
---
|
||||
|
||||
### 3️⃣ Non-Functional Requirements (Mandatory)
|
||||
|
||||
You MUST explicitly clarify or propose assumptions for:
|
||||
|
||||
- Performance expectations
|
||||
- Scale (users, data, traffic)
|
||||
- Security or privacy constraints
|
||||
- Reliability / availability needs
|
||||
- Maintenance and ownership expectations
|
||||
|
||||
If the user is unsure:
|
||||
|
||||
- Propose reasonable defaults
|
||||
- Clearly mark them as **assumptions**
|
||||
|
||||
---
|
||||
|
||||
### 4️⃣ Understanding Lock (Hard Gate)
|
||||
|
||||
Before proposing **any design**, you MUST pause and do the following:
|
||||
|
||||
#### Understanding Summary
|
||||
Provide a concise summary (5–7 bullets) covering:
|
||||
- What is being built
|
||||
- Why it exists
|
||||
- Who it is for
|
||||
- Key constraints
|
||||
- Explicit non-goals
|
||||
|
||||
#### Assumptions
|
||||
List all assumptions explicitly.
|
||||
|
||||
#### Open Questions
|
||||
List unresolved questions, if any.
|
||||
|
||||
Then ask:
|
||||
|
||||
> “Does this accurately reflect your intent?
|
||||
> Please confirm or correct anything before we move to design.”
|
||||
|
||||
**Do NOT proceed until explicit confirmation is given.**
|
||||
|
||||
---
|
||||
|
||||
### 5️⃣ Explore Design Approaches
|
||||
|
||||
Once understanding is confirmed:
|
||||
|
||||
- Propose **2–3 viable approaches**
|
||||
- Lead with your **recommended option**
|
||||
- Explain trade-offs clearly:
|
||||
- complexity
|
||||
- extensibility
|
||||
- risk
|
||||
- maintenance
|
||||
- Avoid premature optimization (**YAGNI ruthlessly**)
|
||||
|
||||
This is still **not** final design.
|
||||
|
||||
---
|
||||
|
||||
### 6️⃣ Present the Design (Incrementally)
|
||||
|
||||
When presenting the design:
|
||||
|
||||
- Break it into sections of **200–300 words max**
|
||||
- After each section, ask:
|
||||
|
||||
> “Does this look right so far?”
|
||||
|
||||
Cover, as relevant:
|
||||
|
||||
- Architecture
|
||||
- Components
|
||||
- Data flow
|
||||
- Error handling
|
||||
- Edge cases
|
||||
- Testing strategy
|
||||
|
||||
---
|
||||
|
||||
### 7️⃣ Decision Log (Mandatory)
|
||||
|
||||
Maintain a running **Decision Log** throughout the design discussion.
|
||||
|
||||
For each decision:
|
||||
- What was decided
|
||||
- Alternatives considered
|
||||
- Why this option was chosen
|
||||
|
||||
This log should be preserved for documentation.
|
||||
|
||||
---
|
||||
|
||||
## After the Design
|
||||
|
||||
**Documentation:**
|
||||
- Write the validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md`
|
||||
- Use elements-of-style:writing-clearly-and-concisely skill if available
|
||||
- Commit the design document to git
|
||||
### 📄 Documentation
|
||||
|
||||
**Implementation (if continuing):**
|
||||
- Ask: "Ready to set up for implementation?"
|
||||
- Use superpowers:using-git-worktrees to create isolated workspace
|
||||
- Use superpowers:writing-plans to create detailed implementation plan
|
||||
Once the design is validated:
|
||||
|
||||
## Key Principles
|
||||
- Write the final design to a durable, shared format (e.g. Markdown)
|
||||
- Include:
|
||||
- Understanding summary
|
||||
- Assumptions
|
||||
- Decision log
|
||||
- Final design
|
||||
|
||||
- **One question at a time** - Don't overwhelm with multiple questions
|
||||
- **Multiple choice preferred** - Easier to answer than open-ended when possible
|
||||
- **YAGNI ruthlessly** - Remove unnecessary features from all designs
|
||||
- **Explore alternatives** - Always propose 2-3 approaches before settling
|
||||
- **Incremental validation** - Present design in sections, validate each
|
||||
- **Be flexible** - Go back and clarify when something doesn't make sense
|
||||
Persist the document according to the project’s standard workflow.
|
||||
|
||||
---
|
||||
|
||||
### 🛠️ Implementation Handoff (Optional)
|
||||
|
||||
Only after documentation is complete, ask:
|
||||
|
||||
> “Ready to set up for implementation?”
|
||||
|
||||
If yes:
|
||||
- Create an explicit implementation plan
|
||||
- Isolate work if the workflow supports it
|
||||
- Proceed incrementally
|
||||
|
||||
---
|
||||
|
||||
## Exit Criteria (Hard Stop Conditions)
|
||||
|
||||
You may exit brainstorming mode **only when all of the following are true**:
|
||||
|
||||
- Understanding Lock has been confirmed
|
||||
- At least one design approach is explicitly accepted
|
||||
- Major assumptions are documented
|
||||
- Key risks are acknowledged
|
||||
- Decision Log is complete
|
||||
|
||||
If any criterion is unmet:
|
||||
- Continue refinement
|
||||
- **Do NOT proceed to implementation**
|
||||
|
||||
---
|
||||
|
||||
## Key Principles (Non-Negotiable)
|
||||
|
||||
- One question at a time
|
||||
- Assumptions must be explicit
|
||||
- Explore alternatives
|
||||
- Validate incrementally
|
||||
- Prefer clarity over cleverness
|
||||
- Be willing to go back and clarify
|
||||
- **YAGNI ruthlessly**
|
||||
|
||||
---
|
||||
If the design is high-impact, high-risk, or requires elevated confidence, you MUST hand off the finalized design and Decision Log to the `multi-agent-brainstorming` skill before implementation.
|
||||
|
||||
30
skills/busybox-on-windows/SKILL.md
Normal file
30
skills/busybox-on-windows/SKILL.md
Normal file
@@ -0,0 +1,30 @@
|
||||
---
|
||||
name: busybox-on-windows
|
||||
description: How to use a Win32 build of BusyBox to run many of the standard UNIX command line tools on Windows.
|
||||
license: MIT
|
||||
---
|
||||
|
||||
BusyBox is a single binary that implements many common Unix tools.
|
||||
|
||||
Use this skill only on Windows. If you are on UNIX, then stop here.
|
||||
|
||||
Run the following steps only if you cannot find a `busybox.exe` file in the same directory as this document is.
|
||||
These are PowerShell commands, if you have a classic `cmd.exe` terminal, then you must use `powershell -Command "..."` to run them.
|
||||
1. Print the type of CPU: `Get-CimInstance -ClassName Win32_Processor | Select-Object Name, NumberOfCores, MaxClockSpeed`
|
||||
2. Print the OS versions: `Get-ItemProperty "HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion" | Select-Object ProductName, DisplayVersion, CurrentBuild`
|
||||
3. Download a suitable build of BusyBox by running one of these PowerShell commands:
|
||||
- 32-bit x86 (ANSI): `$ProgressPreference = 'SilentlyContinue'; Invoke-WebRequest -Uri https://frippery.org/files/busybox/busybox.exe -OutFile busybox.exe`
|
||||
- 64-bit x86 (ANSI): `$ProgressPreference = 'SilentlyContinue'; Invoke-WebRequest -Uri https://frippery.org/files/busybox/busybox64.exe -OutFile busybox.exe`
|
||||
- 64-bit x86 (Unicode): `$ProgressPreference = 'SilentlyContinue'; Invoke-WebRequest -Uri https://frippery.org/files/busybox/busybox64u.exe -OutFile busybox.exe`
|
||||
- 64-bit ARM (Unicode): `$ProgressPreference = 'SilentlyContinue'; Invoke-WebRequest -Uri https://frippery.org/files/busybox/busybox64a.exe -OutFile busybox.exe`
|
||||
|
||||
Useful commands:
|
||||
- Help: `busybox.exe --list`
|
||||
- Available UNIX commands: `busybox.exe --list`
|
||||
|
||||
Usage: Prefix the UNIX command with `busybox.exe`, for example: `busybox.exe ls -1`
|
||||
|
||||
If you need to run a UNIX command under another CWD, then use the absolute path to `busybox.exe`.
|
||||
|
||||
Documentation: https://frippery.org/busybox/
|
||||
Original BusyBox: https://busybox.net/
|
||||
@@ -1,10 +1,10 @@
|
||||
---
|
||||
name: cc-skill-continuous-learning
|
||||
description: Development skill skill from everything-claude-code
|
||||
description: Development skill from everything-claude-code
|
||||
author: affaan-m
|
||||
version: "1.0"
|
||||
---
|
||||
|
||||
# cc-skill-continuous-learning
|
||||
|
||||
Development skill skill.
|
||||
Development skill skill.
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
---
|
||||
name: cc-skill-strategic-compact
|
||||
description: Development skill skill from everything-claude-code
|
||||
description: Development skill from everything-claude-code
|
||||
author: affaan-m
|
||||
version: "1.0"
|
||||
---
|
||||
|
||||
# cc-skill-strategic-compact
|
||||
|
||||
Development skill skill.
|
||||
Development skill skill.
|
||||
|
||||
@@ -1,109 +1,444 @@
|
||||
---
|
||||
name: code-review-checklist
|
||||
description: Code review guidelines covering code quality, security, and best practices.
|
||||
allowed-tools: Read, Glob, Grep
|
||||
description: "Comprehensive checklist for conducting thorough code reviews covering functionality, security, performance, and maintainability"
|
||||
---
|
||||
|
||||
# Code Review Checklist
|
||||
|
||||
## Quick Review Checklist
|
||||
## Overview
|
||||
|
||||
### Correctness
|
||||
- [ ] Code does what it's supposed to do
|
||||
- [ ] Edge cases handled
|
||||
- [ ] Error handling in place
|
||||
- [ ] No obvious bugs
|
||||
Provide a systematic checklist for conducting thorough code reviews. This skill helps reviewers ensure code quality, catch bugs, identify security issues, and maintain consistency across the codebase.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
- Use when reviewing pull requests
|
||||
- Use when conducting code audits
|
||||
- Use when establishing code review standards for a team
|
||||
- Use when training new developers on code review practices
|
||||
- Use when you want to ensure nothing is missed in reviews
|
||||
- Use when creating code review documentation
|
||||
|
||||
## How It Works
|
||||
|
||||
### Step 1: Understand the Context
|
||||
|
||||
Before reviewing code, I'll help you understand:
|
||||
- What problem does this code solve?
|
||||
- What are the requirements?
|
||||
- What files were changed and why?
|
||||
- Are there related issues or tickets?
|
||||
- What's the testing strategy?
|
||||
|
||||
### Step 2: Review Functionality
|
||||
|
||||
Check if the code works correctly:
|
||||
- Does it solve the stated problem?
|
||||
- Are edge cases handled?
|
||||
- Is error handling appropriate?
|
||||
- Are there any logical errors?
|
||||
- Does it match the requirements?
|
||||
|
||||
### Step 3: Review Code Quality
|
||||
|
||||
Assess code maintainability:
|
||||
- Is the code readable and clear?
|
||||
- Are names descriptive?
|
||||
- Is it properly structured?
|
||||
- Are functions/methods focused?
|
||||
- Is there unnecessary complexity?
|
||||
|
||||
### Step 4: Review Security
|
||||
|
||||
Check for security issues:
|
||||
- Are inputs validated?
|
||||
- Is sensitive data protected?
|
||||
- Are there SQL injection risks?
|
||||
- Is authentication/authorization correct?
|
||||
- Are dependencies secure?
|
||||
|
||||
### Step 5: Review Performance
|
||||
|
||||
Look for performance issues:
|
||||
- Are there unnecessary loops?
|
||||
- Is database access optimized?
|
||||
- Are there memory leaks?
|
||||
- Is caching used appropriately?
|
||||
- Are there N+1 query problems?
|
||||
|
||||
### Step 6: Review Tests
|
||||
|
||||
Verify test coverage:
|
||||
- Are there tests for new code?
|
||||
- Do tests cover edge cases?
|
||||
- Are tests meaningful?
|
||||
- Do all tests pass?
|
||||
- Is test coverage adequate?
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Functionality Review Checklist
|
||||
|
||||
```markdown
|
||||
## Functionality Review
|
||||
|
||||
### Requirements
|
||||
- [ ] Code solves the stated problem
|
||||
- [ ] All acceptance criteria are met
|
||||
- [ ] Edge cases are handled
|
||||
- [ ] Error cases are handled
|
||||
- [ ] User input is validated
|
||||
|
||||
### Logic
|
||||
- [ ] No logical errors or bugs
|
||||
- [ ] Conditions are correct (no off-by-one errors)
|
||||
- [ ] Loops terminate correctly
|
||||
- [ ] Recursion has proper base cases
|
||||
- [ ] State management is correct
|
||||
|
||||
### Error Handling
|
||||
- [ ] Errors are caught appropriately
|
||||
- [ ] Error messages are clear and helpful
|
||||
- [ ] Errors don't expose sensitive information
|
||||
- [ ] Failed operations are rolled back
|
||||
- [ ] Logging is appropriate
|
||||
|
||||
### Example Issues to Catch:
|
||||
|
||||
**❌ Bad - Missing validation:**
|
||||
\`\`\`javascript
|
||||
function createUser(email, password) {
|
||||
// No validation!
|
||||
return db.users.create({ email, password });
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
**✅ Good - Proper validation:**
|
||||
\`\`\`javascript
|
||||
function createUser(email, password) {
|
||||
if (!email || !isValidEmail(email)) {
|
||||
throw new Error('Invalid email address');
|
||||
}
|
||||
if (!password || password.length < 8) {
|
||||
throw new Error('Password must be at least 8 characters');
|
||||
}
|
||||
return db.users.create({ email, password });
|
||||
}
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### Example 2: Security Review Checklist
|
||||
|
||||
```markdown
|
||||
## Security Review
|
||||
|
||||
### Input Validation
|
||||
- [ ] All user inputs are validated
|
||||
- [ ] SQL injection is prevented (use parameterized queries)
|
||||
- [ ] XSS is prevented (escape output)
|
||||
- [ ] CSRF protection is in place
|
||||
- [ ] File uploads are validated (type, size, content)
|
||||
|
||||
### Authentication & Authorization
|
||||
- [ ] Authentication is required where needed
|
||||
- [ ] Authorization checks are present
|
||||
- [ ] Passwords are hashed (never stored plain text)
|
||||
- [ ] Sessions are managed securely
|
||||
- [ ] Tokens expire appropriately
|
||||
|
||||
### Data Protection
|
||||
- [ ] Sensitive data is encrypted
|
||||
- [ ] API keys are not hardcoded
|
||||
- [ ] Environment variables are used for secrets
|
||||
- [ ] Personal data follows privacy regulations
|
||||
- [ ] Database credentials are secure
|
||||
|
||||
### Dependencies
|
||||
- [ ] No known vulnerable dependencies
|
||||
- [ ] Dependencies are up to date
|
||||
- [ ] Unnecessary dependencies are removed
|
||||
- [ ] Dependency versions are pinned
|
||||
|
||||
### Example Issues to Catch:
|
||||
|
||||
**❌ Bad - SQL injection risk:**
|
||||
\`\`\`javascript
|
||||
const query = \`SELECT * FROM users WHERE email = '\${email}'\`;
|
||||
db.query(query);
|
||||
\`\`\`
|
||||
|
||||
**✅ Good - Parameterized query:**
|
||||
\`\`\`javascript
|
||||
const query = 'SELECT * FROM users WHERE email = $1';
|
||||
db.query(query, [email]);
|
||||
\`\`\`
|
||||
|
||||
**❌ Bad - Hardcoded secret:**
|
||||
\`\`\`javascript
|
||||
const API_KEY = 'sk_live_abc123xyz';
|
||||
\`\`\`
|
||||
|
||||
**✅ Good - Environment variable:**
|
||||
\`\`\`javascript
|
||||
const API_KEY = process.env.API_KEY;
|
||||
if (!API_KEY) {
|
||||
throw new Error('API_KEY environment variable is required');
|
||||
}
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### Example 3: Code Quality Review Checklist
|
||||
|
||||
```markdown
|
||||
## Code Quality Review
|
||||
|
||||
### Readability
|
||||
- [ ] Code is easy to understand
|
||||
- [ ] Variable names are descriptive
|
||||
- [ ] Function names explain what they do
|
||||
- [ ] Complex logic has comments
|
||||
- [ ] Magic numbers are replaced with constants
|
||||
|
||||
### Structure
|
||||
- [ ] Functions are small and focused
|
||||
- [ ] Code follows DRY principle (Don't Repeat Yourself)
|
||||
- [ ] Proper separation of concerns
|
||||
- [ ] Consistent code style
|
||||
- [ ] No dead code or commented-out code
|
||||
|
||||
### Maintainability
|
||||
- [ ] Code is modular and reusable
|
||||
- [ ] Dependencies are minimal
|
||||
- [ ] Changes are backwards compatible
|
||||
- [ ] Breaking changes are documented
|
||||
- [ ] Technical debt is noted
|
||||
|
||||
### Example Issues to Catch:
|
||||
|
||||
**❌ Bad - Unclear naming:**
|
||||
\`\`\`javascript
|
||||
function calc(a, b, c) {
|
||||
return a * b + c;
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
**✅ Good - Descriptive naming:**
|
||||
\`\`\`javascript
|
||||
function calculateTotalPrice(quantity, unitPrice, tax) {
|
||||
return quantity * unitPrice + tax;
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
**❌ Bad - Function doing too much:**
|
||||
\`\`\`javascript
|
||||
function processOrder(order) {
|
||||
// Validate order
|
||||
if (!order.items) throw new Error('No items');
|
||||
|
||||
// Calculate total
|
||||
let total = 0;
|
||||
for (let item of order.items) {
|
||||
total += item.price * item.quantity;
|
||||
}
|
||||
|
||||
// Apply discount
|
||||
if (order.coupon) {
|
||||
total *= 0.9;
|
||||
}
|
||||
|
||||
// Process payment
|
||||
const payment = stripe.charge(total);
|
||||
|
||||
// Send email
|
||||
sendEmail(order.email, 'Order confirmed');
|
||||
|
||||
// Update inventory
|
||||
updateInventory(order.items);
|
||||
|
||||
return { orderId: order.id, total };
|
||||
}
|
||||
\`\`\`
|
||||
|
||||
**✅ Good - Separated concerns:**
|
||||
\`\`\`javascript
|
||||
function processOrder(order) {
|
||||
validateOrder(order);
|
||||
const total = calculateOrderTotal(order);
|
||||
const payment = processPayment(total);
|
||||
sendOrderConfirmation(order.email);
|
||||
updateInventory(order.items);
|
||||
|
||||
return { orderId: order.id, total };
|
||||
}
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### ✅ Do This
|
||||
|
||||
- **Review Small Changes** - Smaller PRs are easier to review thoroughly
|
||||
- **Check Tests First** - Verify tests pass and cover new code
|
||||
- **Run the Code** - Test it locally when possible
|
||||
- **Ask Questions** - Don't assume, ask for clarification
|
||||
- **Be Constructive** - Suggest improvements, don't just criticize
|
||||
- **Focus on Important Issues** - Don't nitpick minor style issues
|
||||
- **Use Automated Tools** - Linters, formatters, security scanners
|
||||
- **Review Documentation** - Check if docs are updated
|
||||
- **Consider Performance** - Think about scale and efficiency
|
||||
- **Check for Regressions** - Ensure existing functionality still works
|
||||
|
||||
### ❌ Don't Do This
|
||||
|
||||
- **Don't Approve Without Reading** - Actually review the code
|
||||
- **Don't Be Vague** - Provide specific feedback with examples
|
||||
- **Don't Ignore Security** - Security issues are critical
|
||||
- **Don't Skip Tests** - Untested code will cause problems
|
||||
- **Don't Be Rude** - Be respectful and professional
|
||||
- **Don't Rubber Stamp** - Every review should add value
|
||||
- **Don't Review When Tired** - You'll miss important issues
|
||||
- **Don't Forget Context** - Understand the bigger picture
|
||||
|
||||
## Complete Review Checklist
|
||||
|
||||
### Pre-Review
|
||||
- [ ] Read the PR description and linked issues
|
||||
- [ ] Understand what problem is being solved
|
||||
- [ ] Check if tests pass in CI/CD
|
||||
- [ ] Pull the branch and run it locally
|
||||
|
||||
### Functionality
|
||||
- [ ] Code solves the stated problem
|
||||
- [ ] Edge cases are handled
|
||||
- [ ] Error handling is appropriate
|
||||
- [ ] User input is validated
|
||||
- [ ] No logical errors
|
||||
|
||||
### 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
|
||||
- [ ] No SQL injection vulnerabilities
|
||||
- [ ] No XSS vulnerabilities
|
||||
- [ ] Authentication/authorization is correct
|
||||
- [ ] Sensitive data is protected
|
||||
- [ ] No hardcoded secrets
|
||||
|
||||
### Performance
|
||||
- [ ] No N+1 queries
|
||||
- [ ] No unnecessary loops
|
||||
- [ ] Appropriate caching
|
||||
- [ ] Bundle size impact considered
|
||||
- [ ] No unnecessary database queries
|
||||
- [ ] No N+1 query problems
|
||||
- [ ] Efficient algorithms used
|
||||
- [ ] No memory leaks
|
||||
- [ ] Caching used appropriately
|
||||
|
||||
### Code Quality
|
||||
- [ ] Clear naming
|
||||
- [ ] DRY - no duplicate code
|
||||
- [ ] SOLID principles followed
|
||||
- [ ] Appropriate abstraction level
|
||||
- [ ] Code is readable and clear
|
||||
- [ ] Names are descriptive
|
||||
- [ ] Functions are focused and small
|
||||
- [ ] No code duplication
|
||||
- [ ] Follows project conventions
|
||||
|
||||
### Testing
|
||||
- [ ] Unit tests for new code
|
||||
- [ ] Edge cases tested
|
||||
- [ ] Tests readable and maintainable
|
||||
### Tests
|
||||
- [ ] New code has tests
|
||||
- [ ] Tests cover edge cases
|
||||
- [ ] Tests are meaningful
|
||||
- [ ] All tests pass
|
||||
- [ ] Test coverage is adequate
|
||||
|
||||
### Documentation
|
||||
- [ ] Complex logic commented
|
||||
- [ ] Public APIs documented
|
||||
- [ ] README updated if needed
|
||||
- [ ] Code comments explain why, not what
|
||||
- [ ] API documentation is updated
|
||||
- [ ] README is updated if needed
|
||||
- [ ] Breaking changes are documented
|
||||
- [ ] Migration guide provided if needed
|
||||
|
||||
## AI & LLM Review Patterns (2025)
|
||||
### Git
|
||||
- [ ] Commit messages are clear
|
||||
- [ ] No merge conflicts
|
||||
- [ ] Branch is up to date with main
|
||||
- [ ] No unnecessary files committed
|
||||
- [ ] .gitignore is properly configured
|
||||
|
||||
### 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?
|
||||
## Common Pitfalls
|
||||
|
||||
### Prompt Engineering Review
|
||||
### Problem: Missing Edge Cases
|
||||
**Symptoms:** Code works for happy path but fails on edge cases
|
||||
**Solution:** Ask "What if...?" questions
|
||||
- What if the input is null?
|
||||
- What if the array is empty?
|
||||
- What if the user is not authenticated?
|
||||
- What if the network request fails?
|
||||
|
||||
### Problem: Security Vulnerabilities
|
||||
**Symptoms:** Code exposes security risks
|
||||
**Solution:** Use security checklist
|
||||
- Run security scanners (npm audit, Snyk)
|
||||
- Check OWASP Top 10
|
||||
- Validate all inputs
|
||||
- Use parameterized queries
|
||||
- Never trust user input
|
||||
|
||||
### Problem: Poor Test Coverage
|
||||
**Symptoms:** New code has no tests or inadequate tests
|
||||
**Solution:** Require tests for all new code
|
||||
- Unit tests for functions
|
||||
- Integration tests for features
|
||||
- Edge case tests
|
||||
- Error case tests
|
||||
|
||||
### Problem: Unclear Code
|
||||
**Symptoms:** Reviewer can't understand what code does
|
||||
**Solution:** Request improvements
|
||||
- Better variable names
|
||||
- Explanatory comments
|
||||
- Smaller functions
|
||||
- Clear structure
|
||||
|
||||
## Review Comment Templates
|
||||
|
||||
### Requesting Changes
|
||||
```markdown
|
||||
// ❌ Vague prompt in code
|
||||
const response = await ai.generate(userInput);
|
||||
**Issue:** [Describe the problem]
|
||||
|
||||
// ✅ Structured & Safe prompt
|
||||
const response = await ai.generate({
|
||||
system: "You are a specialized parser...",
|
||||
input: sanitize(userInput),
|
||||
schema: ResponseSchema
|
||||
});
|
||||
**Current code:**
|
||||
\`\`\`javascript
|
||||
// Show problematic code
|
||||
\`\`\`
|
||||
|
||||
**Suggested fix:**
|
||||
\`\`\`javascript
|
||||
// Show improved code
|
||||
\`\`\`
|
||||
|
||||
**Why:** [Explain why this is better]
|
||||
```
|
||||
|
||||
## Anti-Patterns to Flag
|
||||
### Asking Questions
|
||||
```markdown
|
||||
**Question:** [Your question]
|
||||
|
||||
```typescript
|
||||
// ❌ Magic numbers
|
||||
if (status === 3) { ... }
|
||||
**Context:** [Why you're asking]
|
||||
|
||||
// ✅ 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 = ...
|
||||
**Suggestion:** [If you have one]
|
||||
```
|
||||
|
||||
## Review Comments Guide
|
||||
### Praising Good Code
|
||||
```markdown
|
||||
**Nice!** [What you liked]
|
||||
|
||||
This is great because [explain why]
|
||||
```
|
||||
// Blocking issues use 🔴
|
||||
🔴 BLOCKING: SQL injection vulnerability here
|
||||
|
||||
// Important suggestions use 🟡
|
||||
🟡 SUGGESTION: Consider using useMemo for performance
|
||||
## Related Skills
|
||||
|
||||
// Minor nits use 🟢
|
||||
🟢 NIT: Prefer const over let for immutable variable
|
||||
- `@requesting-code-review` - Prepare code for review
|
||||
- `@receiving-code-review` - Handle review feedback
|
||||
- `@systematic-debugging` - Debug issues found in review
|
||||
- `@test-driven-development` - Ensure code has tests
|
||||
|
||||
// Questions use ❓
|
||||
❓ QUESTION: What happens if user is null here?
|
||||
```
|
||||
## Additional Resources
|
||||
|
||||
- [Google Code Review Guidelines](https://google.github.io/eng-practices/review/)
|
||||
- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
|
||||
- [Code Review Best Practices](https://github.com/thoughtbot/guides/tree/main/code-review)
|
||||
- [How to Review Code](https://www.kevinlondon.com/2015/05/05/code-review-best-practices.html)
|
||||
|
||||
---
|
||||
|
||||
**Pro Tip:** Use a checklist template for every review to ensure consistency and thoroughness. Customize it for your team's specific needs!
|
||||
|
||||
37
skills/codex-review/SKILL.md
Normal file
37
skills/codex-review/SKILL.md
Normal file
@@ -0,0 +1,37 @@
|
||||
---
|
||||
name: codex-review
|
||||
description: Professional code review with auto CHANGELOG generation, integrated with Codex AI
|
||||
---
|
||||
|
||||
# codex-review
|
||||
|
||||
## Overview
|
||||
Professional code review with auto CHANGELOG generation, integrated with Codex AI
|
||||
|
||||
## When to Use
|
||||
- When you want professional code review before commits
|
||||
- When you need automatic CHANGELOG generation
|
||||
- When reviewing large-scale refactoring
|
||||
|
||||
## Installation
|
||||
```bash
|
||||
npx skills add -g BenedictKing/codex-review
|
||||
```
|
||||
|
||||
## Step-by-Step Guide
|
||||
1. Install the skill using the command above
|
||||
2. Ensure Codex CLI is installed
|
||||
3. Use `/codex-review` or natural language triggers
|
||||
|
||||
## Examples
|
||||
See [GitHub Repository](https://github.com/BenedictKing/codex-review) for examples.
|
||||
|
||||
## Best Practices
|
||||
- Keep CHANGELOG.md in your project root
|
||||
- Use conventional commit messages
|
||||
|
||||
## Troubleshooting
|
||||
See the GitHub repository for troubleshooting guides.
|
||||
|
||||
## Related Skills
|
||||
- context7-auto-research, tavily-web, exa-search, firecrawl-scraper
|
||||
36
skills/context7-auto-research/SKILL.md
Normal file
36
skills/context7-auto-research/SKILL.md
Normal file
@@ -0,0 +1,36 @@
|
||||
---
|
||||
name: context7-auto-research
|
||||
description: Automatically fetch latest library/framework documentation for Claude Code via Context7 API
|
||||
---
|
||||
|
||||
# context7-auto-research
|
||||
|
||||
## Overview
|
||||
Automatically fetch latest library/framework documentation for Claude Code via Context7 API
|
||||
|
||||
## When to Use
|
||||
- When you need up-to-date documentation for libraries and frameworks
|
||||
- When asking about React, Next.js, Prisma, or any other popular library
|
||||
|
||||
## Installation
|
||||
```bash
|
||||
npx skills add -g BenedictKing/context7-auto-research
|
||||
```
|
||||
|
||||
## Step-by-Step Guide
|
||||
1. Install the skill using the command above
|
||||
2. Configure API key (optional, see GitHub repo for details)
|
||||
3. Use naturally in Claude Code conversations
|
||||
|
||||
## Examples
|
||||
See [GitHub Repository](https://github.com/BenedictKing/context7-auto-research) for examples.
|
||||
|
||||
## Best Practices
|
||||
- Configure API keys via environment variables for higher rate limits
|
||||
- Use the skill's auto-trigger feature for seamless integration
|
||||
|
||||
## Troubleshooting
|
||||
See the GitHub repository for troubleshooting guides.
|
||||
|
||||
## Related Skills
|
||||
- tavily-web, exa-search, firecrawl-scraper, codex-review
|
||||
@@ -1,366 +1,162 @@
|
||||
---
|
||||
name: copywriting
|
||||
description: When the user wants to write, rewrite, or improve marketing copy for any page — including homepage, landing pages, pricing pages, feature pages, about pages, or product pages. Also use when the user says "write copy for," "improve this copy," "rewrite this page," "marketing copy," "headline help," or "CTA copy." For email copy, see email-sequence. For popup copy, see popup-cro.
|
||||
description: >
|
||||
Use this skill when writing, rewriting, or improving marketing copy
|
||||
for any page (homepage, landing page, pricing, feature, product, or about page).
|
||||
This skill produces clear, compelling, and testable copy while enforcing
|
||||
alignment, honesty, and conversion best practices.
|
||||
---
|
||||
|
||||
# Copywriting
|
||||
|
||||
You are an expert conversion copywriter. Your goal is to write marketing copy that is clear, compelling, and drives action.
|
||||
## Purpose
|
||||
|
||||
## Before Writing
|
||||
Produce **clear, credible, and action-oriented marketing copy** that aligns with
|
||||
user intent and business goals.
|
||||
|
||||
Gather this context (ask if not provided):
|
||||
This skill exists to prevent:
|
||||
- writing before understanding the audience
|
||||
- vague or hype-driven messaging
|
||||
- misaligned CTAs
|
||||
- overclaiming or fabricated proof
|
||||
- untestable copy
|
||||
|
||||
### 1. Page Purpose
|
||||
- What type of page is this? (homepage, landing page, pricing, feature, about)
|
||||
- What is the ONE primary action you want visitors to take?
|
||||
- What's the secondary action (if any)?
|
||||
|
||||
### 2. Audience
|
||||
- Who is the ideal customer for this page?
|
||||
- What problem are they trying to solve?
|
||||
- What have they already tried?
|
||||
- What objections or hesitations do they have?
|
||||
- What language do they use to describe their problem?
|
||||
|
||||
### 3. Product/Offer
|
||||
- What are you selling or offering?
|
||||
- What makes it different from alternatives?
|
||||
- What's the key transformation or outcome?
|
||||
- Any proof points (numbers, testimonials, case studies)?
|
||||
|
||||
### 4. Context
|
||||
- Where is traffic coming from? (ads, organic, email)
|
||||
- What do visitors already know before arriving?
|
||||
- What messaging are they seeing before this page?
|
||||
You may **not** fabricate claims, statistics, testimonials, or guarantees.
|
||||
|
||||
---
|
||||
|
||||
## Copywriting Principles
|
||||
## Operating Mode
|
||||
|
||||
### Clarity Over Cleverness
|
||||
- If you have to choose between clear and creative, choose clear
|
||||
- Every sentence should have one job
|
||||
- Remove words that don't add meaning
|
||||
You are operating as an **expert conversion copywriter**, not a brand poet.
|
||||
|
||||
### Benefits Over Features
|
||||
- Features: What it does
|
||||
- Benefits: What that means for the customer
|
||||
- Always connect features to outcomes
|
||||
- Clarity beats cleverness
|
||||
- Outcomes beat features
|
||||
- Specificity beats buzzwords
|
||||
- Honesty beats hype
|
||||
|
||||
### Specificity Over Vagueness
|
||||
- Vague: "Save time on your workflow"
|
||||
- Specific: "Cut your weekly reporting from 4 hours to 15 minutes"
|
||||
Your job is to **help the right reader take the right action**.
|
||||
|
||||
### Customer Language Over Company Language
|
||||
- Use words your customers use
|
||||
- Avoid jargon unless your audience uses it
|
||||
- Mirror voice-of-customer from reviews, interviews, support tickets
|
||||
---
|
||||
|
||||
### One Idea Per Section
|
||||
- Don't try to say everything everywhere
|
||||
- Each section should advance one argument
|
||||
- Build a logical flow down the page
|
||||
## Phase 1 — Context Gathering (Mandatory)
|
||||
|
||||
Before writing any copy, gather or confirm the following.
|
||||
If information is missing, ask for it **before proceeding**.
|
||||
|
||||
### 1️⃣ Page Purpose
|
||||
- Page type (homepage, landing page, pricing, feature, about)
|
||||
- ONE primary action (CTA)
|
||||
- Secondary action (if any)
|
||||
|
||||
### 2️⃣ Audience
|
||||
- Target customer or role
|
||||
- Primary problem they are trying to solve
|
||||
- What they have already tried
|
||||
- Main objections or hesitations
|
||||
- Language they use to describe the problem
|
||||
|
||||
### 3️⃣ Product / Offer
|
||||
- What is being offered
|
||||
- Key differentiator vs alternatives
|
||||
- Primary outcome or transformation
|
||||
- Available proof (numbers, testimonials, case studies)
|
||||
|
||||
### 4️⃣ Context
|
||||
- Traffic source (ads, organic, email, referrals)
|
||||
- Awareness level (unaware, problem-aware, solution-aware, product-aware)
|
||||
- What visitors already know or expect
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Copy Brief Lock (Hard Gate)
|
||||
|
||||
Before writing any copy, you MUST present a **Copy Brief Summary** and pause.
|
||||
|
||||
### Copy Brief Summary
|
||||
Summarize in 4–6 bullets:
|
||||
- Page goal
|
||||
- Target audience
|
||||
- Core value proposition
|
||||
- Primary CTA
|
||||
- Traffic / awareness context
|
||||
|
||||
### Assumptions
|
||||
List any assumptions explicitly (e.g. awareness level, urgency, sophistication).
|
||||
|
||||
Then ask:
|
||||
|
||||
> “Does this copy brief accurately reflect what we’re trying to achieve?
|
||||
> Please confirm or correct anything before I write copy.”
|
||||
|
||||
**Do NOT proceed until confirmation is given.**
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — Copywriting Principles
|
||||
|
||||
### Core Principles (Non-Negotiable)
|
||||
|
||||
- **Clarity over cleverness**
|
||||
- **Benefits over features**
|
||||
- **Specificity over vagueness**
|
||||
- **Customer language over company language**
|
||||
- **One idea per section**
|
||||
|
||||
Always connect:
|
||||
> Feature → Benefit → Outcome
|
||||
|
||||
---
|
||||
|
||||
## Writing Style Rules
|
||||
|
||||
Follow these core principles. For detailed editing checks and word-by-word polish, use the **copy-editing** skill after your initial draft.
|
||||
### Style Guidelines
|
||||
- Simple over complex
|
||||
- Active over passive
|
||||
- Confident over hedged
|
||||
- Show outcomes instead of adjectives
|
||||
- Avoid buzzwords unless customers use them
|
||||
|
||||
### Core Style Principles
|
||||
|
||||
1. **Simple over complex** — Use everyday words. "Use" instead of "utilize," "help" instead of "facilitate."
|
||||
|
||||
2. **Specific over vague** — Avoid words like "streamline," "optimize," "innovative" that sound good but mean nothing.
|
||||
|
||||
3. **Active over passive** — "We generate reports" not "Reports are generated."
|
||||
|
||||
4. **Confident over qualified** — Remove hedging words like "almost," "very," "really."
|
||||
|
||||
5. **Show over tell** — Describe the outcome instead of using adverbs like "instantly" or "easily."
|
||||
|
||||
6. **Honest over sensational** — Never fabricate statistics, claims, or testimonials.
|
||||
|
||||
### Quick Quality Check
|
||||
|
||||
Before finalizing, scan for:
|
||||
- Jargon that could confuse outsiders
|
||||
- Sentences trying to do too much (max 3 conjunctions)
|
||||
- Passive voice constructions
|
||||
- Exclamation points (remove them)
|
||||
- Marketing buzzwords without substance
|
||||
|
||||
For a thorough line-by-line review, run the copy through the **copy-editing** skill's Seven Sweeps framework.
|
||||
### Claim Discipline
|
||||
- No fabricated data or testimonials
|
||||
- No implied guarantees unless explicitly stated
|
||||
- No exaggerated speed or certainty
|
||||
- If proof is missing, mark placeholders clearly
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
## Phase 4 — Page Structure Framework
|
||||
|
||||
### Be Direct
|
||||
Get to the point. Don't bury the value in qualifications.
|
||||
|
||||
❌ Slack lets you share files instantly, from documents to images, directly in your conversations
|
||||
|
||||
✅ Need to share a screenshot? Send as many documents, images, and audio files as your heart desires.
|
||||
|
||||
### Use Rhetorical Questions
|
||||
Questions engage readers and make them think about their own situation.
|
||||
|
||||
✅ Hate returning stuff to Amazon?
|
||||
|
||||
✅ Need to share a screenshot?
|
||||
|
||||
✅ Tired of chasing approvals?
|
||||
|
||||
### Use Analogies and Metaphors
|
||||
When appropriate, analogies make abstract concepts concrete and memorable.
|
||||
|
||||
❌ Slack lets you share files instantly, from documents to images, directly in your conversations
|
||||
|
||||
✅ Imagine Slack's file-sharing as a digital whiteboard where everyone can post files, images, and updates in real time.
|
||||
|
||||
### Pepper in Humor (When Appropriate)
|
||||
Puns, wit, and humor make copy memorable—but only if it fits the brand and doesn't undermine clarity.
|
||||
|
||||
---
|
||||
|
||||
## Page Structure Framework
|
||||
|
||||
### Above the Fold (First Screen)
|
||||
### Above the Fold
|
||||
|
||||
**Headline**
|
||||
- Your single most important message
|
||||
- Should communicate core value proposition
|
||||
- Specific > generic
|
||||
|
||||
**Headline Formulas:**
|
||||
|
||||
**{Achieve desirable outcome} without {pain point}**
|
||||
*Example: Understand how users are really experiencing your site without drowning in numbers*
|
||||
|
||||
**The {opposite of usual process} way to {achieve desirable outcome}**
|
||||
*Example: The easiest way to turn your passion into income*
|
||||
|
||||
**Never {unpleasant event} again**
|
||||
*Example: Never miss a sales opportunity again*
|
||||
|
||||
**{Key feature/product type} for {target audience}**
|
||||
*Example: Advanced analytics for Shopify e-commerce*
|
||||
|
||||
**{Key feature/product type} for {target audience} to {what it's used for}**
|
||||
*Example: An online whiteboard for teams to ideate and brainstorm together*
|
||||
|
||||
**You don't have to {skills or resources} to {achieve desirable outcome}**
|
||||
*Example: With Ahrefs, you don't have to be an SEO pro to rank higher and get more traffic*
|
||||
|
||||
**{Achieve desirable outcome} by {how product makes it possible}**
|
||||
*Example: Generate more leads by seeing which companies visit your site*
|
||||
|
||||
**{Key benefit of your product}**
|
||||
*Example: Sound clear in online meetings*
|
||||
|
||||
**{Question highlighting the main pain point}**
|
||||
*Example: Hate returning stuff to Amazon?*
|
||||
|
||||
**Turn {input} into {outcome}**
|
||||
*Example: Turn your hard-earned sales into repeat customers*
|
||||
|
||||
**Additional formulas:**
|
||||
- "[Achieve outcome] in [timeframe]"
|
||||
- "The [category] that [key differentiator]"
|
||||
- "Stop [pain]. Start [pleasure]."
|
||||
- "[Number] [people] use [product] to [outcome]"
|
||||
- Single most important message
|
||||
- Specific value proposition
|
||||
- Outcome-focused
|
||||
|
||||
**Subheadline**
|
||||
- Expands on the headline
|
||||
- Adds specificity or addresses secondary concern
|
||||
- 1-2 sentences max
|
||||
- Adds clarity or context
|
||||
- 1–2 sentences max
|
||||
|
||||
**Primary CTA**
|
||||
- Action-oriented button text
|
||||
- Communicate what they get, not what they do
|
||||
- "Start Free Trial" > "Sign Up"
|
||||
- "Get Your Report" > "Submit"
|
||||
|
||||
**Supporting Visual**
|
||||
- Product screenshot, demo, or hero image
|
||||
- Should reinforce the message, not distract
|
||||
|
||||
### Social Proof Section
|
||||
|
||||
Options (use 1-2):
|
||||
- Customer logos (recognizable > many)
|
||||
- Key metric ("10,000+ teams")
|
||||
- Short testimonial with attribution
|
||||
- Star rating with review count
|
||||
|
||||
### Problem/Pain Section
|
||||
|
||||
- Articulate the problem better than they can
|
||||
- Show you understand their situation
|
||||
- Create recognition ("that's exactly my problem")
|
||||
|
||||
Structure:
|
||||
- "You know the feeling..." or "If you're like most [role]..."
|
||||
- Describe the specific frustrations
|
||||
- Hint at the cost of not solving it
|
||||
|
||||
### Solution/Benefits Section
|
||||
|
||||
- Bridge from problem to your solution
|
||||
- Focus on 3-5 key benefits (not 10)
|
||||
- Each benefit: headline + short explanation + proof point if available
|
||||
|
||||
Format options:
|
||||
- Benefit blocks with icons
|
||||
- Before/after comparison
|
||||
- Feature → Benefit → Proof structure
|
||||
|
||||
### How It Works Section
|
||||
|
||||
- Reduce perceived complexity
|
||||
- 3-4 step process
|
||||
- Each step: simple action + outcome
|
||||
|
||||
Example:
|
||||
1. "Connect your tools (2 minutes)"
|
||||
2. "Set your preferences"
|
||||
3. "Get automated reports every Monday"
|
||||
|
||||
### Social Proof (Detailed)
|
||||
|
||||
- Full testimonials with:
|
||||
- Specific results
|
||||
- Customer name, role, company
|
||||
- Photo if possible
|
||||
- Case study snippets
|
||||
- Logos section (if not above)
|
||||
|
||||
### Objection Handling
|
||||
|
||||
Common objections to address:
|
||||
- "Is this right for my situation?"
|
||||
- "What if it doesn't work?"
|
||||
- "Is it hard to set up?"
|
||||
- "How is this different from X?"
|
||||
|
||||
Formats:
|
||||
- FAQ section
|
||||
- Comparison table
|
||||
- Guarantee/promise section
|
||||
- "Built for [specific audience]" section
|
||||
|
||||
### Final CTA Section
|
||||
|
||||
- Recap the value proposition
|
||||
- Repeat the primary CTA
|
||||
- Add urgency if genuine (deadline, limited availability)
|
||||
- Risk reversal (guarantee, free trial, no credit card)
|
||||
- Action-oriented
|
||||
- Describes what the user gets
|
||||
|
||||
---
|
||||
|
||||
## Landing Page Section Variety
|
||||
### Core Sections (Use as Appropriate)
|
||||
|
||||
A great landing page isn't just a list of features. Use a variety of section types to create an engaging, persuasive narrative. Mix and match from these:
|
||||
- Social proof (logos, stats, testimonials)
|
||||
- Problem / pain articulation
|
||||
- Solution & key benefits (3–5 max)
|
||||
- How it works (3–4 steps)
|
||||
- Objection handling (FAQ, comparisons, guarantees)
|
||||
- Final CTA with recap and risk reduction
|
||||
|
||||
### Section Types to Include
|
||||
|
||||
**How It Works (Numbered Steps)**
|
||||
Walk users through the process in 3-4 clear steps. Reduces perceived complexity and shows the path to value.
|
||||
|
||||
**Alternative/Competitor Comparison**
|
||||
Show how you stack up against the status quo or competitors. Tables, side-by-side comparisons, or "Unlike X, we..." sections.
|
||||
|
||||
**Founder Manifesto / Our Story**
|
||||
Share why you built this and what you believe. Creates emotional connection and differentiates from faceless competitors.
|
||||
|
||||
**Testimonials**
|
||||
Customer quotes with names, photos, and specific results. Multiple formats: quote cards, video testimonials, tweet embeds.
|
||||
|
||||
**Case Studies**
|
||||
Deeper stories of customer success. Problem → Solution → Results format with specific metrics.
|
||||
|
||||
**Use Cases**
|
||||
Show different ways the product is used. Helps visitors self-identify: "This is for people like me."
|
||||
|
||||
**Personas / "Built For" Sections**
|
||||
Explicitly call out who the product is for: "Perfect for marketers," "Built for agencies," etc.
|
||||
|
||||
**Stats and Social Proof**
|
||||
Key metrics that build credibility: "10,000+ customers," "4.9/5 rating," "$2M saved for customers."
|
||||
|
||||
**Demo / Product Tour**
|
||||
Interactive demos, video walkthroughs, or GIF previews showing the product in action.
|
||||
|
||||
**FAQ Section**
|
||||
Address common objections and questions. Good for SEO and reducing support burden.
|
||||
|
||||
**Integrations / Partners**
|
||||
Show what tools you connect with. Logos build credibility and answer "Will this work with my stack?"
|
||||
|
||||
**Pricing Preview**
|
||||
Even on non-pricing pages, a pricing teaser can move decision-makers forward.
|
||||
|
||||
**Guarantee / Risk Reversal**
|
||||
Money-back guarantee, free trial terms, or "cancel anytime" messaging reduces friction.
|
||||
|
||||
### Recommended Section Mix
|
||||
|
||||
For a landing page, aim for variety. Don't just stack features:
|
||||
|
||||
**Typical Feature-Heavy Page (Weak):**
|
||||
1. Hero
|
||||
2. Feature 1
|
||||
3. Feature 2
|
||||
4. Feature 3
|
||||
5. Feature 4
|
||||
6. CTA
|
||||
|
||||
**Varied, Engaging Page (Strong):**
|
||||
1. Hero with clear value prop
|
||||
2. Social proof bar (logos or stats)
|
||||
3. Problem/pain section
|
||||
4. How it works (3 steps)
|
||||
5. Key benefits (2-3, not 10)
|
||||
6. Testimonial
|
||||
7. Use cases or personas
|
||||
8. Comparison to alternatives
|
||||
9. Case study snippet
|
||||
10. FAQ
|
||||
11. Final CTA with guarantee
|
||||
Avoid stacking features without narrative flow.
|
||||
|
||||
---
|
||||
|
||||
## CTA Copy Guidelines
|
||||
|
||||
**Weak CTAs (avoid):**
|
||||
- Submit
|
||||
- Sign Up
|
||||
- Learn More
|
||||
- Click Here
|
||||
- Get Started
|
||||
|
||||
**Strong CTAs (use):**
|
||||
- Start Free Trial
|
||||
- Get [Specific Thing]
|
||||
- See [Product] in Action
|
||||
- Create Your First [Thing]
|
||||
- Book My Demo
|
||||
- Download the Guide
|
||||
- Try It Free
|
||||
|
||||
**CTA formula:**
|
||||
[Action Verb] + [What They Get] + [Qualifier if needed]
|
||||
|
||||
Examples:
|
||||
- "Start My Free Trial"
|
||||
- "Get the Complete Checklist"
|
||||
- "See Pricing for My Team"
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
## Phase 5 — Writing the Copy
|
||||
|
||||
When writing copy, provide:
|
||||
|
||||
@@ -368,88 +164,62 @@ When writing copy, provide:
|
||||
Organized by section with clear labels:
|
||||
- Headline
|
||||
- Subheadline
|
||||
- CTA
|
||||
- CTAs
|
||||
- Section headers
|
||||
- Body copy
|
||||
- Secondary CTAs
|
||||
|
||||
### Annotations
|
||||
For key elements, explain:
|
||||
- Why you made this choice
|
||||
- What principle it applies
|
||||
- Alternatives considered
|
||||
|
||||
### Alternatives
|
||||
For headlines and CTAs, provide 2-3 options:
|
||||
- Option A: [copy] — [rationale]
|
||||
- Option B: [copy] — [rationale]
|
||||
- Option C: [copy] — [rationale]
|
||||
Provide 2–3 options for:
|
||||
- Headlines
|
||||
- Primary CTAs
|
||||
|
||||
### Meta Content (if relevant)
|
||||
- Page title (for SEO)
|
||||
- Meta description
|
||||
Each option must include a brief rationale.
|
||||
|
||||
### Annotations
|
||||
For key sections, explain:
|
||||
- Why this copy was chosen
|
||||
- Which principle it applies
|
||||
- What alternatives were considered
|
||||
|
||||
---
|
||||
|
||||
## Page-Specific Guidance
|
||||
## Testability Guidance
|
||||
|
||||
### Homepage Copy
|
||||
- Serve multiple audiences without being generic
|
||||
- Lead with broadest value proposition
|
||||
- Provide clear paths for different visitor intents
|
||||
- Balance "ready to buy" and "still researching"
|
||||
Write copy with testing in mind:
|
||||
- Clear, isolated value propositions
|
||||
- Headlines and CTAs that can be A/B tested
|
||||
- Avoid combining multiple messages into one element
|
||||
|
||||
### Landing Page Copy
|
||||
- Single message, single CTA
|
||||
- Match headline to ad/traffic source
|
||||
- Complete argument on one page
|
||||
- Remove distractions (often no nav)
|
||||
|
||||
### Pricing Page Copy
|
||||
- Help visitors choose the right plan
|
||||
- Clarify what's included at each level
|
||||
- Address "which is right for me?" anxiety
|
||||
- Make recommended plan obvious
|
||||
|
||||
### Feature Page Copy
|
||||
- Connect feature to benefit to outcome
|
||||
- Show use cases and examples
|
||||
- Differentiate from competitors' versions
|
||||
- Clear path to try or buy
|
||||
|
||||
### About Page Copy
|
||||
- Tell the story of why you exist
|
||||
- Connect company mission to customer benefit
|
||||
- Build trust through transparency
|
||||
- Still include a CTA (it's still a marketing page)
|
||||
If the copy is intended for experimentation, recommend next-step testing.
|
||||
|
||||
---
|
||||
|
||||
## Voice and Tone Considerations
|
||||
## Completion Criteria (Hard Stop)
|
||||
|
||||
Before writing, establish:
|
||||
|
||||
**Formality level:**
|
||||
- Casual/conversational
|
||||
- Professional but friendly
|
||||
- Formal/enterprise
|
||||
|
||||
**Brand personality:**
|
||||
- Playful or serious?
|
||||
- Bold or understated?
|
||||
- Technical or accessible?
|
||||
|
||||
Maintain consistency throughout, but adjust intensity:
|
||||
- Headlines can be bolder
|
||||
- Body copy should be clearer
|
||||
- CTAs should be action-oriented
|
||||
This skill is complete ONLY when:
|
||||
- Copy brief has been confirmed
|
||||
- Page copy is delivered in structured form
|
||||
- Headline and CTA alternatives are provided
|
||||
- Assumptions are documented
|
||||
- Copy is ready for review, editing, or testing
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
## Key Principles (Summary)
|
||||
|
||||
- **copy-editing**: For polishing and improving existing copy (use after writing your first draft)
|
||||
- **page-cro**: If the page structure/strategy needs work, not just copy
|
||||
- **email-sequence**: For email copywriting
|
||||
- **popup-cro**: For popup and modal copy
|
||||
- **ab-test-setup**: To test copy variations properly
|
||||
- Understand before writing
|
||||
- Make assumptions explicit
|
||||
- One page, one goal
|
||||
- One section, one idea
|
||||
- Benefits before features
|
||||
- Honest claims only
|
||||
|
||||
---
|
||||
|
||||
## Final Reminder
|
||||
|
||||
Good copy does not persuade everyone.
|
||||
It persuades **the right person** to take **the right action**.
|
||||
|
||||
If the copy feels clever but unclear,
|
||||
rewrite it until it feels obvious.
|
||||
|
||||
167
skills/design-orchestration/SKILL.md
Normal file
167
skills/design-orchestration/SKILL.md
Normal file
@@ -0,0 +1,167 @@
|
||||
---
|
||||
name: design-orchestration
|
||||
description: >
|
||||
Orchestrates design workflows by routing work through
|
||||
brainstorming, multi-agent review, and execution readiness
|
||||
in the correct order. Prevents premature implementation,
|
||||
skipped validation, and unreviewed high-risk designs.
|
||||
---
|
||||
|
||||
# Design Orchestration (Meta-Skill)
|
||||
|
||||
## Purpose
|
||||
|
||||
Ensure that **ideas become designs**, **designs are reviewed**, and
|
||||
**only validated designs reach implementation**.
|
||||
|
||||
This skill does not generate designs.
|
||||
It **controls the flow between other skills**.
|
||||
|
||||
---
|
||||
|
||||
## Operating Model
|
||||
|
||||
This is a **routing and enforcement skill**, not a creative one.
|
||||
|
||||
It decides:
|
||||
- which skill must run next
|
||||
- whether escalation is required
|
||||
- whether execution is permitted
|
||||
|
||||
---
|
||||
|
||||
## Controlled Skills
|
||||
|
||||
This meta-skill coordinates the following:
|
||||
|
||||
- `brainstorming` — design generation
|
||||
- `multi-agent-brainstorming` — design validation
|
||||
- downstream implementation or planning skills
|
||||
|
||||
---
|
||||
|
||||
## Entry Conditions
|
||||
|
||||
Invoke this skill when:
|
||||
- a user proposes a new feature, system, or change
|
||||
- a design decision carries meaningful risk
|
||||
- correctness matters more than speed
|
||||
|
||||
---
|
||||
|
||||
## Routing Logic
|
||||
|
||||
### Step 1 — Brainstorming (Mandatory)
|
||||
|
||||
If no validated design exists:
|
||||
|
||||
- Invoke `brainstorming`
|
||||
- Require:
|
||||
- Understanding Lock
|
||||
- Initial Design
|
||||
- Decision Log started
|
||||
|
||||
You may NOT proceed without these artifacts.
|
||||
|
||||
---
|
||||
|
||||
### Step 2 — Risk Assessment
|
||||
|
||||
After brainstorming completes, classify the design as:
|
||||
|
||||
- **Low risk**
|
||||
- **Moderate risk**
|
||||
- **High risk**
|
||||
|
||||
Use factors such as:
|
||||
- user impact
|
||||
- irreversibility
|
||||
- operational cost
|
||||
- complexity
|
||||
- uncertainty
|
||||
- novelty
|
||||
|
||||
---
|
||||
|
||||
### Step 3 — Conditional Escalation
|
||||
|
||||
- **Low risk**
|
||||
→ Proceed to implementation planning
|
||||
|
||||
- **Moderate risk**
|
||||
→ Recommend `multi-agent-brainstorming`
|
||||
|
||||
- **High risk**
|
||||
→ REQUIRE `multi-agent-brainstorming`
|
||||
|
||||
Skipping escalation when required is prohibited.
|
||||
|
||||
---
|
||||
|
||||
### Step 4 — Multi-Agent Review (If Invoked)
|
||||
|
||||
If `multi-agent-brainstorming` is run:
|
||||
|
||||
Require:
|
||||
- completed Understanding Lock
|
||||
- current Design
|
||||
- Decision Log
|
||||
|
||||
Do NOT allow:
|
||||
- new ideation
|
||||
- scope expansion
|
||||
- reopening problem definition
|
||||
|
||||
Only critique, revision, and decision resolution are allowed.
|
||||
|
||||
---
|
||||
|
||||
### Step 5 — Execution Readiness Check
|
||||
|
||||
Before allowing implementation:
|
||||
|
||||
Confirm:
|
||||
- design is approved (single-agent or multi-agent)
|
||||
- Decision Log is complete
|
||||
- major assumptions are documented
|
||||
- known risks are acknowledged
|
||||
|
||||
If any condition fails:
|
||||
- block execution
|
||||
- return to the appropriate skill
|
||||
|
||||
---
|
||||
|
||||
## Enforcement Rules
|
||||
|
||||
- Do NOT allow implementation without a validated design
|
||||
- Do NOT allow skipping required review
|
||||
- Do NOT allow silent escalation or de-escalation
|
||||
- Do NOT merge design and implementation phases
|
||||
|
||||
---
|
||||
|
||||
## Exit Conditions
|
||||
|
||||
This meta-skill exits ONLY when:
|
||||
- the next step is explicitly identified, AND
|
||||
- all required prior steps are complete
|
||||
|
||||
Possible exits:
|
||||
- “Proceed to implementation planning”
|
||||
- “Run multi-agent-brainstorming”
|
||||
- “Return to brainstorming for clarification”
|
||||
- "If a reviewed design reports a final disposition of APPROVED, REVISE, or REJECT, you MUST route the workflow accordingly and state the chosen next step explicitly."
|
||||
---
|
||||
|
||||
## Design Philosophy
|
||||
|
||||
This skill exists to:
|
||||
- slow down the right decisions
|
||||
- speed up the right execution
|
||||
- prevent costly mistakes
|
||||
|
||||
Good systems fail early.
|
||||
Bad systems fail in production.
|
||||
|
||||
This meta-skill exists to enforce the former.
|
||||
479
skills/environment-setup-guide/SKILL.md
Normal file
479
skills/environment-setup-guide/SKILL.md
Normal file
@@ -0,0 +1,479 @@
|
||||
---
|
||||
name: environment-setup-guide
|
||||
description: "Guide developers through setting up development environments with proper tools, dependencies, and configurations"
|
||||
---
|
||||
|
||||
# Environment Setup Guide
|
||||
|
||||
## Overview
|
||||
|
||||
Help developers set up complete development environments from scratch. This skill provides step-by-step guidance for installing tools, configuring dependencies, setting up environment variables, and verifying the setup works correctly.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
- Use when starting a new project and need to set up the development environment
|
||||
- Use when onboarding new team members to a project
|
||||
- Use when switching to a new machine or operating system
|
||||
- Use when troubleshooting environment-related issues
|
||||
- Use when documenting setup instructions for a project
|
||||
- Use when creating development environment documentation
|
||||
|
||||
## How It Works
|
||||
|
||||
### Step 1: Identify Requirements
|
||||
|
||||
I'll help you determine what needs to be installed:
|
||||
- Programming language and version (Node.js, Python, Go, etc.)
|
||||
- Package managers (npm, pip, cargo, etc.)
|
||||
- Database systems (PostgreSQL, MongoDB, Redis, etc.)
|
||||
- Development tools (Git, Docker, IDE extensions, etc.)
|
||||
- Environment variables and configuration files
|
||||
|
||||
### Step 2: Check Current Setup
|
||||
|
||||
Before installing anything, I'll help you check what's already installed:
|
||||
```bash
|
||||
# Check versions of installed tools
|
||||
node --version
|
||||
python --version
|
||||
git --version
|
||||
docker --version
|
||||
```
|
||||
|
||||
### Step 3: Provide Installation Instructions
|
||||
|
||||
I'll give platform-specific installation commands:
|
||||
- **macOS:** Using Homebrew
|
||||
- **Linux:** Using apt, yum, or package manager
|
||||
- **Windows:** Using Chocolatey, Scoop, or direct installers
|
||||
|
||||
### Step 4: Configure the Environment
|
||||
|
||||
Help set up:
|
||||
- Environment variables (.env files)
|
||||
- Configuration files (.gitconfig, .npmrc, etc.)
|
||||
- IDE settings (VS Code, IntelliJ, etc.)
|
||||
- Shell configuration (.bashrc, .zshrc, etc.)
|
||||
|
||||
### Step 5: Verify Installation
|
||||
|
||||
Provide verification steps to ensure everything works:
|
||||
- Run version checks
|
||||
- Test basic commands
|
||||
- Verify database connections
|
||||
- Check environment variables are loaded
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Node.js Project Setup
|
||||
|
||||
```markdown
|
||||
## Setting Up Node.js Development Environment
|
||||
|
||||
### Prerequisites
|
||||
- macOS, Linux, or Windows
|
||||
- Terminal/Command Prompt access
|
||||
- Internet connection
|
||||
|
||||
### Step 1: Install Node.js
|
||||
|
||||
**macOS (using Homebrew):**
|
||||
\`\`\`bash
|
||||
# Install Homebrew if not installed
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||||
|
||||
# Install Node.js
|
||||
brew install node
|
||||
\`\`\`
|
||||
|
||||
**Linux (Ubuntu/Debian):**
|
||||
\`\`\`bash
|
||||
# Update package list
|
||||
sudo apt update
|
||||
|
||||
# Install Node.js and npm
|
||||
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
|
||||
sudo apt install -y nodejs
|
||||
\`\`\`
|
||||
|
||||
**Windows (using Chocolatey):**
|
||||
\`\`\`powershell
|
||||
# Install Chocolatey if not installed
|
||||
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
|
||||
|
||||
# Install Node.js
|
||||
choco install nodejs
|
||||
\`\`\`
|
||||
|
||||
### Step 2: Verify Installation
|
||||
|
||||
\`\`\`bash
|
||||
node --version # Should show v20.x.x or higher
|
||||
npm --version # Should show 10.x.x or higher
|
||||
\`\`\`
|
||||
|
||||
### Step 3: Install Project Dependencies
|
||||
|
||||
\`\`\`bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/your-repo/project.git
|
||||
cd project
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
\`\`\`
|
||||
|
||||
### Step 4: Set Up Environment Variables
|
||||
|
||||
Create a \`.env\` file:
|
||||
\`\`\`bash
|
||||
# Copy example environment file
|
||||
cp .env.example .env
|
||||
|
||||
# Edit with your values
|
||||
nano .env
|
||||
\`\`\`
|
||||
|
||||
Example \`.env\` content:
|
||||
\`\`\`
|
||||
NODE_ENV=development
|
||||
PORT=3000
|
||||
DATABASE_URL=postgresql://localhost:5432/mydb
|
||||
API_KEY=your-api-key-here
|
||||
\`\`\`
|
||||
|
||||
### Step 5: Run the Project
|
||||
|
||||
\`\`\`bash
|
||||
# Start development server
|
||||
npm run dev
|
||||
|
||||
# Should see: Server running on http://localhost:3000
|
||||
\`\`\`
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
**Problem:** "node: command not found"
|
||||
**Solution:** Restart your terminal or run \`source ~/.bashrc\` (Linux) or \`source ~/.zshrc\` (macOS)
|
||||
|
||||
**Problem:** "Permission denied" errors
|
||||
**Solution:** Don't use sudo with npm. Fix permissions:
|
||||
\`\`\`bash
|
||||
mkdir ~/.npm-global
|
||||
npm config set prefix '~/.npm-global'
|
||||
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### Example 2: Python Project Setup
|
||||
|
||||
```markdown
|
||||
## Setting Up Python Development Environment
|
||||
|
||||
### Step 1: Install Python
|
||||
|
||||
**macOS:**
|
||||
\`\`\`bash
|
||||
brew install python@3.11
|
||||
\`\`\`
|
||||
|
||||
**Linux:**
|
||||
\`\`\`bash
|
||||
sudo apt update
|
||||
sudo apt install python3.11 python3.11-venv python3-pip
|
||||
\`\`\`
|
||||
|
||||
**Windows:**
|
||||
\`\`\`powershell
|
||||
choco install python --version=3.11
|
||||
\`\`\`
|
||||
|
||||
### Step 2: Verify Installation
|
||||
|
||||
\`\`\`bash
|
||||
python3 --version # Should show Python 3.11.x
|
||||
pip3 --version # Should show pip 23.x.x
|
||||
\`\`\`
|
||||
|
||||
### Step 3: Create Virtual Environment
|
||||
|
||||
\`\`\`bash
|
||||
# Navigate to project directory
|
||||
cd my-project
|
||||
|
||||
# Create virtual environment
|
||||
python3 -m venv venv
|
||||
|
||||
# Activate virtual environment
|
||||
# macOS/Linux:
|
||||
source venv/bin/activate
|
||||
|
||||
# Windows:
|
||||
venv\Scripts\activate
|
||||
\`\`\`
|
||||
|
||||
### Step 4: Install Dependencies
|
||||
|
||||
\`\`\`bash
|
||||
# Install from requirements.txt
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Or install packages individually
|
||||
pip install flask sqlalchemy python-dotenv
|
||||
\`\`\`
|
||||
|
||||
### Step 5: Set Up Environment Variables
|
||||
|
||||
Create \`.env\` file:
|
||||
\`\`\`
|
||||
FLASK_APP=app.py
|
||||
FLASK_ENV=development
|
||||
DATABASE_URL=sqlite:///app.db
|
||||
SECRET_KEY=your-secret-key-here
|
||||
\`\`\`
|
||||
|
||||
### Step 6: Run the Application
|
||||
|
||||
\`\`\`bash
|
||||
# Run Flask app
|
||||
flask run
|
||||
|
||||
# Should see: Running on http://127.0.0.1:5000
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### Example 3: Docker Development Environment
|
||||
|
||||
```markdown
|
||||
## Setting Up Docker Development Environment
|
||||
|
||||
### Step 1: Install Docker
|
||||
|
||||
**macOS:**
|
||||
\`\`\`bash
|
||||
brew install --cask docker
|
||||
# Or download Docker Desktop from docker.com
|
||||
\`\`\`
|
||||
|
||||
**Linux:**
|
||||
\`\`\`bash
|
||||
# Install Docker
|
||||
curl -fsSL https://get.docker.com -o get-docker.sh
|
||||
sudo sh get-docker.sh
|
||||
|
||||
# Add user to docker group
|
||||
sudo usermod -aG docker $USER
|
||||
newgrp docker
|
||||
\`\`\`
|
||||
|
||||
**Windows:**
|
||||
Download Docker Desktop from docker.com
|
||||
|
||||
### Step 2: Verify Installation
|
||||
|
||||
\`\`\`bash
|
||||
docker --version # Should show Docker version 24.x.x
|
||||
docker-compose --version # Should show Docker Compose version 2.x.x
|
||||
\`\`\`
|
||||
|
||||
### Step 3: Create docker-compose.yml
|
||||
|
||||
\`\`\`yaml
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
app:
|
||||
build: .
|
||||
ports:
|
||||
- "3000:3000"
|
||||
environment:
|
||||
- NODE_ENV=development
|
||||
- DATABASE_URL=postgresql://postgres:password@db:5432/mydb
|
||||
volumes:
|
||||
- .:/app
|
||||
- /app/node_modules
|
||||
depends_on:
|
||||
- db
|
||||
|
||||
db:
|
||||
image: postgres:15
|
||||
environment:
|
||||
- POSTGRES_USER=postgres
|
||||
- POSTGRES_PASSWORD=password
|
||||
- POSTGRES_DB=mydb
|
||||
ports:
|
||||
- "5432:5432"
|
||||
volumes:
|
||||
- postgres_data:/var/lib/postgresql/data
|
||||
|
||||
volumes:
|
||||
postgres_data:
|
||||
\`\`\`
|
||||
|
||||
### Step 4: Start Services
|
||||
|
||||
\`\`\`bash
|
||||
# Build and start containers
|
||||
docker-compose up -d
|
||||
|
||||
# View logs
|
||||
docker-compose logs -f
|
||||
|
||||
# Stop services
|
||||
docker-compose down
|
||||
\`\`\`
|
||||
|
||||
### Step 5: Verify Services
|
||||
|
||||
\`\`\`bash
|
||||
# Check running containers
|
||||
docker ps
|
||||
|
||||
# Test database connection
|
||||
docker-compose exec db psql -U postgres -d mydb
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### ✅ Do This
|
||||
|
||||
- **Document Everything** - Write clear setup instructions
|
||||
- **Use Version Managers** - nvm for Node, pyenv for Python
|
||||
- **Create .env.example** - Show required environment variables
|
||||
- **Test on Clean System** - Verify instructions work from scratch
|
||||
- **Include Troubleshooting** - Document common issues and solutions
|
||||
- **Use Docker** - For consistent environments across machines
|
||||
- **Pin Versions** - Specify exact versions in package files
|
||||
- **Automate Setup** - Create setup scripts when possible
|
||||
- **Check Prerequisites** - List required tools before starting
|
||||
- **Provide Verification Steps** - Help users confirm setup works
|
||||
|
||||
### ❌ Don't Do This
|
||||
|
||||
- **Don't Assume Tools Installed** - Always check and provide install instructions
|
||||
- **Don't Skip Environment Variables** - Document all required variables
|
||||
- **Don't Use Sudo with npm** - Fix permissions instead
|
||||
- **Don't Forget Platform Differences** - Provide OS-specific instructions
|
||||
- **Don't Leave Out Verification** - Always include test steps
|
||||
- **Don't Use Global Installs** - Prefer local/virtual environments
|
||||
- **Don't Ignore Errors** - Document how to handle common errors
|
||||
- **Don't Skip Database Setup** - Include database initialization steps
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
### Problem: "Command not found" after installation
|
||||
**Symptoms:** Installed tool but terminal doesn't recognize it
|
||||
**Solution:**
|
||||
- Restart terminal or source shell config
|
||||
- Check PATH environment variable
|
||||
- Verify installation location
|
||||
```bash
|
||||
# Check PATH
|
||||
echo $PATH
|
||||
|
||||
# Add to PATH (example)
|
||||
export PATH="/usr/local/bin:$PATH"
|
||||
```
|
||||
|
||||
### Problem: Permission errors with npm/pip
|
||||
**Symptoms:** "EACCES" or "Permission denied" errors
|
||||
**Solution:**
|
||||
- Don't use sudo
|
||||
- Fix npm permissions or use nvm
|
||||
- Use virtual environments for Python
|
||||
```bash
|
||||
# Fix npm permissions
|
||||
mkdir ~/.npm-global
|
||||
npm config set prefix '~/.npm-global'
|
||||
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
|
||||
```
|
||||
|
||||
### Problem: Port already in use
|
||||
**Symptoms:** "Port 3000 is already in use"
|
||||
**Solution:**
|
||||
- Find and kill process using the port
|
||||
- Use a different port
|
||||
```bash
|
||||
# Find process on port 3000
|
||||
lsof -i :3000
|
||||
|
||||
# Kill process
|
||||
kill -9 <PID>
|
||||
|
||||
# Or use different port
|
||||
PORT=3001 npm start
|
||||
```
|
||||
|
||||
### Problem: Database connection fails
|
||||
**Symptoms:** "Connection refused" or "Authentication failed"
|
||||
**Solution:**
|
||||
- Verify database is running
|
||||
- Check connection string
|
||||
- Verify credentials
|
||||
```bash
|
||||
# Check if PostgreSQL is running
|
||||
sudo systemctl status postgresql
|
||||
|
||||
# Test connection
|
||||
psql -h localhost -U postgres -d mydb
|
||||
```
|
||||
|
||||
## Setup Script Template
|
||||
|
||||
Create a `setup.sh` script to automate setup:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
echo "🚀 Setting up development environment..."
|
||||
|
||||
# Check prerequisites
|
||||
command -v node >/dev/null 2>&1 || { echo "❌ Node.js not installed"; exit 1; }
|
||||
command -v git >/dev/null 2>&1 || { echo "❌ Git not installed"; exit 1; }
|
||||
|
||||
echo "✅ Prerequisites check passed"
|
||||
|
||||
# Install dependencies
|
||||
echo "📦 Installing dependencies..."
|
||||
npm install
|
||||
|
||||
# Copy environment file
|
||||
if [ ! -f .env ]; then
|
||||
echo "📝 Creating .env file..."
|
||||
cp .env.example .env
|
||||
echo "⚠️ Please edit .env with your configuration"
|
||||
fi
|
||||
|
||||
# Run database migrations
|
||||
echo "🗄️ Running database migrations..."
|
||||
npm run migrate
|
||||
|
||||
# Verify setup
|
||||
echo "🔍 Verifying setup..."
|
||||
npm run test:setup
|
||||
|
||||
echo "✅ Setup complete! Run 'npm run dev' to start"
|
||||
```
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `@brainstorming` - Plan environment requirements before setup
|
||||
- `@systematic-debugging` - Debug environment issues
|
||||
- `@doc-coauthoring` - Create setup documentation
|
||||
- `@git-pushing` - Set up Git configuration
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Node.js Installation Guide](https://nodejs.org/en/download/)
|
||||
- [Python Virtual Environments](https://docs.python.org/3/tutorial/venv.html)
|
||||
- [Docker Documentation](https://docs.docker.com/get-started/)
|
||||
- [Homebrew (macOS)](https://brew.sh/)
|
||||
- [Chocolatey (Windows)](https://chocolatey.org/)
|
||||
- [nvm (Node Version Manager)](https://github.com/nvm-sh/nvm)
|
||||
- [pyenv (Python Version Manager)](https://github.com/pyenv/pyenv)
|
||||
|
||||
---
|
||||
|
||||
**Pro Tip:** Create a `setup.sh` or `setup.ps1` script to automate the entire setup process. Test it on a clean system to ensure it works!
|
||||
36
skills/exa-search/SKILL.md
Normal file
36
skills/exa-search/SKILL.md
Normal file
@@ -0,0 +1,36 @@
|
||||
---
|
||||
name: exa-search
|
||||
description: Semantic search, similar content discovery, and structured research using Exa API
|
||||
---
|
||||
|
||||
# exa-search
|
||||
|
||||
## Overview
|
||||
Semantic search, similar content discovery, and structured research using Exa API
|
||||
|
||||
## When to Use
|
||||
- When you need semantic/embeddings-based search
|
||||
- When finding similar content
|
||||
- When searching by category (company, people, research papers, etc.)
|
||||
|
||||
## Installation
|
||||
```bash
|
||||
npx skills add -g BenedictKing/exa-search
|
||||
```
|
||||
|
||||
## Step-by-Step Guide
|
||||
1. Install the skill using the command above
|
||||
2. Configure Exa API key
|
||||
3. Use naturally in Claude Code conversations
|
||||
|
||||
## Examples
|
||||
See [GitHub Repository](https://github.com/BenedictKing/exa-search) for examples.
|
||||
|
||||
## Best Practices
|
||||
- Configure API keys via environment variables
|
||||
|
||||
## Troubleshooting
|
||||
See the GitHub repository for troubleshooting guides.
|
||||
|
||||
## Related Skills
|
||||
- context7-auto-research, tavily-web, firecrawl-scraper, codex-review
|
||||
37
skills/firecrawl-scraper/SKILL.md
Normal file
37
skills/firecrawl-scraper/SKILL.md
Normal file
@@ -0,0 +1,37 @@
|
||||
---
|
||||
name: firecrawl-scraper
|
||||
description: Deep web scraping, screenshots, PDF parsing, and website crawling using Firecrawl API
|
||||
---
|
||||
|
||||
# firecrawl-scraper
|
||||
|
||||
## Overview
|
||||
Deep web scraping, screenshots, PDF parsing, and website crawling using Firecrawl API
|
||||
|
||||
## When to Use
|
||||
- When you need deep content extraction from web pages
|
||||
- When page interaction is required (clicking, scrolling, etc.)
|
||||
- When you want screenshots or PDF parsing
|
||||
- When batch scraping multiple URLs
|
||||
|
||||
## Installation
|
||||
```bash
|
||||
npx skills add -g BenedictKing/firecrawl-scraper
|
||||
```
|
||||
|
||||
## Step-by-Step Guide
|
||||
1. Install the skill using the command above
|
||||
2. Configure Firecrawl API key
|
||||
3. Use naturally in Claude Code conversations
|
||||
|
||||
## Examples
|
||||
See [GitHub Repository](https://github.com/BenedictKing/firecrawl-scraper) for examples.
|
||||
|
||||
## Best Practices
|
||||
- Configure API keys via environment variables
|
||||
|
||||
## Troubleshooting
|
||||
See the GitHub repository for troubleshooting guides.
|
||||
|
||||
## Related Skills
|
||||
- context7-auto-research, tavily-web, exa-search, codex-review
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
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.
|
||||
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
|
||||
---
|
||||
|
||||
|
||||
256
skills/multi-agent-brainstorming/SKILL.md
Normal file
256
skills/multi-agent-brainstorming/SKILL.md
Normal file
@@ -0,0 +1,256 @@
|
||||
---
|
||||
name: multi-agent-brainstorming
|
||||
description: >
|
||||
Use this skill when a design or idea requires higher confidence,
|
||||
risk reduction, or formal review. This skill orchestrates a
|
||||
structured, sequential multi-agent design review where each agent
|
||||
has a strict, non-overlapping role. It prevents blind spots,
|
||||
false confidence, and premature convergence.
|
||||
---
|
||||
|
||||
# Multi-Agent Brainstorming (Structured Design Review)
|
||||
|
||||
## Purpose
|
||||
|
||||
Transform a single-agent design into a **robust, review-validated design**
|
||||
by simulating a formal peer-review process using multiple constrained agents.
|
||||
|
||||
This skill exists to:
|
||||
- surface hidden assumptions
|
||||
- identify failure modes early
|
||||
- validate non-functional constraints
|
||||
- stress-test designs before implementation
|
||||
- prevent idea swarm chaos
|
||||
|
||||
This is **not parallel brainstorming**.
|
||||
It is **sequential design review with enforced roles**.
|
||||
|
||||
---
|
||||
|
||||
## Operating Model
|
||||
|
||||
- One agent designs.
|
||||
- Other agents review.
|
||||
- No agent may exceed its mandate.
|
||||
- Creativity is centralized; critique is distributed.
|
||||
- Decisions are explicit and logged.
|
||||
|
||||
The process is **gated** and **terminates by design**.
|
||||
|
||||
---
|
||||
|
||||
## Agent Roles (Non-Negotiable)
|
||||
|
||||
Each agent operates under a **hard scope limit**.
|
||||
|
||||
### 1️⃣ Primary Designer (Lead Agent)
|
||||
|
||||
**Role:**
|
||||
- Owns the design
|
||||
- Runs the standard `brainstorming` skill
|
||||
- Maintains the Decision Log
|
||||
|
||||
**May:**
|
||||
- Ask clarification questions
|
||||
- Propose designs and alternatives
|
||||
- Revise designs based on feedback
|
||||
|
||||
**May NOT:**
|
||||
- Self-approve the final design
|
||||
- Ignore reviewer objections
|
||||
- Invent requirements post-lock
|
||||
|
||||
---
|
||||
|
||||
### 2️⃣ Skeptic / Challenger Agent
|
||||
|
||||
**Role:**
|
||||
- Assume the design will fail
|
||||
- Identify weaknesses and risks
|
||||
|
||||
**May:**
|
||||
- Question assumptions
|
||||
- Identify edge cases
|
||||
- Highlight ambiguity or overconfidence
|
||||
- Flag YAGNI violations
|
||||
|
||||
**May NOT:**
|
||||
- Propose new features
|
||||
- Redesign the system
|
||||
- Offer alternative architectures
|
||||
|
||||
Prompting guidance:
|
||||
> “Assume this design fails in production. Why?”
|
||||
|
||||
---
|
||||
|
||||
### 3️⃣ Constraint Guardian Agent
|
||||
|
||||
**Role:**
|
||||
- Enforce non-functional and real-world constraints
|
||||
|
||||
Focus areas:
|
||||
- performance
|
||||
- scalability
|
||||
- reliability
|
||||
- security & privacy
|
||||
- maintainability
|
||||
- operational cost
|
||||
|
||||
**May:**
|
||||
- Reject designs that violate constraints
|
||||
- Request clarification of limits
|
||||
|
||||
**May NOT:**
|
||||
- Debate product goals
|
||||
- Suggest feature changes
|
||||
- Optimize beyond stated requirements
|
||||
|
||||
---
|
||||
|
||||
### 4️⃣ User Advocate Agent
|
||||
|
||||
**Role:**
|
||||
- Represent the end user
|
||||
|
||||
Focus areas:
|
||||
- cognitive load
|
||||
- usability
|
||||
- clarity of flows
|
||||
- error handling from user perspective
|
||||
- mismatch between intent and experience
|
||||
|
||||
**May:**
|
||||
- Identify confusing or misleading aspects
|
||||
- Flag poor defaults or unclear behavior
|
||||
|
||||
**May NOT:**
|
||||
- Redesign architecture
|
||||
- Add features
|
||||
- Override stated user goals
|
||||
|
||||
---
|
||||
|
||||
### 5️⃣ Integrator / Arbiter Agent
|
||||
|
||||
**Role:**
|
||||
- Resolve conflicts
|
||||
- Finalize decisions
|
||||
- Enforce exit criteria
|
||||
|
||||
**May:**
|
||||
- Accept or reject objections
|
||||
- Require design revisions
|
||||
- Declare the design complete
|
||||
|
||||
**May NOT:**
|
||||
- Invent new ideas
|
||||
- Add requirements
|
||||
- Reopen locked decisions without cause
|
||||
|
||||
---
|
||||
|
||||
## The Process
|
||||
|
||||
### Phase 1 — Single-Agent Design
|
||||
|
||||
1. Primary Designer runs the **standard `brainstorming` skill**
|
||||
2. Understanding Lock is completed and confirmed
|
||||
3. Initial design is produced
|
||||
4. Decision Log is started
|
||||
|
||||
No other agents participate yet.
|
||||
|
||||
---
|
||||
|
||||
### Phase 2 — Structured Review Loop
|
||||
|
||||
Agents are invoked **one at a time**, in the following order:
|
||||
|
||||
1. Skeptic / Challenger
|
||||
2. Constraint Guardian
|
||||
3. User Advocate
|
||||
|
||||
For each reviewer:
|
||||
- Feedback must be explicit and scoped
|
||||
- Objections must reference assumptions or decisions
|
||||
- No new features may be introduced
|
||||
|
||||
Primary Designer must:
|
||||
- Respond to each objection
|
||||
- Revise the design if required
|
||||
- Update the Decision Log
|
||||
|
||||
---
|
||||
|
||||
### Phase 3 — Integration & Arbitration
|
||||
|
||||
The Integrator / Arbiter reviews:
|
||||
- the final design
|
||||
- the Decision Log
|
||||
- unresolved objections
|
||||
|
||||
The Arbiter must explicitly decide:
|
||||
- which objections are accepted
|
||||
- which are rejected (with rationale)
|
||||
|
||||
---
|
||||
|
||||
## Decision Log (Mandatory Artifact)
|
||||
|
||||
The Decision Log must record:
|
||||
|
||||
- Decision made
|
||||
- Alternatives considered
|
||||
- Objections raised
|
||||
- Resolution and rationale
|
||||
|
||||
No design is considered valid without a completed log.
|
||||
|
||||
---
|
||||
|
||||
## Exit Criteria (Hard Stop)
|
||||
|
||||
You may exit multi-agent brainstorming **only when all are true**:
|
||||
|
||||
- Understanding Lock was completed
|
||||
- All reviewer agents have been invoked
|
||||
- All objections are resolved or explicitly rejected
|
||||
- Decision Log is complete
|
||||
- Arbiter has declared the design acceptable
|
||||
-
|
||||
If any criterion is unmet:
|
||||
- Continue review
|
||||
- Do NOT proceed to implementation
|
||||
If this skill was invoked by a routing or orchestration layer, you MUST report the final disposition explicitly as one of: APPROVED, REVISE, or REJECT, with a brief rationale.
|
||||
---
|
||||
|
||||
## Failure Modes This Skill Prevents
|
||||
|
||||
- Idea swarm chaos
|
||||
- Hallucinated consensus
|
||||
- Overconfident single-agent designs
|
||||
- Hidden assumptions
|
||||
- Premature implementation
|
||||
- Endless debate
|
||||
|
||||
---
|
||||
|
||||
## Key Principles
|
||||
|
||||
- One designer, many reviewers
|
||||
- Creativity is centralized
|
||||
- Critique is constrained
|
||||
- Decisions are explicit
|
||||
- Process must terminate
|
||||
|
||||
---
|
||||
|
||||
## Final Reminder
|
||||
|
||||
This skill exists to answer one question with confidence:
|
||||
|
||||
> “If this design fails, did we do everything reasonable to catch it early?”
|
||||
|
||||
If the answer is unclear, **do not exit this skill**.
|
||||
|
||||
111
skills/nosql-expert/SKILL.md
Normal file
111
skills/nosql-expert/SKILL.md
Normal file
@@ -0,0 +1,111 @@
|
||||
---
|
||||
name: nosql-expert
|
||||
description: "Expert guidance for distributed NoSQL databases (Cassandra, DynamoDB). Focuses on mental models, query-first modeling, single-table design, and avoiding hot partitions in high-scale systems."
|
||||
---
|
||||
|
||||
# NoSQL Expert Patterns (Cassandra & DynamoDB)
|
||||
|
||||
## Overview
|
||||
|
||||
This skill provides professional mental models and design patterns for **distributed wide-column and key-value stores** (specifically Apache Cassandra and Amazon DynamoDB).
|
||||
|
||||
Unlike SQL (where you model data entities), or document stores (like MongoDB), these distributed systems require you to **model your queries first**.
|
||||
|
||||
## When to Use
|
||||
|
||||
- **Designing for Scale**: Moving beyond simple single-node databases to distributed clusters.
|
||||
- **Technology Selection**: Evaluating or using **Cassandra**, **ScyllaDB**, or **DynamoDB**.
|
||||
- **Performance Tuning**: Troubleshooting "hot partitions" or high latency in existing NoSQL systems.
|
||||
- **Microservices**: Implementing "database-per-service" patterns where highly optimized reads are required.
|
||||
|
||||
## The Mental Shift: SQL vs. Distributed NoSQL
|
||||
|
||||
| Feature | SQL (Relational) | Distributed NoSQL (Cassandra/DynamoDB) |
|
||||
| :--- | :--- | :--- |
|
||||
| **Data modeling** | Model Entities + Relationships | Model **Queries** (Access Patterns) |
|
||||
| **Joins** | CPU-intensive, at read time | **Pre-computed** (Denormalized) at write time |
|
||||
| **Storage cost** | Expensive (minimize duplication) | Cheap (duplicate data for read speed) |
|
||||
| **Consistency** | ACID (Strong) | **BASE (Eventual)** / Tunable |
|
||||
| **Scalability** | Vertical (Bigger machine) | **Horizontal** (More nodes/shards) |
|
||||
|
||||
> **The Golden Rule:** In SQL, you design the data model to answer *any* query. In NoSQL, you design the data model to answer *specific* queries efficiently.
|
||||
|
||||
## Core Design Patterns
|
||||
|
||||
### 1. Query-First Modeling (Access Patterns)
|
||||
|
||||
You typically cannot "add a query later" without migration or creating a new table/index.
|
||||
|
||||
**Process:**
|
||||
1. **List all Entities** (User, Order, Product).
|
||||
2. **List all Access Patterns** ("Get User by Email", "Get Orders by User sorted by Date").
|
||||
3. **Design Table(s)** specifically to serve those patterns with a single lookup.
|
||||
|
||||
### 2. The Partition Key is King
|
||||
|
||||
Data is distributed across physical nodes based on the **Partition Key (PK)**.
|
||||
- **Goal:** Even distribution of data and traffic.
|
||||
- **Anti-Pattern:** Using a low-cardinality PK (e.g., `status="active"` or `gender="m"`) creates **Hot Partitions**, limiting throughput to a single node's capacity.
|
||||
- **Best Practice:** Use high-cardinality keys (User IDs, Device IDs, Composite Keys).
|
||||
|
||||
### 3. Clustering / Sort Keys
|
||||
|
||||
Within a partition, data is sorted on disk by the **Clustering Key (Cassandra)** or **Sort Key (DynamoDB)**.
|
||||
- This allows for efficient **Range Queries** (e.g., `WHERE user_id=X AND date > Y`).
|
||||
- It effectively pre-sorts your data for specific retrieval requirements.
|
||||
|
||||
### 4. Single-Table Design (Adjacency Lists)
|
||||
|
||||
*Primary use: DynamoDB (but concepts apply elsewhere)*
|
||||
|
||||
Storing multiple entity types in one table to enable pre-joined reads.
|
||||
|
||||
| PK (Partition) | SK (Sort) | Data Fields... |
|
||||
| :--- | :--- | :--- |
|
||||
| `USER#123` | `PROFILE` | `{ name: "Ian", email: "..." }` |
|
||||
| `USER#123` | `ORDER#998` | `{ total: 50.00, status: "shipped" }` |
|
||||
| `USER#123` | `ORDER#999` | `{ total: 12.00, status: "pending" }` |
|
||||
|
||||
- **Query:** `PK="USER#123"`
|
||||
- **Result:** Fetches User Profile AND all Orders in **one network request**.
|
||||
|
||||
### 5. Denormalization & Duplication
|
||||
|
||||
Don't be afraid to store the same data in multiple tables to serve different query patterns.
|
||||
- **Table A:** `users_by_id` (PK: uuid)
|
||||
- **Table B:** `users_by_email` (PK: email)
|
||||
|
||||
*Trade-off: You must manage data consistency across tables (often using eventual consistency or batch writes).*
|
||||
|
||||
## Specific Guidance
|
||||
|
||||
### Apache Cassandra / ScyllaDB
|
||||
|
||||
- **Primary Key Structure:** `((Partition Key), Clustering Columns)`
|
||||
- **No Joins, No Aggregates:** Do not try to `JOIN` or `GROUP BY`. Pre-calculate aggregates in a separate counter table.
|
||||
- **Avoid `ALLOW FILTERING`:** If you see this in production, your data model is wrong. It implies a full cluster scan.
|
||||
- **Writes are Cheap:** Inserts and Updates are just appends to the LSM tree. Don't worry about write volume as much as read efficiency.
|
||||
- **Tombstones:** Deletes are expensive markers. Avoid high-velocity delete patterns (like queues) in standard tables.
|
||||
|
||||
### AWS DynamoDB
|
||||
|
||||
- **GSI (Global Secondary Index):** Use GSIs to create alternative views of your data (e.g., "Search Orders by Date" instead of by User).
|
||||
- *Note:* GSIs are eventually consistent.
|
||||
- **LSI (Local Secondary Index):** Sorts data differently *within* the same partition. Must be created at table creation time.
|
||||
- **WCU / RCU:** Understand capacity modes. Single-table design helps optimize consumed capacity units.
|
||||
- **TTL:** Use Time-To-Live attributes to automatically expire old data (free delete) without creating tombstones.
|
||||
|
||||
## Expert Checklist
|
||||
|
||||
Before finalizing your NoSQL schema:
|
||||
|
||||
- [ ] **Access Pattern Coverage:** Does every query pattern map to a specific table or index?
|
||||
- [ ] **Cardinality Check:** Does the Partition Key have enough unique values to spread traffic evenly?
|
||||
- [ ] **Split Partition Risk:** For any single partition (e.g., a single user's orders), will it grow indefinitely? (If > 10GB, you need to "shard" the partition, e.g., `USER#123#2024-01`).
|
||||
- [ ] **Consistency Requirement:** Can the application tolerate eventual consistency for this read pattern?
|
||||
|
||||
## Common Anti-Patterns
|
||||
|
||||
❌ **Scatter-Gather:** Querying *all* partitions to find one item (Scan).
|
||||
❌ **Hot Keys:** Putting all "Monday" data into one partition.
|
||||
❌ **Relational Modeling:** Creating `Author` and `Book` tables and trying to join them in code. (Instead, embed Book summaries in Author, or duplicate Author info in Books).
|
||||
64
skills/obsidian-clipper-template-creator/SKILL.md
Normal file
64
skills/obsidian-clipper-template-creator/SKILL.md
Normal file
@@ -0,0 +1,64 @@
|
||||
---
|
||||
name: obsidian-clipper-template-creator
|
||||
description: Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
|
||||
---
|
||||
|
||||
# Obsidian Web Clipper Template Creator
|
||||
|
||||
This skill helps you create importable JSON templates for the Obsidian Web Clipper.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Identify User Intent:** specific site (YouTube), specific type (Recipe), or general clipping?
|
||||
2. **Check Existing Bases:** The user likely has a "Base" schema defined in `Templates/Bases/`.
|
||||
- **Action:** Read `Templates/Bases/*.base` to find a matching category (e.g., `Recipes.base`).
|
||||
- **Action:** Use the properties defined in the Base to structure the Clipper template properties.
|
||||
- See [references/bases-workflow.md](references/bases-workflow.md) for details.
|
||||
3. **Fetch & Analyze Reference URL:** Validate variables against a real page.
|
||||
- **Action:** Ask the user for a sample URL of the content they want to clip (if not provided).
|
||||
- **Action (REQUIRED):** Use `WebFetch` or a browser DOM snapshot to retrieve page content before choosing any selector.
|
||||
- **Action:** Analyze the HTML for Schema.org JSON, Meta tags, and CSS selectors.
|
||||
- **Action (REQUIRED):** Verify each selector against the fetched content. Do not guess selectors.
|
||||
- See [references/analysis-workflow.md](references/analysis-workflow.md) for analysis techniques.
|
||||
4. **Draft the JSON:** Create a valid JSON object following the schema.
|
||||
- See [references/json-schema.md](references/json-schema.md).
|
||||
5. **Verify Variables:** Ensure the chosen variables (Preset, Schema, Selector) exist in your analysis.
|
||||
- **Action (REQUIRED):** If a selector cannot be verified from the fetched content, state that explicitly and ask for another URL.
|
||||
- See [references/variables.md](references/variables.md).
|
||||
|
||||
## Selector Verification Rules
|
||||
|
||||
- **Always verify selectors** against live page content before responding.
|
||||
- **Never guess selectors.** If the DOM cannot be accessed or the element is missing, ask for another URL or a screenshot.
|
||||
- **Prefer stable selectors** (data attributes, semantic roles, unique IDs) over fragile class chains.
|
||||
- **Document the target element** in your reasoning (e.g., "About sidebar paragraph") to reduce mismatch.
|
||||
|
||||
## Output Format
|
||||
|
||||
**ALWAYS** output the final result as a JSON code block that the user can copy and import.
|
||||
|
||||
```json
|
||||
{
|
||||
"schemaVersion": "0.1.0",
|
||||
"name": "My Template",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- [references/variables.md](references/variables.md) - Available data variables.
|
||||
- [references/filters.md](references/filters.md) - Formatting filters.
|
||||
- [references/json-schema.md](references/json-schema.md) - JSON structure documentation.
|
||||
- [references/bases-workflow.md](references/bases-workflow.md) - How to map Bases to Templates.
|
||||
- [references/analysis-workflow.md](references/analysis-workflow.md) - How to validate page data.
|
||||
|
||||
### Official Documentation
|
||||
|
||||
- [Variables](https://help.obsidian.md/web-clipper/variables)
|
||||
- [Filters](https://help.obsidian.md/web-clipper/filters)
|
||||
- [Templates](https://help.obsidian.md/web-clipper/templates)
|
||||
|
||||
## Examples
|
||||
|
||||
See [assets/](assets/) for JSON examples.
|
||||
@@ -0,0 +1,51 @@
|
||||
{
|
||||
"schemaVersion": "0.1.0",
|
||||
"name": "General Clipping",
|
||||
"behavior": "create",
|
||||
"noteContentFormat": "{{content}}",
|
||||
"properties": [
|
||||
{
|
||||
"name": "categories",
|
||||
"value": "[[Clippings]]",
|
||||
"type": "multitext"
|
||||
},
|
||||
{
|
||||
"name": "author",
|
||||
"value": "[[{{author}}]]",
|
||||
"type": "multitext"
|
||||
},
|
||||
{
|
||||
"name": "source",
|
||||
"value": "{{url}}",
|
||||
"type": "text"
|
||||
},
|
||||
{
|
||||
"name": "via",
|
||||
"value": "",
|
||||
"type": "text"
|
||||
},
|
||||
{
|
||||
"name": "published",
|
||||
"value": "{{published}}",
|
||||
"type": "datetime"
|
||||
},
|
||||
{
|
||||
"name": "created",
|
||||
"value": "{{date}}",
|
||||
"type": "datetime"
|
||||
},
|
||||
{
|
||||
"name": "topics",
|
||||
"value": "",
|
||||
"type": "multitext"
|
||||
},
|
||||
{
|
||||
"name": "description",
|
||||
"value": "{{description}}",
|
||||
"type": "text"
|
||||
}
|
||||
],
|
||||
"triggers": [],
|
||||
"noteNameFormat": "{{title}}",
|
||||
"path": "Clippings/"
|
||||
}
|
||||
@@ -0,0 +1,48 @@
|
||||
{
|
||||
"schemaVersion": "0.1.0",
|
||||
"name": "Recipe",
|
||||
"behavior": "create",
|
||||
"noteContentFormat": "![{{schema:Recipe:image|first}}]\n\n## Description\n{{schema:Recipe:description}}\n\n## Ingredients\n{{schema:Recipe:recipeIngredient|list}}\n\n## Instructions\n{{schema:Recipe:recipeInstructions|map:step =>> step.text|list}}\n\n## Nutrition\n- Calories: {{schema:Recipe:nutrition.calories}}",
|
||||
"properties": [
|
||||
{
|
||||
"name": "categories",
|
||||
"value": "[[Recipes]]",
|
||||
"type": "multitext"
|
||||
},
|
||||
{
|
||||
"name": "author",
|
||||
"value": "[[{{schema:Recipe:author.name}}]]",
|
||||
"type": "text"
|
||||
},
|
||||
{
|
||||
"name": "source",
|
||||
"value": "{{url}}",
|
||||
"type": "text"
|
||||
},
|
||||
{
|
||||
"name": "ingredients",
|
||||
"value": "{{schema:Recipe:recipeIngredient}}",
|
||||
"type": "multitext"
|
||||
},
|
||||
{
|
||||
"name": "cuisine",
|
||||
"value": "{{schema:Recipe:recipeCuisine}}",
|
||||
"type": "text"
|
||||
},
|
||||
{
|
||||
"name": "rating",
|
||||
"value": "",
|
||||
"type": "number"
|
||||
},
|
||||
{
|
||||
"name": "type",
|
||||
"value": "Recipe",
|
||||
"type": "text"
|
||||
}
|
||||
],
|
||||
"triggers": [
|
||||
"schema:Recipe"
|
||||
],
|
||||
"noteNameFormat": "{{schema:Recipe:name}}",
|
||||
"path": "Recipes/"
|
||||
}
|
||||
@@ -0,0 +1,79 @@
|
||||
# Analysis Workflow: Validating Variables
|
||||
|
||||
To ensure your template works correctly, you must validate that the target page actually contains the data you want to extract.
|
||||
|
||||
## 1. Fetch the Page
|
||||
|
||||
Use the `WebFetch` tool or a browser DOM snapshot to retrieve the content of a representative URL provided by the user.
|
||||
|
||||
```text
|
||||
WebFetch(url="https://example.com/recipe/chocolate-cake")
|
||||
```
|
||||
|
||||
## 2. Analyze the Output
|
||||
|
||||
### Check for Schema.org (Recommended)
|
||||
|
||||
Look for `<script type="application/ld+json">`. This contains structured data which is the most reliable way to extract info.
|
||||
|
||||
**Example Found in HTML:**
|
||||
|
||||
```html
|
||||
<script type="application/ld+json">
|
||||
{
|
||||
"@context": "https://schema.org/",
|
||||
"@type": "Recipe",
|
||||
"name": "Chocolate Cake",
|
||||
"author": {
|
||||
"@type": "Person",
|
||||
"name": "John Doe"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Conclusion:**
|
||||
|
||||
- `{{schema:Recipe:name}}` is valid.
|
||||
- `{{schema:Recipe:author.name}}` is valid.
|
||||
- **Tip:** You can use `schema:Recipe` in the `triggers` array to automatically select this template for any page with this schema.
|
||||
|
||||
### Check for Meta Tags
|
||||
|
||||
Look for `<meta>` tags in the `<head>` section.
|
||||
|
||||
**Example Found in HTML:**
|
||||
|
||||
```html
|
||||
<meta property="og:title" content="The Best Chocolate Cake" />
|
||||
<meta name="description" content="A rich, moist chocolate cake recipe." />
|
||||
```
|
||||
|
||||
**Conclusion:**
|
||||
|
||||
- `{{meta:og:title}}` is valid.
|
||||
- `{{meta:description}}` is valid.
|
||||
|
||||
### Check for CSS Selectors (Verified)
|
||||
|
||||
If Schema and Meta tags are missing, look for HTML structure (classes and IDs) to use with `{{selector:...}}`.
|
||||
Selectors must be verified against the fetched HTML or DOM snapshot. Do not guess selectors.
|
||||
|
||||
**Example Found in HTML:**
|
||||
|
||||
```html
|
||||
<div class="article-body">
|
||||
<h1 id="main-title">Chocolate Cake</h1>
|
||||
<span class="author-name">By John Doe</span>
|
||||
</div>
|
||||
```
|
||||
|
||||
**Conclusion:**
|
||||
|
||||
- `{{selector:h1#main-title}}` or `{{selector:h1}}` can extract the title.
|
||||
- `{{selector:.author-name}}` can extract the author.
|
||||
|
||||
## 3. Verify Against Base
|
||||
|
||||
Compare the available data from your analysis with the properties required by the user's Base (see `references/bases-workflow.md`).
|
||||
|
||||
- If the Base requires `ingredients` but the page has no Schema or clear list structure, warn the user that this field might need manual entry or a prompt variable.
|
||||
@@ -0,0 +1,44 @@
|
||||
# Working with Obsidian Bases
|
||||
|
||||
The user maintains "Bases" in `Templates/Bases/*.base` which define the schema and properties for different types of notes (e.g., Recipes, Clippings, People).
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Identify the Category:** Determine the type of content the user wants to clip (e.g., a Recipe, a News Article, a YouTube video).
|
||||
2. **Find the Base:** Search `Templates/Bases/` for a matching `.base` file.
|
||||
* Example: For a recipe, look for `Templates/Bases/Recipes.base`.
|
||||
* Example: For a generic article, look for `Templates/Bases/Clippings.base`.
|
||||
3. **Read the Base:** Read the content of the `.base` file to understand the required properties.
|
||||
|
||||
## Interpreting .base Files
|
||||
|
||||
Base files use a YAML-like structure. Look for the `properties` section.
|
||||
|
||||
```yaml
|
||||
properties:
|
||||
file.name:
|
||||
displayName: name
|
||||
note.author:
|
||||
displayName: author
|
||||
note.type:
|
||||
displayName: type
|
||||
note.ingredients:
|
||||
displayName: ingredients
|
||||
```
|
||||
|
||||
* `note.X` corresponds to a property name `X` in the frontmatter.
|
||||
* `displayName` helps understand the intent, but the property key (e.g., `author`, `type`, `ingredients`) is what matters for the template.
|
||||
|
||||
## Mapping to Clipper Properties
|
||||
|
||||
When creating the JSON for the Web Clipper, map the Base properties to the `properties` array in the JSON.
|
||||
|
||||
| Base Property | Clipper JSON Property Name | Value Strategy |
|
||||
| :--- | :--- | :--- |
|
||||
| `note.author` | `author` | `{{author}}` or `{{schema:author.name}}` |
|
||||
| `note.source` | `source` | `{{url}}` |
|
||||
| `note.published` | `published` | `{{published}}` |
|
||||
| `note.ingredients` | `ingredients` | `{{schema:Recipe:recipeIngredient}}` |
|
||||
| `note.type` | `type` | Constant (e.g., `Recipe`) or empty |
|
||||
|
||||
**Crucial Step:** Ask the user which properties should be automatically filled, which should be hardcoded (e.g., `type: Recipe`), and which should be left empty for manual entry.
|
||||
@@ -0,0 +1,51 @@
|
||||
# Obsidian Web Clipper Filters
|
||||
|
||||
**Official Docs:** [help.obsidian.md/web-clipper/filters](https://help.obsidian.md/web-clipper/filters)
|
||||
|
||||
Use filters to format variables: `{{variable|filter}}`.
|
||||
|
||||
## Text Formatting
|
||||
- `markdown`: Convert HTML to Markdown.
|
||||
- `strip_tags`: Remove HTML tags.
|
||||
- `trim`: Remove whitespace.
|
||||
- `upper`: Convert to uppercase.
|
||||
- `lower`: Convert to lowercase.
|
||||
- `title`: Title Case.
|
||||
- `capitalize`: Capitalize first letter.
|
||||
- `camel`: CamelCase.
|
||||
- `kebab`: kebab-case.
|
||||
- `snake`: snake_case.
|
||||
- `pascal`: PascalCase.
|
||||
- `replace:"old","new"`: Replace text.
|
||||
- `safe_name`: Make safe for filenames.
|
||||
- `blockquote`: Format as blockquote.
|
||||
- `link`: Create markdown link.
|
||||
- `wikilink`: Create [[wikilink]].
|
||||
- `list`: Format array as list.
|
||||
- `table`: Format array as table.
|
||||
- `callout`: Format as callout block.
|
||||
|
||||
## Dates
|
||||
- `date:"format"`: Format date (e.g., `YYYY-MM-DD`).
|
||||
- `date_modify:"+1 day"`: Modify date.
|
||||
- `duration`: Format duration.
|
||||
|
||||
## Numbers
|
||||
- `calc`: Perform calculations.
|
||||
- `length`: Get length of string/array.
|
||||
- `round`: Round numbers.
|
||||
|
||||
## HTML Processing
|
||||
- `remove_html`: Remove HTML tags.
|
||||
- `remove_attr`: Remove attributes.
|
||||
- `strip_attr`: Strip specific attributes.
|
||||
|
||||
## Arrays and Objects
|
||||
- `map`: Transform array items (e.g., `map:item =>> item.text`).
|
||||
- `join:"separator"`: Join array items.
|
||||
- `split:"separator"`: Split string into array.
|
||||
- `first`: First item.
|
||||
- `last`: Last item.
|
||||
- `slice:start,end`: Slice array.
|
||||
- `unique`: Unique items.
|
||||
- `template:"format"`: Format items using a template string.
|
||||
@@ -0,0 +1,71 @@
|
||||
# Obsidian Web Clipper JSON Schema
|
||||
|
||||
The Obsidian Web Clipper imports templates via JSON files.
|
||||
|
||||
## Root Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"schemaVersion": "0.1.0",
|
||||
"name": "Template Name",
|
||||
"behavior": "create",
|
||||
"noteContentFormat": "Markdown content here...",
|
||||
"properties": [],
|
||||
"triggers": [],
|
||||
"noteNameFormat": "{{title}}",
|
||||
"path": "Inbox/"
|
||||
}
|
||||
```
|
||||
|
||||
### Fields
|
||||
|
||||
* **`schemaVersion`**: Always "0.1.0".
|
||||
* **`name`**: The display name of the template in the Clipper.
|
||||
* **`behavior`**: How the note is created.
|
||||
* `create`: Create a new note.
|
||||
* `append-specific`: Append to a specific note (requires `path` to be a full file path).
|
||||
* `append-daily`: Append to the daily note.
|
||||
* **`noteContentFormat`**: The body of the note.
|
||||
* Use `\n` for newlines.
|
||||
* Can use all variables (e.g., `{{content}}`, `{{selection}}`).
|
||||
* **`noteNameFormat`**: The filename pattern (e.g., `{{date}} - {{title}}`).
|
||||
* **`path`**: The location to save the note.
|
||||
* For `create` behavior: The *folder* to save the note in (e.g., `Clippings/` or `Recipes/`).
|
||||
* For `append-specific` behavior: The *full file path* of the note to append to (e.g., `Databases/Recipes.md`).
|
||||
* **`triggers`**: Array of strings to automatically select this template.
|
||||
* **URL Patterns**: `["https://www.youtube.com/watch"]` (Simple string or Regex).
|
||||
* **Schema Types**: `["schema:Recipe"]` (Triggers if the page contains this Schema.org type).
|
||||
|
||||
## Properties
|
||||
|
||||
The `properties` array defines the YAML frontmatter of the note.
|
||||
|
||||
```json
|
||||
"properties": [
|
||||
{
|
||||
"name": "category",
|
||||
"value": "Recipes",
|
||||
"type": "text"
|
||||
},
|
||||
{
|
||||
"name": "published",
|
||||
"value": "{{published}}",
|
||||
"type": "datetime"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Property Types
|
||||
|
||||
* **`text`**: Simple text string.
|
||||
* **`multitext`**: List of text strings (for tags/aliases).
|
||||
* **`number`**: Numeric value.
|
||||
* **`checkbox`**: Boolean true/false.
|
||||
* **`date`**: Date string (YYYY-MM-DD).
|
||||
* **`datetime`**: Date and time string.
|
||||
|
||||
### Property Object Structure
|
||||
|
||||
* **`name`**: The key in the YAML frontmatter.
|
||||
* **`value`**: The value to populate. Can contain variables.
|
||||
* **`type`**: One of the types listed above.
|
||||
@@ -0,0 +1,59 @@
|
||||
# Obsidian Web Clipper Variables
|
||||
|
||||
**Official Docs:** [help.obsidian.md/web-clipper/variables](https://help.obsidian.md/web-clipper/variables)
|
||||
|
||||
## Preset Variables
|
||||
Automatically extracted from the page.
|
||||
|
||||
- `{{content}}`: Main article content (markdown).
|
||||
- `{{contentHtml}}`: Main article content (HTML).
|
||||
- `{{title}}`: Page title.
|
||||
- `{{url}}`: Page URL.
|
||||
- `{{author}}`: Author name.
|
||||
- `{{date}}`: Current date.
|
||||
- `{{published}}`: Publication date (if detected).
|
||||
- `{{site}}`: Site name.
|
||||
- `{{description}}`: Meta description.
|
||||
- `{{highlights}}`: Highlighted text (if any).
|
||||
- `{{selection}}`: Selected text.
|
||||
- `{{fullHtml}}`: Full page HTML.
|
||||
- `{{favicon}}`: Favicon URL.
|
||||
- `{{image}}`: Social share image URL.
|
||||
- `{{words}}`: Word count.
|
||||
- `{{domain}}`: Domain name.
|
||||
|
||||
## Prompt Variables (AI)
|
||||
Use `{{"Your prompt here"}}` to ask the AI Interpreter to extract or summarize info.
|
||||
*Requires Interpreter to be enabled.*
|
||||
|
||||
Examples:
|
||||
- `{{"Summarize in 3 bullet points"}}`
|
||||
- `{{"Extract the ingredients list"}}`
|
||||
- `{{"Translate to English"}}`
|
||||
|
||||
## Selector Variables
|
||||
Extract content using CSS selectors.
|
||||
Syntax: `{{selector:css-selector}}` or `{{selector:css-selector?attribute}}`
|
||||
|
||||
Examples:
|
||||
- `{{selector:h1}}`: Text of H1 tag.
|
||||
- `{{selector:img.hero?src}}`: Source of image with class 'hero'.
|
||||
- `{{selector:.author}}`: Text of element with class 'author'.
|
||||
- `{{selectorHtml:body|markdown}}`: Full HTML converted to markdown.
|
||||
|
||||
## Meta Variables
|
||||
Extract data from meta tags.
|
||||
Syntax: `{{meta:name}}` or `{{meta:property}}`
|
||||
|
||||
Examples:
|
||||
- `{{meta:description}}`
|
||||
- `{{meta:og:title}}`
|
||||
|
||||
## Schema.org Variables
|
||||
Extract structured data.
|
||||
Syntax: `{{schema:Property}}` or `{{schema:@Type:Property}}`
|
||||
|
||||
Examples:
|
||||
- `{{schema:Recipe:recipeIngredient}}`
|
||||
- `{{schema:author.name}}`
|
||||
- `{{schema:Article:headline}}`
|
||||
1490
skills/postgres-best-practices/AGENTS.md
Normal file
1490
skills/postgres-best-practices/AGENTS.md
Normal file
File diff suppressed because it is too large
Load Diff
119
skills/postgres-best-practices/README.md
Normal file
119
skills/postgres-best-practices/README.md
Normal file
@@ -0,0 +1,119 @@
|
||||
# Postgres Best Practices - Contributor Guide
|
||||
|
||||
This repository contains Postgres performance optimization rules optimized for
|
||||
AI agents and LLMs.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
cd packages/postgres-best-practices-build
|
||||
npm install
|
||||
|
||||
# Validate existing rules
|
||||
npm run validate
|
||||
|
||||
# Build AGENTS.md
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Creating a New Rule
|
||||
|
||||
1. **Choose a section prefix** based on the category:
|
||||
- `query-` Query Performance (CRITICAL)
|
||||
- `conn-` Connection Management (CRITICAL)
|
||||
- `security-` Security & RLS (CRITICAL)
|
||||
- `schema-` Schema Design (HIGH)
|
||||
- `lock-` Concurrency & Locking (MEDIUM-HIGH)
|
||||
- `data-` Data Access Patterns (MEDIUM)
|
||||
- `monitor-` Monitoring & Diagnostics (LOW-MEDIUM)
|
||||
- `advanced-` Advanced Features (LOW)
|
||||
|
||||
2. **Copy the template**:
|
||||
```bash
|
||||
cp rules/_template.md rules/query-your-rule-name.md
|
||||
```
|
||||
|
||||
3. **Fill in the content** following the template structure
|
||||
|
||||
4. **Validate and build**:
|
||||
```bash
|
||||
npm run validate
|
||||
npm run build
|
||||
```
|
||||
|
||||
5. **Review** the generated `AGENTS.md`
|
||||
|
||||
## Repository Structure
|
||||
|
||||
```
|
||||
skills/postgres-best-practices/
|
||||
├── SKILL.md # Agent-facing skill manifest
|
||||
├── AGENTS.md # [GENERATED] Compiled rules document
|
||||
├── README.md # This file
|
||||
├── metadata.json # Version and metadata
|
||||
└── rules/
|
||||
├── _template.md # Rule template
|
||||
├── _sections.md # Section definitions
|
||||
├── _contributing.md # Writing guidelines
|
||||
└── *.md # Individual rules
|
||||
|
||||
packages/postgres-best-practices-build/
|
||||
├── src/ # Build system source
|
||||
├── package.json # NPM scripts
|
||||
└── test-cases.json # [GENERATED] Test artifacts
|
||||
```
|
||||
|
||||
## Rule File Structure
|
||||
|
||||
See `rules/_template.md` for the complete template. Key elements:
|
||||
|
||||
````markdown
|
||||
---
|
||||
title: Clear, Action-Oriented Title
|
||||
impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
|
||||
impactDescription: Quantified benefit (e.g., "10-100x faster")
|
||||
tags: relevant, keywords
|
||||
---
|
||||
|
||||
## [Title]
|
||||
|
||||
[1-2 sentence explanation]
|
||||
|
||||
**Incorrect (description):**
|
||||
|
||||
```sql
|
||||
-- Comment explaining what's wrong
|
||||
[Bad SQL example]
|
||||
```
|
||||
````
|
||||
|
||||
**Correct (description):**
|
||||
|
||||
```sql
|
||||
-- Comment explaining why this is better
|
||||
[Good SQL example]
|
||||
```
|
||||
|
||||
```
|
||||
## Writing Guidelines
|
||||
|
||||
See `rules/_contributing.md` for detailed guidelines. Key principles:
|
||||
|
||||
1. **Show concrete transformations** - "Change X to Y", not abstract advice
|
||||
2. **Error-first structure** - Show the problem before the solution
|
||||
3. **Quantify impact** - Include specific metrics (10x faster, 50% smaller)
|
||||
4. **Self-contained examples** - Complete, runnable SQL
|
||||
5. **Semantic naming** - Use meaningful names (users, email), not (table1, col1)
|
||||
|
||||
## Impact Levels
|
||||
|
||||
| Level | Improvement | Examples |
|
||||
|-------|-------------|----------|
|
||||
| CRITICAL | 10-100x | Missing indexes, connection exhaustion |
|
||||
| HIGH | 5-20x | Wrong index types, poor partitioning |
|
||||
| MEDIUM-HIGH | 2-5x | N+1 queries, RLS optimization |
|
||||
| MEDIUM | 1.5-3x | Redundant indexes, stale statistics |
|
||||
| LOW-MEDIUM | 1.2-2x | VACUUM tuning, config tweaks |
|
||||
| LOW | Incremental | Advanced patterns, edge cases |
|
||||
```
|
||||
57
skills/postgres-best-practices/SKILL.md
Normal file
57
skills/postgres-best-practices/SKILL.md
Normal file
@@ -0,0 +1,57 @@
|
||||
---
|
||||
name: supabase-postgres-best-practices
|
||||
description: Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.
|
||||
license: MIT
|
||||
metadata:
|
||||
author: supabase
|
||||
version: "1.0.0"
|
||||
---
|
||||
|
||||
# Supabase Postgres Best Practices
|
||||
|
||||
Comprehensive performance optimization guide for Postgres, maintained by Supabase. Contains rules across 8 categories, prioritized by impact to guide automated query optimization and schema design.
|
||||
|
||||
## When to Apply
|
||||
|
||||
Reference these guidelines when:
|
||||
- Writing SQL queries or designing schemas
|
||||
- Implementing indexes or query optimization
|
||||
- Reviewing database performance issues
|
||||
- Configuring connection pooling or scaling
|
||||
- Optimizing for Postgres-specific features
|
||||
- Working with Row-Level Security (RLS)
|
||||
|
||||
## Rule Categories by Priority
|
||||
|
||||
| Priority | Category | Impact | Prefix |
|
||||
|----------|----------|--------|--------|
|
||||
| 1 | Query Performance | CRITICAL | `query-` |
|
||||
| 2 | Connection Management | CRITICAL | `conn-` |
|
||||
| 3 | Security & RLS | CRITICAL | `security-` |
|
||||
| 4 | Schema Design | HIGH | `schema-` |
|
||||
| 5 | Concurrency & Locking | MEDIUM-HIGH | `lock-` |
|
||||
| 6 | Data Access Patterns | MEDIUM | `data-` |
|
||||
| 7 | Monitoring & Diagnostics | LOW-MEDIUM | `monitor-` |
|
||||
| 8 | Advanced Features | LOW | `advanced-` |
|
||||
|
||||
## How to Use
|
||||
|
||||
Read individual rule files for detailed explanations and SQL examples:
|
||||
|
||||
```
|
||||
rules/query-missing-indexes.md
|
||||
rules/schema-partial-indexes.md
|
||||
rules/_sections.md
|
||||
```
|
||||
|
||||
Each rule file contains:
|
||||
- Brief explanation of why it matters
|
||||
- Incorrect SQL example with explanation
|
||||
- Correct SQL example with explanation
|
||||
- Optional EXPLAIN output or metrics
|
||||
- Additional context and references
|
||||
- Supabase-specific notes (when applicable)
|
||||
|
||||
## Full Compiled Document
|
||||
|
||||
For the complete guide with all rules expanded: `AGENTS.md`
|
||||
13
skills/postgres-best-practices/metadata.json
Normal file
13
skills/postgres-best-practices/metadata.json
Normal file
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"organization": "Supabase",
|
||||
"date": "January 2026",
|
||||
"abstract": "Comprehensive Postgres performance optimization guide for developers using Supabase and Postgres. Contains performance rules across 8 categories, prioritized by impact from critical (query performance, connection management) to incremental (advanced features). Each rule includes detailed explanations, incorrect vs. correct SQL examples, query plan analysis, and specific performance metrics to guide automated optimization and code generation.",
|
||||
"references": [
|
||||
"https://www.postgresql.org/docs/current/",
|
||||
"https://supabase.com/docs",
|
||||
"https://wiki.postgresql.org/wiki/Performance_Optimization",
|
||||
"https://supabase.com/docs/guides/database/overview",
|
||||
"https://supabase.com/docs/guides/auth/row-level-security"
|
||||
]
|
||||
}
|
||||
171
skills/postgres-best-practices/rules/_contributing.md
Normal file
171
skills/postgres-best-practices/rules/_contributing.md
Normal file
@@ -0,0 +1,171 @@
|
||||
# Writing Guidelines for Postgres Rules
|
||||
|
||||
This document provides guidelines for creating effective Postgres best
|
||||
practice rules that work well with AI agents and LLMs.
|
||||
|
||||
## Key Principles
|
||||
|
||||
### 1. Concrete Transformation Patterns
|
||||
|
||||
Show exact SQL rewrites. Avoid philosophical advice.
|
||||
|
||||
**Good:** "Use `WHERE id = ANY(ARRAY[...])` instead of
|
||||
`WHERE id IN (SELECT ...)`" **Bad:** "Design good schemas"
|
||||
|
||||
### 2. Error-First Structure
|
||||
|
||||
Always show the problematic pattern first, then the solution. This trains agents
|
||||
to recognize anti-patterns.
|
||||
|
||||
```markdown
|
||||
**Incorrect (sequential queries):** [bad example]
|
||||
|
||||
**Correct (batched query):** [good example]
|
||||
```
|
||||
|
||||
### 3. Quantified Impact
|
||||
|
||||
Include specific metrics. Helps agents prioritize fixes.
|
||||
|
||||
**Good:** "10x faster queries", "50% smaller index", "Eliminates N+1"
|
||||
**Bad:** "Faster", "Better", "More efficient"
|
||||
|
||||
### 4. Self-Contained Examples
|
||||
|
||||
Examples should be complete and runnable (or close to it). Include `CREATE TABLE`
|
||||
if context is needed.
|
||||
|
||||
```sql
|
||||
-- Include table definition when needed for clarity
|
||||
CREATE TABLE users (
|
||||
id bigint PRIMARY KEY,
|
||||
email text NOT NULL,
|
||||
deleted_at timestamptz
|
||||
);
|
||||
|
||||
-- Now show the index
|
||||
CREATE INDEX users_active_email_idx ON users(email) WHERE deleted_at IS NULL;
|
||||
```
|
||||
|
||||
### 5. Semantic Naming
|
||||
|
||||
Use meaningful table/column names. Names carry intent for LLMs.
|
||||
|
||||
**Good:** `users`, `email`, `created_at`, `is_active`
|
||||
**Bad:** `table1`, `col1`, `field`, `flag`
|
||||
|
||||
---
|
||||
|
||||
## Code Example Standards
|
||||
|
||||
### SQL Formatting
|
||||
|
||||
```sql
|
||||
-- Use lowercase keywords, clear formatting
|
||||
CREATE INDEX CONCURRENTLY users_email_idx
|
||||
ON users(email)
|
||||
WHERE deleted_at IS NULL;
|
||||
|
||||
-- Not cramped or ALL CAPS
|
||||
CREATE INDEX CONCURRENTLY USERS_EMAIL_IDX ON USERS(EMAIL) WHERE DELETED_AT IS NULL;
|
||||
```
|
||||
|
||||
### Comments
|
||||
|
||||
- Explain _why_, not _what_
|
||||
- Highlight performance implications
|
||||
- Point out common pitfalls
|
||||
|
||||
### Language Tags
|
||||
|
||||
- `sql` - Standard SQL queries
|
||||
- `plpgsql` - Stored procedures/functions
|
||||
- `typescript` - Application code (when needed)
|
||||
- `python` - Application code (when needed)
|
||||
|
||||
---
|
||||
|
||||
## When to Include Application Code
|
||||
|
||||
**Default: SQL Only**
|
||||
|
||||
Most rules should focus on pure SQL patterns. This keeps examples portable.
|
||||
|
||||
**Include Application Code When:**
|
||||
|
||||
- Connection pooling configuration
|
||||
- Transaction management in application context
|
||||
- ORM anti-patterns (N+1 in Prisma/TypeORM)
|
||||
- Prepared statement usage
|
||||
|
||||
**Format for Mixed Examples:**
|
||||
|
||||
````markdown
|
||||
**Incorrect (N+1 in application):**
|
||||
|
||||
```typescript
|
||||
for (const user of users) {
|
||||
const posts = await db.query("SELECT * FROM posts WHERE user_id = $1", [
|
||||
user.id,
|
||||
]);
|
||||
}
|
||||
```
|
||||
````
|
||||
|
||||
**Correct (batch query):**
|
||||
|
||||
```typescript
|
||||
const posts = await db.query("SELECT * FROM posts WHERE user_id = ANY($1)", [
|
||||
userIds,
|
||||
]);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact Level Guidelines
|
||||
|
||||
| Level | Improvement | Use When |
|
||||
|-------|-------------|----------|
|
||||
| **CRITICAL** | 10-100x | Missing indexes, connection exhaustion, sequential scans on large tables |
|
||||
| **HIGH** | 5-20x | Wrong index types, poor partitioning, missing covering indexes |
|
||||
| **MEDIUM-HIGH** | 2-5x | N+1 queries, inefficient pagination, RLS optimization |
|
||||
| **MEDIUM** | 1.5-3x | Redundant indexes, query plan instability |
|
||||
| **LOW-MEDIUM** | 1.2-2x | VACUUM tuning, configuration tweaks |
|
||||
| **LOW** | Incremental | Advanced patterns, edge cases |
|
||||
|
||||
---
|
||||
|
||||
## Reference Standards
|
||||
|
||||
**Primary Sources:**
|
||||
|
||||
- Official Postgres documentation
|
||||
- Supabase documentation
|
||||
- Postgres wiki
|
||||
- Established blogs (2ndQuadrant, Crunchy Data)
|
||||
|
||||
**Format:**
|
||||
|
||||
```markdown
|
||||
Reference:
|
||||
[Postgres Indexes](https://www.postgresql.org/docs/current/indexes.html)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Review Checklist
|
||||
|
||||
Before submitting a rule:
|
||||
|
||||
- [ ] Title is clear and action-oriented
|
||||
- [ ] Impact level matches the performance gain
|
||||
- [ ] impactDescription includes quantification
|
||||
- [ ] Explanation is concise (1-2 sentences)
|
||||
- [ ] Has at least 1 **Incorrect** SQL example
|
||||
- [ ] Has at least 1 **Correct** SQL example
|
||||
- [ ] SQL uses semantic naming
|
||||
- [ ] Comments explain _why_, not _what_
|
||||
- [ ] Trade-offs mentioned if applicable
|
||||
- [ ] Reference links included
|
||||
- [ ] `npm run validate` passes
|
||||
- [ ] `npm run build` generates correct output
|
||||
39
skills/postgres-best-practices/rules/_sections.md
Normal file
39
skills/postgres-best-practices/rules/_sections.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# Section Definitions
|
||||
|
||||
This file defines the rule categories for Postgres best practices. Rules are automatically assigned to sections based on their filename prefix.
|
||||
|
||||
Take the examples below as pure demonstrative. Replace each section with the actual rule categories for Postgres best practices.
|
||||
|
||||
---
|
||||
|
||||
## 1. Query Performance (query)
|
||||
**Impact:** CRITICAL
|
||||
**Description:** Slow queries, missing indexes, inefficient query plans. The most common source of Postgres performance issues.
|
||||
|
||||
## 2. Connection Management (conn)
|
||||
**Impact:** CRITICAL
|
||||
**Description:** Connection pooling, limits, and serverless strategies. Critical for applications with high concurrency or serverless deployments.
|
||||
|
||||
## 3. Security & RLS (security)
|
||||
**Impact:** CRITICAL
|
||||
**Description:** Row-Level Security policies, privilege management, and authentication patterns.
|
||||
|
||||
## 4. Schema Design (schema)
|
||||
**Impact:** HIGH
|
||||
**Description:** Table design, index strategies, partitioning, and data type selection. Foundation for long-term performance.
|
||||
|
||||
## 5. Concurrency & Locking (lock)
|
||||
**Impact:** MEDIUM-HIGH
|
||||
**Description:** Transaction management, isolation levels, deadlock prevention, and lock contention patterns.
|
||||
|
||||
## 6. Data Access Patterns (data)
|
||||
**Impact:** MEDIUM
|
||||
**Description:** N+1 query elimination, batch operations, cursor-based pagination, and efficient data fetching.
|
||||
|
||||
## 7. Monitoring & Diagnostics (monitor)
|
||||
**Impact:** LOW-MEDIUM
|
||||
**Description:** Using pg_stat_statements, EXPLAIN ANALYZE, metrics collection, and performance diagnostics.
|
||||
|
||||
## 8. Advanced Features (advanced)
|
||||
**Impact:** LOW
|
||||
**Description:** Full-text search, JSONB optimization, PostGIS, extensions, and advanced Postgres features.
|
||||
34
skills/postgres-best-practices/rules/_template.md
Normal file
34
skills/postgres-best-practices/rules/_template.md
Normal file
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: Clear, Action-Oriented Title (e.g., "Use Partial Indexes for Filtered Queries")
|
||||
impact: MEDIUM
|
||||
impactDescription: 5-20x query speedup for filtered queries
|
||||
tags: indexes, query-optimization, performance
|
||||
---
|
||||
|
||||
## [Rule Title]
|
||||
|
||||
[1-2 sentence explanation of the problem and why it matters. Focus on performance impact.]
|
||||
|
||||
**Incorrect (describe the problem):**
|
||||
|
||||
```sql
|
||||
-- Comment explaining what makes this slow/problematic
|
||||
CREATE INDEX users_email_idx ON users(email);
|
||||
|
||||
SELECT * FROM users WHERE email = 'user@example.com' AND deleted_at IS NULL;
|
||||
-- This scans deleted records unnecessarily
|
||||
```
|
||||
|
||||
**Correct (describe the solution):**
|
||||
|
||||
```sql
|
||||
-- Comment explaining why this is better
|
||||
CREATE INDEX users_active_email_idx ON users(email) WHERE deleted_at IS NULL;
|
||||
|
||||
SELECT * FROM users WHERE email = 'user@example.com' AND deleted_at IS NULL;
|
||||
-- Only indexes active users, 10x smaller index, faster queries
|
||||
```
|
||||
|
||||
[Optional: Additional context, edge cases, or trade-offs]
|
||||
|
||||
Reference: [Postgres Docs](https://www.postgresql.org/docs/current/)
|
||||
@@ -0,0 +1,55 @@
|
||||
---
|
||||
title: Use tsvector for Full-Text Search
|
||||
impact: MEDIUM
|
||||
impactDescription: 100x faster than LIKE, with ranking support
|
||||
tags: full-text-search, tsvector, gin, search
|
||||
---
|
||||
|
||||
## Use tsvector for Full-Text Search
|
||||
|
||||
LIKE with wildcards can't use indexes. Full-text search with tsvector is orders of magnitude faster.
|
||||
|
||||
**Incorrect (LIKE pattern matching):**
|
||||
|
||||
```sql
|
||||
-- Cannot use index, scans all rows
|
||||
select * from articles where content like '%postgresql%';
|
||||
|
||||
-- Case-insensitive makes it worse
|
||||
select * from articles where lower(content) like '%postgresql%';
|
||||
```
|
||||
|
||||
**Correct (full-text search with tsvector):**
|
||||
|
||||
```sql
|
||||
-- Add tsvector column and index
|
||||
alter table articles add column search_vector tsvector
|
||||
generated always as (to_tsvector('english', coalesce(title,'') || ' ' || coalesce(content,''))) stored;
|
||||
|
||||
create index articles_search_idx on articles using gin (search_vector);
|
||||
|
||||
-- Fast full-text search
|
||||
select * from articles
|
||||
where search_vector @@ to_tsquery('english', 'postgresql & performance');
|
||||
|
||||
-- With ranking
|
||||
select *, ts_rank(search_vector, query) as rank
|
||||
from articles, to_tsquery('english', 'postgresql') query
|
||||
where search_vector @@ query
|
||||
order by rank desc;
|
||||
```
|
||||
|
||||
Search multiple terms:
|
||||
|
||||
```sql
|
||||
-- AND: both terms required
|
||||
to_tsquery('postgresql & performance')
|
||||
|
||||
-- OR: either term
|
||||
to_tsquery('postgresql | mysql')
|
||||
|
||||
-- Prefix matching
|
||||
to_tsquery('post:*')
|
||||
```
|
||||
|
||||
Reference: [Full Text Search](https://supabase.com/docs/guides/database/full-text-search)
|
||||
@@ -0,0 +1,49 @@
|
||||
---
|
||||
title: Index JSONB Columns for Efficient Querying
|
||||
impact: MEDIUM
|
||||
impactDescription: 10-100x faster JSONB queries with proper indexing
|
||||
tags: jsonb, gin, indexes, json
|
||||
---
|
||||
|
||||
## Index JSONB Columns for Efficient Querying
|
||||
|
||||
JSONB queries without indexes scan the entire table. Use GIN indexes for containment queries.
|
||||
|
||||
**Incorrect (no index on JSONB):**
|
||||
|
||||
```sql
|
||||
create table products (
|
||||
id bigint primary key,
|
||||
attributes jsonb
|
||||
);
|
||||
|
||||
-- Full table scan for every query
|
||||
select * from products where attributes @> '{"color": "red"}';
|
||||
select * from products where attributes->>'brand' = 'Nike';
|
||||
```
|
||||
|
||||
**Correct (GIN index for JSONB):**
|
||||
|
||||
```sql
|
||||
-- GIN index for containment operators (@>, ?, ?&, ?|)
|
||||
create index products_attrs_gin on products using gin (attributes);
|
||||
|
||||
-- Now containment queries use the index
|
||||
select * from products where attributes @> '{"color": "red"}';
|
||||
|
||||
-- For specific key lookups, use expression index
|
||||
create index products_brand_idx on products ((attributes->>'brand'));
|
||||
select * from products where attributes->>'brand' = 'Nike';
|
||||
```
|
||||
|
||||
Choose the right operator class:
|
||||
|
||||
```sql
|
||||
-- jsonb_ops (default): supports all operators, larger index
|
||||
create index idx1 on products using gin (attributes);
|
||||
|
||||
-- jsonb_path_ops: only @> operator, but 2-3x smaller index
|
||||
create index idx2 on products using gin (attributes jsonb_path_ops);
|
||||
```
|
||||
|
||||
Reference: [JSONB Indexes](https://www.postgresql.org/docs/current/datatype-json.html#JSON-INDEXING)
|
||||
46
skills/postgres-best-practices/rules/conn-idle-timeout.md
Normal file
46
skills/postgres-best-practices/rules/conn-idle-timeout.md
Normal file
@@ -0,0 +1,46 @@
|
||||
---
|
||||
title: Configure Idle Connection Timeouts
|
||||
impact: HIGH
|
||||
impactDescription: Reclaim 30-50% of connection slots from idle clients
|
||||
tags: connections, timeout, idle, resource-management
|
||||
---
|
||||
|
||||
## Configure Idle Connection Timeouts
|
||||
|
||||
Idle connections waste resources. Configure timeouts to automatically reclaim them.
|
||||
|
||||
**Incorrect (connections held indefinitely):**
|
||||
|
||||
```sql
|
||||
-- No timeout configured
|
||||
show idle_in_transaction_session_timeout; -- 0 (disabled)
|
||||
|
||||
-- Connections stay open forever, even when idle
|
||||
select pid, state, state_change, query
|
||||
from pg_stat_activity
|
||||
where state = 'idle in transaction';
|
||||
-- Shows transactions idle for hours, holding locks
|
||||
```
|
||||
|
||||
**Correct (automatic cleanup of idle connections):**
|
||||
|
||||
```sql
|
||||
-- Terminate connections idle in transaction after 30 seconds
|
||||
alter system set idle_in_transaction_session_timeout = '30s';
|
||||
|
||||
-- Terminate completely idle connections after 10 minutes
|
||||
alter system set idle_session_timeout = '10min';
|
||||
|
||||
-- Reload configuration
|
||||
select pg_reload_conf();
|
||||
```
|
||||
|
||||
For pooled connections, configure at the pooler level:
|
||||
|
||||
```ini
|
||||
# pgbouncer.ini
|
||||
server_idle_timeout = 60
|
||||
client_idle_timeout = 300
|
||||
```
|
||||
|
||||
Reference: [Connection Timeouts](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-IDLE-IN-TRANSACTION-SESSION-TIMEOUT)
|
||||
44
skills/postgres-best-practices/rules/conn-limits.md
Normal file
44
skills/postgres-best-practices/rules/conn-limits.md
Normal file
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: Set Appropriate Connection Limits
|
||||
impact: CRITICAL
|
||||
impactDescription: Prevent database crashes and memory exhaustion
|
||||
tags: connections, max-connections, limits, stability
|
||||
---
|
||||
|
||||
## Set Appropriate Connection Limits
|
||||
|
||||
Too many connections exhaust memory and degrade performance. Set limits based on available resources.
|
||||
|
||||
**Incorrect (unlimited or excessive connections):**
|
||||
|
||||
```sql
|
||||
-- Default max_connections = 100, but often increased blindly
|
||||
show max_connections; -- 500 (way too high for 4GB RAM)
|
||||
|
||||
-- Each connection uses 1-3MB RAM
|
||||
-- 500 connections * 2MB = 1GB just for connections!
|
||||
-- Out of memory errors under load
|
||||
```
|
||||
|
||||
**Correct (calculate based on resources):**
|
||||
|
||||
```sql
|
||||
-- Formula: max_connections = (RAM in MB / 5MB per connection) - reserved
|
||||
-- For 4GB RAM: (4096 / 5) - 10 = ~800 theoretical max
|
||||
-- But practically, 100-200 is better for query performance
|
||||
|
||||
-- Recommended settings for 4GB RAM
|
||||
alter system set max_connections = 100;
|
||||
|
||||
-- Also set work_mem appropriately
|
||||
-- work_mem * max_connections should not exceed 25% of RAM
|
||||
alter system set work_mem = '8MB'; -- 8MB * 100 = 800MB max
|
||||
```
|
||||
|
||||
Monitor connection usage:
|
||||
|
||||
```sql
|
||||
select count(*), state from pg_stat_activity group by state;
|
||||
```
|
||||
|
||||
Reference: [Database Connections](https://supabase.com/docs/guides/platform/performance#connection-management)
|
||||
41
skills/postgres-best-practices/rules/conn-pooling.md
Normal file
41
skills/postgres-best-practices/rules/conn-pooling.md
Normal file
@@ -0,0 +1,41 @@
|
||||
---
|
||||
title: Use Connection Pooling for All Applications
|
||||
impact: CRITICAL
|
||||
impactDescription: Handle 10-100x more concurrent users
|
||||
tags: connection-pooling, pgbouncer, performance, scalability
|
||||
---
|
||||
|
||||
## Use Connection Pooling for All Applications
|
||||
|
||||
Postgres connections are expensive (1-3MB RAM each). Without pooling, applications exhaust connections under load.
|
||||
|
||||
**Incorrect (new connection per request):**
|
||||
|
||||
```sql
|
||||
-- Each request creates a new connection
|
||||
-- Application code: db.connect() per request
|
||||
-- Result: 500 concurrent users = 500 connections = crashed database
|
||||
|
||||
-- Check current connections
|
||||
select count(*) from pg_stat_activity; -- 487 connections!
|
||||
```
|
||||
|
||||
**Correct (connection pooling):**
|
||||
|
||||
```sql
|
||||
-- Use a pooler like PgBouncer between app and database
|
||||
-- Application connects to pooler, pooler reuses a small pool to Postgres
|
||||
|
||||
-- Configure pool_size based on: (CPU cores * 2) + spindle_count
|
||||
-- Example for 4 cores: pool_size = 10
|
||||
|
||||
-- Result: 500 concurrent users share 10 actual connections
|
||||
select count(*) from pg_stat_activity; -- 10 connections
|
||||
```
|
||||
|
||||
Pool modes:
|
||||
|
||||
- **Transaction mode**: connection returned after each transaction (best for most apps)
|
||||
- **Session mode**: connection held for entire session (needed for prepared statements, temp tables)
|
||||
|
||||
Reference: [Connection Pooling](https://supabase.com/docs/guides/database/connecting-to-postgres#connection-pooler)
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
title: Use Prepared Statements Correctly with Pooling
|
||||
impact: HIGH
|
||||
impactDescription: Avoid prepared statement conflicts in pooled environments
|
||||
tags: prepared-statements, connection-pooling, transaction-mode
|
||||
---
|
||||
|
||||
## Use Prepared Statements Correctly with Pooling
|
||||
|
||||
Prepared statements are tied to individual database connections. In transaction-mode pooling, connections are shared, causing conflicts.
|
||||
|
||||
**Incorrect (named prepared statements with transaction pooling):**
|
||||
|
||||
```sql
|
||||
-- Named prepared statement
|
||||
prepare get_user as select * from users where id = $1;
|
||||
|
||||
-- In transaction mode pooling, next request may get different connection
|
||||
execute get_user(123);
|
||||
-- ERROR: prepared statement "get_user" does not exist
|
||||
```
|
||||
|
||||
**Correct (use unnamed statements or session mode):**
|
||||
|
||||
```sql
|
||||
-- Option 1: Use unnamed prepared statements (most ORMs do this automatically)
|
||||
-- The query is prepared and executed in a single protocol message
|
||||
|
||||
-- Option 2: Deallocate after use in transaction mode
|
||||
prepare get_user as select * from users where id = $1;
|
||||
execute get_user(123);
|
||||
deallocate get_user;
|
||||
|
||||
-- Option 3: Use session mode pooling (port 5432 vs 6543)
|
||||
-- Connection is held for entire session, prepared statements persist
|
||||
```
|
||||
|
||||
Check your driver settings:
|
||||
|
||||
```sql
|
||||
-- Many drivers use prepared statements by default
|
||||
-- Node.js pg: { prepare: false } to disable
|
||||
-- JDBC: prepareThreshold=0 to disable
|
||||
```
|
||||
|
||||
Reference: [Prepared Statements with Pooling](https://supabase.com/docs/guides/database/connecting-to-postgres#connection-pool-modes)
|
||||
54
skills/postgres-best-practices/rules/data-batch-inserts.md
Normal file
54
skills/postgres-best-practices/rules/data-batch-inserts.md
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: Batch INSERT Statements for Bulk Data
|
||||
impact: MEDIUM
|
||||
impactDescription: 10-50x faster bulk inserts
|
||||
tags: batch, insert, bulk, performance, copy
|
||||
---
|
||||
|
||||
## Batch INSERT Statements for Bulk Data
|
||||
|
||||
Individual INSERT statements have high overhead. Batch multiple rows in single statements or use COPY.
|
||||
|
||||
**Incorrect (individual inserts):**
|
||||
|
||||
```sql
|
||||
-- Each insert is a separate transaction and round trip
|
||||
insert into events (user_id, action) values (1, 'click');
|
||||
insert into events (user_id, action) values (1, 'view');
|
||||
insert into events (user_id, action) values (2, 'click');
|
||||
-- ... 1000 more individual inserts
|
||||
|
||||
-- 1000 inserts = 1000 round trips = slow
|
||||
```
|
||||
|
||||
**Correct (batch insert):**
|
||||
|
||||
```sql
|
||||
-- Multiple rows in single statement
|
||||
insert into events (user_id, action) values
|
||||
(1, 'click'),
|
||||
(1, 'view'),
|
||||
(2, 'click'),
|
||||
-- ... up to ~1000 rows per batch
|
||||
(999, 'view');
|
||||
|
||||
-- One round trip for 1000 rows
|
||||
```
|
||||
|
||||
For large imports, use COPY:
|
||||
|
||||
```sql
|
||||
-- COPY is fastest for bulk loading
|
||||
copy events (user_id, action, created_at)
|
||||
from '/path/to/data.csv'
|
||||
with (format csv, header true);
|
||||
|
||||
-- Or from stdin in application
|
||||
copy events (user_id, action) from stdin with (format csv);
|
||||
1,click
|
||||
1,view
|
||||
2,click
|
||||
\.
|
||||
```
|
||||
|
||||
Reference: [COPY](https://www.postgresql.org/docs/current/sql-copy.html)
|
||||
53
skills/postgres-best-practices/rules/data-n-plus-one.md
Normal file
53
skills/postgres-best-practices/rules/data-n-plus-one.md
Normal file
@@ -0,0 +1,53 @@
|
||||
---
|
||||
title: Eliminate N+1 Queries with Batch Loading
|
||||
impact: MEDIUM-HIGH
|
||||
impactDescription: 10-100x fewer database round trips
|
||||
tags: n-plus-one, batch, performance, queries
|
||||
---
|
||||
|
||||
## Eliminate N+1 Queries with Batch Loading
|
||||
|
||||
N+1 queries execute one query per item in a loop. Batch them into a single query using arrays or JOINs.
|
||||
|
||||
**Incorrect (N+1 queries):**
|
||||
|
||||
```sql
|
||||
-- First query: get all users
|
||||
select id from users where active = true; -- Returns 100 IDs
|
||||
|
||||
-- Then N queries, one per user
|
||||
select * from orders where user_id = 1;
|
||||
select * from orders where user_id = 2;
|
||||
select * from orders where user_id = 3;
|
||||
-- ... 97 more queries!
|
||||
|
||||
-- Total: 101 round trips to database
|
||||
```
|
||||
|
||||
**Correct (single batch query):**
|
||||
|
||||
```sql
|
||||
-- Collect IDs and query once with ANY
|
||||
select * from orders where user_id = any(array[1, 2, 3, ...]);
|
||||
|
||||
-- Or use JOIN instead of loop
|
||||
select u.id, u.name, o.*
|
||||
from users u
|
||||
left join orders o on o.user_id = u.id
|
||||
where u.active = true;
|
||||
|
||||
-- Total: 1 round trip
|
||||
```
|
||||
|
||||
Application pattern:
|
||||
|
||||
```sql
|
||||
-- Instead of looping in application code:
|
||||
-- for user in users: db.query("SELECT * FROM orders WHERE user_id = $1", user.id)
|
||||
|
||||
-- Pass array parameter:
|
||||
select * from orders where user_id = any($1::bigint[]);
|
||||
-- Application passes: [1, 2, 3, 4, 5, ...]
|
||||
```
|
||||
|
||||
Reference: [N+1 Query Problem](https://supabase.com/docs/guides/database/query-optimization)
|
||||
50
skills/postgres-best-practices/rules/data-pagination.md
Normal file
50
skills/postgres-best-practices/rules/data-pagination.md
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: Use Cursor-Based Pagination Instead of OFFSET
|
||||
impact: MEDIUM-HIGH
|
||||
impactDescription: Consistent O(1) performance regardless of page depth
|
||||
tags: pagination, cursor, keyset, offset, performance
|
||||
---
|
||||
|
||||
## Use Cursor-Based Pagination Instead of OFFSET
|
||||
|
||||
OFFSET-based pagination scans all skipped rows, getting slower on deeper pages. Cursor pagination is O(1).
|
||||
|
||||
**Incorrect (OFFSET pagination):**
|
||||
|
||||
```sql
|
||||
-- Page 1: scans 20 rows
|
||||
select * from products order by id limit 20 offset 0;
|
||||
|
||||
-- Page 100: scans 2000 rows to skip 1980
|
||||
select * from products order by id limit 20 offset 1980;
|
||||
|
||||
-- Page 10000: scans 200,000 rows!
|
||||
select * from products order by id limit 20 offset 199980;
|
||||
```
|
||||
|
||||
**Correct (cursor/keyset pagination):**
|
||||
|
||||
```sql
|
||||
-- Page 1: get first 20
|
||||
select * from products order by id limit 20;
|
||||
-- Application stores last_id = 20
|
||||
|
||||
-- Page 2: start after last ID
|
||||
select * from products where id > 20 order by id limit 20;
|
||||
-- Uses index, always fast regardless of page depth
|
||||
|
||||
-- Page 10000: same speed as page 1
|
||||
select * from products where id > 199980 order by id limit 20;
|
||||
```
|
||||
|
||||
For multi-column sorting:
|
||||
|
||||
```sql
|
||||
-- Cursor must include all sort columns
|
||||
select * from products
|
||||
where (created_at, id) > ('2024-01-15 10:00:00', 12345)
|
||||
order by created_at, id
|
||||
limit 20;
|
||||
```
|
||||
|
||||
Reference: [Pagination](https://supabase.com/docs/guides/database/pagination)
|
||||
50
skills/postgres-best-practices/rules/data-upsert.md
Normal file
50
skills/postgres-best-practices/rules/data-upsert.md
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: Use UPSERT for Insert-or-Update Operations
|
||||
impact: MEDIUM
|
||||
impactDescription: Atomic operation, eliminates race conditions
|
||||
tags: upsert, on-conflict, insert, update
|
||||
---
|
||||
|
||||
## Use UPSERT for Insert-or-Update Operations
|
||||
|
||||
Using separate SELECT-then-INSERT/UPDATE creates race conditions. Use INSERT ... ON CONFLICT for atomic upserts.
|
||||
|
||||
**Incorrect (check-then-insert race condition):**
|
||||
|
||||
```sql
|
||||
-- Race condition: two requests check simultaneously
|
||||
select * from settings where user_id = 123 and key = 'theme';
|
||||
-- Both find nothing
|
||||
|
||||
-- Both try to insert
|
||||
insert into settings (user_id, key, value) values (123, 'theme', 'dark');
|
||||
-- One succeeds, one fails with duplicate key error!
|
||||
```
|
||||
|
||||
**Correct (atomic UPSERT):**
|
||||
|
||||
```sql
|
||||
-- Single atomic operation
|
||||
insert into settings (user_id, key, value)
|
||||
values (123, 'theme', 'dark')
|
||||
on conflict (user_id, key)
|
||||
do update set value = excluded.value, updated_at = now();
|
||||
|
||||
-- Returns the inserted/updated row
|
||||
insert into settings (user_id, key, value)
|
||||
values (123, 'theme', 'dark')
|
||||
on conflict (user_id, key)
|
||||
do update set value = excluded.value
|
||||
returning *;
|
||||
```
|
||||
|
||||
Insert-or-ignore pattern:
|
||||
|
||||
```sql
|
||||
-- Insert only if not exists (no update)
|
||||
insert into page_views (page_id, user_id)
|
||||
values (1, 123)
|
||||
on conflict (page_id, user_id) do nothing;
|
||||
```
|
||||
|
||||
Reference: [INSERT ON CONFLICT](https://www.postgresql.org/docs/current/sql-insert.html#SQL-ON-CONFLICT)
|
||||
56
skills/postgres-best-practices/rules/lock-advisory.md
Normal file
56
skills/postgres-best-practices/rules/lock-advisory.md
Normal file
@@ -0,0 +1,56 @@
|
||||
---
|
||||
title: Use Advisory Locks for Application-Level Locking
|
||||
impact: MEDIUM
|
||||
impactDescription: Efficient coordination without row-level lock overhead
|
||||
tags: advisory-locks, coordination, application-locks
|
||||
---
|
||||
|
||||
## Use Advisory Locks for Application-Level Locking
|
||||
|
||||
Advisory locks provide application-level coordination without requiring database rows to lock.
|
||||
|
||||
**Incorrect (creating rows just for locking):**
|
||||
|
||||
```sql
|
||||
-- Creating dummy rows to lock on
|
||||
create table resource_locks (
|
||||
resource_name text primary key
|
||||
);
|
||||
|
||||
insert into resource_locks values ('report_generator');
|
||||
|
||||
-- Lock by selecting the row
|
||||
select * from resource_locks where resource_name = 'report_generator' for update;
|
||||
```
|
||||
|
||||
**Correct (advisory locks):**
|
||||
|
||||
```sql
|
||||
-- Session-level advisory lock (released on disconnect or unlock)
|
||||
select pg_advisory_lock(hashtext('report_generator'));
|
||||
-- ... do exclusive work ...
|
||||
select pg_advisory_unlock(hashtext('report_generator'));
|
||||
|
||||
-- Transaction-level lock (released on commit/rollback)
|
||||
begin;
|
||||
select pg_advisory_xact_lock(hashtext('daily_report'));
|
||||
-- ... do work ...
|
||||
commit; -- Lock automatically released
|
||||
```
|
||||
|
||||
Try-lock for non-blocking operations:
|
||||
|
||||
```sql
|
||||
-- Returns immediately with true/false instead of waiting
|
||||
select pg_try_advisory_lock(hashtext('resource_name'));
|
||||
|
||||
-- Use in application
|
||||
if (acquired) {
|
||||
-- Do work
|
||||
select pg_advisory_unlock(hashtext('resource_name'));
|
||||
} else {
|
||||
-- Skip or retry later
|
||||
}
|
||||
```
|
||||
|
||||
Reference: [Advisory Locks](https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS)
|
||||
@@ -0,0 +1,68 @@
|
||||
---
|
||||
title: Prevent Deadlocks with Consistent Lock Ordering
|
||||
impact: MEDIUM-HIGH
|
||||
impactDescription: Eliminate deadlock errors, improve reliability
|
||||
tags: deadlocks, locking, transactions, ordering
|
||||
---
|
||||
|
||||
## Prevent Deadlocks with Consistent Lock Ordering
|
||||
|
||||
Deadlocks occur when transactions lock resources in different orders. Always
|
||||
acquire locks in a consistent order.
|
||||
|
||||
**Incorrect (inconsistent lock ordering):**
|
||||
|
||||
```sql
|
||||
-- Transaction A -- Transaction B
|
||||
begin; begin;
|
||||
update accounts update accounts
|
||||
set balance = balance - 100 set balance = balance - 50
|
||||
where id = 1; where id = 2; -- B locks row 2
|
||||
|
||||
update accounts update accounts
|
||||
set balance = balance + 100 set balance = balance + 50
|
||||
where id = 2; -- A waits for B where id = 1; -- B waits for A
|
||||
|
||||
-- DEADLOCK! Both waiting for each other
|
||||
```
|
||||
|
||||
**Correct (lock rows in consistent order first):**
|
||||
|
||||
```sql
|
||||
-- Explicitly acquire locks in ID order before updating
|
||||
begin;
|
||||
select * from accounts where id in (1, 2) order by id for update;
|
||||
|
||||
-- Now perform updates in any order - locks already held
|
||||
update accounts set balance = balance - 100 where id = 1;
|
||||
update accounts set balance = balance + 100 where id = 2;
|
||||
commit;
|
||||
```
|
||||
|
||||
Alternative: use a single statement to update atomically:
|
||||
|
||||
```sql
|
||||
-- Single statement acquires all locks atomically
|
||||
begin;
|
||||
update accounts
|
||||
set balance = balance + case id
|
||||
when 1 then -100
|
||||
when 2 then 100
|
||||
end
|
||||
where id in (1, 2);
|
||||
commit;
|
||||
```
|
||||
|
||||
Detect deadlocks in logs:
|
||||
|
||||
```sql
|
||||
-- Check for recent deadlocks
|
||||
select * from pg_stat_database where deadlocks > 0;
|
||||
|
||||
-- Enable deadlock logging
|
||||
set log_lock_waits = on;
|
||||
set deadlock_timeout = '1s';
|
||||
```
|
||||
|
||||
Reference:
|
||||
[Deadlocks](https://www.postgresql.org/docs/current/explicit-locking.html#LOCKING-DEADLOCKS)
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: Keep Transactions Short to Reduce Lock Contention
|
||||
impact: MEDIUM-HIGH
|
||||
impactDescription: 3-5x throughput improvement, fewer deadlocks
|
||||
tags: transactions, locking, contention, performance
|
||||
---
|
||||
|
||||
## Keep Transactions Short to Reduce Lock Contention
|
||||
|
||||
Long-running transactions hold locks that block other queries. Keep transactions as short as possible.
|
||||
|
||||
**Incorrect (long transaction with external calls):**
|
||||
|
||||
```sql
|
||||
begin;
|
||||
select * from orders where id = 1 for update; -- Lock acquired
|
||||
|
||||
-- Application makes HTTP call to payment API (2-5 seconds)
|
||||
-- Other queries on this row are blocked!
|
||||
|
||||
update orders set status = 'paid' where id = 1;
|
||||
commit; -- Lock held for entire duration
|
||||
```
|
||||
|
||||
**Correct (minimal transaction scope):**
|
||||
|
||||
```sql
|
||||
-- Validate data and call APIs outside transaction
|
||||
-- Application: response = await paymentAPI.charge(...)
|
||||
|
||||
-- Only hold lock for the actual update
|
||||
begin;
|
||||
update orders
|
||||
set status = 'paid', payment_id = $1
|
||||
where id = $2 and status = 'pending'
|
||||
returning *;
|
||||
commit; -- Lock held for milliseconds
|
||||
```
|
||||
|
||||
Use `statement_timeout` to prevent runaway transactions:
|
||||
|
||||
```sql
|
||||
-- Abort queries running longer than 30 seconds
|
||||
set statement_timeout = '30s';
|
||||
|
||||
-- Or per-session
|
||||
set local statement_timeout = '5s';
|
||||
```
|
||||
|
||||
Reference: [Transaction Management](https://www.postgresql.org/docs/current/tutorial-transactions.html)
|
||||
54
skills/postgres-best-practices/rules/lock-skip-locked.md
Normal file
54
skills/postgres-best-practices/rules/lock-skip-locked.md
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: Use SKIP LOCKED for Non-Blocking Queue Processing
|
||||
impact: MEDIUM-HIGH
|
||||
impactDescription: 10x throughput for worker queues
|
||||
tags: skip-locked, queue, workers, concurrency
|
||||
---
|
||||
|
||||
## Use SKIP LOCKED for Non-Blocking Queue Processing
|
||||
|
||||
When multiple workers process a queue, SKIP LOCKED allows workers to process different rows without waiting.
|
||||
|
||||
**Incorrect (workers block each other):**
|
||||
|
||||
```sql
|
||||
-- Worker 1 and Worker 2 both try to get next job
|
||||
begin;
|
||||
select * from jobs where status = 'pending' order by created_at limit 1 for update;
|
||||
-- Worker 2 waits for Worker 1's lock to release!
|
||||
```
|
||||
|
||||
**Correct (SKIP LOCKED for parallel processing):**
|
||||
|
||||
```sql
|
||||
-- Each worker skips locked rows and gets the next available
|
||||
begin;
|
||||
select * from jobs
|
||||
where status = 'pending'
|
||||
order by created_at
|
||||
limit 1
|
||||
for update skip locked;
|
||||
|
||||
-- Worker 1 gets job 1, Worker 2 gets job 2 (no waiting)
|
||||
|
||||
update jobs set status = 'processing' where id = $1;
|
||||
commit;
|
||||
```
|
||||
|
||||
Complete queue pattern:
|
||||
|
||||
```sql
|
||||
-- Atomic claim-and-update in one statement
|
||||
update jobs
|
||||
set status = 'processing', worker_id = $1, started_at = now()
|
||||
where id = (
|
||||
select id from jobs
|
||||
where status = 'pending'
|
||||
order by created_at
|
||||
limit 1
|
||||
for update skip locked
|
||||
)
|
||||
returning *;
|
||||
```
|
||||
|
||||
Reference: [SELECT FOR UPDATE SKIP LOCKED](https://www.postgresql.org/docs/current/sql-select.html#SQL-FOR-UPDATE-SHARE)
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: Use EXPLAIN ANALYZE to Diagnose Slow Queries
|
||||
impact: LOW-MEDIUM
|
||||
impactDescription: Identify exact bottlenecks in query execution
|
||||
tags: explain, analyze, diagnostics, query-plan
|
||||
---
|
||||
|
||||
## Use EXPLAIN ANALYZE to Diagnose Slow Queries
|
||||
|
||||
EXPLAIN ANALYZE executes the query and shows actual timings, revealing the true performance bottlenecks.
|
||||
|
||||
**Incorrect (guessing at performance issues):**
|
||||
|
||||
```sql
|
||||
-- Query is slow, but why?
|
||||
select * from orders where customer_id = 123 and status = 'pending';
|
||||
-- "It must be missing an index" - but which one?
|
||||
```
|
||||
|
||||
**Correct (use EXPLAIN ANALYZE):**
|
||||
|
||||
```sql
|
||||
explain (analyze, buffers, format text)
|
||||
select * from orders where customer_id = 123 and status = 'pending';
|
||||
|
||||
-- Output reveals the issue:
|
||||
-- Seq Scan on orders (cost=0.00..25000.00 rows=50 width=100) (actual time=0.015..450.123 rows=50 loops=1)
|
||||
-- Filter: ((customer_id = 123) AND (status = 'pending'::text))
|
||||
-- Rows Removed by Filter: 999950
|
||||
-- Buffers: shared hit=5000 read=15000
|
||||
-- Planning Time: 0.150 ms
|
||||
-- Execution Time: 450.500 ms
|
||||
```
|
||||
|
||||
Key things to look for:
|
||||
|
||||
```sql
|
||||
-- Seq Scan on large tables = missing index
|
||||
-- Rows Removed by Filter = poor selectivity or missing index
|
||||
-- Buffers: read >> hit = data not cached, needs more memory
|
||||
-- Nested Loop with high loops = consider different join strategy
|
||||
-- Sort Method: external merge = work_mem too low
|
||||
```
|
||||
|
||||
Reference: [EXPLAIN](https://supabase.com/docs/guides/database/inspect)
|
||||
@@ -0,0 +1,55 @@
|
||||
---
|
||||
title: Enable pg_stat_statements for Query Analysis
|
||||
impact: LOW-MEDIUM
|
||||
impactDescription: Identify top resource-consuming queries
|
||||
tags: pg-stat-statements, monitoring, statistics, performance
|
||||
---
|
||||
|
||||
## Enable pg_stat_statements for Query Analysis
|
||||
|
||||
pg_stat_statements tracks execution statistics for all queries, helping identify slow and frequent queries.
|
||||
|
||||
**Incorrect (no visibility into query patterns):**
|
||||
|
||||
```sql
|
||||
-- Database is slow, but which queries are the problem?
|
||||
-- No way to know without pg_stat_statements
|
||||
```
|
||||
|
||||
**Correct (enable and query pg_stat_statements):**
|
||||
|
||||
```sql
|
||||
-- Enable the extension
|
||||
create extension if not exists pg_stat_statements;
|
||||
|
||||
-- Find slowest queries by total time
|
||||
select
|
||||
calls,
|
||||
round(total_exec_time::numeric, 2) as total_time_ms,
|
||||
round(mean_exec_time::numeric, 2) as mean_time_ms,
|
||||
query
|
||||
from pg_stat_statements
|
||||
order by total_exec_time desc
|
||||
limit 10;
|
||||
|
||||
-- Find most frequent queries
|
||||
select calls, query
|
||||
from pg_stat_statements
|
||||
order by calls desc
|
||||
limit 10;
|
||||
|
||||
-- Reset statistics after optimization
|
||||
select pg_stat_statements_reset();
|
||||
```
|
||||
|
||||
Key metrics to monitor:
|
||||
|
||||
```sql
|
||||
-- Queries with high mean time (candidates for optimization)
|
||||
select query, mean_exec_time, calls
|
||||
from pg_stat_statements
|
||||
where mean_exec_time > 100 -- > 100ms average
|
||||
order by mean_exec_time desc;
|
||||
```
|
||||
|
||||
Reference: [pg_stat_statements](https://supabase.com/docs/guides/database/extensions/pg_stat_statements)
|
||||
@@ -0,0 +1,55 @@
|
||||
---
|
||||
title: Maintain Table Statistics with VACUUM and ANALYZE
|
||||
impact: MEDIUM
|
||||
impactDescription: 2-10x better query plans with accurate statistics
|
||||
tags: vacuum, analyze, statistics, maintenance, autovacuum
|
||||
---
|
||||
|
||||
## Maintain Table Statistics with VACUUM and ANALYZE
|
||||
|
||||
Outdated statistics cause the query planner to make poor decisions. VACUUM reclaims space, ANALYZE updates statistics.
|
||||
|
||||
**Incorrect (stale statistics):**
|
||||
|
||||
```sql
|
||||
-- Table has 1M rows but stats say 1000
|
||||
-- Query planner chooses wrong strategy
|
||||
explain select * from orders where status = 'pending';
|
||||
-- Shows: Seq Scan (because stats show small table)
|
||||
-- Actually: Index Scan would be much faster
|
||||
```
|
||||
|
||||
**Correct (maintain fresh statistics):**
|
||||
|
||||
```sql
|
||||
-- Manually analyze after large data changes
|
||||
analyze orders;
|
||||
|
||||
-- Analyze specific columns used in WHERE clauses
|
||||
analyze orders (status, created_at);
|
||||
|
||||
-- Check when tables were last analyzed
|
||||
select
|
||||
relname,
|
||||
last_vacuum,
|
||||
last_autovacuum,
|
||||
last_analyze,
|
||||
last_autoanalyze
|
||||
from pg_stat_user_tables
|
||||
order by last_analyze nulls first;
|
||||
```
|
||||
|
||||
Autovacuum tuning for busy tables:
|
||||
|
||||
```sql
|
||||
-- Increase frequency for high-churn tables
|
||||
alter table orders set (
|
||||
autovacuum_vacuum_scale_factor = 0.05, -- Vacuum at 5% dead tuples (default 20%)
|
||||
autovacuum_analyze_scale_factor = 0.02 -- Analyze at 2% changes (default 10%)
|
||||
);
|
||||
|
||||
-- Check autovacuum status
|
||||
select * from pg_stat_progress_vacuum;
|
||||
```
|
||||
|
||||
Reference: [VACUUM](https://supabase.com/docs/guides/database/database-size#vacuum-operations)
|
||||
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: Create Composite Indexes for Multi-Column Queries
|
||||
impact: HIGH
|
||||
impactDescription: 5-10x faster multi-column queries
|
||||
tags: indexes, composite-index, multi-column, query-optimization
|
||||
---
|
||||
|
||||
## Create Composite Indexes for Multi-Column Queries
|
||||
|
||||
When queries filter on multiple columns, a composite index is more efficient than separate single-column indexes.
|
||||
|
||||
**Incorrect (separate indexes require bitmap scan):**
|
||||
|
||||
```sql
|
||||
-- Two separate indexes
|
||||
create index orders_status_idx on orders (status);
|
||||
create index orders_created_idx on orders (created_at);
|
||||
|
||||
-- Query must combine both indexes (slower)
|
||||
select * from orders where status = 'pending' and created_at > '2024-01-01';
|
||||
```
|
||||
|
||||
**Correct (composite index):**
|
||||
|
||||
```sql
|
||||
-- Single composite index (leftmost column first for equality checks)
|
||||
create index orders_status_created_idx on orders (status, created_at);
|
||||
|
||||
-- Query uses one efficient index scan
|
||||
select * from orders where status = 'pending' and created_at > '2024-01-01';
|
||||
```
|
||||
|
||||
**Column order matters** - place equality columns first, range columns last:
|
||||
|
||||
```sql
|
||||
-- Good: status (=) before created_at (>)
|
||||
create index idx on orders (status, created_at);
|
||||
|
||||
-- Works for: WHERE status = 'pending'
|
||||
-- Works for: WHERE status = 'pending' AND created_at > '2024-01-01'
|
||||
-- Does NOT work for: WHERE created_at > '2024-01-01' (leftmost prefix rule)
|
||||
```
|
||||
|
||||
Reference: [Multicolumn Indexes](https://www.postgresql.org/docs/current/indexes-multicolumn.html)
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Use Covering Indexes to Avoid Table Lookups
|
||||
impact: MEDIUM-HIGH
|
||||
impactDescription: 2-5x faster queries by eliminating heap fetches
|
||||
tags: indexes, covering-index, include, index-only-scan
|
||||
---
|
||||
|
||||
## Use Covering Indexes to Avoid Table Lookups
|
||||
|
||||
Covering indexes include all columns needed by a query, enabling index-only scans that skip the table entirely.
|
||||
|
||||
**Incorrect (index scan + heap fetch):**
|
||||
|
||||
```sql
|
||||
create index users_email_idx on users (email);
|
||||
|
||||
-- Must fetch name and created_at from table heap
|
||||
select email, name, created_at from users where email = 'user@example.com';
|
||||
```
|
||||
|
||||
**Correct (index-only scan with INCLUDE):**
|
||||
|
||||
```sql
|
||||
-- Include non-searchable columns in the index
|
||||
create index users_email_idx on users (email) include (name, created_at);
|
||||
|
||||
-- All columns served from index, no table access needed
|
||||
select email, name, created_at from users where email = 'user@example.com';
|
||||
```
|
||||
|
||||
Use INCLUDE for columns you SELECT but don't filter on:
|
||||
|
||||
```sql
|
||||
-- Searching by status, but also need customer_id and total
|
||||
create index orders_status_idx on orders (status) include (customer_id, total);
|
||||
|
||||
select status, customer_id, total from orders where status = 'shipped';
|
||||
```
|
||||
|
||||
Reference: [Index-Only Scans](https://www.postgresql.org/docs/current/indexes-index-only-scans.html)
|
||||
45
skills/postgres-best-practices/rules/query-index-types.md
Normal file
45
skills/postgres-best-practices/rules/query-index-types.md
Normal file
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: Choose the Right Index Type for Your Data
|
||||
impact: HIGH
|
||||
impactDescription: 10-100x improvement with correct index type
|
||||
tags: indexes, btree, gin, brin, hash, index-types
|
||||
---
|
||||
|
||||
## Choose the Right Index Type for Your Data
|
||||
|
||||
Different index types excel at different query patterns. The default B-tree isn't always optimal.
|
||||
|
||||
**Incorrect (B-tree for JSONB containment):**
|
||||
|
||||
```sql
|
||||
-- B-tree cannot optimize containment operators
|
||||
create index products_attrs_idx on products (attributes);
|
||||
select * from products where attributes @> '{"color": "red"}';
|
||||
-- Full table scan - B-tree doesn't support @> operator
|
||||
```
|
||||
|
||||
**Correct (GIN for JSONB):**
|
||||
|
||||
```sql
|
||||
-- GIN supports @>, ?, ?&, ?| operators
|
||||
create index products_attrs_idx on products using gin (attributes);
|
||||
select * from products where attributes @> '{"color": "red"}';
|
||||
```
|
||||
|
||||
Index type guide:
|
||||
|
||||
```sql
|
||||
-- B-tree (default): =, <, >, BETWEEN, IN, IS NULL
|
||||
create index users_created_idx on users (created_at);
|
||||
|
||||
-- GIN: arrays, JSONB, full-text search
|
||||
create index posts_tags_idx on posts using gin (tags);
|
||||
|
||||
-- BRIN: large time-series tables (10-100x smaller)
|
||||
create index events_time_idx on events using brin (created_at);
|
||||
|
||||
-- Hash: equality-only (slightly faster than B-tree for =)
|
||||
create index sessions_token_idx on sessions using hash (token);
|
||||
```
|
||||
|
||||
Reference: [Index Types](https://www.postgresql.org/docs/current/indexes-types.html)
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
title: Add Indexes on WHERE and JOIN Columns
|
||||
impact: CRITICAL
|
||||
impactDescription: 100-1000x faster queries on large tables
|
||||
tags: indexes, performance, sequential-scan, query-optimization
|
||||
---
|
||||
|
||||
## Add Indexes on WHERE and JOIN Columns
|
||||
|
||||
Queries filtering or joining on unindexed columns cause full table scans, which become exponentially slower as tables grow.
|
||||
|
||||
**Incorrect (sequential scan on large table):**
|
||||
|
||||
```sql
|
||||
-- No index on customer_id causes full table scan
|
||||
select * from orders where customer_id = 123;
|
||||
|
||||
-- EXPLAIN shows: Seq Scan on orders (cost=0.00..25000.00 rows=100 width=85)
|
||||
```
|
||||
|
||||
**Correct (index scan):**
|
||||
|
||||
```sql
|
||||
-- Create index on frequently filtered column
|
||||
create index orders_customer_id_idx on orders (customer_id);
|
||||
|
||||
select * from orders where customer_id = 123;
|
||||
|
||||
-- EXPLAIN shows: Index Scan using orders_customer_id_idx (cost=0.42..8.44 rows=100 width=85)
|
||||
```
|
||||
|
||||
For JOIN columns, always index the foreign key side:
|
||||
|
||||
```sql
|
||||
-- Index the referencing column
|
||||
create index orders_customer_id_idx on orders (customer_id);
|
||||
|
||||
select c.name, o.total
|
||||
from customers c
|
||||
join orders o on o.customer_id = c.id;
|
||||
```
|
||||
|
||||
Reference: [Query Optimization](https://supabase.com/docs/guides/database/query-optimization)
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: Use Partial Indexes for Filtered Queries
|
||||
impact: HIGH
|
||||
impactDescription: 5-20x smaller indexes, faster writes and queries
|
||||
tags: indexes, partial-index, query-optimization, storage
|
||||
---
|
||||
|
||||
## Use Partial Indexes for Filtered Queries
|
||||
|
||||
Partial indexes only include rows matching a WHERE condition, making them smaller and faster when queries consistently filter on the same condition.
|
||||
|
||||
**Incorrect (full index includes irrelevant rows):**
|
||||
|
||||
```sql
|
||||
-- Index includes all rows, even soft-deleted ones
|
||||
create index users_email_idx on users (email);
|
||||
|
||||
-- Query always filters active users
|
||||
select * from users where email = 'user@example.com' and deleted_at is null;
|
||||
```
|
||||
|
||||
**Correct (partial index matches query filter):**
|
||||
|
||||
```sql
|
||||
-- Index only includes active users
|
||||
create index users_active_email_idx on users (email)
|
||||
where deleted_at is null;
|
||||
|
||||
-- Query uses the smaller, faster index
|
||||
select * from users where email = 'user@example.com' and deleted_at is null;
|
||||
```
|
||||
|
||||
Common use cases for partial indexes:
|
||||
|
||||
```sql
|
||||
-- Only pending orders (status rarely changes once completed)
|
||||
create index orders_pending_idx on orders (created_at)
|
||||
where status = 'pending';
|
||||
|
||||
-- Only non-null values
|
||||
create index products_sku_idx on products (sku)
|
||||
where sku is not null;
|
||||
```
|
||||
|
||||
Reference: [Partial Indexes](https://www.postgresql.org/docs/current/indexes-partial.html)
|
||||
46
skills/postgres-best-practices/rules/schema-data-types.md
Normal file
46
skills/postgres-best-practices/rules/schema-data-types.md
Normal file
@@ -0,0 +1,46 @@
|
||||
---
|
||||
title: Choose Appropriate Data Types
|
||||
impact: HIGH
|
||||
impactDescription: 50% storage reduction, faster comparisons
|
||||
tags: data-types, schema, storage, performance
|
||||
---
|
||||
|
||||
## Choose Appropriate Data Types
|
||||
|
||||
Using the right data types reduces storage, improves query performance, and prevents bugs.
|
||||
|
||||
**Incorrect (wrong data types):**
|
||||
|
||||
```sql
|
||||
create table users (
|
||||
id int, -- Will overflow at 2.1 billion
|
||||
email varchar(255), -- Unnecessary length limit
|
||||
created_at timestamp, -- Missing timezone info
|
||||
is_active varchar(5), -- String for boolean
|
||||
price varchar(20) -- String for numeric
|
||||
);
|
||||
```
|
||||
|
||||
**Correct (appropriate data types):**
|
||||
|
||||
```sql
|
||||
create table users (
|
||||
id bigint generated always as identity primary key, -- 9 quintillion max
|
||||
email text, -- No artificial limit, same performance as varchar
|
||||
created_at timestamptz, -- Always store timezone-aware timestamps
|
||||
is_active boolean default true, -- 1 byte vs variable string length
|
||||
price numeric(10,2) -- Exact decimal arithmetic
|
||||
);
|
||||
```
|
||||
|
||||
Key guidelines:
|
||||
|
||||
```sql
|
||||
-- IDs: use bigint, not int (future-proofing)
|
||||
-- Strings: use text, not varchar(n) unless constraint needed
|
||||
-- Time: use timestamptz, not timestamp
|
||||
-- Money: use numeric, not float (precision matters)
|
||||
-- Enums: use text with check constraint or create enum type
|
||||
```
|
||||
|
||||
Reference: [Data Types](https://www.postgresql.org/docs/current/datatype.html)
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
title: Index Foreign Key Columns
|
||||
impact: HIGH
|
||||
impactDescription: 10-100x faster JOINs and CASCADE operations
|
||||
tags: foreign-key, indexes, joins, schema
|
||||
---
|
||||
|
||||
## Index Foreign Key Columns
|
||||
|
||||
Postgres does not automatically index foreign key columns. Missing indexes cause slow JOINs and CASCADE operations.
|
||||
|
||||
**Incorrect (unindexed foreign key):**
|
||||
|
||||
```sql
|
||||
create table orders (
|
||||
id bigint generated always as identity primary key,
|
||||
customer_id bigint references customers(id) on delete cascade,
|
||||
total numeric(10,2)
|
||||
);
|
||||
|
||||
-- No index on customer_id!
|
||||
-- JOINs and ON DELETE CASCADE both require full table scan
|
||||
select * from orders where customer_id = 123; -- Seq Scan
|
||||
delete from customers where id = 123; -- Locks table, scans all orders
|
||||
```
|
||||
|
||||
**Correct (indexed foreign key):**
|
||||
|
||||
```sql
|
||||
create table orders (
|
||||
id bigint generated always as identity primary key,
|
||||
customer_id bigint references customers(id) on delete cascade,
|
||||
total numeric(10,2)
|
||||
);
|
||||
|
||||
-- Always index the FK column
|
||||
create index orders_customer_id_idx on orders (customer_id);
|
||||
|
||||
-- Now JOINs and cascades are fast
|
||||
select * from orders where customer_id = 123; -- Index Scan
|
||||
delete from customers where id = 123; -- Uses index, fast cascade
|
||||
```
|
||||
|
||||
Find missing FK indexes:
|
||||
|
||||
```sql
|
||||
select
|
||||
conrelid::regclass as table_name,
|
||||
a.attname as fk_column
|
||||
from pg_constraint c
|
||||
join pg_attribute a on a.attrelid = c.conrelid and a.attnum = any(c.conkey)
|
||||
where c.contype = 'f'
|
||||
and not exists (
|
||||
select 1 from pg_index i
|
||||
where i.indrelid = c.conrelid and a.attnum = any(i.indkey)
|
||||
);
|
||||
```
|
||||
|
||||
Reference: [Foreign Keys](https://www.postgresql.org/docs/current/ddl-constraints.html#DDL-CONSTRAINTS-FK)
|
||||
@@ -0,0 +1,55 @@
|
||||
---
|
||||
title: Use Lowercase Identifiers for Compatibility
|
||||
impact: MEDIUM
|
||||
impactDescription: Avoid case-sensitivity bugs with tools, ORMs, and AI assistants
|
||||
tags: naming, identifiers, case-sensitivity, schema, conventions
|
||||
---
|
||||
|
||||
## Use Lowercase Identifiers for Compatibility
|
||||
|
||||
PostgreSQL folds unquoted identifiers to lowercase. Quoted mixed-case identifiers require quotes forever and cause issues with tools, ORMs, and AI assistants that may not recognize them.
|
||||
|
||||
**Incorrect (mixed-case identifiers):**
|
||||
|
||||
```sql
|
||||
-- Quoted identifiers preserve case but require quotes everywhere
|
||||
CREATE TABLE "Users" (
|
||||
"userId" bigint PRIMARY KEY,
|
||||
"firstName" text,
|
||||
"lastName" text
|
||||
);
|
||||
|
||||
-- Must always quote or queries fail
|
||||
SELECT "firstName" FROM "Users" WHERE "userId" = 1;
|
||||
|
||||
-- This fails - Users becomes users without quotes
|
||||
SELECT firstName FROM Users;
|
||||
-- ERROR: relation "users" does not exist
|
||||
```
|
||||
|
||||
**Correct (lowercase snake_case):**
|
||||
|
||||
```sql
|
||||
-- Unquoted lowercase identifiers are portable and tool-friendly
|
||||
CREATE TABLE users (
|
||||
user_id bigint PRIMARY KEY,
|
||||
first_name text,
|
||||
last_name text
|
||||
);
|
||||
|
||||
-- Works without quotes, recognized by all tools
|
||||
SELECT first_name FROM users WHERE user_id = 1;
|
||||
```
|
||||
|
||||
Common sources of mixed-case identifiers:
|
||||
|
||||
```sql
|
||||
-- ORMs often generate quoted camelCase - configure them to use snake_case
|
||||
-- Migrations from other databases may preserve original casing
|
||||
-- Some GUI tools quote identifiers by default - disable this
|
||||
|
||||
-- If stuck with mixed-case, create views as a compatibility layer
|
||||
CREATE VIEW users AS SELECT "userId" AS user_id, "firstName" AS first_name FROM "Users";
|
||||
```
|
||||
|
||||
Reference: [Identifiers and Key Words](https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS)
|
||||
55
skills/postgres-best-practices/rules/schema-partitioning.md
Normal file
55
skills/postgres-best-practices/rules/schema-partitioning.md
Normal file
@@ -0,0 +1,55 @@
|
||||
---
|
||||
title: Partition Large Tables for Better Performance
|
||||
impact: MEDIUM-HIGH
|
||||
impactDescription: 5-20x faster queries and maintenance on large tables
|
||||
tags: partitioning, large-tables, time-series, performance
|
||||
---
|
||||
|
||||
## Partition Large Tables for Better Performance
|
||||
|
||||
Partitioning splits a large table into smaller pieces, improving query performance and maintenance operations.
|
||||
|
||||
**Incorrect (single large table):**
|
||||
|
||||
```sql
|
||||
create table events (
|
||||
id bigint generated always as identity,
|
||||
created_at timestamptz,
|
||||
data jsonb
|
||||
);
|
||||
|
||||
-- 500M rows, queries scan everything
|
||||
select * from events where created_at > '2024-01-01'; -- Slow
|
||||
vacuum events; -- Takes hours, locks table
|
||||
```
|
||||
|
||||
**Correct (partitioned by time range):**
|
||||
|
||||
```sql
|
||||
create table events (
|
||||
id bigint generated always as identity,
|
||||
created_at timestamptz not null,
|
||||
data jsonb
|
||||
) partition by range (created_at);
|
||||
|
||||
-- Create partitions for each month
|
||||
create table events_2024_01 partition of events
|
||||
for values from ('2024-01-01') to ('2024-02-01');
|
||||
|
||||
create table events_2024_02 partition of events
|
||||
for values from ('2024-02-01') to ('2024-03-01');
|
||||
|
||||
-- Queries only scan relevant partitions
|
||||
select * from events where created_at > '2024-01-15'; -- Only scans events_2024_01+
|
||||
|
||||
-- Drop old data instantly
|
||||
drop table events_2023_01; -- Instant vs DELETE taking hours
|
||||
```
|
||||
|
||||
When to partition:
|
||||
|
||||
- Tables > 100M rows
|
||||
- Time-series data with date-based queries
|
||||
- Need to efficiently drop old data
|
||||
|
||||
Reference: [Table Partitioning](https://www.postgresql.org/docs/current/ddl-partitioning.html)
|
||||
61
skills/postgres-best-practices/rules/schema-primary-keys.md
Normal file
61
skills/postgres-best-practices/rules/schema-primary-keys.md
Normal file
@@ -0,0 +1,61 @@
|
||||
---
|
||||
title: Select Optimal Primary Key Strategy
|
||||
impact: HIGH
|
||||
impactDescription: Better index locality, reduced fragmentation
|
||||
tags: primary-key, identity, uuid, serial, schema
|
||||
---
|
||||
|
||||
## Select Optimal Primary Key Strategy
|
||||
|
||||
Primary key choice affects insert performance, index size, and replication
|
||||
efficiency.
|
||||
|
||||
**Incorrect (problematic PK choices):**
|
||||
|
||||
```sql
|
||||
-- identity is the SQL-standard approach
|
||||
create table users (
|
||||
id serial primary key -- Works, but IDENTITY is recommended
|
||||
);
|
||||
|
||||
-- Random UUIDs (v4) cause index fragmentation
|
||||
create table orders (
|
||||
id uuid default gen_random_uuid() primary key -- UUIDv4 = random = scattered inserts
|
||||
);
|
||||
```
|
||||
|
||||
**Correct (optimal PK strategies):**
|
||||
|
||||
```sql
|
||||
-- Use IDENTITY for sequential IDs (SQL-standard, best for most cases)
|
||||
create table users (
|
||||
id bigint generated always as identity primary key
|
||||
);
|
||||
|
||||
-- For distributed systems needing UUIDs, use UUIDv7 (time-ordered)
|
||||
-- Requires pg_uuidv7 extension: create extension pg_uuidv7;
|
||||
create table orders (
|
||||
id uuid default uuid_generate_v7() primary key -- Time-ordered, no fragmentation
|
||||
);
|
||||
|
||||
-- Alternative: time-prefixed IDs for sortable, distributed IDs (no extension needed)
|
||||
create table events (
|
||||
id text default concat(
|
||||
to_char(now() at time zone 'utc', 'YYYYMMDDHH24MISSMS'),
|
||||
gen_random_uuid()::text
|
||||
) primary key
|
||||
);
|
||||
```
|
||||
|
||||
Guidelines:
|
||||
|
||||
- Single database: `bigint identity` (sequential, 8 bytes, SQL-standard)
|
||||
- Distributed/exposed IDs: UUIDv7 (requires pg_uuidv7) or ULID (time-ordered, no
|
||||
fragmentation)
|
||||
- `serial` works but `identity` is SQL-standard and preferred for new
|
||||
applications
|
||||
- Avoid random UUIDs (v4) as primary keys on large tables (causes index
|
||||
fragmentation)
|
||||
|
||||
Reference:
|
||||
[Identity Columns](https://www.postgresql.org/docs/current/sql-createtable.html#SQL-CREATETABLE-PARMS-GENERATED-IDENTITY)
|
||||
54
skills/postgres-best-practices/rules/security-privileges.md
Normal file
54
skills/postgres-best-practices/rules/security-privileges.md
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: Apply Principle of Least Privilege
|
||||
impact: MEDIUM
|
||||
impactDescription: Reduced attack surface, better audit trail
|
||||
tags: privileges, security, roles, permissions
|
||||
---
|
||||
|
||||
## Apply Principle of Least Privilege
|
||||
|
||||
Grant only the minimum permissions required. Never use superuser for application queries.
|
||||
|
||||
**Incorrect (overly broad permissions):**
|
||||
|
||||
```sql
|
||||
-- Application uses superuser connection
|
||||
-- Or grants ALL to application role
|
||||
grant all privileges on all tables in schema public to app_user;
|
||||
grant all privileges on all sequences in schema public to app_user;
|
||||
|
||||
-- Any SQL injection becomes catastrophic
|
||||
-- drop table users; cascades to everything
|
||||
```
|
||||
|
||||
**Correct (minimal, specific grants):**
|
||||
|
||||
```sql
|
||||
-- Create role with no default privileges
|
||||
create role app_readonly nologin;
|
||||
|
||||
-- Grant only SELECT on specific tables
|
||||
grant usage on schema public to app_readonly;
|
||||
grant select on public.products, public.categories to app_readonly;
|
||||
|
||||
-- Create role for writes with limited scope
|
||||
create role app_writer nologin;
|
||||
grant usage on schema public to app_writer;
|
||||
grant select, insert, update on public.orders to app_writer;
|
||||
grant usage on sequence orders_id_seq to app_writer;
|
||||
-- No DELETE permission
|
||||
|
||||
-- Login role inherits from these
|
||||
create role app_user login password 'xxx';
|
||||
grant app_writer to app_user;
|
||||
```
|
||||
|
||||
Revoke public defaults:
|
||||
|
||||
```sql
|
||||
-- Revoke default public access
|
||||
revoke all on schema public from public;
|
||||
revoke all on all tables in schema public from public;
|
||||
```
|
||||
|
||||
Reference: [Roles and Privileges](https://supabase.com/blog/postgres-roles-and-privileges)
|
||||
50
skills/postgres-best-practices/rules/security-rls-basics.md
Normal file
50
skills/postgres-best-practices/rules/security-rls-basics.md
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: Enable Row Level Security for Multi-Tenant Data
|
||||
impact: CRITICAL
|
||||
impactDescription: Database-enforced tenant isolation, prevent data leaks
|
||||
tags: rls, row-level-security, multi-tenant, security
|
||||
---
|
||||
|
||||
## Enable Row Level Security for Multi-Tenant Data
|
||||
|
||||
Row Level Security (RLS) enforces data access at the database level, ensuring users only see their own data.
|
||||
|
||||
**Incorrect (application-level filtering only):**
|
||||
|
||||
```sql
|
||||
-- Relying only on application to filter
|
||||
select * from orders where user_id = $current_user_id;
|
||||
|
||||
-- Bug or bypass means all data is exposed!
|
||||
select * from orders; -- Returns ALL orders
|
||||
```
|
||||
|
||||
**Correct (database-enforced RLS):**
|
||||
|
||||
```sql
|
||||
-- Enable RLS on the table
|
||||
alter table orders enable row level security;
|
||||
|
||||
-- Create policy for users to see only their orders
|
||||
create policy orders_user_policy on orders
|
||||
for all
|
||||
using (user_id = current_setting('app.current_user_id')::bigint);
|
||||
|
||||
-- Force RLS even for table owners
|
||||
alter table orders force row level security;
|
||||
|
||||
-- Set user context and query
|
||||
set app.current_user_id = '123';
|
||||
select * from orders; -- Only returns orders for user 123
|
||||
```
|
||||
|
||||
Policy for authenticated role:
|
||||
|
||||
```sql
|
||||
create policy orders_user_policy on orders
|
||||
for all
|
||||
to authenticated
|
||||
using (user_id = auth.uid());
|
||||
```
|
||||
|
||||
Reference: [Row Level Security](https://supabase.com/docs/guides/database/postgres/row-level-security)
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user