docs: restore detailed guides mixed with V3 updates (reverting aggressive pruning) [skip ci]

CONTRIBUTING.md

@@ -1,13 +1,13 @@
 # 🤝 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. Here is how you can contribute effectively.
+With V3, we raised the bar for quality. This guide covers everything from your first Pull Request to our new Quality Standards.
 
 ---
 
-## 🧐 The "Quality Bar"
+## 🧐 The "Quality Bar" (V3 Standard)
 
-Every skill submitted must pass our **5-Point Quality Check** (see `docs/QUALITY_BAR.md` for details):
+**Critical for new skills:** Every skill submitted must pass our **5-Point Quality Check** (see `docs/QUALITY_BAR.md` for details):
 
 1.  **Metadata**: Correct Frontmatter (`name`, `description`).
 2.  **Safety**: No harmful commands without "Risk" labels.
@@ -17,7 +17,28 @@ Every skill submitted must pass our **5-Point Quality Check** (see `docs/QUALITY
 
 ---
 
-## 🛠️ How to Create a New Skill
+## 🛠️ Ways to Contribute
+
+You don't need to be an expert! Here are ways anyone can help:
+
+### 1. Improve Documentation
+
+- Fix typos or grammar
+- Add examples to existing skills
+- Translate documentation
+
+### 2. Create New Skills
+
+- Share your expertise as a skill
+- Fill gaps in the current collection
+
+### 3. Report Issues
+
+- Found a bug? [Open an issue](https://github.com/sickn33/antigravity-awesome-skills/issues)
+
+---
+
+## 🚀 Step-by-Step: Create Your First Skill
 
 ### Step 1: Fork & Clone
 
@@ -31,13 +52,16 @@ cd antigravity-awesome-skills
 Skills live in `skills/`. Names must be `kebab-case`.
 
 ```bash
+# Good
 mkdir skills/my-new-skill
-touch skills/my-new-skill/SKILL.md
+
+# Bad
+mkdir skills/MyNewSkill
 ```
 
-### Step 3: Write the Content
+### Step 3: Write the Content (`SKILL.md`)
 
-Copy this template to start:
+Every skill needs this basic structure. Copy this template:
 
 ```markdown
 ---
@@ -54,6 +78,10 @@ What problem does this solve?
 ## Usage Examples
 
 > "@my-new-skill help me..."
+
+## Core Instructions
+
+[Detailed instructions for the AI]
 ```
 
 ### Step 4: Validate (CRITICAL)
@@ -68,15 +96,19 @@ python3 scripts/validate_skills.py
 python3 scripts/validate_skills.py --strict
 ```
 
----
-
-## 🧪 Testing Your Skill
-
-Don't just write it—run it!
+### Step 5: Test & Submit
 
 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.
+2.  Test it with your AI.
+3.  Push and open a Pull Request!
+
+---
+
+## 💡 Best Practices for V3
+
+- **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".
 
 ---
 

FAQ.md

@@ -1,11 +1,15 @@
 # ❓ Frequently Asked Questions (V3)
 
+**Got questions?** Here are answers to the most common questions about Antigravity Awesome Skills.
+
 ---
 
-## 🔒 Security & Trust
+## 🔒 Security & Trust (V3)
 
 ### Q: What do the Risk Labels mean?
 
+In V3, we classify skills so you know what you're running:
+
 - ⚪ **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.).
@@ -18,12 +22,21 @@ _Always review the code before creating a skill, and check the Risk label._
 
 ---
 
-## 📦 Installation & Usage
+## 📦 Installation & Setup
 
-### Q: Why shouldn't I just copy all files?
+### Q: Do I need to install all 250+ skills?
 
-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.
+**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/`:
+
+```bash
+git clone https://github.com/sickn33/antigravity-awesome-skills.git .agent/skills
+```
 
 ### Q: Does this work with Windows?
 
@@ -34,7 +47,30 @@ Or enable "Developer Mode" in Windows Settings.
 
 ---
 
-## 🛠️ Contribution
+## 🛠️ Usage & Troubleshooting
+
+### Q: How do I invoke a skill?
+
+In your AI chat (Claude, Cursor, etc.), just use the `@` mention:
+
+```
+@brainstorming help me design a todo app
+```
+
+### Q: My AI assistant doesn't recognize skills. Why?
+
+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.
+
+### Q: What if a skill gives bad code?
+
+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.
+
+---
+
+## 🤝 Contribution
 
 ### Q: My PR failed "Quality Bar" check. Why?
 
@@ -48,3 +84,7 @@ V3 introduces automated quality control. Your skill might be missing:
 
 **No.** Official skills (in `skills/official/`) are mirrored from vendors.
 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).