402 lines
8.5 KiB
Markdown
402 lines
8.5 KiB
Markdown
# 🤝 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.
|
|
|
|
---
|
|
|
|
## 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 needs this basic structure:
|
|
|
|
```markdown
|
|
---
|
|
name: my-awesome-skill
|
|
description: "Brief one-line description of what this skill does"
|
|
---
|
|
|
|
# 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
|
|
|
|
Run the validation script:
|
|
|
|
```bash
|
|
python3 scripts/validate_skills.py
|
|
```
|
|
|
|
This checks:
|
|
- ✅ SKILL.md exists
|
|
- ✅ Frontmatter is correct
|
|
- ✅ Name matches folder name
|
|
- ✅ Description exists
|
|
|
|
#### 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)
|
|
|
|
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]
|
|
- 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)
|
|
- [ ] I've included examples
|
|
- [ ] I've tested the skill with an AI assistant
|
|
- [ ] I've run `python3 scripts/validate_skills.py`
|
|
- [ ] 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!
|