docs: update visual guide and skill anatomy for V3 specs [skip ci]

docs/SKILL_ANATOMY.md

@@ -31,6 +31,7 @@ skills/
 Every `SKILL.md` file has two main parts:
 
 ### 1. Frontmatter (Metadata)
+
 ### 2. Content (Instructions)
 
 Let's break down each part:
@@ -51,12 +52,14 @@ description: "Brief description of what this skill does"
 ### Required Fields
 
 #### `name`
+
 - **What it is:** The skill's identifier
 - **Format:** lowercase-with-hyphens
 - **Must match:** The folder name exactly
 - **Example:** `stripe-integration`
 
 #### `description`
+
 - **What it is:** One-sentence summary
 - **Format:** String in quotes
 - **Length:** Keep it under 150 characters
@@ -70,9 +73,9 @@ Some skills include additional metadata:
 ---
 name: my-skill-name
 description: "Brief description"
-version: "1.0.0"
+risk: "safe" # safe | risk | official
-author: "Your Name"
+source: "community"
-tags: ["react", "typescript", "testing"]
+tags: ["react", "typescript"]
 ---
 ```
 
@@ -85,13 +88,16 @@ After the frontmatter comes the actual skill content. Here's the recommended str
 ### Recommended Sections
 
 #### 1. Title (H1)
+
 ```markdown
 # Skill Title
 ```
+
 - Use a clear, descriptive title
 - Usually matches or expands on the skill name
 
 #### 2. Overview
+
 ```markdown
 ## Overview
 
@@ -100,6 +106,7 @@ A brief explanation of what this skill does and why it exists.
 ```
 
 #### 3. When to Use
+
 ```markdown
 ## When to Use This Skill
 
@@ -111,28 +118,34 @@ A brief explanation of what this skill does and why it exists.
 **Why this matters:** Helps the AI know when to activate this skill
 
 #### 4. Core Instructions
+
 ```markdown
 ## How It Works
 
 ### Step 1: [Action]
+
 Detailed instructions...
 
 ### Step 2: [Action]
+
 More instructions...
 ```
 
 **This is the heart of your skill** - clear, actionable steps
 
 #### 5. Examples
+
 ```markdown
 ## Examples
 
 ### Example 1: [Use Case]
+
 \`\`\`javascript
 // Example code
 \`\`\`
 
 ### Example 2: [Another Use Case]
+
 \`\`\`javascript
 // More code
 \`\`\`
@@ -141,6 +154,7 @@ More instructions...
 **Why examples matter:** They show the AI exactly what good output looks like
 
 #### 6. Best Practices
+
 ```markdown
 ## Best Practices
 
@@ -151,6 +165,7 @@ More instructions...
 ```
 
 #### 7. Common Pitfalls
+
 ```markdown
 ## Common Pitfalls
 
@@ -159,6 +174,7 @@ More instructions...
 ```
 
 #### 8. Related Skills
+
 ```markdown
 ## Related Skills
 
@@ -173,11 +189,13 @@ More instructions...
 ### Use Clear, Direct Language
 
 **❌ Bad:**
+
 ```markdown
 You might want to consider possibly checking if the user has authentication.
 ```
 
 **✅ Good:**
+
 ```markdown
 Check if the user is authenticated before proceeding.
 ```
@@ -185,11 +203,13 @@ Check if the user is authenticated before proceeding.
 ### Use Action Verbs
 
 **❌ Bad:**
+
 ```markdown
 The file should be created...
 ```
 
 **✅ Good:**
+
 ```markdown
 Create the file...
 ```
@@ -197,11 +217,13 @@ Create the file...
 ### Be Specific
 
 **❌ Bad:**
+
 ```markdown
 Set up the database properly.
 ```
 
 **✅ Good:**
+
 ```markdown
 1. Create a PostgreSQL database
 2. Run migrations: `npm run migrate`
@@ -224,6 +246,7 @@ scripts/
 ```
 
 **Reference them in SKILL.md:**
+
 ```markdown
 Run the setup script:
 \`\`\`bash
@@ -256,6 +279,7 @@ templates/
 ```
 
 **Reference in SKILL.md:**
+
 ```markdown
 Use this template as a starting point:
 \`\`\`typescript
@@ -279,16 +303,19 @@ references/
 ## Skill Size Guidelines
 
 ### Minimum Viable Skill
+
 - **Frontmatter:** name + description
 - **Content:** 100-200 words
 - **Sections:** Overview + Instructions
 
 ### Standard Skill
+
 - **Frontmatter:** name + description
 - **Content:** 300-800 words
 - **Sections:** Overview + When to Use + Instructions + Examples
 
 ### Comprehensive Skill
+
 - **Frontmatter:** name + description + optional fields
 - **Content:** 800-2000 words
 - **Sections:** All recommended sections
@@ -303,7 +330,9 @@ references/
 ### Use Markdown Effectively
 
 #### Code Blocks
+
 Always specify the language:
+
 ```markdown
 \`\`\`javascript
 const example = "code";
@@ -311,7 +340,9 @@ const example = "code";
 ```
 
 #### Lists
+
 Use consistent formatting:
+
 ```markdown
 - Item 1
 - Item 2
@@ -320,11 +351,13 @@ Use consistent formatting:
 ```
 
 #### Emphasis
+
 - **Bold** for important terms: `**important**`
-- *Italic* for emphasis: `*emphasis*`
+- _Italic_ for emphasis: `*emphasis*`
 - `Code` for commands/code: `` `code` ``
 
 #### Links
+
 ```markdown
 [Link text](https://example.com)
 ```
@@ -336,24 +369,28 @@ Use consistent formatting:
 Before finalizing your skill:
 
 ### Content Quality
+
 - [ ] Instructions are clear and actionable
 - [ ] Examples are realistic and helpful
 - [ ] No typos or grammar errors
 - [ ] Technical accuracy verified
 
 ### Structure
+
 - [ ] Frontmatter is valid YAML
 - [ ] Name matches folder name
 - [ ] Sections are logically organized
 - [ ] Headings follow hierarchy (H1 → H2 → H3)
 
 ### Completeness
+
 - [ ] Overview explains the "why"
 - [ ] Instructions explain the "how"
 - [ ] Examples show the "what"
 - [ ] Edge cases are addressed
 
 ### Usability
+
 - [ ] A beginner could follow this
 - [ ] An expert would find it useful
 - [ ] The AI can parse it correctly
@@ -373,6 +410,7 @@ description: "You MUST use this before any creative work..."
 ```
 
 **Analysis:**
+
 - ✅ Clear name
 - ✅ Strong description with urgency ("MUST use")
 - ✅ Explains when to use it
@@ -381,10 +419,12 @@ description: "You MUST use this before any creative work..."
 # Brainstorming Ideas Into Designs
 
 ## Overview
+
 Help turn ideas into fully formed designs...
 ```
 
 **Analysis:**
+
 - ✅ Clear title
 - ✅ Concise overview
 - ✅ Explains the value proposition
@@ -393,11 +433,13 @@ Help turn ideas into fully formed designs...
 ## The Process
 
 **Understanding the idea:**
+
 - Check out the current project state first
 - Ask questions one at a time
 ```
 
 **Analysis:**
+
 - ✅ Broken into clear phases
 - ✅ Specific, actionable steps
 - ✅ Easy to follow
@@ -412,10 +454,12 @@ Help turn ideas into fully formed designs...
 ## Instructions
 
 If the user is working with React:
+
 - Use functional components
 - Prefer hooks over class components
 
 If the user is working with Vue:
+
 - Use Composition API
 - Follow Vue 3 patterns
 ```
@@ -424,9 +468,11 @@ If the user is working with Vue:
 
 ```markdown
 ## Basic Usage
+
 [Simple instructions for common cases]
 
 ## Advanced Usage
+
 [Complex patterns for power users]
 ```
 
@@ -447,15 +493,18 @@ If the user is working with Vue:
 How to know if your skill is good:
 
 ### Clarity Test
+
 - Can someone unfamiliar with the topic follow it?
 - Are there any ambiguous instructions?
 
 ### Completeness Test
+
 - Does it cover the happy path?
 - Does it handle edge cases?
 - Are error scenarios addressed?
 
 ### Usefulness Test
+
 - Does it solve a real problem?
 - Would you use this yourself?
 - Does it save time or improve quality?
@@ -467,11 +516,13 @@ How to know if your skill is good:
 ### Study These Examples
 
 **For Beginners:**
+
 - `skills/brainstorming/SKILL.md` - Clear structure
 - `skills/git-pushing/SKILL.md` - Simple and focused
 - `skills/copywriting/SKILL.md` - Good examples
 
 **For Advanced:**
+
 - `skills/systematic-debugging/SKILL.md` - Comprehensive
 - `skills/react-best-practices/SKILL.md` - Multiple files
 - `skills/loki-mode/SKILL.md` - Complex workflows
@@ -491,22 +542,28 @@ How to know if your skill is good:
 ## Common Mistakes to Avoid
 
 ### ❌ Mistake 1: Too Vague
+
 ```markdown
 ## Instructions
+
 Make the code better.
 ```
 
 **✅ Fix:**
+
 ```markdown
 ## Instructions
+
 1. Extract repeated logic into functions
 2. Add error handling for edge cases
 3. Write unit tests for core functionality
 ```
 
 ### ❌ Mistake 2: Too Complex
+
 ```markdown
 ## Instructions
+
 [5000 words of dense technical jargon]
 ```
 
@@ -514,8 +571,10 @@ Make the code better.
 Break into multiple skills or use progressive disclosure
 
 ### ❌ Mistake 3: No Examples
+
 ```markdown
 ## Instructions
+
 [Instructions without any code examples]
 ```
 
@@ -523,6 +582,7 @@ Break into multiple skills or use progressive disclosure
 Add at least 2-3 realistic examples
 
 ### ❌ Mistake 4: Outdated Information
+
 ```markdown
 Use React class components...
 ```

docs/VISUAL_GUIDE.md

@@ -32,9 +32,10 @@ antigravity-awesome-skills/
 │
 ├── 📄 README.md                    ← Overview & skill list
 ├── 📄 GETTING_STARTED.md           ← Start here! (NEW)
-├── 📄 CONTRIBUTING.md        ← How to contribute (NEW)
+├── 📄 CONTRIBUTING.md              ← How to contribute
+├── 📄 FAQ.md                       ← Troubleshooting
 │
-├── 📁 skills/                      ← All 179 skills live here
+├── 📁 skills/                      ← All 250+ skills live here
 │   │
 │   ├── 📁 brainstorming/
 │   │   └── 📄 SKILL.md             ← Skill definition
@@ -43,20 +44,20 @@ antigravity-awesome-skills/
 │   │   ├── 📄 SKILL.md
 │   │   └── 📁 examples/            ← Optional extras
 │   │
-│   ├── 📁 react-best-practices/
+│   └── ... (250+ more skills)
-│   │   ├── 📄 SKILL.md
-│   │   ├── 📁 rules/
-│   │   └── 📄 README.md
-│   │
-│   └── ... (176 more skills)
 │
 ├── 📁 scripts/                     ← Validation & management
-│   ├── validate_skills.py
+│   ├── validate_skills.py          ← Quality Bar Enforcer
-│   └── generate_index.py
+│   └── generate_index.py           ← Registry Generator
 │
-└── 📁 docs/                        ← Documentation (NEW)
+├── 📁 .github/
+│   └── 📄 MAINTENANCE.md           ← Maintainers Guide
+│
+└── 📁 docs/                        ← Documentation
+    ├── 📄 BUNDLES.md               ← Starter Packs (NEW)
+    ├── 📄 QUALITY_BAR.md           ← Quality Standards
     ├── 📄 SKILL_ANATOMY.md         ← How skills work
-    └── 📄 VISUAL_GUIDE.md    ← This file!
+    └── 📄 VISUAL_GUIDE.md          ← This file!
 ```
 
 ---
@@ -95,7 +96,7 @@ antigravity-awesome-skills/
 
 ```
                     ┌─────────────────────────┐
-                    │  179 AWESOME SKILLS     │
+                    │   250+ AWESOME SKILLS   │
                     └────────────┬────────────┘
                                  │
         ┌────────────────────────┼────────────────────────┐
@@ -129,7 +130,7 @@ antigravity-awesome-skills/
 
 ## Skill File Anatomy (Visual)
 
-```
+````
 ┌─────────────────────────────────────────────────────────┐
 │ SKILL.md                                                │
 ├─────────────────────────────────────────────────────────┤
@@ -167,13 +168,14 @@ antigravity-awesome-skills/
 │  └───────────────────────────────────────────────┘     │
 │                                                         │
 └─────────────────────────────────────────────────────────┘
-```
+````
 
 ---
 
 ## Installation (Visual Steps)
 
 ### Step 1: Clone the Repository
+
 ```
 ┌─────────────────────────────────────────┐
 │ Terminal                                │
@@ -188,6 +190,7 @@ antigravity-awesome-skills/
 ```
 
 ### Step 2: Verify Installation
+
 ```
 ┌─────────────────────────────────────────┐
 │ File Explorer                           │
@@ -202,6 +205,7 @@ antigravity-awesome-skills/
 ```
 
 ### Step 3: Use a Skill
+
 ```
 ┌─────────────────────────────────────────┐
 │ AI Assistant Chat                       │
@@ -271,16 +275,19 @@ antigravity-awesome-skills/
 ## Finding Skills (Visual Guide)
 
 ### Method 1: Browse by Category
+
 ```
 README.md → Scroll to "Full Skill Registry" → Find category → Pick skill
 ```
 
 ### Method 2: Search by Keyword
+
 ```
 Terminal → ls skills/ | grep "keyword" → See matching skills
 ```
 
 ### Method 3: Use the Index
+
 ```
 Open skills_index.json → Search for keyword → Find skill path
 ```
@@ -465,19 +472,19 @@ START HERE
 Day 1: Install skills
   │
   └─→ "Wow, @brainstorming helped me design my app!"
-  
+
 Day 3: Use 5 different skills
   │
   └─→ "These skills save me so much time!"
-  
+
 Week 1: Create first skill
   │
   └─→ "I shared my expertise as a skill!"
-  
+
 Week 2: Skill gets merged
   │
   └─→ "My skill is helping others! 🎉"
-  
+
 Month 1: Regular contributor
   │
   └─→ "I've contributed 5 skills and improved docs!"
@@ -497,6 +504,7 @@ Month 1: Regular contributor
 ---
 
 **Visual learner?** This guide should help! Still have questions? Check out:
+
 - [GETTING_STARTED.md](../GETTING_STARTED.md) - Text-based intro
 - [SKILL_ANATOMY.md](SKILL_ANATOMY.md) - Detailed breakdown
 - [CONTRIBUTING.md](../CONTRIBUTING.md) - How to contribute