docs: Add comprehensive beginner-friendly documentation (#7)
* Add files via upload * Standardize section headers in CONTRIBUTING.md * Remove emojis from GETTING_STARTED.md headings * Update section headings in FAQ.md * Remove emojis from example section headers * Remove emoji from SKILL_ANATOMY.md headings * Remove emojis from Visual Quick Start Guide
This commit is contained in:
Mohammad Faiz
401
CONTRIBUTING.md
Normal file
401
CONTRIBUTING.md
Normal file
@@ -0,0 +1,401 @@
|
||||
# 🤝 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!
|
||||
Reference in New Issue
Block a user