firefrost-gaming/antigravity-skills-reference
3
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: update CONTRIBUTING and FAQ for V3 Quality Bar and Security [skip ci]

Browse Source
This commit is contained in:
sck_0
2026-01-25 20:14:27 +01:00
parent 1e03172075
commit c96815ed7c
2 changed files with 74 additions and 886 deletions
Download Patch File Download Diff File Expand all files Collapse all files

391
CONTRIBUTING.md
View File

@@ -1,401 +1,96 @@
# 🤝 Contributing Guide - Make It Easy for Everyone!
# 🤝 Contributing Guide - V3 Enterprise Edition
**Thank you for wanting to make this repo better!** This guide shows you exactly how to contribute, even if you're new to open source.
**Thank you for wanting to help!** This repository is built by the community, for the community.
With V3, we raised the bar for quality. Here is how you can contribute effectively.
---
## Ways to Contribute
## 🧐 The "Quality Bar"
You don't need to be an expert! Here are ways anyone can help:
Every skill submitted must pass our **5-Point Quality Check** (see `docs/QUALITY_BAR.md` for details):
### 1. Improve Documentation (Easiest!)
- Fix typos or grammar
- Make explanations clearer
- Add examples to existing skills
- Translate documentation to other languages
### 2. Report Issues
- Found something confusing? Tell us!
- Skill not working? Let us know!
- Have suggestions? We want to hear them!
### 3. Create New Skills
- Share your expertise as a skill
- Fill gaps in the current collection
- Improve existing skills
### 4. Test and Validate
- Try skills and report what works/doesn't work
- Test on different AI tools
- Suggest improvements
1. **Metadata**: Correct Frontmatter (`name`, `description`).
2. **Safety**: No harmful commands without "Risk" labels.
3. **Clarity**: Clear "When to use" section.
4. **Examples**: At least one copy-paste usage example.
5. **Actions**: Must define concrete steps, not just "thoughts".
---
## How to Improve Documentation
## 🛠️ How to Create a New Skill
### Super Easy Method (No Git Knowledge Needed!)
1. **Find the file** you want to improve on GitHub
2. **Click the pencil icon** (✏️) to edit
3. **Make your changes** in the browser
4. **Click "Propose changes"** at the bottom
5. **Done!** We'll review and merge it
### Using Git (If You Know How)
### Step 1: Fork & Clone
```bash
# 1. Fork the repo on GitHub (click the Fork button)
# 2. Clone your fork
git clone https://github.com/YOUR-USERNAME/antigravity-awesome-skills.git
cd antigravity-awesome-skills
# 3. Create a branch
git checkout -b improve-docs
# 4. Make your changes
# Edit files in your favorite editor
# 5. Commit and push
git add .
git commit -m "docs: make XYZ clearer"
git push origin improve-docs
# 6. Open a Pull Request on GitHub
```
---
### Step 2: Create the Folder
## How to Create a New Skill
### What Makes a Good Skill?
A skill should:
- ✅ Solve a specific problem
- ✅ Be reusable across projects
- ✅ Have clear instructions
- ✅ Include examples when possible
### Step-by-Step: Create Your First Skill
#### Step 1: Choose Your Skill Topic
Ask yourself:
- What am I good at?
- What do I wish my AI assistant knew better?
- What task do I do repeatedly?
**Examples:**
- "I'm good at Docker, let me create a Docker skill"
- "I wish AI understood Tailwind better"
- "I keep setting up the same testing patterns"
#### Step 2: Create the Folder Structure
Skills live in `skills/`. Names must be `kebab-case`.
```bash
# Navigate to the skills directory
cd skills/
# Create your skill folder (use lowercase with hyphens)
mkdir my-awesome-skill
# Create the SKILL.md file
cd my-awesome-skill
touch SKILL.md
mkdir skills/my-new-skill
touch skills/my-new-skill/SKILL.md
```
#### Step 3: Write Your SKILL.md
### Step 3: Write the Content
Every skill needs this basic structure:
Copy this template to start:
```markdown
---
name: my-awesome-skill
description: "Brief one-line description of what this skill does"
name: my-new-skill
description: One line description of what this does.
---
# Skill Title
# My New Skill
## Overview
Explain what this skill does and when to use it.
What problem does this solve?
## When to Use This Skill
## Usage Examples
- Use when [scenario 1]
- Use when [scenario 2]
- Use when [scenario 3]
## How It Works
### Step 1: [First Step]
Explain what to do first...
### Step 2: [Second Step]
Explain the next step...
### Step 3: [Final Step]
Explain how to finish...
## Examples
### Example 1: [Common Use Case]
\`\`\`
Show example code or commands here
\`\`\`
### Example 2: [Another Use Case]
\`\`\`
More examples...
\`\`\`
## Best Practices
- ✅ Do this
- ✅ Also do this
- ❌ Don't do this
- ❌ Avoid this
## Common Pitfalls
- **Problem:** Description of common issue
**Solution:** How to fix it
## Additional Resources
- [Link to documentation](https://example.com)
- [Tutorial](https://example.com)
> "@my-new-skill help me..."
```
#### Step 4: Test Your Skill
### Step 4: Validate (CRITICAL)
1. **Copy it to your AI tool's skills directory:**
```bash
cp -r skills/my-awesome-skill ~/.agent/skills/
```
2. **Try using it:**
```
@my-awesome-skill help me with [task]
```
3. **Does it work?** Great! If not, refine it.
#### Step 5: Validate Your Skill
Run the validation script:
Run the validation script locally. **We will not merge PRs that fail this check.**
```bash
# Soft mode (warnings only)
python3 scripts/validate_skills.py
```
This checks:
- ✅ SKILL.md exists
- ✅ Frontmatter is correct
- ✅ Name matches folder name
- ✅ Description exists
#### Step 6: Submit Your Skill
```bash
# 1. Add your skill
git add skills/my-awesome-skill/
# 2. Commit with a clear message
git commit -m "feat: add my-awesome-skill for [purpose]"
# 3. Push to your fork
git push origin my-branch
# 4. Open a Pull Request on GitHub
# Hard mode (what CI runs)
python3 scripts/validate_skills.py --strict
```
---
## Skill Template (Copy & Paste)
## 🧪 Testing Your Skill
Save time! Copy this template:
Don't just write it—run it!
```markdown
---
name: your-skill-name
description: "One sentence describing what this skill does and when to use it"
---
# Your Skill Name
## Overview
[2-3 sentences explaining what this skill does]
## When to Use This Skill
- Use when you need to [scenario 1]
- Use when you want to [scenario 2]
- Use when working with [scenario 3]
## Core Concepts
### Concept 1
[Explain key concept]
### Concept 2
[Explain another key concept]
## Step-by-Step Guide
### 1. [First Step Name]
[Detailed instructions]
### 2. [Second Step Name]
[Detailed instructions]
### 3. [Third Step Name]
[Detailed instructions]
## Examples
### Example 1: [Use Case Name]
\`\`\`language
// Example code here
\`\`\`
**Explanation:** [What this example demonstrates]
### Example 2: [Another Use Case]
\`\`\`language
// More example code
\`\`\`
**Explanation:** [What this example demonstrates]
## Best Practices
- ✅ **Do:** [Good practice]
- ✅ **Do:** [Another good practice]
- ❌ **Don't:** [What to avoid]
- ❌ **Don't:** [Another thing to avoid]
## Troubleshooting
### Problem: [Common Issue]
**Symptoms:** [How you know this is the problem]
**Solution:** [How to fix it]
### Problem: [Another Issue]
**Symptoms:** [How you know this is the problem]
**Solution:** [How to fix it]
## Related Skills
- `@related-skill-1` - [When to use this instead]
- `@related-skill-2` - [How this complements your skill]
## Additional Resources
- [Official Documentation](https://example.com)
- [Tutorial](https://example.com)
- [Community Guide](https://example.com)
```
1. Copy it to your local agent folder (`.agent/skills/`).
2. Open your AI (Claude/Cursor).
3. Type `@my-new-skill` and see if it behaves as expected.
---
## How to Report Issues
## ⚖️ Code of Conduct
### Found a Bug?
1. **Check existing issues** - Maybe it's already reported
2. **Open a new issue** with this info:
- What skill has the problem?
- What AI tool are you using?
- What did you expect to happen?
- What actually happened?
- Steps to reproduce
### Found Something Confusing?
1. **Open an issue** titled: "Documentation unclear: [topic]"
2. **Explain:**
- What part is confusing?
- What did you expect to find?
- How could it be clearer?
We adhere to the [Contributor Covenant](https://www.contributor-covenant.org).
**Rule #1**: Be kind.
**Rule #2**: No malware/harmful skills. (See `docs/SECURITY_GUARDRAILS.md`).
---
## Contribution Checklist
## 📦 Submission Checklist
Before submitting your contribution:
- [ ] My skill has a clear, descriptive name
- [ ] The `SKILL.md` has proper frontmatter (name + description)
- [ ] I've included examples
- [ ] I've tested the skill with an AI assistant
- [ ] I've run `python3 scripts/validate_skills.py`
- [ ] My commit message is clear (e.g., "feat: add docker-compose skill")
- [ ] I've checked for typos and grammar
---
## Commit Message Guidelines
Use these prefixes:
- `feat:` - New skill or major feature
- `docs:` - Documentation improvements
- `fix:` - Bug fixes
- `refactor:` - Code improvements without changing functionality
- `test:` - Adding or updating tests
- `chore:` - Maintenance tasks
**Examples:**
```
feat: add kubernetes-deployment skill
docs: improve getting started guide
fix: correct typo in stripe-integration skill
docs: add examples to react-best-practices
```
---
## Learning Resources
### New to Git/GitHub?
- [GitHub's Hello World Guide](https://guides.github.com/activities/hello-world/)
- [Git Basics](https://git-scm.com/book/en/v2/Getting-Started-Git-Basics)
### New to Markdown?
- [Markdown Guide](https://www.markdownguide.org/basic-syntax/)
- [GitHub Markdown](https://guides.github.com/features/mastering-markdown/)
### New to Open Source?
- [First Contributions](https://github.com/firstcontributions/first-contributions)
- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
---
## Need Help?
- **Questions?** Open a [Discussion](https://github.com/sickn33/antigravity-awesome-skills/discussions)
- **Stuck?** Open an [Issue](https://github.com/sickn33/antigravity-awesome-skills/issues)
- **Want feedback?** Open a [Draft Pull Request](https://github.com/sickn33/antigravity-awesome-skills/pulls)
---
## Recognition
All contributors are recognized in our [Contributors](https://github.com/sickn33/antigravity-awesome-skills/graphs/contributors) page!
---
## Code of Conduct
- Be respectful and inclusive
- Welcome newcomers
- Focus on constructive feedback
- Help others learn
---
**Thank you for making this project better for everyone!**
Every contribution, no matter how small, makes a difference. Whether you fix a typo, improve a sentence, or create a whole new skill - you're helping thousands of developers!
- [ ] Folder name is `kebab-case`
- [ ] `SKILL.md` exists
- [ ] `scripts/validate_skills.py` passes
- [ ] You tested it in an actual AI session

569
FAQ.md
View File

@@ -1,557 +1,50 @@
# ❓ Frequently Asked Questions (FAQ)
**Got questions?** You're not alone! Here are answers to the most common questions about Antigravity Awesome Skills.
# ❓ Frequently Asked Questions (V3)
---
## 🎯 General Questions
## 🔒 Security & Trust
### What are "skills" exactly?
### Q: What do the Risk Labels mean?
Skills are specialized instruction files that teach AI assistants how to handle specific tasks. Think of them as expert knowledge modules that your AI can load on-demand.
- ⚪ **Safe (White/Blue)**: Read-only, planning, or benign skills. Safe to run anywhere.
- 🔴 **Risk (Red)**: Skills that modify files, delete resources, or perform security scans. **Use with caution.**
- 🟣 **Official (Purple)**: Maintained by trusted vendors (Anthropic, DeepMind, etc.).
**Simple analogy:** Just like you might consult different experts (a lawyer, a doctor, a mechanic), skills let your AI become an expert in different areas when you need them.
### Q: Can these skills hack my computer?
**No.** Skills are just text files (markdown instructions). However, they _instruct_ the AI to run commands.
If a skill says "delete all files", your AI might try to do it.
_Always review the code before creating a skill, and check the Risk label._
---
### Do I need to install all 233 skills?
## 📦 Installation & Usage
**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`.
### Q: Why shouldn't I just copy all files?
It's like having a library - all the books are there, but you only read the ones you need.
You can! But 250+ files might clutter your context window.
We recommend using **Starter Packs** (`docs/BUNDLES.md`) to install only what you need for your specific role.
### Q: Does this work with Windows?
**Yes**, but some "Official" skills use **symlinks** which Windows handles poorly by default.
Run git with:
`git clone -c core.symlinks=true ...`
Or enable "Developer Mode" in Windows Settings.
---
### Which AI tools work with these skills?
## 🛠️ Contribution
These skills work with any AI coding assistant that supports the `SKILL.md` format:
### Q: My PR failed "Quality Bar" check. Why?
- ✅ **Claude Code** (Anthropic CLI)
- ✅ **Gemini CLI** (Google)
- ✅ **Codex CLI** (OpenAI)
- ✅ **Cursor** (AI IDE)
- ✅ **Antigravity IDE**
- ✅ **OpenCode**
- ⚠️ **GitHub Copilot** (partial support)
V3 introduces automated quality control. Your skill might be missing:
---
1. A valid `description` in the metadata.
2. Usage examples.
Or it might be triggering a security filter. Run `python3 scripts/validate_skills.py` locally to see the error.
### Are these skills free to use?
### Q: Can I update an "Official" skill?
**Yes!** This repository is licensed under MIT License, which means:
- ✅ Free for personal use
- ✅ Free for commercial use
- ✅ You can modify them
- ✅ You can redistribute them
---
### Do skills work offline?
The skill files themselves are stored locally on your computer, but your AI assistant needs an internet connection to function. So:
- ✅ Skills are local files
- ❌ AI assistant needs internet
---
## Installation & Setup
### Where should I install the skills?
The universal path that works with most tools is `.agent/skills/`:
```bash
git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
```
**Tool-specific paths:**
- Claude Code: `.claude/skills/` or `.agent/skills/`
- Gemini CLI: `.gemini/skills/` or `.agent/skills/`
- Cursor: `.cursor/skills/` or project root
- Antigravity: `.agent/skills/`
- OpenCode: `.opencode/skills/` or `.claude/skills/`
---
### Can I install skills in multiple projects?
**Yes!** You have two options:
**Option 1: Global Installation** (recommended)
Install once in your home directory, works for all projects:
```bash
cd ~
git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
```
**Option 2: Per-Project Installation**
Install in each project directory:
```bash
cd /path/to/your/project
git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
```
---
### How do I update skills to the latest version?
Navigate to your skills directory and pull the latest changes:
```bash
cd .agent/skills
git pull origin main
```
---
### Can I install only specific skills?
**Yes!** You can manually copy individual skill folders:
```bash
# Clone the full repo first
git clone https://github.com/sickn33/antigravity-awesome-skills.git temp-skills
# Copy only the skills you want
mkdir -p .agent/skills
cp -r temp-skills/skills/brainstorming .agent/skills/
cp -r temp-skills/skills/stripe-integration .agent/skills/
# Clean up
rm -rf temp-skills
```
---
## Using Skills
### How do I invoke a skill?
Use the `@` symbol followed by the skill name:
```
@skill-name your request here
```
**Examples:**
```
@brainstorming help me design a todo app
@stripe-integration add subscription billing
@systematic-debugging fix this test failure
```
Some tools also support `/skill-name` syntax.
---
### How do I know which skill to use?
**Method 1: Browse the README**
Check the [Full Skill Registry](README.md#full-skill-registry-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]?
```
---
### Can I use multiple skills at once?
**Yes!** You can invoke multiple skills in the same conversation:
```
@brainstorming help me design this feature
[After brainstorming...]
@test-driven-development now let's implement it with tests
```
---
### What if a skill doesn't work?
**Troubleshooting steps:**
1. **Check installation path**
```bash
ls .agent/skills/
```
2. **Verify skill exists**
```bash
ls .agent/skills/skill-name/
```
3. **Check SKILL.md exists**
```bash
cat .agent/skills/skill-name/SKILL.md
```
4. **Try restarting your AI assistant**
5. **Check for typos in skill name**
- Use `@brainstorming` not `@brain-storming`
- Names are case-sensitive in some tools
6. **Report the issue**
[Open an issue](https://github.com/sickn33/antigravity-awesome-skills/issues) with details
---
## 🤝 Contributing
### I'm new to open source. Can I still contribute?
**Absolutely!** Everyone starts somewhere. We welcome contributions from beginners:
- Fix typos or grammar
- Improve documentation clarity
- Add examples to existing skills
- Report issues or confusing parts
Check out [CONTRIBUTING.md](CONTRIBUTING.md) for step-by-step instructions.
---
### Do I need to know how to code to contribute?
**No!** Many valuable contributions don't require coding:
- **Documentation improvements** - Make things clearer
- **Examples** - Add real-world usage examples
- **Issue reporting** - Tell us what's confusing
- **Testing** - Try skills and report what works
---
### How do I create a new skill?
**Quick version:**
1. Create a folder: `skills/my-skill-name/`
2. Create `SKILL.md` with frontmatter and content
3. Test it with your AI assistant
4. Run validation: `python3 scripts/validate_skills.py`
5. Submit a Pull Request
**Detailed version:** See [CONTRIBUTING.md](CONTRIBUTING.md)
---
### What makes a good skill?
A good skill:
- ✅ Solves a specific problem
- ✅ Has clear, actionable instructions
- ✅ Includes examples
- ✅ Is reusable across projects
- ✅ Follows the standard structure
See [SKILL_ANATOMY.md](docs/SKILL_ANATOMY.md) for details.
---
### How long does it take for my contribution to be reviewed?
Review times vary, but typically:
- **Simple fixes** (typos, docs): 1-3 days
- **New skills**: 3-7 days
- **Major changes**: 1-2 weeks
You can speed this up by:
- Following the contribution guidelines
- Writing clear commit messages
- Testing your changes
- Responding to feedback quickly
---
## Technical Questions
### What's the difference between SKILL.md and README.md?
- **SKILL.md** (required): The actual skill definition that the AI reads
- **README.md** (optional): Human-readable documentation about the skill
The AI primarily uses `SKILL.md`, while developers read `README.md`.
---
### Can I use scripts or code in my skill?
**Yes!** Skills can include:
- `scripts/` - Helper scripts
- `examples/` - Example code
- `templates/` - Code templates
- `references/` - Documentation
Reference them in your `SKILL.md`:
```markdown
Run the setup script:
\`\`\`bash
bash scripts/setup.sh
\`\`\`
```
---
### What programming languages can skills cover?
**Any language!** Current skills cover:
- JavaScript/TypeScript
- Python
- Go
- Rust
- Swift
- Kotlin
- Shell scripting
- And many more...
---
### Can skills call other skills?
**Yes!** Skills can reference other skills:
```markdown
## Workflow
1. First, use `@brainstorming` to design
2. Then, use `@writing-plans` to plan
3. Finally, use `@test-driven-development` to implement
```
---
### How do I validate my skill before submitting?
Run the validation script:
```bash
python3 scripts/validate_skills.py
```
This checks:
- ✅ SKILL.md exists
- ✅ Frontmatter is valid
- ✅ Name matches folder name
- ✅ Description exists
---
## Learning & Best Practices
### Which skills should I try first?
**For beginners:**
- `@brainstorming` - Design before coding
- `@systematic-debugging` - Fix bugs methodically
- `@git-pushing` - Commit with good messages
**For developers:**
- `@test-driven-development` - Write tests first
- `@react-best-practices` - Modern React patterns
- `@senior-fullstack` - Full-stack development
**For security:**
- `@ethical-hacking-methodology` - Security basics
- `@burp-suite-testing` - Web app testing
---
### How do I learn to write good skills?
**Learning path:**
1. **Read existing skills** - Study 5-10 well-written skills
2. **Use skills** - Try them with your AI assistant
3. **Read guides** - Check [SKILL_ANATOMY.md](docs/SKILL_ANATOMY.md)
4. **Start simple** - Create a basic skill first
5. **Get feedback** - Submit and learn from reviews
6. **Iterate** - Improve based on feedback
**Recommended skills to study:**
- `skills/brainstorming/SKILL.md` - Clear structure
- `skills/systematic-debugging/SKILL.md` - Comprehensive
- `skills/git-pushing/SKILL.md` - Simple and focused
---
### Are there any skills for learning AI/ML?
**Yes!** Check out:
- `@rag-engineer` - RAG systems
- `@prompt-engineering` - Prompt design
- `@langgraph` - Multi-agent systems
- `@ai-agents-architect` - Agent architecture
- `@llm-app-patterns` - LLM application patterns
---
## Troubleshooting
### My AI assistant doesn't recognize skills
**Possible causes:**
1. **Wrong installation path**
- Check your tool's documentation for the correct path
- Try `.agent/skills/` as the universal path
2. **Skill name typo**
- Verify the exact skill name: `ls .agent/skills/`
- Use the exact name from the folder
3. **Tool doesn't support skills**
- Verify your tool supports the SKILL.md format
- Check the [Compatibility](#-compatibility) section
4. **Need to restart**
- Restart your AI assistant after installing skills
---
### A skill gives incorrect or outdated advice
**Please report it!**
1. [Open an issue](https://github.com/sickn33/antigravity-awesome-skills/issues)
2. Include:
- Which skill
- What's incorrect
- What should it say instead
- Links to correct documentation
We'll update it quickly!
---
### Can I modify skills for my own use?
**Yes!** The MIT License allows you to:
- ✅ Modify skills for your needs
- ✅ Create private versions
- ✅ Customize for your team
**To modify:**
1. Copy the skill to a new location
2. Edit the SKILL.md file
3. Use your modified version
**Consider contributing improvements back!**
---
## Statistics & Info
### How many skills are there?
**233 skills** across 10+ categories as of the latest update.
---
### How often are skills updated?
- **Bug fixes**: As soon as reported
- **New skills**: Added regularly by contributors
- **Updates**: When best practices change
**Stay updated:**
```bash
cd .agent/skills
git pull origin main
```
---
### Who maintains this repository?
This is a community-driven project with contributions from:
- Original creators
- Open source contributors
- AI coding assistant users worldwide
See [Credits & Sources](README.md#credits--sources) for attribution.
---
## Still Have Questions?
### Where can I get help?
- **[GitHub Discussions](https://github.com/sickn33/antigravity-awesome-skills/discussions)** - Ask questions
- **[GitHub Issues](https://github.com/sickn33/antigravity-awesome-skills/issues)** - Report bugs
- **Documentation** - Read the guides in this repo
- **Community** - Connect with other users
---
### How can I stay updated?
- **Star the repository** on GitHub
- **Watch the repository** for updates
- **Subscribe to releases** for notifications
- **Follow contributors** on social media
---
### Can I use these skills commercially?
**Yes!** The MIT License permits commercial use. You can:
- ✅ Use in commercial projects
- ✅ Use in client work
- ✅ Include in paid products
- ✅ Modify for commercial purposes
**Only requirement:** Keep the license notice.
---
## 💡 Pro Tips
- Start with `@brainstorming` before building anything new
- Use `@systematic-debugging` when stuck on bugs
- Try `@test-driven-development` for better code quality
- Explore `@skill-creator` to make your own skills
- Read skill descriptions to understand when to use them
---
**Question not answered?**
[Open a discussion](https://github.com/sickn33/antigravity-awesome-skills/discussions) and we'll help you out! 🙌
**No.** Official skills (in `skills/official/`) are mirrored from vendors.
Open an issue instead, and we will forward it to the maintainers.