Add github-project-management skill #121
Conversation
Design for a tactical workflow integration skill that manages GitHub issues and project items at natural development checkpoints (after brainstorming, plan creation, bug discovery, and branch completion). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Tactical workflow integration skill that manages GitHub issues at natural development checkpoints: - After brainstorming (create feature issue) - After writing plans (create task issues) - During implementation (track discovered bugs/debt) - After finishing branches (update/close issues) Includes gh-reference.md with CLI command quick reference. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
WalkthroughThe PR introduces a new GitHub Project Management skill with comprehensive documentation, including design specifications, skill implementation guide, and GitHub CLI command reference for managing issues and project items through integration points in the development workflow. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant Agent
participant GitHub
rect rgb(200, 220, 240)
Note over Agent,GitHub: Integration Point 1: After Brainstorming
Agent->>User: Propose issues based on design
User-->>Agent: Confirm/reject proposals
Agent->>GitHub: Create confirmed issues
end
rect rgb(220, 240, 200)
Note over Agent,GitHub: Integration Point 2: After Writing Plans
Agent->>User: Propose task breakdown as issues
User-->>Agent: Confirm/reject proposals
Agent->>GitHub: Create/associate confirmed issues
end
rect rgb(240, 220, 200)
Note over Agent,GitHub: Integration Point 3: During Implementation
Agent->>User: Propose bugs/tech debt as issues
User-->>Agent: Confirm/reject proposals
Agent->>GitHub: Create issues in project
end
rect rgb(240, 230, 220)
Note over Agent,GitHub: Integration Point 4: After Branch Completion
Agent->>GitHub: Update/close associated issues
GitHub-->>User: Reflect work completion
end
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
woo, claude got over-eager and opened this on its own. Swapping to draft! |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (4)
skills/github-project-management/gh-reference.md (2)
15-31: Add language specifications to all fenced code blocks for consistent rendering.All bash command examples in this file lack language specifications. Add
bashto each code block for proper syntax highlighting:-``` +```bash # List projects for owner gh project list --owner obraThis applies to all five code block sections: Project Operations (lines 15–31), Issue Operations (lines 35–60), Project Item Operations (lines 64–83), Common Workflows (lines 89–103), and JSON Output Examples (lines 137–146).
Also applies to: 35-60, 64-83, 89-103, 137-146
1-146: Ensure consistent capitalization of "GitHub" throughout.The official name of the platform is "GitHub" (capital G and H). Review for instances where it appears as "github" in variable names like
github_project(which is correct as a configuration key), but in prose text, use "GitHub". For example, line 1 reads well, but double-check any prose references for consistency.Based on static analysis hints, verify lines around configuration examples use proper capitalization in descriptive text.
skills/github-project-management/SKILL.md (1)
18-22: Add language specifications to code blocks for consistency.Similar to gh-reference.md, add language identifiers to fenced code blocks:
- Lines 18–22:
markdown(CLAUDE.md config example)- Lines 39–42:
markdown(issue template example)- Lines 68–71:
markdown(issue template example)- Lines 112–122:
bash(CLI commands)-``` +```markdown ## GitHub ProjectAlso applies to: 39-42, 68-71, 112-122
docs/plans/2025-11-25-github-project-management-design.md (1)
19-23: Add language specifications to code blocks.Fenced code blocks should specify a language for consistent rendering. Apply these changes:
- Lines 19–23:
markdown(CLAUDE.md config)- Lines 26–32:
markdown(config examples)- Lines 56–67:
markdown(feature issue template)- Lines 101–113:
markdown(bug/tech debt template)- Lines 132–138:
bash(auth commands)-``` +```markdown ## GitHub ProjectAlso applies to: 26-32, 56-67, 101-113, 132-138
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
docs/plans/2025-11-25-github-project-management-design.md(1 hunks)skills/github-project-management/SKILL.md(1 hunks)skills/github-project-management/gh-reference.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
skills/github-project-management/SKILL.md
[uncategorized] ~24-~24: The official name of this software platform is spelled with a capital “H”.
Context: ...ct: owner/project-number ``` Examples: github_project: obra/1 (user) or `github_proj...
(GITHUB)
[uncategorized] ~24-~24: The official name of this software platform is spelled with a capital “H”.
Context: ...les: github_project: obra/1 (user) or github_project: my-org/5 (org) If missing, a...
(GITHUB)
docs/plans/2025-11-25-github-project-management-design.md
[uncategorized] ~34-~34: The official name of this software platform is spelled with a capital “H”.
Context: ...ject github_project: my-org/5 ``` - If github_project is missing and agent needs to ...
(GITHUB)
🪛 markdownlint-cli2 (0.18.1)
skills/github-project-management/SKILL.md
39-39: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
68-68: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/plans/2025-11-25-github-project-management-design.md
56-56: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
101-101: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (5)
skills/github-project-management/gh-reference.md (1)
1-146: Documentation is well-structured and comprehensive.The reference guide covers prerequisites, common operations, workflows, and examples clearly. The progression from simple to complex commands is logical, and copy-pasteable examples will serve users well. Cross-references to SKILL.md and design doc are implicit and helpful.
skills/github-project-management/SKILL.md (2)
30-85: Integration points are well-defined and include helpful context.The four integration points (Brainstorming, Writing Plans, Implementation, Finishing Branch) are clearly triggered, actionable, and include issue templates. The decision tree for bug discovery (lines 61–63) is practical. The "Common Rationalizations" table (lines 96–103) provides useful guidance for agent behavior that avoids over-apologizing for workflow integration.
87-95: Issue type guidance (repo vs. project draft) is clear and actionable.The table at lines 89–94 effectively distinguishes when to use repo issues (single-repo, referenced in commits) versus project drafts (cross-repo, unclear scope). This guidance will help users and agents make the right choice.
docs/plans/2025-11-25-github-project-management-design.md (2)
1-159: Design document is comprehensive, well-aligned, and appropriately scoped.The design clearly distinguishes repo issues from project drafts, defines configuration, integration points with triggers and templates, and explains what the skill is NOT. The alignment with SKILL.md and gh-reference.md is strong, and the explicit confirmation requirement (line 39) matches the PR objectives. The authentication section ensures users have the necessary tooling setup.
42-127: Integration points are well-rationalized and include clear decision criteria.Each of the four integration points includes:
- A clear trigger (e.g., "Brainstorming skill completes and writes design doc to
docs/plans/")- Detailed agent behavior with confirmation steps
- Practical issue templates with relevant fields
- Context for decision-making (e.g., bug discovery decision tree at lines 88–92)
This structure will help implementers understand when and how to surface issue creation prompts to users.
There was a problem hiding this comment.
I presume we probably don't want to keep these around, but...maybe we do?
|
So, I don't find claude to need help with doing this using the gh tool. can you tell me more about the use case or problem you're solving? |
|
@obra For one org I am part of, we use gh projects to do our basic project management, especially since our work is not in a monorepo and various work may cut across multiple repos. I was finding I needed to keep prompting it on how to drive the issue tracking and roadmap that is in our gh project via the cli and decided at least a cli reference sheet was in order instead of it grepping around the cli I then found that this would pair well with a general skill around project management, and started throwing design docs, meeting notes for product prioritization, general product ideas, etc at it. I'm using this skill to do the grunt work of |
2 participants
Summary
gh projectandgh issuecommandsI think I'd like to re-write this to be a generic "Project Management" skill with instructions to use the appropriate reference file for the particular project management software you may be using in your project (gh projects, Jira, etc, simple gh issues only), etc. However, I think it would be good to do some extended play with this first with my known use-case of GH projects and iterate.
Blocker
As written, I think this is too tightly coupled to be invoked and it should be entirely optional. I'm not sure if there are known, deterministic practices around selectively enabling or disabling skills within a claude "Skill".
Files
skills/github-project-management/SKILL.md- workflow integration skillskills/github-project-management/gh-reference.md- CLI command referencedocs/plans/2025-11-25-github-project-management-design.md- design documentTest plan
🤖 Generated with Claude Code
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.