github-app

Files (5)

• SKILL.md
• gh-app-issue-dependency.sh · scripts/
• gh-app-issue-sub-issue.sh · scripts/
• gh-app-token.sh · scripts/
• gh-app.sh · scripts/

SKILL.md (first lines)

# /github-app — GitHub as the App, through `gh`

`${CLAUDE_SKILL_DIR}/scripts/gh-app.sh` runs the real `gh` CLI as a GitHub App
installation. It exports an installation token as `GH_TOKEN` and passes your
arguments to `gh` unchanged. Flags, output, exit codes, and `--help` are
`gh`'s own. When a command prints a URL — creating, editing or transferring
an issue or PR — **always relay it back to the user.** `${CLAUDE_SKILL_DIR}` is
the directory containing this SKILL.md.

These are **outward-facing actions** (they publish to GitHub and notify people).
This skill only runs when explicitly requested by the user- this includes explicitly invoking another skill that explicitly invokes this skill.
Confirm the target (repo, branch, title) before running if there's any ambiguity.

## Guardrails

`gh` can do anything the token allows, so these rules are the guard:

- Ask the user before acting on a repository outside the current project.
- Read the target project's `AGENTS.md` and `CONTRIBUTING.md` first and follow
  their restrictions.
- The App's granted scopes are the hard ceiling: `write` on `actions`,
  `contents`, `issues`, `pull_requests`, and `workflows`; the remaining 20
  scopes are read-only. That still allows deleting branches and editing
  workflows: it is a ceiling, not a guard.
- Never move or delete the default branch through `gh` (for example
  `gh api …/git/refs/heads/main` or `gh repo sync --force`); the `git push`
  guard does not cover it.
- Report a `403` to the user. Never work around it.
- Never run bare `gh`: it acts as the user, not the App.

## Setup reference

Three files live outside this repo, in `~/.config/github-app/` (override with
`GITHUB_APP_SECRETS_DIR`):

- `client-id` — the App's client ID (used as the JWT `iss` claim)
- `installation-id` — the installation scope id
- `private-key.pem` — the App's private key (signs the JWT)

These files should only be accessible to the user (permission 0600).

If these files are missing, the skill is not configured.
If the skill needs to be used, prompt the user to add these files.

The token is minted for you and cached in `${XDG_CACHE_HOME:-~/.cache}/gh-app/`
until five minutes before it expires. You never handle the private key.
Requires `gh`, `jq`, `curl`, and OpenSSL.

## Commands

| Action | Command |
|---|---|
| Push the current branch | `${CLAUDE_SKILL_DIR}/scripts/gh-app.sh git push` |
| Open a PR | `${CLAUDE_SKILL_DIR}/scripts/gh-app.sh pr create --base BASE --head HEAD --title TITLE --body-file FILE` |
| Update a PR | `${CLAUDE_SKILL_DIR}/scripts/gh-app.sh pr edit NUMBER --title TITLE --body-file FILE` |
| Read an issue | `${CLAUDE_SKILL_DIR}/scripts/gh-app.sh issue view NUMBER --json number,title,state,labels,body` |
| File an issue | `${CLAUDE_SKILL_DIR}/scripts/gh-app.sh issue create --title TITLE --body-file FILE` |
| Update an issue | `${CLAUDE_SKILL_DIR}/scripts/gh-app.sh issue edit NUMBER --body-file FILE` |
| Assign an issue | `${CLAUDE_SKILL_DIR}/scripts/gh-app.sh issue edit NUMBER --add-assignee USER` |
| Transfer an issue | `${CLAUDE_SKILL_DIR}/scripts/gh-app.sh issue transfer NUMBER OWNER/REPO` |
| Comment on an issue or PR | `${CLAUDE_SKILL_DIR}/scripts/gh-app.sh issue comment NUMBER --body-file FILE` |
| Link blocked-by | `${CLAUDE_SKILL_DIR}/scripts/gh-app-issue-dependency.sh add --blocked NUMBER --blocker NUMBER` |
| Remove blocked-by | `${CLAUDE_SKILL_DIR}/scripts/gh-app-issue-dependency.sh remove --blocked NUMBER --blocker NUMBER` |
| List blocking edges | `${CLAUDE_SKILL_DIR}/scripts/gh-app-issue-dependency.sh list --issue NUMBER` |
| Link sub-issue | `${CLAUDE_SKILL_DIR}/scripts/gh-app-issue-sub-issue.sh add --parent NUMBER --child NUMBER` |

Anything else `gh` does, run through `${CLAUDE_SKILL_DIR}/scripts/gh-app.sh`
with `gh`'s own arguments, for example `api`, `pr view`, or `run view`. Use the
`github-actions-ci` skill for check status and waiting.

Commands act on the repository of the directory they run in, which `gh`
resolves for itself.

With more than one remote (for example a fork with `upstream`), that resolution
does not follow the remote `git push` uses: with no default set,
`{owner}/{repo}` and `issue create` resolve to `upstream`, so a write lands in
the wrong repository. Name the repository explicitly instead. Use `origin`, the
remote `git push` uses:

```text
git remote get-url origin
```

That prints `git@github.com:OWNER/REPO.git` or
`https://github.com/OWNER/REPO.git`, possibly without the trailing `.git`;
`OWNER/REPO` is the part after the host.
Pass it as `--repo OWNER/REPO` to the `gh` subcommands that accept it and to
both issue scripts, and use a `repos/OWNER/REPO/...` path with `gh api`, which
has no `--repo`. Pass `--repo` for another repository only when the user asked
for it, and ask first (see Guardrails). `repo set-default --view` shows only a
default that was set explicitly, not what `gh` would otherwise resolve; never
run `repo set-default` without an argument, because it fails when not run
interactively. Run `repo set-default OWNER/REPO` only when the user asks for
it, because it writes `remote.<name>.gh-resolved` into the repository's config.

Other skills call the same scripts as
`${CLAUDE_SKILL_DIR}/../github-app/scripts/gh-app.sh` (and likewise for the two
issue scripts). Skill directories are siblings both in this repo and when
installed.

## Recording blocked-by / blocking dependencies

`gh` has no command for issue dependencies or sub-issues, so two bundled
scripts call `gh api` and resolve issue numbers to the database ids GitHub
needs.

GitHub stores a dependency as a single directed edge: "issue A blocks issue B"
is recorded as "B is blocked_by A". Name the issue that **cannot start** with
`--blocked`:

```
${CLAUDE_SKILL_DIR}/scripts/gh-app-issue-dependency.sh add --blocked 42 --blocker 40
```

reads as "issue 42 is blocked by issue 40". `list --issue N` prints both
directions (`blocked by:` / `blocking:`). To undo a link, pass the same pair to
`remove`.

## Permission-efficient command shapes

From gregwebs/skills-sdlc, MIT.

More from gregwebs/skills-sdlc