| name | gh-agent-task |
| description | GitHub CLI (`gh agent-task`) operations for creating, listing, and viewing preview agent tasks. You MUST load this skill when working with the `gh agent-task` command. |
| license | MIT |
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
- Determine if the goal is to create a new task, list existing tasks, view a specific task, or view tasks associated with a PR.
- Select the correct subcommand (
create, list, or view).
- 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
Related Skills
- gh: Use for general GitHub CLI operations.
- gh-pr: Use for pull request specific operations.
