# How to Report a Bug in Google Skills: Complete GitHub Issue Guide

> Report bugs in google/skills by creating a GitHub issue. Follow our guide for clear reproduction steps and affected file paths. Learn how to submit effective bug reports.

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

---

**Report bugs in google/skills by opening a GitHub issue at https://github.com/google/skills/issues with clear reproduction steps and affected file paths—external pull requests are not accepted.**

The **google/skills** repository hosts open-source Agent Skills for Google Cloud products. While the project welcomes community feedback to surface defects and outdated patterns, all code changes flow through Google's internal pipeline. Understanding the proper bug reporting workflow ensures your issue gets triaged and resolved efficiently.

## Where to File a Bug Report

All bug reports must go through the GitHub issue tracker. The repository's **README.md** explicitly directs users to this channel for help and bug reports at lines 68-73, stating that issues are the primary mechanism for community contribution.

Navigate to https://github.com/google/skills/issues and click **"New issue"**. Select the appropriate template if available, then provide a complete, reproducible description including:

- The exact skill or markdown file path (e.g., [`skills/cloud/bigquery-basics/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/bigquery-basics/SKILL.md))
- Steps to reproduce or the specific snippet that appears incorrect
- Expected versus actual behavior
- Version information (e.g., `npx skills add google/skills@latest`)

The **CONTRIBUTING.md** file reinforces this workflow at lines 17-20, emphasizing that issues are the only supported channel for external feedback.

## What to Include in Your Bug Report

A high-quality issue accelerates triage. Structure your report with these components:

**1. Precise file location**

Reference the specific skill directory and file. Google Skills organizes content under `skills/` by cloud product and capability level.

**2. Reproduction steps**

Numbered steps that maintainers can follow to observe the defect.

**3. Code snippets**

Fenced code blocks showing both the problematic content and the corrected version.

**4. Environment details**

Include how you accessed the skills (CLI version, direct clone, etc.).

### Example Bug Report Template

Copy and adapt this markdown when filing your issue:

```markdown
**Title:** Incorrect IAM permission example in `skills/cloud/spanner-basics/references/iam-security.md`

**Description:**
The IAM policy snippet for granting `roles/spanner.databaseUser` is missing the required `resource` field, which leads to deployment failures.

**Steps to Reproduce:**
1. Open `skills/cloud/spanner-basics/references/iam-security.md`.
2. Locate the "Grant permissions" code block.
3. Apply the snippet with `gcloud` – the command fails with `ERROR: (gcloud...)`.

**Expected Behavior:**
The snippet should include the full resource identifier, e.g.:

```yaml
- role: roles/spanner.databaseUser
  members:
    - user:example@example.com
  resource: projects/PROJECT_ID/instances/INSTANCE_ID/databases/DATABASE_ID

```

**Actual Behavior:**
The `resource` field is omitted, causing the error above.

**Environment:**
- `skills` version: latest (`npx skills add google/skills`)
- OS: macOS 14.5
- gcloud CLI version: 447.0.0

**Additional Context:**
[Link to related documentation] (optional)

```

Paste this directly into the GitHub issue editor. The markdown renders cleanly and provides maintainers with actionable information.

## What Happens After Submission

The google/skills resolution process follows a predictable path:

1. **Triage** — A project maintainer receives notification and evaluates the issue
2. **Internal fix** — If confirmed, the Google team creates a correction in the private codebase (per CONTRIBUTING.md lines 7-10, no external pull requests are accepted)
3. **Resolution** — The fix propagates to the public repository, and maintainers close the issue with a reference to the resolving commit

This closed-loop workflow ensures all changes meet Google's internal security and quality standards while preserving community input.

## Critical Policy Constraints

Understanding these limitations prevents wasted effort:

- **No external pull requests** — CONTRIBUTING.md lines 7-10 explicitly states that all contributions go through an internal Google process. Do not open PRs; they will be closed.

- **Issues only** — The repository accepts feedback exclusively through the GitHub issue tracker.

- **Feature requests welcome** — New skill ideas follow the same issue-based workflow. Open an issue describing your proposal for internal evaluation.

## Key Repository Files for Bug Reporting

| File | Purpose | Relevant Lines |
|------|---------|--------------|
| [`README.md`](https://github.com/google/skills/blob/main/README.md) | Entry point; directs users to issue tracker for help | 68-73 |
| [`CONTRIBUTING.md`](https://github.com/google/skills/blob/main/CONTRIBUTING.md) | Contribution policy; defines issues-only workflow | 7-10, 17-20 |
| `skills/*/SKILL.md` | Individual skill specifications; common bug locations | Variable by skill |

Familiarity with these files helps you reference authoritative sources when describing issues.

## Summary

- **Report bugs** exclusively through https://github.com/google/skills/issues
- **Include file paths**, reproduction steps, and environment details in every report
- **Never submit pull requests** — all fixes flow through Google's internal pipeline
- **Use the provided template** to structure clear, actionable issues
- **Reference source files** ([`README.md`](https://github.com/google/skills/blob/main/README.md), [`CONTRIBUTING.md`](https://github.com/google/skills/blob/main/CONTRIBUTING.md)) to demonstrate understanding of project conventions

## Frequently Asked Questions

### Can I submit a pull request to fix a bug I found?

No. According to CONTRIBUTING.md lines 7-10, the google/skills repository does not accept external pull requests. All code modifications undergo internal Google review. File an issue describing the bug and desired fix instead.

### How long does it take for a reported bug to get fixed?

Resolution timelines vary. After triage, confirmed bugs enter Google's internal workflow. The public repository updates when the internal fix propagates. Critical security issues typically receive faster attention than documentation corrections.

### What types of bugs should I report?

Report any defect in skill accuracy, broken code examples, outdated API references, or security concerns in the provided configurations. Feature requests for new skills also belong in the issue tracker. The team evaluates all submissions internally.