Use when managing team tasks through GitHub Projects V2 or synchronizing project state via GraphQL API. Trigger with /sync-projects or when updating project items.
Use when managing team tasks through GitHub Projects V2 or synchronizing project state via GraphQL API. Trigger with /sync-projects or when updating project items.
license
Apache-2.0
compatibility
Requires GitHub CLI authentication, GitHub Projects V2 enabled repository, GraphQL API access, Python 3.8+, and AI Maestro integration for notifications. Requires AI Maestro installed.
metadata
{"author":"Emasoft","version":"1.0.0"}
agent
api-coordinator
context
fork
workflow-instruction
Step 13
procedure
proc-populate-kanban
user-invocable
false
GitHub Projects Sync
Overview
The GitHub Projects Sync skill enables the INTEGRATOR-AGENT to manage team tasks through GitHub Projects V2. This is the OFFICIAL task management interface for coordinating work across remote developer agents.
Claude Tasks = Orchestrator personal tasks ONLY (reading docs, planning, reviewing)
Prerequisites
GitHub CLI (gh) installed and authenticated with project scope
GitHub Projects V2 enabled repository
GraphQL API access
Python 3.8+ for automation scripts
AI Maestro integration for notifications (optional)
Instructions
Follow these steps when using this skill:
Identify the task type - Determine if you need to create, update, query, or sync GitHub Projects data
Authenticate - Verify GitHub CLI is authenticated with gh auth status and has project scope
Locate the project - Find the project ID using GraphQL queries (see Quick Start section below)
Select the appropriate operation - Refer to the Reference Documentation section to find the matching use case
Execute the operation - Use GraphQL API via gh api graphql or run automation scripts
Verify the result - Check the project board or query the API to confirm the change was applied
Notify stakeholders - Send AI Maestro messages to relevant agents if coordination is needed
Document the change - Add comments to issues or update task lists to maintain audit trail
Checklist
Copy this checklist and track your progress:
Identify the task type (create/update/query/sync)
Verify GitHub CLI authentication with project scope
Locate the project using GraphQL queries
Select the appropriate operation from reference documentation
Execute the operation via GraphQL API or automation scripts
Verify the result on the project board or via API query
Notify stakeholders via AI Maestro if needed
Document the change in issue comments or task lists
When to invoke this skill:
Assigning GitHub issues to remote agents
Tracking feature implementation progress
Synchronizing PR status with project boards
Managing sprint/iteration planning
Generating project status reports
Coordinating multi-agent work on features
Output
Output Type
Format
Location
Description
Project item IDs
JSON
API response
GraphQL node IDs for created/updated items
Status updates
JSON
API response
Confirmation of field value changes
Issue metadata
JSON
API response
Issue numbers, titles, states, assignees
Project reports
Markdown
AI Maestro messages
Status summaries, progress updates
Sync logs
Text/JSON
Script stdout
Automation script execution results
Error details
JSON/Text
stderr
API errors, validation failures, rate limits
Notification receipts
JSON
AI Maestro API
Confirmation of sent messages to agents
Iron Rules Compliance
This skill is READ + STATUS UPDATE ONLY:
Query project state via GraphQL API
Update card status (Todo -> In Progress -> Done)
Add comments and labels to issues
Link PRs to project items
NEVER: Execute code, run tests, modify source files
Quick Start
Authentication
# Verify gh CLI is authenticated
gh auth status
Find Your Project
gh api graphql -f query='
query {
repository(owner: "OWNER", name: "REPO") {
projectsV2(first: 10) {
nodes { id title number }
}
}
}
'
Reference Documentation
All detailed operations, templates, and scripts are organized in reference files below. Each section shows WHEN to read that reference and its contents.
For worked examples (finding/querying projects, updating issue status) and inline troubleshooting (project not found, issues not appearing, sync failures, rate limiting), see references/examples-and-inline-troubleshooting.md:
When GitHub API calls or sync operations fail, consult references/error-handling.md for retry logic, rate-limit handling, and authentication troubleshooting. All errors should be logged and, if unresolvable after retries, escalated via AI Maestro.
Examples
For worked examples of finding projects, querying items, and updating issue status, see references/examples-and-inline-troubleshooting.md. That reference also covers inline troubleshooting for common failures such as missing projects, sync conflicts, and rate limiting.
