# 🤝 Contributing Guide - Make It Easy for Everyone! **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. --- ## Quick Start for Contributors ```bash # 1. Fork and clone git clone https://github.com/YOUR-USERNAME/antigravity-awesome-skills.git cd antigravity-awesome-skills # 2. Install dependencies npm install # 3. Create your skill mkdir -p skills/my-awesome-skill # 4. Use the canonical template cp docs/contributors/skill-template.md skills/my-awesome-skill/SKILL.md # 5. Edit and validate npm run validate # 6. Open a PR git add skills/my-awesome-skill/ git commit -m "feat: add my-awesome-skill for [purpose]" git push origin my-branch ``` If you only want to improve docs, editing directly in GitHub is still perfectly fine. --- ## Ways to Contribute You don't need to be an expert! Here are ways anyone can help: ### 1. Improve Documentation (Easiest!) - Fix typos or grammar - Make explanations clearer - Add examples to existing skills - Translate documentation to other languages ### 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 ### 4. Test and Validate - Try skills and report what works/doesn't work - Test on different AI tools - Suggest improvements --- ## How to Improve Documentation ### Super Easy Method (No Git Knowledge Needed!) 1. **Find the file** you want to improve on GitHub 2. **Click the pencil icon** (✏️) to edit 3. **Make your changes** in the browser 4. **Click "Propose changes"** at the bottom 5. **Done!** We'll review and merge it ### Using Git (If You Know How) ```bash # 1. Fork the repo on GitHub (click the Fork button) # 2. Clone your fork git clone https://github.com/YOUR-USERNAME/antigravity-awesome-skills.git cd antigravity-awesome-skills # 3. Create a branch git checkout -b improve-docs # 4. Make your changes # Edit files in your favorite editor # 5. Commit and push git add . git commit -m "docs: make XYZ clearer" git push origin improve-docs # 6. Open a Pull Request on GitHub ``` --- ## How to Create a New Skill ### What Makes a Good Skill? A skill should: - ✅ Solve a specific problem - ✅ Be reusable across projects - ✅ Have clear instructions - ✅ Include examples when possible ### Step-by-Step: Create Your First Skill #### Step 1: Choose Your Skill Topic Ask yourself: - What am I good at? - What do I wish my AI assistant knew better? - What task do I do repeatedly? **Examples:** - "I'm good at Docker, let me create a Docker skill" - "I wish AI understood Tailwind better" - "I keep setting up the same testing patterns" #### Step 2: Create the Folder Structure ```bash # Navigate to the skills directory cd skills/ # Create your skill folder (use lowercase with hyphens) mkdir my-awesome-skill # Create the SKILL.md file cd my-awesome-skill touch SKILL.md ``` #### Step 3: Write Your SKILL.md Every skill should start from the canonical template in [`docs/contributors/skill-template.md`](docs/contributors/skill-template.md). Minimum frontmatter: ```markdown --- name: my-awesome-skill description: "Brief one-line description of what this skill does" risk: safe source: community date_added: "2026-03-06" --- # Skill Title ## Overview Explain what this skill does and when to use it. ## When to Use This Skill - Use when [scenario 1] - Use when [scenario 2] - Use when [scenario 3] ## How It Works ### Step 1: [First Step] Explain what to do first... ### Step 2: [Second Step] Explain the next step... ### Step 3: [Final Step] Explain how to finish... ## Examples ### Example 1: [Common Use Case] \`\`\` Show example code or commands here \`\`\` ### Example 2: [Another Use Case] \`\`\` More examples... \`\`\` ## Best Practices - ✅ Do this - ✅ Also do this - ❌ Don't do this - ❌ Avoid this ## Common Pitfalls - **Problem:** Description of common issue **Solution:** How to fix it ## Additional Resources - [Link to documentation](https://example.com) - [Tutorial](https://example.com) ``` #### Step 4: Test Your Skill 1. **Copy it to your AI tool's skills directory:** ```bash cp -r skills/my-awesome-skill ~/.agent/skills/ ``` 2. **Try using it:** ``` @my-awesome-skill help me with [task] ``` 3. **Does it work?** Great! If not, refine it. #### Step 5: Validate Your Skill Recommended validation path: ```bash npm install npm run validate npm run validate:references npm test ``` Python-only fallback: ```bash python3 tools/scripts/validate_skills.py ``` This checks: - ✅ SKILL.md exists - ✅ Frontmatter is correct - ✅ Name matches folder name - ✅ Description exists - ✅ Reference data and docs bundles stay coherent Optional hardening pass: ```bash npm run validate:strict ``` `validate:strict` is useful before larger cleanup PRs, but the repository still contains legacy skills that do not all satisfy the strict quality bar. #### Step 6: Submit Your Skill ```bash # 1. Add your skill git add skills/my-awesome-skill/ # 2. Commit with a clear message git commit -m "feat: add my-awesome-skill for [purpose]" # 3. Push to your fork git push origin my-branch # 4. Open a Pull Request on GitHub ``` --- ## Skill Template (Copy & Paste) The canonical template now lives at [`docs/contributors/skill-template.md`](docs/contributors/skill-template.md). You can still use the inline version below as a starting point: ```markdown --- name: your-skill-name description: "One sentence describing what this skill does and when to use it" risk: safe source: community date_added: "2026-03-06" --- # 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] - Use when working with [scenario 3] ## Core Concepts ### Concept 1 [Explain key concept] ### Concept 2 [Explain another key concept] ## Step-by-Step Guide ### 1. [First Step Name] [Detailed instructions] ### 2. [Second Step Name] [Detailed instructions] ### 3. [Third Step Name] [Detailed instructions] ## Examples ### Example 1: [Use Case Name] \`\`\`language // Example code here \`\`\` **Explanation:** [What this example demonstrates] ### Example 2: [Another Use Case] \`\`\`language // More example code \`\`\` **Explanation:** [What this example demonstrates] ## Best Practices - ✅ **Do:** [Good practice] - ✅ **Do:** [Another good practice] - ❌ **Don't:** [What to avoid] - ❌ **Don't:** [Another thing to avoid] ## Troubleshooting ### Problem: [Common Issue] **Symptoms:** [How you know this is the problem] **Solution:** [How to fix it] ### Problem: [Another Issue] **Symptoms:** [How you know this is the problem] **Solution:** [How to fix it] ## Related Skills - `@related-skill-1` - [When to use this instead] - `@related-skill-2` - [How this complements your skill] ## Additional Resources - [Official Documentation](https://example.com) - [Tutorial](https://example.com) - [Community Guide](https://example.com) ``` --- ## How to Report Issues ### Found a Bug? 1. **Check existing issues** - Maybe it's already reported 2. **Open a new issue** with this info: - What skill has the problem? - What AI tool are you using? - What did you expect to happen? - What actually happened? - Steps to reproduce ### Found Something Confusing? 1. **Open an issue** titled: "Documentation unclear: [topic]" 2. **Explain:** - What part is confusing? - What did you expect to find? - How could it be clearer? --- ## Contribution Checklist Before submitting your contribution: - [ ] My skill has a clear, descriptive name - [ ] The `SKILL.md` has proper frontmatter (`name`, `description`, `risk`, `source`, `date_added`) - [ ] I've included examples - [ ] I've tested the skill with an AI assistant - [ ] I've run `npm run validate` - [ ] I've run `npm run validate:references` and `npm test` when my change affects docs, bundles, workflows, or generated artifacts - [ ] My commit message is clear (e.g., "feat: add docker-compose skill") - [ ] I've checked for typos and grammar --- ## Commit Message Guidelines 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 docs: add examples to react-best-practices ``` --- ## Learning Resources ### 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/) - [GitHub Markdown](https://guides.github.com/features/mastering-markdown/) ### New to Open Source? - [First Contributions](https://github.com/firstcontributions/first-contributions) - [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/) --- ## Need Help? - **Questions?** Open a [Discussion](https://github.com/sickn33/antigravity-awesome-skills/discussions) - **Stuck?** Open an [Issue](https://github.com/sickn33/antigravity-awesome-skills/issues) - **Want feedback?** Open a [Draft Pull Request](https://github.com/sickn33/antigravity-awesome-skills/pulls) --- ## Recognition All contributors are recognized in our [Contributors](https://github.com/sickn33/antigravity-awesome-skills/graphs/contributors) page! --- ## Code of Conduct - Be respectful and inclusive - Welcome newcomers - Focus on constructive feedback - Help others learn --- **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!