Help us improve
Share bugs, ideas, or general feedback.
From compass-rose
This skill provides Python scripts for reliable GitHub Project API operations. It replaces embedded GraphQL guidance in command markdown files with tested, reusable abstractions.
npx claudepluginhub rjroy/vibe-garden --plugin compass-roseHow this skill is triggered — by the user, by Claude, or both
Slash command
/compass-rose:gh-api-scriptsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill provides Python scripts for reliable GitHub Project API operations. It replaces embedded GraphQL guidance in command markdown files with tested, reusable abstractions.
Manages GitHub Projects v2 via gh CLI: create/edit/list projects, add issues/PRs as items, manage fields, link repos, automate workflows.
Triages GitHub issues by viewing content, determining and setting project fields (component, priority, size), issue type (Bug/Feature/Task), and milestone.
Manage GitHub issues via CLI with bulk operations, JSON/jq parsing, search filters, and issue-to-PR workflow. Also stores AI session context for resuming tasks.
Share bugs, ideas, or general feedback.
This skill provides Python scripts for reliable GitHub Project API operations. It replaces embedded GraphQL guidance in command markdown files with tested, reusable abstractions.
Operations require a configuration file at .compass-rose/config.json:
{
"project": {
"owner": "<org-or-username>",
"owner_type": "user",
"number": <project-number>
}
}
| Field | Type | Description |
|---|---|---|
owner | string | GitHub username or organization name |
owner_type | string | Either "user" or "organization" |
number | integer | Project number (from project URL) |
"user" for personal projects: github.com/users/<name>/projects/<n>"organization" for org projects: github.com/orgs/<name>/projects/<n>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:
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 repositoryISSUE_NOT_IN_PROJECT - Issue exists but isn't linked to the configured projectUpdate 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:
"Ready", "In progress", "Done", "To Do"Error Cases:
STATUS_INVALID - Provided status value doesn't match project optionsFIELD_NOT_FOUND - Project doesn't have a Status field configuredAdd 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:
item_id can be used for subsequent field updatesError Cases:
ISSUE_NOT_FOUND - Issue number doesn't exist in the repositoryUpdate 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:
"P0", "P1", "P2", "P3"Error Cases:
STATUS_INVALID - Provided priority value doesn't match project optionsFIELD_NOT_FOUND - Project doesn't have a Priority field configuredISSUE_NOT_IN_PROJECT - Issue is not linked to the configured projectUpdate 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:
"S", "M", "L", "XL"Error Cases:
STATUS_INVALID - Provided size value doesn't match project optionsFIELD_NOT_FOUND - Project doesn't have a Size field configuredISSUE_NOT_IN_PROJECT - Issue is not linked to the configured projectAll 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"
}
}
| 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 |
gh CLI installed and authenticatedproject scope authorized (gh auth refresh -s project)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 |
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)'
.sdd/specs/2025-12-24-compass-rose-gh-api-scripts.md.sdd/plans/2025-12-24-compass-rose-gh-api-scripts-plan.md.sdd/tasks/2025-12-25-compass-rose-gh-api-scripts-tasks.md