OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add github/gh-aw --skill gh-agent-task
Use gh agent-task commands to create, run, and monitor agent tasks.
npx skills add github/gh-aw --skill gh-agent-task
The gh agent-task extension creates GitHub Copilot coding agent tasks from the CLI. A task is a GitHub issue that triggers automated code changes from natural language instructions.
Repository: https://github.com/github/agent-task (internal GitHub extension)
Agent tasks are GitHub issues that:
Install via GitHub CLI:
Note: This extension requires authentication with a Personal Access Token (PAT) that has appropriate permissions for creating issues and pull requests.
Create a new agent task from a description:
Command Parameters:
--from-file <path>: Read task description from file--base <branch>: Base branch for the pull request (default: repository default branch)--repo <owner/repo>: Target repository (default: current repository)Output Format: The command outputs the URL of the created agent task:
List agent tasks in a repository:
View details of a specific agent task:
Update an existing agent task:
Agent task descriptions should be clear, specific natural language instructions:
Good Example:
Poor Example:
Best Practices:
The gh agent-task extension is used by the create-agent-task safe output feature in GitHub Agentic Workflows (gh-aw).
The safe output processor:
create_agent_task items from the structured outputgh agent-task create --from-file <file> --base <branch>Environment Variables:
GITHUB_AW_AGENT_TASK_BASE: Base branch for the pull requestGITHUB_AW_TARGET_REPO: Target repository for cross-repo task creationGITHUB_AW_SAFE_OUTPUTS_STAGED: Preview mode flagAgent task creation requires elevated permissions beyond the default GITHUB_TOKEN:
Required Permissions:
contents: write - To create branches and commitsissues: write - To create the agent task issuepull-requests: write - To create pull requestsToken Precedence:
COPILOT_GITHUB_TOKEN - Dedicated Copilot operations token (recommended)GH_AW_GITHUB_TOKEN - General override token (legacy)github-token configuration fieldNote: The default GITHUB_TOKEN is not supported as it lacks required permissions. The COPILOT_CLI_TOKEN and GH_AW_COPILOT_TOKEN secrets are no longer supported as of v0.26+.
Store your Personal Access Token in repository secrets:
:::note[Backward Compatibility]
Legacy token name GH_AW_GITHUB_TOKEN is still supported for backward compatibility. The GH_AW_COPILOT_TOKEN token is no longer supported as of v0.26+.
:::
Solution: Configure COPILOT_GITHUB_TOKEN or legacy GH_AW_GITHUB_TOKEN with a PAT.
Solution: Ensure the token has contents: write, issues: write, and pull-requests: write permissions.
Solution: Verify the target repository exists and the token has access to it.
When safe-outputs.staged: true, agent tasks are previewed without creation:
Staged Output:
Symptom: No error but no task created
Check:
COPILOT_GITHUB_TOKEN is set in repository secretsSymptom: Task created but no automated PR
Possible Causes:
Solution: Check repository Copilot settings and refine task description.
Symptom: Error when creating tasks in different repository
Check:
When used via safe outputs, the create-agent-task job provides outputs:
Usage in Dependent Jobs:
https://github.com/owner/repo/issues/123# List all agent tasks
gh agent-task list
# List with filters
gh agent-task list --state open
gh agent-task list --state closed
gh agent-task list --state all# View by number
gh agent-task view 123
# View by URL
gh agent-task view https://github.com/owner/repo/issues/123# Update description
gh agent-task update 123 "Updated task description"
# Update from file
gh agent-task update 123 --from-file updated-description.md# Refactor User Authentication
Refactor the user authentication flow in `src/auth/login.js` to:
1. Use async/await instead of callbacks
2. Add proper error handling with specific error messages
3. Add input validation for email format
4. Update tests to cover the new implementation
Maintain backward compatibility with the existing API.Fix authsafe-outputs:
create-agent-task:
base: main # Base branch for agent task PR
target-repo: "owner/target-repo" # Cross-repository task creationon:
issues:
types: [labeled]
permissions:
contents: read
actions: read
engine: claude
safe-outputs:
create-agent-task:
base: main
# Code Task Delegator
When an issue is labeled with "code-task", analyze the requirements and create a GitHub Copilot coding agent task with detailed instructions for implementing the requested changes.# In your repository settings, add secret:
# Name: COPILOT_GITHUB_TOKEN (recommended)
# Value: ghp_YourPersonalAccessTokenError: failed to create agent task
authentication requiredError: 403 Forbidden
Resource not accessible by integrationError: repository not foundsafe-outputs:
staged: true
create-agent-task:## 🎭 Staged Mode: Create Agent Tasks Preview
The following agent tasks would be created if staged mode was disabled:
### Task 1
**Description:**
Refactor authentication to use async/await pattern
**Base Branch:** main
**Target Repository:** owner/repoon:
issues:
types: [labeled]
engine: claude
safe-outputs:
create-agent-task:
When issue is labeled with "needs-implementation", create an agent task with implementation instructions.on:
schedule:
- cron: "0 9 * * 1" # Monday 9AM
engine: copilot
safe-outputs:
create-agent-task:
base: develop
Analyze codebase for improvement opportunities and create agent tasks for top 3 improvements.on: workflow_dispatch
engine: claude
safe-outputs:
create-agent-task:
target-repo: "organization/backend-repo"
base: main
Create agent task in backend repository to implement the API changes described in this issue.outputs:
task_number: "123"
task_url: "https://github.com/owner/repo/issues/123"jobs:
follow_up:
needs: create_agent_task
steps:
- name: Notify team
run: |
echo "Agent task created: ${{ needs.create_agent_task.outputs.task_url }}"