GitHub Project Operator Skill

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

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.

# 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

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.

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-sub-issue-creator skill to create a sub-issue linked to a parent issue, then add it to the project following the same steps as above.

Workflow: Add Existing Issue or PR to Project

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.

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:

Resolve the item ID if not already known:

gh project item-list <PROJECT_NUMBER> --owner "@me" --format json | \
  jq '.items[] | select(.content.number == <ISSUE_NUMBER>)'

Update the field:

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

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

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.

Agent Skills: GitHub Project Operator

Install this agent skill to your local

Skill Files