issue-progress-tracking — Claude Code skill: setup & guide
issue-progress-tracking guides GitHub issue ceremonies using the gh CLI by updating progress labels, creating dedicated branches, enforcing atomic commits, and linking PRs.
MIT 221 installs ★ 305 updated 2026-10-24
npx skills add yonatangross/orchestkit --skill issue-progress-tracking -a claude-codeWhat issue-progress-tracking does
The skill standardizes tracking GitHub issues using the gh CLI and Bash. When work begins, it applies the status:in-progress label, clears status:todo, writes an initial comment, and branches off the default branch using the issue/<number>-description pattern. Commits follow conventional syntax and link directly to the issue number.
Once implementation wraps up, the skill generates a pull request containing Closes #N and switches labels to status:in-review. Manually running gh issue close is restricted. Issues close strictly via merged pull requests.
This configuration sets user-invocable: false and disable-model-invocation: true. You cannot run it as a slash command, and the model does not trigger it automatically. Instead, parent workflows explicitly read the skill file.
What it helps with
- label issues as in-progress and branch from main
- format atomic commits linked to issue numbers
- post progress updates to long-running tasks
- open pull requests that close target issues upon merge
Example prompts for the agent
- Start working on issue #42 and create the feature branch
- Post a status update on issue #15 with completed components
- Create a pull request for issue #108 and set its label to in-review
How to install issue-progress-tracking
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill issue-progress-tracking -a claude-code2Manually: put the files in place
~/.claude/skills/issue-progress-tracking/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/issue-progress-tracking/
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill issue-progress-tracking -a codex2Manually: put the files in place
.agents/skills/issue-progress-tracking/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill issue-progress-tracking -a cursor2Manually: put the files in place
.cursor/skills/issue-progress-tracking/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install yonatangross/orchestkit src/skills/issue-progress-tracking2Manually: put the files in place
.github/skills/issue-progress-tracking/SKILL.md1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill issue-progress-tracking -a gemini-cli2Platform CLI
gemini skills install https://github.com/yonatangross/orchestkit --path src/skills/issue-progress-trackingManually: put the files in place
.devin/skills/issue-progress-tracking/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill issue-progress-tracking -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about issue-progress-tracking
How do I install issue-progress-tracking in Claude Code?
Run npx skills add yonatangross/orchestkit --skill issue-progress-tracking -a claude-code. The file will be placed at ~/.claude/skills/issue-progress-tracking/SKILL.md.
What does issue-progress-tracking do?
It orchestrates the GitHub issue lifecycle via the gh command-line tool. It manages branch naming, atomic commit formats, milestone comments, and pull request linking.
Can I run this skill with a slash command?
No, it has user-invocable: false and disable-model-invocation: true. An agent loads the file explicitly as part of an orchestration workflow rather than through a slash command.
Source text
SKILL.md · MIT
---
name: issue-progress-tracking
license: MIT
compatibility: "Claude Code 2.1.277+."
description: "GitHub issue workflow ceremony using gh CLI — labels issues as in-progress, creates feature branches (issue/N-description), commits with issue references, posts progress comments, and links PRs with Closes #N. Keeps issues in sync with development work. Use when starting work on an issue, tracking progress, or completing work with a PR."
context: inherit
user-invocable: false
disable-model-invocation: true
allowed-tools: "Bash"
effort: low
model: haiku
metadata:
category: workflow-automation
version: "1.0.0"
author: "OrchestKit"
complexity: "low"
tags: "git, github, issues, tracking, workflow"
---
# Issue Progress Tracking
Ceremony guide for tracking GitHub issue progress via `gh` CLI. Ensures issues stay updated as work progresses from start to PR.
## Invocation
This skill is `user-invocable: false` and `disable-model-invocation: true`:
there is no `/ork:` form and the model cannot auto-select it (#3313). An agent
loads it explicitly by Reading this file's path:
```text
${CLAUDE_PLUGIN_ROOT}/skills/issue-progress-tracking/SKILL.md
```
---
## Phase 1: Start Work
Label the issue and create a feature branch:
```bash
# Move issue to in-progress
gh issue edit $ARGUMENTS[0] --add-label "status:in-progress" --remove-label "status:todo"
gh issue comment $ARGUMENTS[0] --body "Starting work on this issue."
# Create feature branch
git checkout -b issue/$ARGUMENTS[0]-brief-description
```
**Rules:**
- Always branch from the default branch (main/dev)
- Branch name format: `issue/<number>-<brief-description>`
- Never work directly on main/dev
---
## Phase 2: During Work — Small Commits
Commit after each logical step, not at the end. Every commit references the issue:
```bash
# Each commit references the issue number
git commit -m "feat(#$ARGUMENTS[0]): add user model
Co-Authored-By: Claude <[email protected]>"
```
**Rules:**
- One logical change per commit (atomic)
- Reference issue in every commit: `type(#N): description`
- Commit early and often — don't accumulate a massive diff
---
## Phase 3: Report Progress (Long Implementations)
For multi-step work, post progress updates:
```bash
gh issue comment $ARGUMENTS[0] --body "Progress update:
- Completed: database schema, API endpoints
- In progress: frontend components
- Remaining: tests, documentation"
```
**When to post updates:**
- After completing a major milestone
- When blocked or changing approach
- Before stepping away from a long task
---
## Phase 4: Complete Work
Create the PR and update labels:
```bash
# Create PR that closes the issue
gh pr create \
--title "feat(#$ARGUMENTS[0]): brief description" \
--body "Closes #$ARGUMENTS[0]
## Changes
- Change 1
- Change 2
## Test Plan
- [ ] Unit tests pass
- [ ] Manual verification"
# Update issue status
gh issue edit $ARGUMENTS[0] --add-label "status:in-review" --remove-label "status:in-progress"
```
---
## Rules Quick Reference
| Rule | Impact | What It Covers |
|------|--------|----------------|
| [Start Work Ceremony](rules/start-work-ceremony.md) | HIGH | Branch creation, label updates, initial comment |
| [Small Commits](rules/small-commits.md) | HIGH | Atomic commits referencing issues |
**Total: 2 rules across 2 categories**
---
## Key Decisions
| Decision | Choice | Rationale |
|----------|--------|-----------|
| Label prefix | `status:` | Consistent with GitHub conventions |
| Branch format | `issue/<N>-desc` | Links branch to issue automatically |
| Commit reference | `type(#N):` | Conventional commits + issue linking |
| Progress comments | Manual | Keeps humans in the loop |
---
## Common Mistakes
1. **Starting work without labeling** — team loses visibility into who is working on what
2. **Giant commits at the end** — makes review harder and history useless for bisect
3. **Forgetting to link PR to issue** — issue stays open after merge
4. **Not updating labels on PR creation** — issue shows "in-progress" during review
5. **Closing issues manually with `gh issue close`** — issues are closed ONLY by merging a PR with `Closes #N` in the body. During work, comment progress with `gh issue comment`; never close directly.
---
## Related Skills
- `ork:commit` — Commit with conventional format
- `ork:fix-issue` — Full issue resolution workflow
- `ork:implement` — Feature implementation with parallel agents
- `ork:create-pr` — Create pull requests
© OrchestKit · MIT · yonatangross/orchestkit