From e242186fe20ec79de8c7d83d7177ac019db2a344 Mon Sep 17 00:00:00 2001 From: sck_0 Date: Sun, 25 Jan 2026 20:17:00 +0100 Subject: [PATCH] docs: restore VERY detailed documentation while keeping V3 updates [skip ci] --- CONTRIBUTING.md | 212 ++++++++++++++++++++++++++++++++++++------------ FAQ.md | 166 ++++++++++++++++++++++++++++--------- 2 files changed, 287 insertions(+), 91 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 017445cf..6e1fe367 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,7 @@ # 🤝 Contributing Guide - V3 Enterprise Edition -**Thank you for wanting to help!** This repository is built by the community, for the community. -With V3, we raised the bar for quality. This guide covers everything from your first Pull Request to our new Quality Standards. +**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. 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: -### 1. Improve Documentation +### 1. Improve Documentation (Easiest!) - Fix typos or grammar +- Make explanations clearer - 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 - 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 -git clone https://github.com/YOUR-USERNAME/antigravity-awesome-skills.git -cd antigravity-awesome-skills +# Navigate to 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`. - -```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: +Every skill needs this basic structure. **Copy this template:** ```markdown --- -name: my-new-skill -description: One line description of what this does. +name: my-awesome-skill +description: "Brief one-line description of what this skill does" --- -# My New Skill +# Skill Title ## 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.** @@ -96,33 +124,113 @@ python3 scripts/validate_skills.py python3 scripts/validate_skills.py --strict ``` -### Step 5: Test & Submit +This checks: -1. Copy it to your local agent folder (`.agent/skills/`). -2. Test it with your AI. -3. Push and open a Pull Request! +- ✅ `SKILL.md` exists +- ✅ Frontmatter is correct +- ✅ 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...". -- **Use Examples**: The AI learns best from examples. -- **Keep it Atomic**: One skill, one job. Don't make "god skills". +Save time! Copy this template: + +```markdown +--- +name: your-skill-name +description: "One sentence describing what this skill does and when to use it" +--- + +# Your Skill Name + +## Overview + +[2-3 sentences explaining what this skill does] + +## When to Use This Skill + +- Use when you need to [scenario 1] +- Use when you want to [scenario 2] + +## 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). -**Rule #1**: Be kind. -**Rule #2**: No malware/harmful skills. (See `docs/SECURITY_GUARDRAILS.md`). +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 +``` --- -## 📦 Submission Checklist +## Learning Resources -- [ ] Folder name is `kebab-case` -- [ ] `SKILL.md` exists -- [ ] `scripts/validate_skills.py` passes -- [ ] You tested it in an actual AI session +### 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/) + +--- + +## 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! diff --git a/FAQ.md b/FAQ.md index 412706d4..8ff197f9 100644 --- a/FAQ.md +++ b/FAQ.md @@ -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. -- 🔴 **Risk (Red)**: Skills that modify files, delete resources, or perform security scans. **Use with caution.** +### Do I need to install all 250+ 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`. +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.). -### 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. -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._ +**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. +_Always check the Risk label and review the code._ --- ## 📦 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`. -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/`: +The universal path that works with most tools is `.agent/skills/`: ```bash 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. 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. +### 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 ``` -### 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. -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. +**Yes!** You can invoke multiple skills: -### 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)! -Describe what happened and which skill was responsible. We update skills regularly to fix hallucinations. +### How do I know which skill to use? + +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 -### 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: -1. A valid `description` in the metadata. +1. A valid `description`. 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. -Open an issue instead, and we will forward it to the maintainers. +**No.** Official skills (in `skills/official/`) are mirrored from vendors. Open an issue instead. -### 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! 🙌