# How to Contribute to the Google Skills Repository: A Complete Guide to Community Contributions

> Learn how to contribute to the google skills project. Discover how to report bugs, request features, or fork the repository for custom skill variants.

- Repository: [Google/skills](https://github.com/google/skills)
- Tags: how-to-guide
- Published: 2026-08-16

---

**The Google Skills repository does not accept external pull requests that modify existing skill definitions, but you can contribute by reporting bugs, requesting new features, or forking the repository to create custom skill variants.**

The Google Skills repository is a curated collection of Agent Skills that provide step-by-step workflows for Google Cloud products and related technologies. While the core maintainers restrict direct modifications to ensure quality control, the project welcomes community feedback and derivative work through specific channels defined in [`CONTRIBUTING.md`](https://github.com/google/skills/blob/main/CONTRIBUTING.md). Understanding the repository’s markdown-based architecture and contribution policies is essential for anyone looking to participate in this ecosystem.

## Understanding the Google Skills Contribution Policy

The project’s governance model is explicitly defined in the root-level [`CONTRIBUTING.md`](https://github.com/google/skills/blob/main/CONTRIBUTING.md) file. According to this policy, the maintainers do **not** accept pull requests from external contributors that modify existing skill definitions. This restriction protects the integrity of the curated workflows and ensures consistency across the Google Cloud documentation ecosystem.

However, the repository actively maintains an open Issues tracker where you can report problems, suggest improvements, and propose new capabilities. This creates a structured feedback loop that allows the community to influence the project without requiring direct write access to the canonical source.

## Reporting Bugs and Inaccuracies

When you encounter typos, outdated CLI commands, or broken examples in any skill file, you should open a bug report via the GitHub Issues page. Effective bug reports should include the specific file path (e.g., [`skills/cloud/google-cloud-recipe-auth/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/google-cloud-recipe-auth/SKILL.md)) and detailed reproduction steps.

To file a bug report:

1. Navigate to <https://github.com/google/skills/issues>.
2. Click **New issue** and select the **Bug report** template.
3. Fill in the skill name, description of the problem, and any relevant logs or error messages.
4. Submit the issue for maintainer review.

This process allows the core team to verify inaccuracies against the latest Google Cloud APIs and patch the canonical source files directly.

## Requesting New Skills for Google Cloud

The repository welcomes proposals for new skills covering Google Cloud products or cross-product integration patterns. While you cannot directly add these via pull request, you can submit a feature request issue describing the proposed workflow, target audience, and prerequisite knowledge.

After submitting your request, maintainers evaluate it against the project roadmap and existing skill catalog. Compelling requests that address significant gaps in the current collection may be implemented by the core team in future updates.

## Contributing via Forking and Remixing

The primary method for contributing functionality to the Google Skills ecosystem is the **fork-and-remix workflow**. Because skills are plain-markdown packages defined by [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) files, you can clone the repository, adapt existing workflows for your organization, or create entirely new skills in your own fork.

### Creating a New Skill in Your Fork

Each skill resides under `skills/<category>/<skill-name>/SKILL.md` within the repository structure. To add a custom skill to your fork:

```bash

# 1. Fork the repo on GitHub (click the "Fork" button)

# 2. Clone your fork locally

git clone https://github.com/<your-username>/skills.git
cd skills

# 3. Create a new skill directory following the convention

mkdir -p skills/cloud/my-new-skill
cat > skills/cloud/my-new-skill/SKILL.md <<'EOF'

# My New Skill

## Description

A short description of what the skill does.

## Steps

1. First step ...
2. Second step ...
EOF

# 4. Commit and push to your fork

git add .
git commit -m "Add My New Skill"
git push origin main

```

After pushing your changes, your fork will contain the new skill definition, making it available for installation via the CLI tools that parse [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) files.

### Installing Skills from Your Fork

You can test and distribute skills from any fork using the official CLI. The `npx skills add` command reads the [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) metadata to resolve dependencies and present a selection UI:

```bash
npx skills add google/skills

# When prompted, select the skill you want, e.g., "Google Cloud Recipe: Foundation Builder"

```

When users install from your forked repository URL instead of `google/skills`, they gain access to your custom skill variants while maintaining compatibility with the plugin architecture.

## Google Skills Architecture and File Structure

To contribute effectively, you must understand how the repository structures its content. The architecture centers on declarative markdown definitions and extensible plugin integrations.

### The SKILL.md Specification

Every skill follows the [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) format stored under `skills/<category>/<skill-name>/SKILL.md`. These files contain YAML frontmatter for metadata, a description section, and enumerated step-by-step instructions.

The top-level [`README.md`](https://github.com/google/skills/blob/main/README.md) automatically generates its "Available Skills" list by scanning the `skills/` directory. Adding a new directory with a valid [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) file makes the skill immediately discoverable to the discovery tools, though it will only appear in the official README if merged by maintainers.

### Plugin Integration Architecture

The repository bundles plugins for various AI agent platforms (including Claude, Codex, and Antigravity CLI) under the `plugins/` directory. According to the source code implementation, each plugin references sub-paths inside the repo to expose workflows as command-line or API-driven operations.

When you fork the repository, these plugins retain the ability to parse your custom [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) files provided you maintain the schema compatibility defined in the specification. The `plugins/` directory structure allows you to extend support to additional AI platforms by placing appropriate adapter files and updating the lookup table referenced in [`README.md`](https://github.com/google/skills/blob/main/README.md).

## Summary

- The Google Skills repository restricts direct pull requests to existing skills as defined in [`CONTRIBUTING.md`](https://github.com/google/skills/blob/main/CONTRIBUTING.md).
- Contribute by opening GitHub Issues to report bugs or request new capabilities.
- Fork the repository to create custom skill variants under `skills/<category>/<skill-name>/`.
- Skills are plain-markdown files using the [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) specification parsed by the [`skills.sh`](https://github.com/google/skills/blob/main/skills.sh) installer.
- The `npx skills add` command enables installation and testing from any public fork.
- Plugin integrations under `plugins/` allow AI agents to consume skill definitions via CLI or API.

## Frequently Asked Questions

### Does the Google Skills repository accept pull requests?

No, the maintainers do not accept external pull requests that modify existing skill definitions. This policy ensures quality control over the curated Google Cloud workflows. You must fork the repository to propose changes or create variants for your specific use cases.

### How do I report a typo or inaccuracy in a skill file?

Navigate to <https://github.com/google/skills/issues> and open a bug report. Include the specific file path (such as [`skills/cloud/example/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/example/SKILL.md)) and describe the inaccuracy in detail. The maintainers will verify the issue and update the canonical source if confirmed.

### Can I add a new skill to the official Google Skills repository?

You cannot directly add skills via pull request, but you can submit a feature request issue detailing the proposed workflow, target audience, and Google Cloud products involved. Alternatively, implement the skill in your fork following the [`SKILL.md`](https://github.com/google/skills/blob/main/SKILL.md) specification and distribute it to your organization or community.

### What license governs contributions to the Google Skills project?

The repository uses the Apache 2.0 license as defined in the `LICENSE` file. This license allows you to freely fork, modify, and redistribute skill definitions, provided you maintain the copyright notices and license terms specified in the original files.