GitHub CLI Skill

Execute GitHub CLI and git commands with proper authentication.

You must source the helpers before use:

source ./_skills/connections/github/github/scripts/github_helpers.sh

CLI Tips

CRITICAL: Always Use --repo Flag

ALL commands require explicit --repo owner/repo flag.

✅ CORRECT:  gh pr list --repo owner/repo
❌ WRONG:    gh pr list              # No repo context!

For Code Review - Use Helper Functions

ALWAYS use github_create_pr_comment helper function for code review inline comments.

Why? Helper functions auto-handle:

• Commit SHA fetching
• Line number targeting
• Suggestion block rendering
• Error recovery

GitHub Helper Functions (Code Review)

Inline comment with suggestion block:

github_create_pr_comment OWNER REPO PR "file.py" LINE 'Comment text

```suggestion
fixed code

' "SIDE"

- `SIDE`: "RIGHT" for new code, "LEFT" for old code
- Use single quotes to preserve backticks literally - NO escaping needed

**Discussion comment:**
```bash
github_create_pr_discussion OWNER REPO PR 'Comment text'

Suggestion Block Syntax (CRITICAL)

✅ CORRECT - Single quotes preserve backticks:

github_create_pr_comment owner repo 123 "file.py" 45 '🔴 CRITICAL: Issue

```suggestion
if not input:
    raise ValueError("Required")

' "RIGHT"

**❌ WRONG - Escaped backticks break rendering:**
```bash
github_create_pr_comment owner repo 123 "file.py" 45 "\`\`\`suggestion
code
\`\`\`" "RIGHT"

Key rules:

• Use single quotes to wrap comment body containing markdown
• Backticks inside single quotes are literal - write them normally
• NEVER escape backticks with backslashes (\`) - this breaks GitHub's markdown parser
• Triple backticks for suggestion blocks must be literal: ```suggestion

Supported Parameters Reference

gh pr list

Supported flags:

• --repo owner/repo : REQUIRED - Repository target
• --state open|closed|merged|all : Filter by state
• --author username : Filter by author
• --assignee username : Filter by assignee
• --label name : Filter by label
• --limit N : Max number of PRs (default: 30)

NOT SUPPORTED:

• --created : Date filtering not available in gh CLI
• Alternative: Use gh api with GraphQL for date filtering

gh issue list

Supported flags:

• --repo owner/repo : REQUIRED
• --state open|closed|all
• --author username
• --assignee username
• --label name
• --limit N

NOT SUPPORTED:

• --created-after : Not available
• Alternative: Use gh api endpoint

gh pr view

Supported flags:

• --repo owner/repo : REQUIRED
• --json FIELDS : Output specific fields as JSON
• --web : Open in browser

NOT SUPPORTED:

• --diff : Not available (use gh pr diff instead)

gh pr diff

Supported flags:

• --repo owner/repo : REQUIRED
• --patch : Show full patch format

NOT SUPPORTED:

• --filter : File filtering not available (pipe to grep instead)

Helper Function Parameters

github_create_pr_comment

Required parameters:

1. owner : Repository owner (org or user)
2. repo : Repository name
3. pr_number : PR number (not prefixed with #)
4. file_path : File path in repository
5. end_line : Line number for comment
6. body : Comment text (use single quotes for markdown)
7. side : "RIGHT" (new code) or "LEFT" (old code), optional, default: RIGHT
8. start_line : Start line for multi-line, optional

NOT SUPPORTED:

• commit_sha : Automatically fetched by helper
• position : Automatically calculated by helper

Example:

# ✅ Correct - single line comment
github_create_pr_comment owner repo 123 "src/main.py" 45 'Fix this issue' "RIGHT"

# ✅ Correct - multi-line with suggestion
github_create_pr_comment owner repo 123 "src/main.py" 45 '```suggestion
fixed code
```' "RIGHT" 43

# ❌ Wrong - escaped backticks
github_create_pr_comment owner repo 123 "src/main.py" 45 "\`\`\`suggestion..." "RIGHT"

github_create_pr_discussion

Required parameters:

1. owner : Repository owner
2. repo : Repository name
3. pr_number : PR number
4. body : Comment text

Parameter Validation Rules

BEFORE using gh CLI or GitHub helpers:

1. Check supported flags - Verify in this SKILL.md
2. --repo flag is MANDATORY - Every gh command needs it
3. If unsure about a flag - Use gh pr list --help to check
4. For advanced filtering - Consider gh api with GraphQL

Common mistake pattern:

# User asks: "List PRs created after January 1"
# ❌ WRONG: Assume date filtering exists
gh pr list --repo owner/repo --created-after "2026-01-01"  # Will fail

# ✅ CORRECT: Check SKILL.md first, use alternative
gh api graphql -f query='query { repository(owner:"owner", name:"repo") { pullRequests(first:100, orderBy:{field:CREATED_AT, direction:DESC}) { nodes { number title createdAt } } } }' | jq '.data.repository.pullRequests.nodes[] | select(.createdAt >= "2026-01-01")'

Key Rules

1. ALWAYS use helper functions for code review inline comments - Use github_create_pr_comment
2. Always use --repo flag with gh CLI commands
3. For general operations: Use gh CLI (list, view, merge, etc.) - NOT for code review comments
4. Write operations: All require user approval
5. Suggestion blocks: Must use helper functions with single quotes
6. Parameter validation: Check this SKILL.md before using any flag

Output Format

Present results as a structured report:

Github Report
═════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Anti-Hallucination Rules

1. NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
2. NEVER fabricate metric names or dimensions — verify against the service documentation or --help output.
3. NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
4. ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
5. ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.

Counter-Rationalizations

Shortcut	Counter	Why
"I'll skip discovery and check known resources"	Always run Phase 1 discovery first	Resource names change, new resources appear — assumed names cause errors
"The user only asked for a quick check"	Follow the full discovery → analysis flow	Quick checks miss critical issues; structured analysis catches silent failures
"Default configuration is probably fine"	Audit configuration explicitly	Defaults often leave logging, security, and optimization features disabled
"Metrics aren't needed for this"	Always check relevant metrics when available	API/CLI responses show current state; metrics reveal trends and intermittent issues
"I don't have access to that"	Try the command and report the actual error	Assumed permission failures prevent useful investigation; actual errors are informative