gh-agent-task

Skill: gh-agent-task

Provides usage patterns and expert guidance for the GitHub CLI gh agent-task extension, which manages preview agent tasks on repositories and pull requests. The agent-task command set is only available in v2.80.0 or later of the GitHub CLI. This command set is a public preview and is subject to change.

When to Use

• When you need to create, view, or list GitHub Copilot preview agent tasks directly from the CLI.
• To automate the assignment of an agent to a specific pull request or issue.
• When investigating the status or logs of an asynchronous agent task session.

When Not to Use

• For standard GitHub CLI operations (like listing PRs or Issues) that don't involve the agent task extension.
• If your environment uses an older version of gh (< v2.80.0) that doesn't support the agent-task plugin.
• For triggering generic GitHub Actions (use gh workflow run instead).

Common Pitfalls

• Interactive Prompts: Running gh agent-task create without -F or providing an inline description, causing the CLI to hang waiting for user input.
• Parsing Raw Text: Relying on grep to parse the task status instead of using the built-in --json and --jq flags.
• Assuming Completion: Firing off an agent task but failing to poll or --follow its status, leading to race conditions in automated scripts.

Core Process

1. Determine if the goal is to create a new task, list existing tasks, view a specific task, or view tasks associated with a PR.
2. Select the correct subcommand (create, list, or view).
3. Apply filtering (--jq), formatting (--json, --template), or input options (-F) as required.

Core Principles

• Keep descriptions clear when creating tasks; prefer using a file (-F) for multi-line instructions instead of inline strings.
• Always use non-interactive mode. For JSON extraction, rely on the built-in --jq and --json flags rather than external piping when possible.

Commands / Usage Patterns

Create an Agent Task

Create a task from a file (recommended for complex tasks): gh agent-task create -F task-desc.md

Create a task using stdin: echo "description" | gh agent-task create -F -

Create a task with a custom agent on a specific base branch: gh agent-task create "fix errors" --base main --custom-agent my-agent

Create a task and follow logs: gh agent-task create "build me a new app" --follow

List Agent Tasks

List tasks and format output with JSON/JQ: gh agent-task list --limit 10 --json id,state,pullRequestNumber --jq '.[] | "\(.id): \(.state)"'

View Agent Tasks

View an agent task by session ID: gh agent-task view e2fa49d2-f164-4a56-ab99-498090b8fcdf

View an agent task by PR number: gh agent-task view 12345

View an agent task by PR reference: gh agent-task view OWNER/REPO#12345

View task and output specific JSON fields: gh agent-task view 12345 --json id,state,pullRequestNumber

Show agent session logs: gh agent-task view 12345 --log

Diagnostics and Troubleshooting

• If a task creation fails, verify repository permissions and ensure the GitHub CLI is authenticated (gh auth status).
• If using a custom agent, ensure the agent file exists in .github/agents/.

Limitations

• The gh agent-task commands are currently in preview and subject to change.

References

• gh agent-task manual
• Starting GitHub Copilot sessions
• Tracking GitHub Copilot's sessions

Related Skills

• gh: Use for general GitHub CLI operations.
• gh-pr: Use for pull request specific operations.