Copilot cloud agent

Copilot Cloud Agent Skill

You help the user manage GitHub Copilot's cloud coding agent using the gh agent-task CLI (aliases: gh agent, gh agents). The agent runs autonomously in the cloud, opens a [WIP] PR, and works on the task.

Preview: This feature is in public preview and subject to change.

Creating a Task

gh agent create "task description"

• Runs against the current repo by default
• Use --repo OWNER/REPO to target another repo
• Use --custom-agent <name> to specify a custom agent defined in .github/agents/<name>.md
• No --model flag — use the REST API below to select a model

Assigning an Issue to Copilot (REST API)

Use gh api to assign an issue and optionally customize the task. The agent_assignment object accepts these fields:

Field	Description
target_repo	Repo where Copilot will work (defaults to current repo)
base_branch	Branch Copilot will branch from
custom_instructions	Per-task instructions appended to the agent prompt
model	Model to use. Defaults to gpt-5.4. Requires the GraphQL-Features: coding_agent_model_selection header on every request that sets this field.

Add Copilot to an existing issue

gh api \
  --method POST \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "GraphQL-Features: coding_agent_model_selection" \
  /repos/OWNER/REPO/issues/ISSUE_NUMBER/assignees \
  --input - <<< '{
  "assignees": ["copilot-swe-agent[bot]"],
  "agent_assignment": {
    "target_repo": "OWNER/REPO",
    "base_branch": "main",
    "custom_instructions": "",
    "model": "gpt-5.4"
  }
}'

Create a new issue and assign to Copilot

gh api \
  --method POST \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "GraphQL-Features: coding_agent_model_selection" \
  /repos/OWNER/REPO/issues \
  --input - <<< '{
  "title": "Issue title",
  "body": "Issue description.",
  "assignees": ["copilot-swe-agent[bot]"],
  "agent_assignment": {
    "target_repo": "OWNER/REPO",
    "base_branch": "main",
    "custom_instructions": "",
    "model": "gpt-5.4"
  }
}'

Update an existing issue and assign to Copilot

gh api \
  --method PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -H "GraphQL-Features: coding_agent_model_selection" \
  /repos/OWNER/REPO/issues/ISSUE_NUMBER \
  --input - <<< '{
  "assignees": ["copilot-swe-agent[bot]"],
  "agent_assignment": {
    "target_repo": "OWNER/REPO",
    "base_branch": "main",
    "custom_instructions": "",
    "model": "gpt-5.4"
  }
}'

Listing and Viewing Tasks

gh agent list                        # list recent tasks (last 30)
gh agent view <session-id|pr-number> # view a task
gh agent view 123 --log              # show session logs
gh agent view 123 --follow           # stream logs live

Tracking Progress

Poll for the Copilot-authored PR:

gh pr list --repo OWNER/REPO --author "copilot-swe-agent[bot]" --json number,title,state,url

Prompt Layering (most → least specific)

1. custom_instructions field (per-task REST API)
2. .github/copilot-instructions.md (repo-wide)
3. GitHub's default agent prompt (not published)

Workflow

When the user asks to create or assign a Copilot agent task:

1. Confirm the target repo (gh repo view if unclear)
2. Ask for a task description if not provided
3. If they want a specific model or custom instructions, use the REST API (POST /assignees for an existing issue, or POST /issues to create a new one)
4. If no customization needed, use gh agent create directly
5. Offer to stream logs with gh agent view <id> --follow