Running in CI

First Steps — Read Context

When triggered by a comment or issue, read the full context before responding. The prompt provides a URL — extract the PR/issue number from it.

For PRs:

gh pr view <number> --json title,body,comments,reviews,state,statusCheckRollup
gh pr diff <number>
gh pr checks <number>

For issues:

gh issue view <number> --json title,body,comments,state

Read the triggering comment, the PR/issue description, the diff (for PRs), and recent comments to understand the full conversation before taking action.

Security

NEVER run commands that could expose secrets (env, printenv, set, export, cat/echo on config files containing credentials). NEVER include environment variables, API keys, tokens, or credentials in responses or comments.

PR Creation

When the triggering comment asks for a PR (e.g., “make a new PR”, “open a PR”, “create a PR”), create it directly with gh pr create. The comment is the user’s explicit request — don’t downgrade it to a compare link.

CI Monitoring

After pushing changes to a PR branch, monitor CI until all checks pass:

1. Monitor with gh pr checks or gh run list --branch <branch>
2. Wait for completion with gh run watch
3. If CI fails, diagnose with gh run view <run-id> --log-failed
4. Fix issues, commit, push, and repeat
5. Do not return until CI is green — local tests alone are not sufficient (CI runs on Linux, Windows, macOS)

Comment Formatting

Keep comments concise. Put detailed analysis (file-by-file breakdowns, code snippets) inside <details> tags with a short summary. The top-level comment should be a brief overview (a few sentences); all supporting detail belongs in collapsible sections.

Use Links

When referencing files, issues, PRs, or docs, always use markdown links so readers can click through — never leave them as plain text.

Prefer permalinks (URLs with a commit SHA) over branch-based links (blob/main/...). Permalinks stay valid even when files move or lines shift. This is especially important for line references — a blob/main/...#L42 link breaks as soon as the line numbers change. On GitHub, pressing y on any file view copies the permalink.

• Repository files — link to the file on GitHub: docs/content/hook.md, not just docs/content/hook.md
• Issues and PRs — use #123 shorthand (GitHub auto-links these)
• Specific lines — link with a line fragment: src/cli/mod.rs#L42
• External resources — always use [text](url) format

For file-level links, blob/main/... is acceptable since file paths are stable. For line references, always use a permalink with a commit SHA (blob/<sha>/...#L42) — line numbers shift frequently and branch-based line links go stale fast.

Example:

<details><summary>Detailed findings (6 files)</summary>

...details here...

</details>

Do not add job links, branch links, or other footers at the bottom of your comment. claude-code-action automatically adds these to the comment header. Adding them yourself creates duplicates and broken links (the action deletes unused branches after the run).

Shell Quoting in gh Commands

Claude tends to mangle shell quoting in CI. Two common failure modes:

1. $ in GraphQL queries — gh api graphql -f query='...$var...' fails because Claude corrupts the $ signs. Write queries to a temp file instead:

   cat > /tmp/query.graphql << 'GRAPHQL'
   query($owner: String!, $repo: String!, $name: String!) {
     repository(owner: $owner, name: $name) { ... }
   }
   GRAPHQL
   
   gh api graphql -F query=@/tmp/query.graphql -f owner="$OWNER" -f name="$NAME"
   

2. ! in comment/body text — gh issue comment N --body "Thanks!" gets over-escaped to Thanks\! because ! is a bash history expansion character. Use a heredoc:

   gh issue comment N --body "$(cat <<'EOF'
   Comment text here — no escaping needed.
   EOF
   )"
   

General rule: When a gh command argument contains $ or !, use either a temp file (-F field=@file) or a heredoc with a quoted delimiter (<<'EOF').

Atomic PRs

When creating PRs, split unrelated changes into separate PRs — one concern per PR. For example, a skill file fix and a workflow dependency cleanup are two independent changes and should be two PRs, even if discovered in the same session. This makes PRs easier to review, revert, and bisect.

A good test: if one change could be reverted without affecting the other, they belong in separate PRs.

Tone

You are a helpful reviewer raising observations, not a manager assigning work. Never create checklists or task lists for the PR author. Instead, note what you found and let the author decide what to act on.

PR Review Comments

For PR review comments on specific lines (shown as [Comment on path:line] in <review_comments>), ALWAYS read that file and examine the code at that line before answering. The question is about that specific code, not the PR in general.