PR Review Process for Contributing New Skills to Antigravity Awesome Skills

The typical PR review process for contributing new skills to the antigravity-awesome-skills repository involves a 10-step workflow that combines local validation scripts, automated CI checks via GitHub Actions, and mandatory human review before merging into the main branch.

Contributing a new skill to the sickn33/antigravity-awesome-skills repository requires following a structured quality assurance pipeline. This process ensures that every skill meets strict schema requirements, maintains catalog consistency, and passes security audits before reaching end users. The workflow is fully automated by CI scripts and documented in the repository's contribution guides, balancing automation with human oversight.

Pre-Submission: Local Development and Validation

Before opening a pull request, contributors must complete several local preparation steps that validate the skill's structure and metadata.

Forking and Branch Strategy

Start by forking the repository and creating a descriptive feature branch. Use a naming convention like add-my-awesome-skill to clearly indicate the contribution's purpose. This branch will contain all changes related to your new skill submission.

Skill File Structure and Templates

Place the new skill files under the skills/ directory (or appropriate subdirectory) following the strict template defined in docs_zh-CN/contributors/skill-template.md. Each skill requires:

• A <skill-name>.json file containing the skill definition
• Optional asset files as needed
• Required front-matter (---\napplyTo: '**'\n---) enforced by helper scripts

The JSON schema requires specific fields including name, description, author, version, tags, and commands. Here is a minimal valid example:

{
  "name": "my-awesome-skill",
  "description": "A brief description of what the skill does.",
  "author": "Your Name",
  "version": "1.0.0",
  "tags": ["productivity", "automation"],
  "commands": [
    {
      "trigger": "my-skill",
      "script": "node index.js"
    }
  ]
}

Running Local Validation Scripts

Execute the validation suite locally before opening a PR to catch errors early. The tools/scripts/validate_skills.py script checks JSON schema compliance, required fields, and link integrity, while tools/scripts/validate_references.py verifies cross-references:

python tools/scripts/validate_skills.py
python tools/scripts/validate_references.py

Additionally, run tools/scripts/generate_index.py to ensure your skill properly appears in skills_index.json and the catalog. These scripts enforce the required front-matter and update metadata automatically.

The Pull Request Workflow

Once local validation passes, contributors initiate the formal review process through GitHub's PR mechanism.

Opening the Pull Request

Push your feature branch to your fork and create a pull request against the main branch. The repository uses the template defined in .github/PULL_REQUEST_TEMPLATE.md, which prompts for:

• A short description of the skill's functionality
• Screenshots or visual examples
• Verification steps for reviewers

Use clear commit messages following conventional commit standards, such as:

git checkout -b add-my-awesome-skill
git add skills/my-awesome-skill.json
git commit -m "feat: add my-awesome-skill"
git push origin add-my-awesome-skill

Automated CI Checks

Upon PR creation, GitHub Actions immediately triggers the Skill Review workflow defined in .github/workflows/skill-review.yml. This workflow runs in a sandboxed environment and executes:

• Linting checks for code quality
• Validation scripts (validate_skills.py and validate_references.py)
• Catalog generation via generate_index.py
• Dependency audits for security vulnerabilities

These automated checks prevent malformed skills from entering the catalog and ensure no malicious code is introduced.

Human Review and Quality Assurance

After automated checks pass, human maintainers examine the contribution for semantic correctness and policy compliance.

Maintainer Review Criteria

Reviewers evaluate submissions based on criteria documented in docs_zh-CN/maintainers/audit.md. The human review focuses on:

• Correctness: Accuracy of skill descriptions and working examples
• License compliance: Verification that all assets and code meet licensing requirements
• Catalog compatibility: Ensuring the skill integrates properly with existing entries without conflicts

Addressing Feedback and Iteration

If CI scripts or maintainers identify issues, amend your PR by fixing JSON schema violations, adding missing screenshots, or correcting metadata. Push new commits to the same branch; the Skill Review workflow re-runs automatically with each update. This iterative process continues until all validation checks pass and at least one maintainer approves the changes.

Merge and Release Cycle

Once approved, the contribution enters the final deployment pipeline.

When all checks pass and a maintainer provides approval, the PR merges into main. This merge triggers the Release Cycle workflow (.github/workflows/release-cycle.sh), which:

1. Publishes the updated skill set to NPM
2. Updates the public data/catalog.json
3. Regenerates documentation in README.md and GETTING_STARTED.md

The new skill becomes immediately available to end users, with the catalog.json and documentation updated automatically by the release scripts.

Summary

• Local validation is mandatory: Run tools/scripts/validate_skills.py and validate_references.py before submitting to ensure JSON schema compliance.
• Automated CI enforces quality: The .github/workflows/skill-review.yml workflow handles linting, validation, and security audits automatically upon PR creation.
• Human review checks semantics: Maintainers verify correctness, licensing, and catalog compatibility according to docs_zh-CN/maintainers/audit.md.
• Release is fully automated: Merging triggers .github/workflows/release-cycle.sh to update NPM, data/catalog.json, and public documentation immediately.

Frequently Asked Questions

What files must I modify when adding a new skill?

You must create a JSON file under skills/ following the template in docs_zh-CN/contributors/skill-template.md, then run tools/scripts/generate_index.py to update skills_index.json. The validation scripts in tools/scripts/validate_skills.py will verify your changes against the required schema.

How do I run the CI checks locally before opening a PR?

Execute python tools/scripts/validate_skills.py and python tools/scripts/validate_references.py to check JSON schema and links. For the full GitHub Actions workflow locally, install act and run act -j skill-review after installing dependencies with npm ci.

What happens if my PR fails the automated checks?

If the Skill Review workflow in .github/workflows/skill-review.yml detects issues, the PR status checks will fail and block merging. Fix the reported errors—such as JSON schema violations or broken references—commit the changes to your branch, and push again; the checks will re-run automatically.

Who reviews my skill contribution after the CI passes?

Human maintainers conduct the final review according to docs_zh-CN/maintainers/audit.md, examining semantic correctness, license compliance, and catalog integration. At least one maintainer approval is required before the merge can proceed, even if all automated checks pass.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}