GitHub API Scripts Skill

Overview

This skill provides Python scripts for reliable GitHub Project API operations. It replaces embedded GraphQL guidance in command markdown files with tested, reusable abstractions.

Configuration

Operations require a configuration file at .compass-rose/config.json:

json

{
  "project": {
    "owner": "<org-or-username>",
    "owner_type": "user",
    "number": <project-number>
  }
}

Required Fields

Field	Type	Description
`owner`	string	GitHub username or organization name
`owner_type`	string	Either `"user"` or `"organization"`
`number`	integer	Project number (from project URL)

Owner Type

•Use "user" for personal projects: github.com/users/<name>/projects/<n>
•Use "organization" for org projects: github.com/orgs/<name>/projects/<n>

Operations

list-issues

List all open issues in the configured project with automatic pagination.

bash

${CLAUDE_PLUGIN_ROOT}/skills/gh-api-scripts/scripts/gh_project.sh list-issues

Example Output:

json

{
  "success": true,
  "data": {
    "issues": [
      {
        "number": 42,
        "title": "Fix login timeout",
        "body": "Users experiencing timeouts after 30 seconds...",
        "url": "https://github.com/my-org/my-repo/issues/42",
        "state": "OPEN",
        "labels": ["bug", "priority-high"],
        "status": "Ready",
        "priority": "P0",
        "size": "S"
      },
      {
        "number": 58,
        "title": "Add user preferences panel",
        "body": "Feature request for user settings...",
        "url": "https://github.com/my-org/my-repo/issues/58",
        "state": "OPEN",
        "labels": ["feature"],
        "status": "To Do",
        "priority": "P1",
        "size": "M"
      }
    ],
    "count": 2
  }
}

Notes:

•Automatically paginates through projects with >100 items
•Only returns issues in OPEN state
•Field values (status, priority, size) are extracted from project custom fields

get-issue

Get a single issue by number with full project field values.

bash

${CLAUDE_PLUGIN_ROOT}/skills/gh-api-scripts/scripts/gh_project.sh get-issue <number>

Example:

bash

${CLAUDE_PLUGIN_ROOT}/skills/gh-api-scripts/scripts/gh_project.sh get-issue 42

Example Output:

json

{
  "success": true,
  "data": {
    "issue": {
      "number": 42,
      "title": "Fix login timeout",
      "body": "Users experiencing timeouts after 30 seconds...",
      "url": "https://github.com/my-org/my-repo/issues/42",
      "state": "OPEN",
      "labels": ["bug", "priority-high"],
      "status": "Ready",
      "priority": "P0",
      "size": "S"
    }
  }
}

Error Cases:

•ISSUE_NOT_FOUND - Issue number doesn't exist in the repository
•ISSUE_NOT_IN_PROJECT - Issue exists but isn't linked to the configured project

set-status

Update the Status field of an issue in the project.

bash

${CLAUDE_PLUGIN_ROOT}/skills/gh-api-scripts/scripts/gh_project.sh set-status <number> "<status>"

Example:

bash

${CLAUDE_PLUGIN_ROOT}/skills/gh-api-scripts/scripts/gh_project.sh set-status 42 "In progress"

Example Output:

json

{
  "success": true,
  "data": {
    "issue_number": 42,
    "previous_status": "Ready",
    "new_status": "In progress"
  }
}

Notes:

•Status value must match one of the project's configured status options (case-sensitive)
•Common status values: "Ready", "In progress", "Done", "To Do"

Error Cases:

•STATUS_INVALID - Provided status value doesn't match project options
•FIELD_NOT_FOUND - Project doesn't have a Status field configured

add-to-project

Add an existing repository issue to the configured project.

bash

${CLAUDE_PLUGIN_ROOT}/skills/gh-api-scripts/scripts/gh_project.sh add-to-project <number>

Example:

bash

${CLAUDE_PLUGIN_ROOT}/skills/gh-api-scripts/scripts/gh_project.sh add-to-project 156

Example Output:

json

{
  "success": true,
  "data": {
    "issue_number": 156,
    "item_id": "PVTI_lADOBQ..."
  }
}

Notes:

•Issue must exist in the repository before adding to project
•The returned item_id can be used for subsequent field updates

Error Cases:

•ISSUE_NOT_FOUND - Issue number doesn't exist in the repository

set-priority

Update the Priority field of an issue in the project.

bash

${CLAUDE_PLUGIN_ROOT}/skills/gh-api-scripts/scripts/gh_project.sh set-priority <number> "<priority>"

Example:

bash

${CLAUDE_PLUGIN_ROOT}/skills/gh-api-scripts/scripts/gh_project.sh set-priority 42 "P1"

Example Output:

json

{
  "success": true,
  "data": {
    "number": 42,
    "previous_priority": null,
    "new_priority": "P1"
  }
}

Notes:

•Priority value must match one of the project's configured priority options (case-sensitive)
•Common priority values: "P0", "P1", "P2", "P3"

Error Cases:

•STATUS_INVALID - Provided priority value doesn't match project options
•FIELD_NOT_FOUND - Project doesn't have a Priority field configured
•ISSUE_NOT_IN_PROJECT - Issue is not linked to the configured project

set-size

Update the Size field of an issue in the project.

bash

${CLAUDE_PLUGIN_ROOT}/skills/gh-api-scripts/scripts/gh_project.sh set-size <number> "<size>"

Example:

bash

${CLAUDE_PLUGIN_ROOT}/skills/gh-api-scripts/scripts/gh_project.sh set-size 42 "M"

Example Output:

json

{
  "success": true,
  "data": {
    "number": 42,
    "previous_size": null,
    "new_size": "M"
  }
}

Notes:

•Size value must match one of the project's configured size options (case-sensitive)
•Common size values: "S", "M", "L", "XL"

Error Cases:

•STATUS_INVALID - Provided size value doesn't match project options
•FIELD_NOT_FOUND - Project doesn't have a Size field configured
•ISSUE_NOT_IN_PROJECT - Issue is not linked to the configured project

Output Format

All operations return JSON with a consistent envelope:

Success:

json

{
  "success": true,
  "data": { ... }
}

Error:

json

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": "Actionable remediation guidance"
  }
}

Error Codes

Code	When	Remediation
`CONFIG_MISSING`	Config file not found	Create `.compass-rose/config.json`
`CONFIG_INVALID`	Required fields missing or invalid	Check owner, owner_type, number fields
`AUTH_REQUIRED`	gh CLI not authenticated	Run `gh auth login`
`AUTH_SCOPE_MISSING`	project scope not authorized	Run `gh auth refresh -s project`
`ISSUE_NOT_FOUND`	Issue number doesn't exist	Verify issue number
`ISSUE_NOT_IN_PROJECT`	Issue not linked to project	Add issue to project first
`STATUS_INVALID`	Status value not valid	Check project's status options
`FIELD_NOT_FOUND`	Status field not in project	Add Status field to project
`RATE_LIMITED`	API rate limit exceeded	Wait and retry
`API_ERROR`	Other API errors	Check error details

Requirements

•Python 3.12+ (stdlib only, no pip dependencies)
•gh CLI installed and authenticated
•project scope authorized (gh auth refresh -s project)

Usage in Commands

This skill is used by Compass Rose commands to interact with GitHub Projects:

Command	Operations Used
`/backlog`	`list-issues`
`/next-item`	`list-issues`
`/start-work`	`get-issue`, `set-status`
`/add-item`	`add-to-project`, `set-status`, `set-priority`, `set-size`
`/reprioritize`	`list-issues`, `set-priority`, `set-status`

Common Patterns

Check for errors before processing:

bash

RESPONSE=$(${CLAUDE_PLUGIN_ROOT}/skills/gh-api-scripts/scripts/gh_project.sh list-issues)

if echo "$RESPONSE" | jq -e '.success == false' > /dev/null; then
  echo "$RESPONSE" | jq -r '.error.details'
  exit 1
fi

# Process successful response
echo "$RESPONSE" | jq '.data.issues'

Filter by status:

bash

# Get only "Ready" items
echo "$RESPONSE" | jq '[.data.issues[] | select(.status == "Ready")]'

Sort by priority:

bash

# Sort by priority (P0 first)
echo "$RESPONSE" | jq '.data.issues | sort_by(.priority)'

Gh Api Scripts

GitHub API Scripts Skill

Overview

Configuration

Required Fields

Owner Type

Operations

list-issues

get-issue

set-status

add-to-project

set-priority

set-size

Output Format

Error Codes

Requirements

Usage in Commands

Common Patterns

Related Documentation