How to Report a Bug in google/skills: Complete Guide for Agent Skill Issues

To report a bug in google/skills, open a GitHub issue at https://github.com/google/skills/issues with the specific skill path, description, and reproduction steps—external pull requests are not accepted.

The google/skills repository contains Agent Skills: Markdown-based guides and recipes that enable AI agents to interact with Google Cloud products. While the repository is publicly visible, all content is curated and verified internally by Google product teams. This structure means you can help improve the project by spotting and reporting bugs, even though you cannot submit direct code changes.

---

Why Issues Are the Only Path for Bug Reports

Google's contribution policy explicitly directs users to "open an issue" for bug reports, as documented in CONTRIBUTING.md. The repository does not accept external pull requests due to two critical requirements:

• Internal verification — Every skill undergoes rigorous review by Google product teams to guarantee technical accuracy and security compliance
• Centralized tracking — Issues create a single source of truth that maintainers can prioritize and reference publicly

This workflow is implemented in CONTRIBUTING.md at the repository root, where the reporting policy is clearly stated.

---

Step-by-Step Bug Reporting Process

1. Identify the Problem Location

Locate the specific .md skill file containing the bug. Common issues include stale SDK commands, broken documentation links, or security anti-patterns. Note the full file path, such as skills/cloud/gke-basics/SKILL.md.

2. Gather Reproduction Details

Collect the following information before filing:

• Exact skill path and line number or section
• Current behavior versus expected behavior
• Screenshots, log excerpts, or command outputs
• Steps to reproduce (if applicable)

3. Submit via GitHub Issues

Navigate to https://github.com/google/skills/issues and create a new issue. Provide:

• Skill path (e.g., skills/cloud/gke-basics/SKILL.md)
• Description of the bug
• Steps to reproduce
• Desired correction or suggestion

If a bug report template appears in .github/ISSUE_TEMPLATE/bug_report.md, fill in all required fields.

---

Command-Line Methods to Create Issues

You can automate issue creation using either GitHub CLI or the REST API.

Using GitHub CLI (gh)

# Install GitHub CLI: https://cli.github.com/

# Authenticate once per machine

gh auth login

# Create a new issue in google/skills

gh issue create \
  --repo google/skills \
  --title "Bug in GKE Basics skill: outdated gcloud command" \
  --body "File: skills/cloud/gke-basics/SKILL.md

The command 'gcloud container clusters create' is missing the required --region flag.

**Expected:** Include --region us-central1.

**Impact:** Users receive a validation error when following the tutorial."

Using curl with GitHub REST API

# Replace <YOUR_TOKEN> with a personal access token (repo scope)

curl -X POST \
  -H "Authorization: token <YOUR_TOKEN>" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/google/skills/issues \
  -d '{
    "title": "Broken link in BigQuery AI & ML skill",
    "body": "File: skills/cloud/bigquery-ai-ml/SKILL.md\nThe link to the BigQuery AI documentation points to a 404 page.\n\n**Fix:** Update URL to https://cloud.google.com/bigquery/ai"
  }'

Both methods create an issue that Google maintainers will triage and address internally.

---

Key Repository Files for Bug Reporters

File	Purpose
README.md	Overview, installation guidance, and link to issue tracker
CONTRIBUTING.md	Official bug reporting policy and PR restrictions
SKILL.md files (e.g., skills/cloud/gke-basics/SKILL.md)	Individual skill definitions where bugs typically occur
.github/ISSUE_TEMPLATE/bug_report.md	Structured template for consistent reports (if present)

The CONTRIBUTING.md file is your authoritative reference—it explicitly states that all improvements must flow through the issue tracker rather than pull requests.

---

What Happens After You Report

Once submitted, the Google team:

1. Triages the issue and assigns priority
2. Discusses technical details publicly or privately as needed
3. Implements fixes internally through their verification pipeline
4. Closes the issue when resolved

Your issue remains visible as a public record of known problems and their resolution status.

---

Summary

• Report bugs in google/skills exclusively through GitHub Issues—no external PRs are accepted
• Use CONTRIBUTING.md as your authoritative guide for the reporting policy
• Include skill path, reproduction steps, and suggested fixes to accelerate resolution
• Automate issue creation with gh CLI or curl API calls for efficient reporting

---

Frequently Asked Questions

Can I submit a pull request to fix a bug myself?

No. The google/skills repository does not accept external pull requests. According to CONTRIBUTING.md, all skills must be verified internally by Google product teams before publication. Submit an issue instead, and the team will implement verified fixes.

What information should I include in a bug report issue?

Include the full skill file path (e.g., skills/cloud/bigquery-ai-ml/SKILL.md), a clear description of the error, steps to reproduce if applicable, and your suggested correction. Screenshots and log excerpts strengthen your report.

How do I find the correct skill file to reference in my issue?

Browse the skills/ directory in the repository. Skills are organized by category (e.g., cloud/, security/) and each contains a SKILL.md file. The README.md provides an overview of available skills and their purposes.

Will I receive credit for reporting a bug that gets fixed?

GitHub issues are publicly attributed to your username. While google/skills does not use a formal contributor license agreement for external submissions, your issue remains a visible record of your contribution to improving the repository.

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