Create skills for using the gh tool (#7019)

This covers basic usage and using it to make API calls to GitHub. It also works to establish some reasonable safety guards to avoid inappropriate commands. Also introduces a skill specifically for ingesting the content in GitHub issues using the command line tool. This is especially useful as otherwise agents may try to browse the web version of an issues that is significantly slower and harder to ensure the agent correctly gets all of the context into its window and is able to leverage it. This also disables the Google documentation style checking for agent skills, as we want to instead try to follow the conventions, phrasing, and other patterns that map best for agents' training sets. For example, this avoids replacing `repo` with `repository` and avoids replacing `e.g.` with `for example`. While these replacements make lots of sense for our human-facing documentation, the agent-facing docs probably benefit from being terse and using the exact patterns that agents are trained on. Assisted-by: Antigravity with Gemini
2026-09-24 19:40:10 +01:00 · 2026-04-03 20:35:39 +00:00
parent 451b50a3ad
commit fed9e8c878
3 changed files with 271 additions and 0 deletions
@@ -0,0 +1,171 @@
+---
+name: GitHub CLI usage
+description:
+    Instructions for using the `gh` command to query and inspect GitHub state
+    safely.
+---
+
+# GitHub CLI usage
+
+<!--
+Part of the Carbon Language project, under the Apache License v2.0 with LLVM
+Exceptions. See /LICENSE for license information.
+SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+-->
+
+This skill provides instructions for using the GitHub CLI (`gh`) to query,
+inspect, and search GitHub state (issues, pull requests, repositories) for the
+Carbon project.
+
+## Safety First: Read-Only Usage
+
+> [!IMPORTANT] AI assistants MUST NOT use the `gh` tool to modify any GitHub
+> project state. Do NOT run commands that create, edit, delete, label, comment
+> on, or merge issues, pull requests, releases, or any other resources.
+
+### Allowed Verbs
+
+-   `list`
+-   `view`
+-   `search`
+-   `status`
+-   `api` (Only with `GET` requests)
+
+### Prohibited Verbs
+
+-   `create`
+-   `edit`
+-   `delete`
+-   `merge`
+-   `reopen`
+-   `close`
+-   `comment`
+-   `label`
+
+## Repository Configuration
+
+The `gh` tool interacts with a default repository when run within a local check
+out. For this project, the default repository is expected to be
+`carbon-language/carbon-lang`.
+
+### Verifying Default Repository
+
+To verify the current default repository configuration:
+
+```bash
+gh repo view
+```
+
+The output should indicate the repository is `carbon-language/carbon-lang`.
+
+### Correcting Misconfigurations
+
+If the default repository is misconfigured (for example, pointing to a personal
+fork or a different repository), the human operator must correct it.
+
+> [!IMPORTANT] AI Assistants MUST NOT attempt to mutate `gh` configuration or
+> run commands that change the default repository (such as
+> `gh repository set-default`).
+
+Instruct the human operator to run the following command to select the correct
+default repository:
+
+```bash
+gh repo set-default
+```
+
+The operator will be prompted to select the correct repository (e.g.,
+`carbon-language/carbon-lang`) from the available remotes.
+
+## Common Query Commands
+
+### Issues
+
+-   **List issues**: `gh issue list`
+-   **View specific issue**: `gh issue view <number>`
+-   **Search issues**: `gh issue search "<query>"`
+    -   Example: `gh issue search "crash" --state open`
+
+### Pull Requests
+
+-   **List PRs**: `gh pr list`
+-   **View specific PR**: `gh pr view <number>`
+-   **View PR diff**: `gh pr diff <number>`
+-   **Check PR status**: `gh pr status`
+
+### Search
+
+-   **Search code**: `gh search code "<query>"`
+-   **Search repositories**: `gh search repos "<query>"`
+
+## Advanced Usage: GitHub API
+
+For queries that are not supported by standard `gh` commands, you can use the
+`gh api` command to query the GitHub REST or GraphQL APIs.
+
+### REST API
+
+Query the REST API using paths relative to the API root.
+
+-   **List contributors**:
+
+    ```bash
+    gh api repos/carbon-language/carbon-lang/contributors
+    ```
+
+-   **List issue comments**:
+
+    ```bash
+    gh api repos/carbon-language/carbon-lang/issues/<issue_number>/comments
+    ```
+
+### GraphQL API
+
+For complex queries, use GraphQL to fetch exactly the data needed.
+
+-   **Get repository information**:
+
+    ```bash
+    gh api graphql -f query='
+      query {
+        repository(owner: "carbon-language", name: "carbon-lang") {
+          description
+          stargazerCount
+        }
+      }
+    '
+    ```
+
+### Pagination
+
+Use the `--paginate` flag to automatically fetch all pages of results.
+
+```bash
+gh api --paginate repos/carbon-language/carbon-lang/issues
+```
+
+### Filtering and Formatting
+
+Use `--json` to request JSON output, and `--jq` or `--template` to filter or
+format the results.
+
+-   **List PR titles and authors**:
+
+    ```bash
+    gh pr list --json title,author --jq '.[] | "\(.title) by \(.author.login)"'
+    ```
+
+-   **Format with Go templates**:
+
+    ```bash
+    gh issue list --template '{{range .}}{{.number}} - {{.title}}{{"\n"}}{{end}}'
+    ```
+
+## Documentation References
+
+-   **GitHub CLI Manual**:
+    [cli.github.com/manual](https://cli.github.com/manual/)
+-   **GitHub REST API Documentation**:
+    [docs.github.com/en/rest](https://docs.github.com/en/rest)
+-   **GitHub GraphQL API Documentation**:
+    [docs.github.com/en/graphql](https://docs.github.com/en/graphql)
@@ -0,0 +1,95 @@
+---
+name: Accessing GitHub issues
+description:
+    Instructions for safely viewing and accessing GitHub issues by way of
+    command line.
+---
+
+# Accessing GitHub issues
+
+<!--
+Part of the Carbon Language project, under the Apache License v2.0 with LLVM
+Exceptions. See /LICENSE for license information.
+SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+-->
+
+This skill provides instructions for AI assistants on how to access and view
+GitHub issues. Agents should strongly prefer using the command line `gh` tool to
+access and view the contents of issues rather than viewing their contents by way
+of a web browser.
+
+## Safety First
+
+> [!IMPORTANT] AI assistants MUST NOT modify any GitHub issue state. Only use
+> read-only access commands like `view` or `list`. Do NOT comment, edit, create,
+> close, or delete issues.
+
+## Accessing Issues
+
+Agents must use this skill to access issues regardless of how they are mentioned
+(for example, by URL or by issue number).
+
+### Basic View
+
+To view an issue in the current default repository (expected to be Carbon):
+
+```bash
+gh issue view <issue_number>
+```
+
+### Including Full Context (All Comments)
+
+To ensure the view includes the entire context of the issue, always include the
+`--comments` flag to dump all comments:
+
+```bash
+gh issue view <issue_number> --comments
+```
+
+> [!TIP] If the issue is extremely large and comments are truncated, or you need
+> to process comments programmatically, use the JSON output with `jq`:
+>
+> ```bash
+> gh issue view <issue_number> --json comments --jq '.comments[].body'
+> ```
+
+### Accessing Issues in Other Repositories
+
+To view an issue in another repository (for example, LLVM), use the `-R` or
+`--repo` flag to specify the repository:
+
+```bash
+gh issue view <issue_number> -R <owner>/<repo> --comments
+```
+
+Examples:
+
+-   **LLVM Issue**:
+
+    ```bash
+    gh issue view 5678 -R llvm/llvm-project --comments
+    ```
+
+-   **Carbon Issue (Explicit)**:
+
+    ```bash
+    gh issue view 1234 -R carbon-language/carbon-lang --comments
+    ```
+
+## Mentions via URL
+
+If an issue is mentioned via URL, parse the URL to extract the repository owner,
+repository name, and issue number.
+
+-   **URL pattern**: `https://github.com/<owner>/<repo>/issues/<number>`
+-   **Extraction**:
+    -   Host: `github.com`
+    -   Owner: `<owner>`
+    -   Repo: `<repo>`
+    -   Number: `<number>`
+
+Run the command specifying the repository:
+
+```bash
+gh issue view <number> -R <owner>/<repo> --comments
+```
@@ -33,6 +33,11 @@ repos:
    rev: efaea7c61c774c0b1a9805fd999e754a2d19dbd1 # frozen: v1.2.5
    hooks:
      - id: check-google-doc-style
+        exclude: |
+          (?x)^(
+            .*\.agents/.*|
+            .*AGENTS.md
+          )$
      - id: markdown-toc
  - repo: local
    hooks: