GitHub API Scripts Skill

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:

{
  "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.

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

Example Output:

{
  "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.

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

Example:

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

Example Output:

{
  "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.

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

Example:

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

Example Output:

{
  "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.

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

Example:

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

Example Output:

{
  "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.

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

Example:

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

Example Output:

{
  "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.

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

Example:

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

Example Output:

{
  "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:

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

Error:

{
  "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:

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:

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

Sort by priority:

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

Related Documentation

• Spec: .sdd/specs/2025-12-24-compass-rose-gh-api-scripts.md
• Plan: .sdd/plans/2025-12-24-compass-rose-gh-api-scripts-plan.md
• Tasks: .sdd/tasks/2025-12-25-compass-rose-gh-api-scripts-tasks.md