diff --git a/.agents/skills/github_cli/SKILL.md b/.agents/skills/github_cli/SKILL.md new file mode 100644 index 000000000000..b4383cd093d8 --- /dev/null +++ b/.agents/skills/github_cli/SKILL.md @@ -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 + + + +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 ` +- **Search issues**: `gh issue search ""` + - Example: `gh issue search "crash" --state open` + +### Pull Requests + +- **List PRs**: `gh pr list` +- **View specific PR**: `gh pr view ` +- **View PR diff**: `gh pr diff ` +- **Check PR status**: `gh pr status` + +### Search + +- **Search code**: `gh search code ""` +- **Search repositories**: `gh search repos ""` + +## 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//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) diff --git a/.agents/skills/github_issues/SKILL.md b/.agents/skills/github_issues/SKILL.md new file mode 100644 index 000000000000..ce26001c2e9c --- /dev/null +++ b/.agents/skills/github_issues/SKILL.md @@ -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 + + + +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 +``` + +### 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 --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 --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 -R / --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///issues/` +- **Extraction**: + - Host: `github.com` + - Owner: `` + - Repo: `` + - Number: `` + +Run the command specifying the repository: + +```bash +gh issue view -R / --comments +``` diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 06a2e7ddc699..bc37d90e11af 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -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: