firefrost-gaming/antigravity-skills-reference

Files

sck_0 45844de534 refactor: reorganize repo docs and tooling layout

Consolidate the repository into clearer apps, tools, and layered docs areas so contributors can navigate and maintain it more reliably. Align validation, metadata sync, and CI around the same canonical workflow to reduce drift across local checks and GitHub Actions.

2026-03-06 15:01:38 +01:00

10 KiB

Raw Blame History

🤝 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

# 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!)

Find the file you want to improve on GitHub
Click the pencil icon (✏️) to edit
Make your changes in the browser
Click "Propose changes" at the bottom
Done! We'll review and merge it

Using Git (If You Know How)

# 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

# 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.

Minimum frontmatter:

---
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

Copy it to your AI tool's skills directory:

cp -r skills/my-awesome-skill ~/.agent/skills/

Try using it:
```
@my-awesome-skill help me with [task]
```
Does it work? Great! If not, refine it.

Step 5: Validate Your Skill

Recommended validation path:

npm install
npm run validate
npm run validate:references
npm test

Python-only fallback:

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:

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

# 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. You can still use the inline version below as a starting point:

---
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?

Check existing issues - Maybe it's already reported
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?

Open an issue titled: "Documentation unclear: [topic]"
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