Contribution Guide

Contribution Guide

We're thrilled you're considering contributing to Antigravity Awesome Skills! This project thrives on community contributions, expanding our catalog of agentic skills and improving the platform for everyone. Whether you're adding a new skill, enhancing existing ones, or improving the documentation, your efforts are highly valued.

Ways to Contribute

There are several ways you can make a difference:

• Contribute New Agentic Skills: This is the core of the project. Create powerful SKILL.md playbooks for AI assistants.
• Improve Existing Skills: Refine prompts, add better examples, expand use cases, or fix issues in existing skills.
• Contribute Code: Enhance the Antigravity Awesome Skills platform, the web application, or tooling scripts.
• Improve Documentation: Clarify existing documentation, add guides, or improve explanations.
• Report Bugs & Suggest Features: Help us identify issues or propose new ideas.

Contributing New Agentic Skills

New skills are the lifeblood of Antigravity Awesome Skills. A "skill" typically comprises a SKILL.md playbook and any supporting assets or scripts that make it effective.

Skill Directory Structure

Each skill resides in its own directory, organized by the AI assistant it primarily targets (or a general _common if applicable). For example, a skill named api-design-principles for Claude would follow this structure:

plugins/
└── antigravity-awesome-skills-claude/
    └── skills/
        └── api-design-principles/
            ├── SKILL.md                  <-- The core playbook
            ├── assets/                   <-- Optional: templates, example files, images
            │   └── rest-api-template.py
            └── scripts/                  <-- Optional: helper scripts, validators, APIs
                └── api_validator.py

SKILL.md Playbook Guidelines

The SKILL.md is the heart of your skill. It defines the instructions, context, and expectations for an AI agent.

1. Clear Goal and Purpose: Start with a concise explanation of what the skill achieves and the problem it solves.
2. Inputs and Context: Clearly define what information the AI will receive or needs to understand to execute the skill. This includes expected data formats, project context, or prior steps.
3. Expected Outputs: Specify the desired output format, content, and quality. Be as explicit as possible (e.g., "return JSON," "write a Python class," "provide a diff").
4. Constraints and Best Practices: Detail any limitations, safety measures, or specific methodologies the AI should adhere to. This might include:
   • Language (e.g., "Respond in Python 3.9+").
   • Libraries/Frameworks to use or avoid.
   • Performance considerations.
   • Security guidelines.
5. Concrete Examples: Provide one or more illustrative examples of the skill in action. These examples are crucial for AI assistants to understand the desired behavior. Show both input and ideal output.
6. Guidance for AI: Offer advice to the AI on how to effectively apply the skill, troubleshoot common issues, or adapt to different scenarios.
7. Supported AI Tools: Explicitly state which AI coding assistants the skill is designed for and any specific adaptations for each.
8. Readability: Write SKILL.md files in clear, concise language using Markdown. Use headings, lists, and code blocks effectively.

Supporting Assets and Scripts

If your skill requires specific files (like code templates, configuration examples, or diagram images) or helper scripts (for validation, data processing, local API servers, or benchmarking), include them in the assets/ and scripts/ subdirectories. Ensure these supporting files are well-commented and easy to understand.

• assets/: Use this for static files that serve as input or examples for the skill (e.g., rest-api-template.py).
• scripts/: Use this for executable code that extends the skill's capabilities or helps validate its output (e.g., api_validator.py, serve_api.py). If these scripts have dependencies, ensure they are documented or managed via requirements.txt or package.json within the skill's directory if it becomes a standalone tool.

Skill Quality Standards

• Effectiveness: Does the skill genuinely help AI agents perform tasks better and more reliably?
• Clarity: Is the SKILL.md easy for both humans and AI to understand?
• Reusability: Is the skill generalizable enough to be useful in various contexts?
• Testability: Can the skill's performance be easily verified? Consider including validation steps in the SKILL.md or a scripts/ folder.
• Completeness: Does it include all necessary context, examples, and constraints?

Skill Naming Conventions

• Use kebab-case for skill directory names (e.g., api-design-principles, claude-monitor).
• Keep names descriptive and concise.

Contributing Code

If you're looking to improve the underlying platform, web application, or shared tooling:

Setting Up Your Development Environment

1. Fork and Clone: Fork the sickn33/antigravity-awesome-skills repository and clone your fork locally.

   git clone https://github.com/YOUR_USERNAME/antigravity-awesome-skills.git
   cd antigravity-awesome-skills
   

2. Install Dependencies: The project may involve Node.js for the web app and Python for plugins/scripts.
   • For Node.js projects (e.g., apps/web-app):

     npm install
     

   • For Python scripts within skills: Install dependencies mentioned in any requirements.txt or explicitly listed in the script (e.g., pip install fastapi uvicorn psutil).
3. Run Locally: Follow specific README.md instructions for the part of the project you are working on (e.g., npm run dev for the web app, python scripts/serve_api.py for a skill's API).

Coding Standards and Practices

• Maintain Consistency: Adhere to the existing coding style and patterns found in the codebase.
• Write Tests: For any new features or bug fixes, include appropriate tests.
• Clear Commits: Write clear, concise commit messages that explain the purpose of your changes.

Contributing Documentation

High-quality documentation is critical for usability. Contributions to documentation include:

• Improving the clarity, accuracy, or completeness of README.md files.
• Adding new guides or tutorials in the docs/ directory.
• Enhancing the instructions and examples within SKILL.md files.

Ensure your documentation is easy to understand, uses appropriate Markdown formatting, and follows the project's friendly tone.

General Contribution Workflow

We follow a standard GitHub Fork-and-Pull Request workflow:

1. Fork the Repository: Create your own fork of sickn33/antigravity-awesome-skills on GitHub.
2. Clone Your Fork: Clone your forked repository to your local machine.

   git clone https://github.com/YOUR_USERNAME/antigravity-awesome-skills.git
   cd antigravity-awesome-skills
   

3. Create a New Branch: Always work on a new branch for your contribution.

   git checkout -b feature/your-awesome-skill
   # or
   git checkout -b fix/issue-description
   

4. Make Your Changes: Implement your new skill, code, or documentation changes.
5. Commit Your Changes: Commit your changes with a descriptive message.

   git add .
   git commit -m "feat: Add new skill for API design principles"
   

6. Push to Your Fork: Push your branch to your forked repository.

   git push origin feature/your-awesome-skill
   

7. Open a Pull Request (PR): Go to the original sickn33/antigravity-awesome-skills repository on GitHub and open a new Pull Request.
   • Provide a Clear Description: Explain what your PR does, why it's needed, and any relevant context.
   • Link Issues: If your PR addresses an existing issue, link to it (e.g., Closes #123).
   • Screenshots/Demos: For new features or visual changes, include screenshots or GIFs.
8. Address Feedback: Be prepared to discuss your changes and address any feedback from maintainers.

Community and Support

If you have questions, need help, or want to discuss ideas before contributing, please feel free to open a GitHub Issue.

Thank you for making Antigravity Awesome Skills even better!