claude-github-skills 1.0.0

package/README.md

@@ -0,0 +1,142 @@
+# claude-github-skills
+
+GitHub-focused skills for Claude Code. Work on issues, review PRs, and fix review feedback — all scoped to a single project.
+
+## Install
+
+```bash
+npx claude-github-skills@latest
+```
+
+This copies the skill commands to `~/.claude/commands/gh/` (global install). For project-local install:
+
+```bash
+npx claude-github-skills@latest --local
+```
+
+Project-local install copies commands to `.claude/commands/gh/` in your current working directory, so the skills are only available when working in that project.
+
+## Prerequisites
+
+- [Claude Code](https://claude.ai/code) installed
+- [GitHub CLI (`gh`)](https://cli.github.com/) installed and authenticated (`gh auth login`)
+- [Node.js](https://nodejs.org/) >= 18.0.0
+
+## Quick Start
+
+1. Install the skills: `npx claude-github-skills@latest`
+2. Open your project in Claude Code
+3. Run `/gh:setup` to scope the skills to your repository
+4. Start using `/gh:work`, `/gh:review-pr`, or `/gh:fix-pr`
+
+## Commands
+
+### `/gh:setup` — Onboarding (run this first)
+
+Detects your project's GitHub remote, confirms it with you, and writes the scope to `CLAUDE.md`. All other commands read this scope to know which repo to target.
+
+```
+/gh:setup
+```
+
+What it does:
+1. Verifies `gh` CLI is authenticated (`gh auth status`)
+2. Detects the GitHub remote from `git remote get-url origin` (supports both HTTPS and SSH URLs)
+3. Confirms the detected `owner/repo` with you
+4. Verifies the repository exists and is accessible
+5. Writes a `<!-- gh-skills-start -->` configuration block to your project's `CLAUDE.md` (creates the file if it doesn't exist, preserves existing content if it does)
+
+The configuration block scopes all `/gh:*` commands to that single repository, preventing accidental interaction with other repos.
+
+### `/gh:work <issue#>` — Work on an issue
+
+Fetches the issue, creates a feature branch, implements the solution, and opens a draft PR.
+
+```
+/gh:work 27
+```
+
+What it does:
+1. Reads issue #27 (title, body, labels, assignees, comments, state)
+2. Creates branch `feat/27-<slug>` (e.g., `feat/27-add-user-auth`) — if the branch already exists, it checks it out so you can resume work
+3. Explores the codebase, summarizes a 3–5 bullet implementation plan, then implements
+4. Makes focused, incremental commits — each referencing the issue (e.g., `Add auth middleware (#27)`)
+5. Pushes and creates a draft PR with a summary, change list, and `Closes #27` link
+
+### `/gh:review-pr <pr#>` — Review a PR
+
+Performs a focused code review on the PR's changed files and posts comments directly on GitHub.
+
+```
+/gh:review-pr 42
+```
+
+What it does:
+1. Fetches the PR diff, metadata, and existing reviews
+2. Reads full changed files for context, but reviews only the diff — does not critique untouched code
+3. Checks for: correctness, security, error handling, naming clarity, test coverage, and performance issues
+4. Skips nitpicks already handled by linters (style, formatting, subjective naming)
+5. Posts a review summary with key findings and inline comments on specific lines
+6. Approves the PR if no issues are found
+7. For PRs with 15+ changed files, prioritizes core logic, largest diffs, and new files
+8. Optionally offers to run Playwright for visual regression checks on UI changes (only if Playwright is in the project)
+
+### `/gh:fix-pr <pr#>` — Fix review feedback
+
+Reads all review comments on a PR and addresses each one.
+
+```
+/gh:fix-pr 42
+```
+
+What it does:
+1. Fetches all inline review comments, conversation comments, and review threads
+2. Filters to unresolved, actionable comments — skips resolved threads, acknowledgments, and already-answered questions
+3. Presents a numbered list of items to address (with file, line, and requested change)
+4. Checks out the PR branch and fixes each item
+5. Groups related fixes into logical commits with descriptive messages
+6. Pushes the fixes
+7. Replies to each addressed comment on GitHub with a link to the fixing commit (e.g., `Fixed in abc1234`)
+8. Reports any skipped comments with reasons (disagreement, out of scope, needs discussion)
+
+## How It Works
+
+- **Project scoping**: All commands read `CLAUDE.md` for the `<!-- gh-skills-start -->` block to find the scoped `owner/repo`. They refuse to run without it — run `/gh:setup` first.
+- **GitHub CLI only**: Uses `gh` CLI exclusively. No API tokens needed beyond what `gh auth` provides.
+- **Respects your setup**: Works alongside your existing Claude Code skills, plugins, and `CLAUDE.md` conventions.
+- **Namespaced**: Commands live under `/gh:*` to avoid collisions with other skills.
+- **No destructive actions**: Commands create branches and PRs but never force-push, delete branches, or merge without your approval.
+
+## File Structure
+
+```
+claude-github-skills/
+├── bin/
+│   └── install.js          # Installer — copies commands to ~/.claude or ./.claude
+├── commands/
+│   └── gh/
+│       ├── setup.md        # /gh:setup skill definition
+│       ├── work.md         # /gh:work skill definition
+│       ├── review-pr.md    # /gh:review-pr skill definition
+│       └── fix-pr.md       # /gh:fix-pr skill definition
+├── package.json
+└── README.md
+```
+
+## Uninstall
+
+Remove the command files:
+
+```bash
+# Global install
+rm -rf ~/.claude/commands/gh
+
+# Project-local install
+rm -rf .claude/commands/gh
+```
+
+And optionally remove the `<!-- gh-skills-start -->` to `<!-- gh-skills-end -->` block from your project's `CLAUDE.md`.
+
+## License
+
+MIT

package/bin/install.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+const COMMANDS_DIR = "commands/gh";
+
+function getClaudeHome() {
+  const home = process.env.HOME || process.env.USERPROFILE;
+  return path.join(home, ".claude");
+}
+
+function copyDirRecursive(src, dest) {
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+      console.log(`  Copied: ${entry.name}`);
+    }
+  }
+}
+
+function install() {
+  const args = process.argv.slice(2);
+  const isLocal = args.includes("--local");
+
+  let targetBase;
+  if (isLocal) {
+    targetBase = path.join(process.cwd(), ".claude");
+  } else {
+    targetBase = getClaudeHome();
+  }
+
+  const packageRoot = path.resolve(__dirname, "..");
+  const commandsSrc = path.join(packageRoot, COMMANDS_DIR);
+  const commandsDest = path.join(targetBase, COMMANDS_DIR);
+
+  if (!fs.existsSync(commandsSrc)) {
+    console.error("Error: commands directory not found at", commandsSrc);
+    process.exit(1);
+  }
+
+  console.log("\n  claude-github-skills installer\n");
+  console.log(`  Installing to: ${targetBase}\n`);
+
+  console.log("  Installing commands...");
+  copyDirRecursive(commandsSrc, commandsDest);
+
+  console.log("\n  Installation complete!");
+  console.log("\n  Available commands:");
+  console.log("    /gh:setup       - Set up project (run this first)");
+  console.log("    /gh:work <#>    - Work on a GitHub issue");
+  console.log("    /gh:review-pr <#> - Review a pull request");
+  console.log("    /gh:fix-pr <#>  - Fix PR review feedback");
+  console.log("\n  Prerequisites:");
+  console.log("    - GitHub CLI (gh) installed and authenticated");
+  console.log("    - Run /gh:setup in your project first\n");
+}
+
+install();

package/commands/gh/fix-pr.md

@@ -0,0 +1,127 @@
+---
+name: gh:fix-pr
+description: Fix PR review feedback — reads review comments and addresses each one
+argument-hint: "<pr-number>"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<role>
+You are a developer addressing PR review feedback. You read every review comment, understand what's being asked, and make the fixes. You're methodical — you address each comment one by one and don't miss any.
+</role>
+
+<objective>
+Given a PR number, read all review comments and conversation comments, then fix every actionable item.
+</objective>
+
+<context>
+PR number: $ARGUMENTS
+</context>
+
+<process>
+
+## Step 1: Read project scope
+
+Read `CLAUDE.md` in the project root. Look for the `<!-- gh-skills-start -->` block to find the scoped `owner/repo`.
+
+If the block is missing, tell the user to run `/gh:setup` first and stop.
+
+## Step 2: Fetch PR and review comments
+
+Gather all feedback:
+
+```bash
+# PR details and conversation comments
+gh pr view $ARGUMENTS --repo owner/repo --json title,body,headRefName,comments,reviews
+
+# Inline review comments (file-level and line-level)
+gh api repos/owner/repo/pulls/$ARGUMENTS/comments --paginate
+
+# Review threads (to see which are resolved vs unresolved)
+gh api repos/owner/repo/pulls/$ARGUMENTS/reviews --paginate
+```
+
+## Step 3: Check out the PR branch
+
+```bash
+gh pr checkout $ARGUMENTS --repo owner/repo
+```
+
+If already on the branch, just make sure it's up to date:
+```bash
+git pull origin $(gh pr view $ARGUMENTS --repo owner/repo --json headRefName --jq .headRefName)
+```
+
+## Step 4: Catalog all feedback
+
+Parse all comments and create a list of actionable items. For each comment, note:
+- The file and line it references (if inline)
+- What change is being requested
+- Whether it's resolved or unresolved
+
+Focus on **unresolved** comments. Skip:
+- Already resolved threads
+- Comments that are just acknowledgments ("looks good", "thanks")
+- Questions that were already answered in the thread
+
+Present the list to the user:
+> "Found **N** actionable review comments:"
+> 1. `file.ts:42` — "Should handle the null case here"
+> 2. `utils.ts:15` — "This function name is misleading"
+> ...
+
+## Step 5: Address each comment
+
+For each actionable item:
+
+1. Read the relevant file and understand the context
+2. Make the fix
+3. After fixing, move to the next item
+
+Group related fixes into logical commits:
+
+```bash
+git add <files>
+git commit -m "Address review feedback: <summary>
+
+- <fix 1>
+- <fix 2>
+"
+```
+
+If a comment is unclear or you disagree with it, ask the user for guidance rather than guessing.
+
+## Step 6: Push the fixes
+
+```bash
+git push
+```
+
+## Step 7: Reply to comments (optional)
+
+For each addressed comment, post a reply indicating it's been fixed:
+
+```bash
+gh api repos/owner/repo/pulls/$ARGUMENTS/comments/<comment-id>/replies \
+  --method POST \
+  -f body="Fixed in $(git rev-parse --short HEAD)"
+```
+
+If a comment was not addressed (disagreement, needs discussion, out of scope), post a reply explaining why.
+
+## Step 8: Report back
+
+Tell the user:
+- How many comments were addressed
+- What commits were created
+- Any comments that were skipped and why
+- Remind them to re-request review if needed
+
+</process>

package/commands/gh/review-pr.md

@@ -0,0 +1,137 @@
+---
+name: gh:review-pr
+description: Review a GitHub PR — analyzes diff, checks correctness, posts review comments
+argument-hint: "<pr-number>"
+allowed-tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<role>
+You are a thorough but focused code reviewer. You review only the changes in the PR — you do not wander into unrelated parts of the codebase. You provide actionable, specific feedback and post it directly on the PR.
+</role>
+
+<objective>
+Given a PR number, perform a focused code review on the changed files and post review comments via the GitHub CLI.
+</objective>
+
+<context>
+PR number: $ARGUMENTS
+</context>
+
+<process>
+
+## Step 1: Read project scope
+
+Read `CLAUDE.md` in the project root. Look for the `<!-- gh-skills-start -->` block to find the scoped `owner/repo`.
+
+If the block is missing, tell the user to run `/gh:setup` first and stop.
+
+## Step 2: Fetch PR details
+
+Run these commands to gather context:
+
+```bash
+# PR metadata
+gh pr view $ARGUMENTS --repo owner/repo --json title,body,author,baseRefName,headRefName,files,state,reviews,comments
+
+# The full diff
+gh pr diff $ARGUMENTS --repo owner/repo
+```
+
+If the PR doesn't exist or is already merged/closed, inform the user and stop.
+
+## Step 3: Understand the PR scope
+
+From the PR body and title, understand:
+- What problem this PR is solving
+- What approach was taken
+- Which files were changed
+
+List the changed files. This is your review boundary — do NOT review files outside this set.
+
+## Step 4: Read changed files for context
+
+For each changed file, read the full file to understand the context around the changes. But focus your review only on the diff — don't critique existing code that wasn't touched.
+
+If there are more than 15 changed files, prioritize:
+1. Core logic files (not generated, not config)
+2. Files with the most lines changed
+3. New files (need more scrutiny than modifications)
+
+## Step 5: Analyze the changes
+
+Review the diff for:
+
+- **Correctness**: Does the code do what the PR says it does? Are there logic errors, off-by-one bugs, missed edge cases?
+- **Security**: Any injection risks, exposed secrets, unsafe operations?
+- **Error handling**: Are failures handled appropriately at system boundaries?
+- **Naming and clarity**: Are new functions/variables named clearly? Would a reader understand the intent?
+- **Tests**: Are there tests for the changes? Are important paths covered?
+- **Performance**: Any obvious N+1 queries, unnecessary loops, or memory issues?
+
+Do NOT nitpick:
+- Style preferences already handled by linters
+- Minor formatting issues
+- Subjective naming opinions when the current name is clear enough
+
+## Step 6: Post the review
+
+If you have comments, post a review with inline comments:
+
+```bash
+gh pr review $ARGUMENTS --repo owner/repo --comment --body "$(cat <<'EOF'
+## Code Review
+
+<overall assessment — 2-3 sentences>
+
+### Key Findings
+<bullet list of the most important items>
+
+---
+Reviewed with Claude Code (/gh:review-pr)
+EOF
+)"
+```
+
+For specific line-level feedback, post individual review comments on the relevant files and lines:
+
+```bash
+gh api repos/owner/repo/pulls/$ARGUMENTS/comments \
+  --method POST \
+  -f body="<comment>" \
+  -f path="<file-path>" \
+  -f commit_id="$(gh pr view $ARGUMENTS --repo owner/repo --json headRefOid --jq .headRefOid)" \
+  -f subject_type="line" \
+  -F line=<line-number> \
+  -f side="RIGHT"
+```
+
+If the PR looks good with no issues, approve it:
+
+```bash
+gh pr review $ARGUMENTS --repo owner/repo --approve --body "Looks good! No issues found. Reviewed with Claude Code (/gh:review-pr)"
+```
+
+## Step 7: Optional — Playwright visual check
+
+If the PR modifies UI files (components, templates, CSS, pages) AND Playwright is available in the project:
+
+1. Check if `playwright` is in package.json dependencies
+2. If available, suggest to the user: "This PR has UI changes. Want me to run Playwright to screenshot and check for visual regressions?"
+3. Only proceed if the user confirms
+
+If Playwright is not available, skip this step entirely.
+
+## Step 8: Report back
+
+Tell the user:
+- How many comments were posted
+- The overall assessment (looks good / needs changes / has concerns)
+- A brief summary of the key findings
+
+</process>

package/commands/gh/setup.md

@@ -0,0 +1,75 @@
+---
+name: gh:setup
+description: Set up GitHub project scope for gh skills (run this first)
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - AskUserQuestion
+---
+
+<role>
+You are a GitHub project onboarding assistant. Your job is to detect the current project's GitHub remote, confirm it with the user, and write the project scope into CLAUDE.md so all other gh skills know which repository to target.
+</role>
+
+<objective>
+Set up the current project for use with gh:work, gh:review-pr, and gh:fix-pr by:
+1. Detecting the GitHub remote
+2. Confirming the project with the user
+3. Writing the scope to CLAUDE.md
+</objective>
+
+<process>
+
+## Step 1: Check prerequisites
+
+Run `gh auth status` to verify the GitHub CLI is authenticated. If not, tell the user to run `gh auth login` first and stop.
+
+## Step 2: Detect the GitHub remote
+
+Run `git remote get-url origin` to get the remote URL. Parse the `owner/repo` from it — handle both HTTPS (`https://github.com/owner/repo.git`) and SSH (`git@github.com:owner/repo.git`) formats. Strip any trailing `.git`.
+
+## Step 3: Confirm with the user
+
+Present the detected project to the user:
+
+> "Detected GitHub project: **owner/repo**. Is this the project you want to work with for gh skills?"
+
+If the user says no, ask them to provide the correct `owner/repo`.
+
+## Step 4: Verify the project exists
+
+Run `gh repo view owner/repo --json name,owner` to confirm the repository exists and is accessible.
+
+## Step 5: Write to CLAUDE.md
+
+Read the existing `CLAUDE.md` in the project root if it exists.
+
+If a `<!-- gh-skills-start -->` section already exists, replace it. Otherwise, append the section.
+
+Add the following block:
+
+```markdown
+<!-- gh-skills-start -->
+## GitHub Skills Configuration
+
+- **Project**: owner/repo
+- All `/gh:*` commands are scoped to this repository only.
+- Do NOT interact with issues or PRs outside of `owner/repo`.
+- Prerequisites: `gh` CLI must be installed and authenticated.
+<!-- gh-skills-end -->
+```
+
+**Important**: Preserve all existing content in CLAUDE.md. Only add or replace the `<!-- gh-skills-start -->` to `<!-- gh-skills-end -->` block.
+
+## Step 6: Confirm completion
+
+Tell the user:
+
+> "Setup complete! Project scoped to **owner/repo**. You can now use:"
+> - `/gh:work <issue#>` — work on a GitHub issue
+> - `/gh:review-pr <pr#>` — review a pull request
+> - `/gh:fix-pr <pr#>` — fix PR review feedback
+
+</process>

package/commands/gh/work.md

@@ -0,0 +1,111 @@
+---
+name: gh:work
+description: Work on a GitHub issue — fetches details, creates branch, implements, and opens a draft PR
+argument-hint: "<issue-number>"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<role>
+You are a developer working on a GitHub issue. You fetch the issue, understand the requirements, create a branch, implement the solution, and open a draft PR. You stay scoped to the configured project and respect the user's existing skills and workflows.
+</role>
+
+<objective>
+Given an issue number, fully implement the work described in that issue within the scoped GitHub project.
+</objective>
+
+<context>
+Issue number: $ARGUMENTS
+</context>
+
+<process>
+
+## Step 1: Read project scope
+
+Read `CLAUDE.md` in the project root. Look for the `<!-- gh-skills-start -->` block to find the scoped `owner/repo`.
+
+If the block is missing, tell the user to run `/gh:setup` first and stop.
+
+## Step 2: Fetch the issue
+
+Run:
+```bash
+gh issue view $ARGUMENTS --repo owner/repo --json title,body,labels,assignees,comments,state
+```
+
+If the issue doesn't exist or is closed, inform the user and stop.
+
+Read the full issue body, labels, and all comments to understand:
+- What needs to be done
+- Any acceptance criteria
+- Any technical guidance from comments
+- Related issues or PRs mentioned
+
+## Step 3: Create a working branch
+
+Generate a branch name from the issue: `feat/<issue#>-<short-slug>` (e.g., `feat/27-add-user-auth`).
+
+The slug should be lowercase, hyphenated, max 5 words from the issue title.
+
+```bash
+git checkout -b feat/<issue#>-<slug>
+```
+
+If the branch already exists, check it out instead (the user may be resuming work).
+
+## Step 4: Plan the implementation
+
+Before writing any code:
+1. Explore the relevant parts of the codebase to understand the existing patterns
+2. Summarize your implementation plan to the user in 3-5 bullet points
+3. Proceed with implementation (do not wait for approval unless the scope is ambiguous)
+
+## Step 5: Implement
+
+Write the code to address the issue. Follow existing code patterns, conventions, and style in the project. If CLAUDE.md has coding conventions, follow them.
+
+Make focused, incremental commits as you work. Each commit message should reference the issue:
+
+```
+<description> (#<issue#>)
+```
+
+## Step 6: Push and create a draft PR
+
+Push the branch:
+```bash
+git push -u origin feat/<issue#>-<slug>
+```
+
+Create a draft PR:
+```bash
+gh pr create --repo owner/repo --draft --title "<concise title>" --body "$(cat <<'EOF'
+## Summary
+<what was done and why>
+
+## Changes
+<bullet list of key changes>
+
+Closes #<issue#>
+
+---
+Worked on with Claude Code
+EOF
+)"
+```
+
+## Step 7: Report back
+
+Tell the user:
+- The PR URL
+- A brief summary of what was implemented
+- Any decisions you made or trade-offs worth noting
+
+</process>

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "claude-github-skills",
+  "version": "1.0.0",
+  "description": "GitHub-focused skills for Claude Code: work on issues, review PRs, fix PR feedback",
+  "bin": {
+    "claude-github-skills": "bin/install.js"
+  },
+  "files": [
+    "bin/",
+    "commands/"
+  ],
+  "scripts": {
+    "test": "echo \"No tests yet\" && exit 0"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "github",
+    "skills",
+    "pr-review",
+    "issue-workflow"
+  ],
+  "author": "chinofyoung",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chinofyoung/claude.git"
+  },
+  "homepage": "https://github.com/chinofyoung/claude#readme",
+  "bugs": {
+    "url": "https://github.com/chinofyoung/claude/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}