Agent skill

github-project-operator

Manages GitHub Projects v2 write operations using gh CLI. Use when adding issues or PRs to a project, creating tasks (issues) in a project, updating field values (Status, Priority, Size, Sprint, etc.), creating draft issues, creating fields, or archiving items. Also use at the start of a session when selecting a project to work with.

View SKILL.md on GitHub Repository
Stars 1
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/scizorman/dotfiles/tree/main/modules/home/coding-agent/config/skills/github-project-operator

SKILL.md

GitHub Project Operator

This skill defines rules and procedures for write operations on GitHub Projects v2.

Session Initialization: Project Selection

At the start of each session, select the target project and collect all required IDs.

Step 1: List Projects

bash
gh project list --owner "@me" --format json

Present the list to the user and ask which project to use.

Step 2: Collect Project Metadata

Once the user selects a project, retrieve the Project ID and field definitions in one batch.

bash
# Get the project number from the list output
gh project view <NUMBER> --owner "@me" --format json

# List all fields with their IDs and option IDs
gh project field-list <NUMBER> --owner "@me" --format json

Retain the following values for the entire session:

Value Description
Project ID id field from gh project view (node ID format: PVT_...)
Field ID id field per field from gh project field-list
Option ID id per option within single-select fields

For field type specifics and ID resolution procedures, see references/field-operations.md.

Workflow: Create a Task

Use this workflow when the user wants to create a new issue and add it to the project.

Step 1: Create the Issue

Use the github-issue-creator skill to create the issue. This applies issue templates, title guidelines, and language settings.

Note the issue URL from the output (e.g., https://github.com/OWNER/REPO/issues/123).

Step 2: Add the Issue to the Project

bash
gh project item-add <PROJECT_NUMBER> --owner "@me" --url <ISSUE_URL>

Note the item ID from the output (PVTI_...).

Step 3: Set Field Values

Set Status, Priority, Size, Sprint, and other fields as needed.

bash
gh project item-edit \
  --project-id <PROJECT_ID> \
  --id <ITEM_ID> \
  --field-id <FIELD_ID> \
  --single-select-option-id <OPTION_ID>

For the full flag reference by field type, see references/field-operations.md.

Workflow: Create a Sub-task

Use the github-issue-creator skill with the parent issue number to create and link the sub-issue, then add it to the project following the same steps as above.

Workflow: Add Existing Issue or PR to Project

bash
gh project item-add <PROJECT_NUMBER> --owner "@me" --url <ISSUE_OR_PR_URL>

Workflow: Create a Draft Issue

Draft issues exist only within the project and have no associated repository issue.

bash
gh project item-create <PROJECT_NUMBER> --owner "@me" \
  --title "<title>" \
  --body "<body>"

After creation, set field values using gh project item-edit as needed.

Workflow: Update Field Values

When updating fields on an existing project item:

  1. Resolve the item ID if not already known:
bash
gh project item-list <PROJECT_NUMBER> --owner "@me" --format json | \
  jq '.items[] | select(.content.number == <ISSUE_NUMBER>)'
  1. Update the field:
bash
gh project item-edit \
  --project-id <PROJECT_ID> \
  --id <ITEM_ID> \
  --field-id <FIELD_ID> \
  --single-select-option-id <OPTION_ID>   # for single-select fields

For other field types (number, date, text, iteration), see references/field-operations.md.

Workflow: Create a Field

bash
gh project field-create <PROJECT_NUMBER> --owner "@me" \
  --name "<Field Name>" \
  --data-type <TYPE>

Supported --data-type values: TEXT, NUMBER, DATE, SINGLE_SELECT, ITERATION.

For SINGLE_SELECT, options must be added via the GitHub web UI or GraphQL API after creation.

Workflow: Archive an Item

bash
gh project item-archive <PROJECT_NUMBER> --owner "@me" --id <ITEM_ID>

Notes

  • Always resolve Project ID, Field ID, and Option ID before making edits. These IDs are node IDs (e.g., PVT_..., PVTF_..., 62c28424), not human-readable names.
  • Project numbers (integers) are used with gh project item-add, gh project item-list, and gh project field-list. Project IDs (node IDs) are used with gh project item-edit.
  • When the user does not specify field values, omit them rather than guessing defaults.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

scizorman/dotfiles

project-plan-creator

Creates project management plans in Markdown. Use when creating project plans, defining how to manage scope/schedule/risk/communication, or detailing project execution strategy. Primarily for internal projects that build systems, processes, or organizational capabilities.

1 0
Explore
scizorman/dotfiles

github-issue-creator

Create GitHub issues with gh CLI, including standard issues and sub-issues linked to a parent issue. Use when creating a new issue, breaking down a larger issue into child issues, or establishing a parent-child relationship between issues. Detect repository issue templates, apply title and body conventions, and create the issue with gh CLI.

1 0
Explore
scizorman/dotfiles

github-issue-pr-commenter

Post structured comments to GitHub Issues and Pull Requests with gh CLI. Use when reporting completed work, sharing progress, summarizing investigation results, recording design decisions, proposing implementation plans, asking for feedback, or adding supplementary context to a pull request conversation. Do not use for inline pull request review comments on specific files or lines.

1 0
Explore
scizorman/dotfiles

github-pr-creator

Submit changes as a GitHub Pull Request with gh CLI. Covers the full workflow: issue confirmation, branch naming, ghq-based git worktree creation or reuse, commit and push, PR template detection, and PR creation with gh pr create. Use when creating a pull request, opening a PR, starting work on an issue, or cutting a working branch.

1 0
Explore
scizorman/dotfiles

project-charter-creator

Use this skill whenever the user wants to create, draft, or improve a Project Charter. Triggers include: any mention of 'project charter', 'charter', 'プロジェクト憲章', 'プロジェクトチャーター', 'プロジェクト企画書', or requests to formally authorize a project, define project scope and objectives, align stakeholders, or establish project governance. Also use when the user says 'プロジェクトの立ち上げ', 'プロジェクトの認可', 'キックオフ文書', or mentions needing to get sponsor approval for a project. This skill covers project charters for any methodology (Waterfall, Agile, Lean Six Sigma) and any domain (IT, construction, marketing, organizational change, product development, etc.). Use this skill even if the user just says 'help me start a project' or 'I need to get alignment on my project'.

1 0
Explore
scizorman/dotfiles

github-project-reporter

Reads and analyzes GitHub Projects v2 data using gh CLI. Use when listing items by status, extracting high-priority tasks, generating sprint progress summaries, detecting blockers or health issues (unassigned items, overdue items, WIP excess), or producing progress reports.

1 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results