ayrisdev/app-store-optimization
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: restore VERY detailed documentation while keeping V3 updates [skip ci]

Browse Source
This commit is contained in:
sck_0
2026-01-25 20:17:00 +01:00
parent 45e2049663
commit e242186fe2
2 changed files with 287 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files

212
CONTRIBUTING.md
View File

@@ -1,7 +1,7 @@
# 🤝 Contributing Guide - V3 Enterprise Edition # 🤝 Contributing Guide - V3 Enterprise Edition
**Thank you for wanting to help!** This repository is built by the community, for the community. **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.
With V3, we raised the bar for quality. This guide covers everything from your first Pull Request to our new Quality Standards. With V3, we raised the bar for quality. Please read the **new Quality Standards** below carefully.
--- ---
@@ -17,74 +17,102 @@ With V3, we raised the bar for quality. This guide covers everything from your f
--- ---
## 🛠️ Ways to Contribute ## Ways to Contribute
You don't need to be an expert! Here are ways anyone can help: You don't need to be an expert! Here are ways anyone can help:
### 1. Improve Documentation ### 1. Improve Documentation (Easiest!)
- Fix typos or grammar - Fix typos or grammar
- Make explanations clearer
- Add examples to existing skills - Add examples to existing skills
- Translate documentation - Translate documentation to other languages
### 2. Create New Skills ### 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 - Share your expertise as a skill
- Fill gaps in the current collection - Fill gaps in the current collection
- Improve existing skills
### 3. Report Issues ### 4. Test and Validate
- Found a bug? [Open an issue](https://github.com/sickn33/antigravity-awesome-skills/issues) - Try skills and report what works/doesn't work
- Test on different AI tools
- Suggest improvements
--- ---
## 🚀 Step-by-Step: Create Your First Skill ## How to Create a New Skill
### Step 1: Fork & Clone ### Step-by-Step Guide
#### Step 1: Choose Your Skill Topic
Ask yourself: "What do I wish my AI assistant knew better?".
Example: "I'm good at Docker, let me create a Docker skill".
#### Step 2: Create the Folder Structure
Skills live in the `skills/` directory. Use `kebab-case` for folder names.
```bash ```bash
git clone https://github.com/YOUR-USERNAME/antigravity-awesome-skills.git # Navigate to skills
cd antigravity-awesome-skills cd skills/
# Create your skill folder
mkdir my-awesome-skill
cd my-awesome-skill
# Create the SKILL.md file
touch SKILL.md
``` ```
### Step 2: Create the Folder #### Step 3: Write Your SKILL.md
Skills live in `skills/`. Names must be `kebab-case`. Every skill needs this basic structure. **Copy this template:**
```bash
# Good
mkdir skills/my-new-skill
# Bad
mkdir skills/MyNewSkill
```
### Step 3: Write the Content (`SKILL.md`)
Every skill needs this basic structure. Copy this template:
```markdown ```markdown
--- ---
name: my-new-skill name: my-awesome-skill
description: One line description of what this does. description: "Brief one-line description of what this skill does"
--- ---
# My New Skill # Skill Title
## Overview ## Overview
What problem does this solve? Explain what this skill does and when to use it.
## Usage Examples ## When to Use This Skill
> "@my-new-skill help me..." - Use when [scenario 1]
- Use when [scenario 2]
## Core Instructions ## How It Works
[Detailed instructions for the AI] Detailed step-by-step instructions for the AI...
## Examples
### Example 1
\`\`\`
code example here
\`\`\`
## Best Practices
- ✅ Do this
- ❌ Don't do this
``` ```
### Step 4: Validate (CRITICAL) #### Step 4: Validate (CRITICAL V3 STEP)
Run the validation script locally. **We will not merge PRs that fail this check.** Run the validation script locally. **We will not merge PRs that fail this check.**
@@ -96,33 +124,113 @@ python3 scripts/validate_skills.py
python3 scripts/validate_skills.py --strict python3 scripts/validate_skills.py --strict
``` ```
### Step 5: Test & Submit This checks:
1. Copy it to your local agent folder (`.agent/skills/`). - ✅ `SKILL.md` exists
2. Test it with your AI. - ✅ Frontmatter is correct
3. Push and open a Pull Request! - ✅ Name matches folder name
- ✅ Quality Bar checks passed
#### Step 5: Submit Your Skill
```bash
git add skills/my-awesome-skill/
git commit -m "feat: add my-awesome-skill"
git push origin my-branch
```
--- ---
## 💡 Best Practices for V3 ## Skill Template (Copy & Paste)
- **Be Specific**: Don't say "Write code". Say "Write strict TypeScript code using these patterns...". Save time! Copy this template:
- **Use Examples**: The AI learns best from examples.
- **Keep it Atomic**: One skill, one job. Don't make "god skills". ```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]
## Step-by-Step Guide
### 1. [First Step Name]
[Detailed instructions]
## Examples
### Example 1: [Use Case Name]
\`\`\`language
// Example code here
\`\`\`
## Best Practices
- ✅ **Do:** [Good practice]
- ❌ **Don't:** [What to avoid]
## Troubleshooting
**Problem:** [Common Issue]
**Solution:** [How to fix it]
```
--- ---
## ⚖️ Code of Conduct ## Commit Message Guidelines
We adhere to the [Contributor Covenant](https://www.contributor-covenant.org). Use these prefixes:
**Rule #1**: Be kind.
**Rule #2**: No malware/harmful skills. (See `docs/SECURITY_GUARDRAILS.md`). - `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
```
--- ---
## 📦 Submission Checklist ## Learning Resources
- [ ] Folder name is `kebab-case` ### New to Git/GitHub?
- [ ] `SKILL.md` exists
- [ ] `scripts/validate_skills.py` passes - [GitHub's Hello World Guide](https://guides.github.com/activities/hello-world/)
- [ ] You tested it in an actual AI session - [Git Basics](https://git-scm.com/book/en/v2/Getting-Started-Git-Basics)
### New to Markdown?
- [Markdown Guide](https://www.markdownguide.org/basic-syntax/)
---
## Code of Conduct
- Be respectful and inclusive
- Welcome newcomers
- Focus on constructive feedback
- **No harmful content**: See `docs/SECURITY_GUARDRAILS.md`.
---
**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!

166
FAQ.md
View File

@@ -1,90 +1,178 @@
# ❓ Frequently Asked Questions (V3) # ❓ Frequently Asked Questions (FAQ)
**Got questions?** Here are answers to the most common questions about Antigravity Awesome Skills. **Got questions?** You're not alone! Here are answers to the most common questions about Antigravity Awesome Skills.
--- ---
## 🔒 Security & Trust (V3) ## 🎯 General Questions
### Q: What do the Risk Labels mean? ### What are "skills" exactly?
In V3, we classify skills so you know what you're running: Skills are specialized instruction files that teach AI assistants how to handle specific tasks. Think of them as expert knowledge modules that your AI can load on-demand.
**Simple analogy:** Just like you might consult different experts (a lawyer, a doctor, a mechanic), these skills let your AI become an expert in different areas when you need them.
- ⚪ **Safe (White/Blue)**: Read-only, planning, or benign skills. Safe to run anywhere. ### Do I need to install all 250+ skills?
- 🔴 **Risk (Red)**: Skills that modify files, delete resources, or perform security scans. **Use with caution.**
**No!** When you clone the repository, all skills are available, but your AI only loads them when you explicitly invoke them with `@skill-name`.
It's like having a library - all books are there, but you only read the ones you need.
**Pro Tip:** Use [Starter Packs](docs/BUNDLES.md) to install only what matches your role.
### Which AI tools work with these skills?
- ✅ **Claude Code** (Anthropic CLI)
- ✅ **Gemini CLI** (Google)
- ✅ **Codex CLI** (OpenAI)
- ✅ **Cursor** (AI IDE)
- ✅ **Antigravity IDE**
- ✅ **OpenCode**
- ⚠️ **GitHub Copilot** (partial support via copy-paste)
### Are these skills free to use?
**Yes!** This repository is licensed under MIT License.
- ✅ Free for personal use
- ✅ Free for commercial use
- ✅ You can modify 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.
---
## 🔒 Security & Trust (V3 Update)
### What do the Risk Labels mean?
We classify skills so you know what you're running:
- ⚪ **Safe (White/Blue)**: Read-only, planning, or benign skills.
- 🔴 **Risk (Red)**: Skills that modify files (delete), use network scanners, or perform destructive actions. **Use with caution.**
- 🟣 **Official (Purple)**: Maintained by trusted vendors (Anthropic, DeepMind, etc.). - 🟣 **Official (Purple)**: Maintained by trusted vendors (Anthropic, DeepMind, etc.).
### Q: Can these skills hack my computer? ### Can these skills hack my computer?
**No.** Skills are just text files (markdown instructions). However, they _instruct_ the AI to run commands. **No.** Skills are text files. However, they _instruct_ the AI to run commands. If a skill says "delete all files", a compliant AI might try to do it.
If a skill says "delete all files", your AI might try to do it. _Always check the Risk label and review the code._
_Always review the code before creating a skill, and check the Risk label._
--- ---
## 📦 Installation & Setup ## 📦 Installation & Setup
### Q: Do I need to install all 250+ skills? ### Where should I install the 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`. The universal path that works with most tools is `.agent/skills/`:
It's like having a library - all the books are there, but you only read the ones you need.
_Pro Tip: Use [Starter Packs](docs/BUNDLES.md) to install only what matches your role._
### Q: Where should I install the skills?
The universal path is `.agent/skills/`:
```bash ```bash
git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
``` ```
### Q: Does this work with Windows? **Tool-specific paths:**
- Claude Code: `.claude/skills/`
- Gemini CLI: `.gemini/skills/`
- Cursor: `.cursor/skills/` or project root
### Does this work with Windows?
**Yes**, but some "Official" skills use **symlinks** which Windows handles poorly by default. **Yes**, but some "Official" skills use **symlinks** which Windows handles poorly by default.
Run git with: Run git with:
`git clone -c core.symlinks=true ...`
```bash
git clone -c core.symlinks=true https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
```
Or enable "Developer Mode" in Windows Settings. Or enable "Developer Mode" in Windows Settings.
### How do I update skills?
Navigate to your skills directory and pull the latest changes:
```bash
cd .agent/skills
git pull origin main
```
--- ---
## 🛠️ Usage & Troubleshooting ## 🛠️ Using Skills
### Q: How do I invoke a skill? ### How do I invoke a skill?
In your AI chat (Claude, Cursor, etc.), just use the `@` mention: Use the `@` symbol followed by the skill name:
``` ```
@brainstorming help me design a todo app @brainstorming help me design a todo app
``` ```
### Q: My AI assistant doesn't recognize skills. Why? ### Can I use multiple skills at once?
1. **Wrong Path**: Did you clone to `.agent/skills/`? Check your tool's settings. **Yes!** You can invoke multiple skills:
2. **Restart Needed**: Some tools (like Cursor) need a restart to index new files.
3. **Typos**: Check `ls .agent/skills/` to see the exact folder name.
### Q: What if a skill gives bad code? ```
@brainstorming help me design this, then use @writing-plans to create a task list.
```
Please [Open an Issue](https://github.com/sickn33/antigravity-awesome-skills/issues)! ### How do I know which skill to use?
Describe what happened and which skill was responsible. We update skills regularly to fix hallucinations.
1. **Browse the README**: Check the [Full Skill Registry](README.md#full-skill-registry-253253).
2. **Search**: `ls skills/ | grep "keyword"`
3. **Ask your AI**: "What skills do you have for testing?"
---
## 🏗️ Troubleshooting
### My AI assistant doesn't recognize skills
**Possible causes:**
1. **Wrong installation path**: Check your tool's docs. Try `.agent/skills/`.
2. **Restart Needed**: Restart your AI/IDE after installing.
3. **Typos**: Did you type `@brain-storming` instead of `@brainstorming`?
### A skill gives incorrect or outdated advice
Please [Open an issue](https://github.com/sickn33/antigravity-awesome-skills/issues)!
Include:
- Which skill
- What went wrong
- What should happen instead
--- ---
## 🤝 Contribution ## 🤝 Contribution
### Q: My PR failed "Quality Bar" check. Why? ### I'm new to open source. Can I contribute?
**Absolutely!** We welcome beginners.
- Fix typos
- Add examples
- Improve docs
Check out [CONTRIBUTING.md](CONTRIBUTING.md) for instructions.
### My PR failed "Quality Bar" check. Why?
V3 introduces automated quality control. Your skill might be missing: V3 introduces automated quality control. Your skill might be missing:
1. A valid `description` in the metadata. 1. A valid `description`.
2. Usage examples. 2. Usage examples.
Or it might be triggering a security filter. Run `python3 scripts/validate_skills.py` locally to see the error. Run `python3 scripts/validate_skills.py` locally to check before you push.
### Q: Can I update an "Official" skill? ### Can I update an "Official" skill?
**No.** Official skills (in `skills/official/`) are mirrored from vendors. **No.** Official skills (in `skills/official/`) are mirrored from vendors. Open an issue instead.
Open an issue instead, and we will forward it to the maintainers.
### Q: Can I make my own skills? ---
**Absolutely!** Check out the **@skill-creator** skill or read [CONTRIBUTING.md](CONTRIBUTING.md). ## 💡 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
**Still confused?** [Open a discussion](https://github.com/sickn33/antigravity-awesome-skills/discussions) and we'll help you out! 🙌