diff --git a/docs/SKILL_ANATOMY.md b/docs/SKILL_ANATOMY.md index a851d7ac..d61b16a5 100644 --- a/docs/SKILL_ANATOMY.md +++ b/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" -author: "Your Name" -tags: ["react", "typescript", "testing"] +risk: "safe" # safe | risk | official +source: "community" +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... ``` diff --git a/docs/VISUAL_GUIDE.md b/docs/VISUAL_GUIDE.md index b17ddd14..0957a715 100644 --- a/docs/VISUAL_GUIDE.md +++ b/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/ -│ │ ├── 📄 SKILL.md -│ │ ├── 📁 rules/ -│ │ └── 📄 README.md -│ │ -│ └── ... (176 more skills) +│ └── ... (250+ more skills) │ ├── 📁 scripts/ ← Validation & management -│ ├── validate_skills.py -│ └── generate_index.py +│ ├── validate_skills.py ← Quality Bar Enforcer +│ └── 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