yu-iskw GitHub Project Management
Purpose
Consolidates all GitHub Project (v2) operations into a single, token-efficient skill. This reduces context overhead and simplifies workflows for synchronizing issues with project boards.
1. Safety & Verification
- Mandatory Context: Ensure
gh-verifying-contexthas been run and confirmed by the user. - Human-in-the-Loop: You MUST present all state-changing commands (add item, edit field, archive, delete) and their parameters to the user before execution.
- Verification: Always verify Project IDs and Item IDs before editing. Use listing workflows if these are unknown.
- Owner Flag: Ensure the correct
--owner(user or organization) is specified.
2. Common Workflows
Workflow: Identify Project and Items
Finds the target project and lists its current contents.
Command:
# List projects for an owner
gh project list --owner "my-org" --json number,title,id
# List items in a project
gh project item-list <project-number> --owner "my-org" --json id,title,content
Workflow: Add and Categorize Items
Adds an issue to a project and moves it to a specific status.
Command:
# Add issue to project
gh project item-add <project-number> --owner <owner> --url <issue-url>
# Update a field (e.g., Status)
gh project item-edit --id <item-id> --project-id <project-id> --field-id <field-id> --single-select-option-id <option-id>
Workflow: Manage Project Structure
Discovers fields and creates draft items.
Command:
# List fields in a project
gh project field-list <project-number> --owner <owner> --json id,name,options
# Create a draft issue
gh project item-create <project-number> --owner <owner> --title "Draft Title" --body "Draft Body"
3. Reference Table of Actions
See references/commands.md for the full action reference table, ID type guide, and list of state-changing commands that require approval.
4. Output Handling
Always prefer --json for structured data. The internal Item ID (e.g., PVTI_...) is critical for item-edit and item-archive operations, while the Project Number is used for item-list and item-add.