name: copilot description: GitHub CLI (gh) operations and CopilotSpawner with full event tracking when_to_use:

Creating pull requests and issues
Managing GitHub repositories
Git operations via gh CLI (direct execution via Bash)
GitHub Copilot for code generation (via CopilotSpawner)
Git workflows with full HtmlGraph tracking
GitHub authentication and configuration skill_type: executable

GitHub Copilot & GitHub CLI (gh) Operations

⚠️ IMPORTANT: This skill provides TWO EXECUTION PATTERNS

GitHub CLI (gh) - Documentation for command syntax. Execute via Bash tool.
CopilotSpawner - AI-powered code generation. Invoke via Python SDK with parent event context.

This skill teaches HOW to use both. See "EXECUTION PATTERNS" below for when to use each.

🚀 CopilotSpawner Pattern: Full Event Tracking

What is CopilotSpawner?

CopilotSpawner is the HtmlGraph-integrated way to invoke external CLIs (Copilot, Gemini, Codex) with full parent event context and subprocess tracking.

Key distinction: CopilotSpawner is invoked directly via Python SDK - NOT wrapped in Task(). Task() is only for Claude subagents (Haiku, Sonnet, Opus).

Instead of running CLI commands directly (which creates "black boxes"), CopilotSpawner:

✅ Invokes external Copilot CLI directly
✅ Creates parent event context in database
✅ Links to parent Task delegation event
✅ Records subprocess invocations as child events
✅ Tracks all activities in HtmlGraph event hierarchy
✅ Provides full observability of external tool execution

When to Use CopilotSpawner

Use CopilotSpawner when:

You need to invoke external CLIs (copilot, gemini, codex)
You want full event tracking in HtmlGraph
Parent event context is available (from hooks)
You need subprocess event recording
You're in a Claude Code session with hook system

Use Bash directly when:

Running simple one-off commands
No tracking needed
Testing/debugging
Not in Claude Code environment

How to Use CopilotSpawner

import os
import sys
from pathlib import Path
from datetime import datetime, timezone
import uuid

# Add plugin agents directory to path
PLUGIN_AGENTS_DIR = Path("/path/to/htmlgraph/packages/claude-plugin/.claude-plugin/agents")
sys.path.insert(0, str(PLUGIN_AGENTS_DIR))

from htmlgraph import SDK
from htmlgraph.orchestration.spawners import CopilotSpawner
from htmlgraph.db.schema import HtmlGraphDB
from htmlgraph.config import get_database_path
from spawner_event_tracker import SpawnerEventTracker

# Initialize
sdk = SDK(agent='claude')
db = HtmlGraphDB(str(get_database_path()))
session_id = f"sess-{uuid.uuid4().hex[:8]}"
db._ensure_session_exists(session_id, "claude")

# Create parent event context (like PreToolUse hook does)
user_query_event_id = f"event-query-{uuid.uuid4().hex[:8]}"
parent_event_id = f"event-{uuid.uuid4().hex[:8]}"
start_time = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")

# Insert UserQuery event
db.connection.cursor().execute(
    """INSERT INTO agent_events
       (event_id, agent_id, event_type, session_id, tool_name, input_summary, status, created_at)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
    (user_query_event_id, "claude-code", "tool_call", session_id, "UserPromptSubmit",
     "Test git workflow", "completed", start_time)
)

# Insert Task delegation event
db.connection.cursor().execute(
    """INSERT INTO agent_events
       (event_id, agent_id, event_type, session_id, tool_name, input_summary,
        context, parent_event_id, subagent_type, status, created_at)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
    (parent_event_id, "claude-code", "task_delegation", session_id, "Task",
     "Guide git workflow", '{"subagent_type":"general-purpose"}',
     user_query_event_id, "general-purpose", "started", start_time)
)
db.connection.commit()

# Export parent context (like PreToolUse hook does)
os.environ["HTMLGRAPH_PARENT_EVENT"] = parent_event_id
os.environ["HTMLGRAPH_PARENT_SESSION"] = session_id
os.environ["HTMLGRAPH_SESSION_ID"] = session_id

# Create tracker with parent context
tracker = SpawnerEventTracker(
    delegation_event_id=parent_event_id,
    parent_agent="claude",
    spawner_type="copilot",
    session_id=session_id
)
tracker.db = db

# Invoke CopilotSpawner with FULL tracking
spawner = CopilotSpawner()
result = spawner.spawn(
    prompt="Recommend next semantic version and git workflow commands",
    track_in_htmlgraph=True,      # Enable SDK activity tracking
    tracker=tracker,               # Enable subprocess event tracking
    parent_event_id=parent_event_id,  # Link to parent event
    allow_all_tools=True,
    timeout=120
)

# Check results
print(f"Success: {result.success}")
print(f"Response: {result.response}")
if result.tracked_events:
    print(f"Tracked {len(result.tracked_events)} events in HtmlGraph")

Key Parameters for CopilotSpawner.spawn()

Parameter	Type	Required	Description
`prompt`	str	✅	Task description for Copilot
`track_in_htmlgraph`	bool	❌	Enable SDK activity tracking (default: True)
`tracker`	SpawnerEventTracker	❌	Tracker instance for subprocess events
`parent_event_id`	str	❌	Parent event ID for event hierarchy
`allow_tools`	list[str]	❌	Tools to auto-approve (e.g., ["shell(git)"])
`allow_all_tools`	bool	❌	Auto-approve all tools (default: False)
`deny_tools`	list[str]	❌	Tools to deny
`timeout`	int	❌	Max seconds to wait (default: 120)

Event Tracking Hierarchy

With CopilotSpawner, you get this event hierarchy in HtmlGraph:

UserQuery Event (from UserPromptSubmit hook)
├── Task Delegation Event (from PreToolUse hook)
    ├── CopilotSpawner Start (activity tracking)
    ├── Subprocess Invocation (subprocess event)
    │   └── subprocess.copilot tool call
    ├── CopilotSpawner Result (activity tracking)
    └── All activities linked with parent_event_id

This provides complete observability - no "black boxes" for external tool execution.

Real Example: Version Update Workflow

# See above code example + this prompt:
result = spawner.spawn(
    prompt="""HtmlGraph project status:
    - Completed CLI module refactoring (all tests passing)
    - Completed skill documentation clarification
    - Completed spawner architecture modularization
    - Current version: ~0.26.x

    Please recommend:
    1. Next semantic version (MAJOR.MINOR.PATCH)
    2. Version update git workflow including all necessary files
    3. Tag and push commands
    """,
    track_in_htmlgraph=True,
    tracker=tracker,
    parent_event_id=parent_event_id,
    allow_all_tools=True,
    timeout=120
)

# Result: Full tracking with Copilot's version recommendation (0.27.0)
# All subprocess invocations recorded in HtmlGraph

Fallback & Error Handling Pattern

CRITICAL: If external spawner fails, delegate to Claude sub-agent (NOT direct execution).

# Try external spawner first
try:
    spawner = CopilotSpawner()
    result = spawner.spawn(
        prompt="Your task",
        tracker=tracker,
        parent_event_id=parent_event_id,
        allow_all_tools=True,
        timeout=120
    )

    if result.success:
        return result  # Success, use spawner result
    else:
        # Spawner returned error result
        raise Exception(f"Spawner failed: {result.error}")

except Exception as e:
    # External spawner failed (CLI not installed, timeout, permission denied, etc.)
    # FALLBACK to Claude sub-agent - do NOT attempt direct execution
    print(f"⚠️ CopilotSpawner failed: {e}")
    print("📌 Falling back to Claude sub-agent...")

    return Task(
        subagent_type="general-purpose",
        prompt="Your task here"
    )
    # Task() guarantees execution via Claude

Why fallback to Task()?

✅ External CLI may not be installed on user's system
✅ Network/permissions issues may affect external tools
✅ Claude sub-agent provides guaranteed execution fallback
✅ Never attempt direct execution as fallback (violates orchestration principles)
✅ Task() handles all retries, error recovery, and parent context automatically

Pattern Summary:

Try external spawner first (Copilot CLI)
If spawner succeeds → return result
If spawner fails → delegate to Claude sub-agent via Task()
Never try direct execution as fallback

What is GitHub CLI (gh)?

GitHub CLI (gh) is a command-line tool for GitHub operations:

Pull Requests - Create, view, merge, and manage PRs
Issues - Create, list, and manage GitHub issues
Repositories - Clone, fork, and manage repos
Authentication - Manage GitHub credentials and tokens
Workflows - Trigger and view GitHub Actions

Works in your terminal with the gh command.

Skill vs Execution Model

CRITICAL DISTINCTION:

What	Description
This Skill	Documentation teaching HOW to use `gh` CLI
Bash Tool	ACTUAL execution of `gh` commands

Workflow:

Read this skill to learn gh CLI syntax and options
Use Bash tool to execute the actual commands
Use SDK to track results in HtmlGraph

Installation

# Install GitHub CLI
# macOS
brew install gh

# Ubuntu/Debian
sudo apt update && sudo apt install gh

# Windows
choco install gh

# Authenticate with GitHub
gh auth login

# Verify installation
gh --version

EXECUTION - Real Commands to Use in Bash Tool

⚠️ To actually execute GitHub operations, use these commands via the Bash tool:

Create Pull Request

# Basic PR creation
gh pr create --title "Feature: Add authentication" --body "Implements JWT auth"

# PR with multiple options
gh pr create --title "Fix bug" --body "Description" --base main --head feature-branch

# Interactive PR creation
gh pr create --web

Manage Issues

# Create issue
gh issue create --title "Bug: Login fails" --body "Steps to reproduce..."

# List issues
gh issue list --state open

# View issue
gh issue view 123

Repository Operations

# Clone repository
gh repo clone owner/repo

# Fork repository
gh repo fork owner/repo --clone

# Create repository
gh repo create my-new-repo --public

Git Operations via gh

# Check status and create commit
git add . && git commit -m "feat: add new feature"

# Push and create PR in one command
git push && gh pr create --fill

# View PR status
gh pr status

How to Use This Skill

STEP 1: Read this skill to learn gh CLI syntax

# This loads the documentation (this file)
Skill(skill=".claude-plugin:copilot")

STEP 2: Execute commands via Bash tool

# This ACTUALLY creates a PR
Bash("gh pr create --title 'Feature' --body 'Description'")

# This ACTUALLY creates an issue
Bash("gh issue create --title 'Bug' --body 'Details'")

# This ACTUALLY clones a repo
Bash("gh repo clone user/repo")

What this skill does:

✅ Provides documentation and examples
✅ Teaches gh CLI syntax and options
✅ Shows common workflows and patterns
❌ Does NOT execute commands
❌ Does NOT create PRs or issues
❌ Does NOT run git operations

To execute: Use Bash tool with the commands shown in "EXECUTION" section.

Example Use Cases (Execute via Bash)

1. Pull Request Workflows

# Create PR after committing changes
Bash("gh pr create --title 'Add feature X' --body 'Implements X with tests'")

# Create draft PR
Bash("gh pr create --draft --title 'WIP: Feature Y'")

# List your PRs
Bash("gh pr list --author @me")

# Merge PR
Bash("gh pr merge 123 --squash")

2. Issue Management

# Create bug report
Bash("gh issue create --title 'Bug: Auth fails' --body 'Steps: 1. Login 2. Error'")

# List open issues
Bash("gh issue list --state open")

# Close issue
Bash("gh issue close 456")

3. Repository Operations

# Clone repo
Bash("gh repo clone anthropics/claude-code")

# Fork and clone
Bash("gh repo fork user/repo --clone")

# View repo details
Bash("gh repo view")

4. Commit and Push Workflows

# Commit all changes and create PR
Bash("git add . && git commit -m 'feat: new feature' && git push && gh pr create --fill")

# Amend last commit and force push
Bash("git commit --amend --no-edit && git push --force-with-lease")

# Check PR status
Bash("gh pr status")

5. GitHub Actions

# List workflow runs
Bash("gh run list")

# View specific run
Bash("gh run view 123")

# Re-run failed jobs
Bash("gh run rerun 123 --failed")

Use Cases

Pull Requests - Create, manage, and merge PRs via command line
Issues - Create and track GitHub issues efficiently
Repository Management - Clone, fork, and configure repos
Authentication - Manage GitHub credentials and tokens
CI/CD - Trigger and monitor GitHub Actions workflows
Code Review - View and comment on PRs from terminal

Requirements

GitHub account
gh CLI installed
Authenticated via gh auth login
Git configured (for git operations)

Integration with HtmlGraph

Track GitHub operations in features:

from htmlgraph import SDK

sdk = SDK(agent="claude")

# Document PR creation
feature = sdk.features.create(
    title="Authentication Feature PR",
    description="""
    Created PR via gh CLI:
    - Title: Add JWT authentication
    - Branch: feature/jwt-auth
    - Status: Ready for review

    Command used:
    gh pr create --title "Add JWT auth" --body "Full implementation with tests"
    """
).save()

When to Use

✅ Use GitHub CLI (gh) for:

Creating and managing pull requests
Creating and tracking issues
Cloning and forking repositories
GitHub authentication
Viewing and managing workflows
Command-line GitHub operations

❌ Don't use gh CLI for:

Code generation (use Task() delegation or direct implementation)
Exploring codebases (use /gemini skill instead)
Complex git operations (use git commands directly)
Local file operations (use standard bash/python)

Tips for Best Results

Use --fill flag - Auto-populate PR details from commits: gh pr create --fill
Check status first - Run gh pr status or gh issue list before creating new items
Use templates - Leverage repository issue/PR templates when available
Authenticate early - Run gh auth login at start of session
Combine with git - Chain git and gh commands: git push && gh pr create
Use --web flag - Open operations in browser when needed: gh pr create --web

Common Patterns (Execute via Bash)

Pattern 1: Feature Development Workflow

# 1. Create feature branch
Bash("git checkout -b feature/new-feature")

# 2. Make changes, commit
Bash("git add . && git commit -m 'feat: implement feature'")

# 3. Push and create PR
Bash("git push -u origin feature/new-feature && gh pr create --fill")

Pattern 2: Bug Fix Workflow

# 1. Create issue for bug
Bash("gh issue create --title 'Bug: Description' --body 'Steps to reproduce'")

# 2. Create branch from issue
Bash("git checkout -b fix/issue-123")

# 3. Fix, commit, and create PR
Bash("git add . && git commit -m 'fix: resolve issue #123' && gh pr create --fill")

Pattern 3: Quick PR Creation

# 1. Commit all changes
Bash("git add . && git commit -m 'feat: quick feature'")

# 2. Push and create PR in one command
Bash("git push && gh pr create --title 'Quick Feature' --body 'Description'")

Limitations

Requires GitHub account and authentication
Internet connection required for GitHub API
Rate limits apply to API calls
Some operations require repository permissions
Cannot execute local git operations (use git directly)

/gemini - For exploring repository structure and large codebases
/codex - For code generation and implementation
/code-quality - For validating code quality before creating PR
Git commands - For local repository operations (use Bash directly)

When NOT to Use

Avoid GitHub CLI for:

Code generation (use Task() delegation)
Exploratory research (use /gemini skill)
Local file operations (use standard bash commands)
Operations not related to GitHub (use appropriate tool)

Error Handling (Use Bash for Diagnostics)

GitHub CLI Not Installed

Error: "gh: command not found"

Solution (via Bash):
# macOS
Bash("brew install gh")

# Verify
Bash("gh --version")

Authentication Required

Error: "authentication required"

Solution (via Bash):
Bash("gh auth login")
# Follow prompts in terminal

Permission Denied

Error: "permission denied to repository"

Solution (via Bash):
# Check authentication status
Bash("gh auth status")

# Re-authenticate if needed
Bash("gh auth login --force")

Advanced Usage (Execute via Bash)

PR with Reviewers and Labels

Bash("gh pr create --title 'Feature' --body 'Desc' --reviewer user1,user2 --label bug,enhancement")

Create Issue from Template

Bash("gh issue create --template bug_report.md")

Batch Operations

# Close multiple issues
Bash("gh issue list --state open --json number --jq '.[].number' | xargs -I {} gh issue close {}")

Integration with Git Workflows

# Rebase and force push
Bash("git rebase main && git push --force-with-lease && gh pr ready")

# Squash commits and update PR
Bash("git rebase -i HEAD~3 && git push --force-with-lease")

Key Features

Feature	GitHub CLI (gh)	Description
Pull Requests	✅	Create, merge, review, comment
Issues	✅	Create, list, close, assign
Repositories	✅	Clone, fork, create, view
Authentication	✅	Login, status, token management
GitHub Actions	✅	List, view, re-run workflows
API Access	✅	Direct GitHub API calls via `gh api`

copilot

SKILL.md