Building the Perfect GitHub Workflow Skill for Claude Code

A deep dive into designing AI-assisted developer workflows

When I first started using Claude Code, I found myself repeatedly explaining the same gh CLI patterns—how to fetch PR review comments, the right sequence for handling feedback loops, how worktrees fit into a ticket-based workflow. It was getting repetitive. So I decided to encode this knowledge into a skill.

What emerged is /github—my go-to skill for PR workflow automation. Here's how I designed it, and why the design choices matter.

The Problem: Tribal Knowledge Buried in Terminal History

Every engineering team develops their own GitHub workflow rituals. Ours involves:

• Git worktrees for parallel ticket work
• Specific PR body templates linking to Jira
• A feedback loop pattern: fetch comments → fix → reply → re-request review
• Squash merges with branch cleanup

None of this is complicated individually. But strung together, it's a 15-step process that's easy to mess up. Claude is smart enough to figure out gh pr create, but it doesn't know our conventions without being told.

Designing with Skill-Writer Principles

Following the skill-writer guide, I started by identifying the category: workflow automation. This isn't about generating documents or coordinating MCP servers—it's a multi-step process with clear validation gates.

The Description: Trigger Words Matter

From skill-writer:

"The description determines when Claude loads your skill. Get this right."

My description:

1description: Reference for GitHub PR workflow using gh CLI. Use when
2creating pull requests, requesting reviewers, fetching review comments,
3checking CI status, or merging PRs. Covers the full review feedback loop
4pattern.

Note the specific trigger phrases: "creating pull requests", "fetching review comments", "checking CI status". These aren't accidental—they match exactly how I phrase requests in conversation.

Structure: Reference, Not Tutorial

The skill-writer guide recommends keeping SKILL.md concise and actionable. I organized /github as a reference document, not a tutorial:

1## Common Commands
2   └── Create PR
3   └── Request Reviewers
4   └── Check Status
5   └── Merge PR
6
7## Review Feedback Loop
8   └── Fetch Reviews
9   └── Parse Review Feedback
10   └── Respond to Feedback
11
12## Branch Operations (Using Worktrees)
13   ...

Each section is a lookup table. Claude doesn't need an essay—it needs the exact command syntax and the patterns we use.

Embedding Domain Expertise

This is where skills shine over raw documentation. Look at the worktree section:

1# From main repo, create worktree with new branch
2cd ~/code/<org>/<repo>
3git fetch origin
4git worktree add ~/stories/DEX-XXX/repos/<repo> -b DEX-XXX-brief-description origin/main

This encodes a directory convention (~/stories/DEX-XXX/repos/<repo>), our branch naming (DEX-XXX-brief-description), and our base branch pattern (origin/main). Generic gh documentation doesn't know any of this.

The Feedback Loop Pattern

The most valuable part of the skill is the review feedback loop workflow:

1# 1. Fetch feedback
2gh api repos/{owner}/{repo}/pulls/{number}/comments | jq '.[].body'
3
4# 2. Make changes, commit, push
5
6# 3. Reply with commit hash
7gh api repos/{owner}/{repo}/pulls/{number}/comments/{comment_id}/replies \
8  -f body="Fixed in af8040d6 - now validates input"
9
10# 4. Re-request review
11gh pr edit <number> --add-reviewer original-reviewer

This pattern—reply with the fixing commit hash—is a team convention that makes code review faster. Without the skill, I'd have to explain this every time.

What Makes This Skill Work

Looking back, here a few design choices made /github effective:

1. Specific triggers - "fetching review comments" vs just "GitHub"
2. Reference structure - Quick lookups, not narratives
3. Team conventions baked in - Directory layouts, branch naming, merge strategy
4. Complete workflows - Not just individual commands, but the full sequence with validation steps
5. Error handling included - "PR has conflicts", "Checks failing" with exact resolution steps

The Payoff

Now when I say "fetch the review comments on PR 247 and address them", Claude:

• Knows the exact gh api incantation
• Understands our reply convention (include commit hash)
• Follows up with re-requesting review

No context-setting. No explaining our workflow. It just works.

Skills aren't about teaching Claude new capabilities—it already knows gh. Skills are about encoding your team's specific way of working so Claude becomes a true collaborator, not just a command-generator.

The /github skill took maybe an hour to write. It's saved me dozens of hours since.