Menu
GitHub CLI Agent Session Extension
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/az9713/gh-aw --skill gh-agent-sessionThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Showing SKILL.md
Based on SOC occupation classification
| name | gh-agent-session |
| description | GitHub CLI Agent Session Extension |
The gh agent-task CLI extension enables creating GitHub Copilot agent sessions through the command line. An agent session is a specialized GitHub issue that triggers GitHub Copilot to perform automated code changes based on natural language instructions.
Repository: https://github.com/github/agent-task (internal GitHub extension)
Agent sessions are GitHub issues that:
Install via GitHub CLI:
gh extension install github/agent-task
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 session from a description:
# Create task with inline description
gh agent-task create "Fix the bug in authentication flow"
# Create task from file
gh agent-task create --from-file task-description.md
# Specify base branch
gh agent-task create --base develop "Implement new feature"
# Create in different repository
gh agent-task create --repo owner/repo "Update documentation"
--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 session:
https://github.com/owner/repo/issues/123
List agent sessions in a repository:
# List all agent sessions
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 details of a specific agent session:
# View by number
gh agent-task view 123
# View by URL
gh agent-task view https://github.com/owner/repo/issues/123
Update an existing agent session:
# Update description
gh agent-task update 123 "Updated task description"
# Update from file
gh agent-task update 123 --from-file updated-description.md
Agent session descriptions should be clear, specific natural language instructions:
Good Example:
# 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.
Poor Example:
Fix auth
Best Practices:
The gh agent-task extension is used by the create-agent-session safe output feature in GitHub Agentic Workflows (gh-aw).
safe-outputs:
create-agent-session:
base: main # Base branch for agent session PR
target-repo: "owner/target-repo" # Cross-repository task creation
on:
issues:
types: [labeled]
permissions:
contents: read
actions: read
engine: claude
safe-outputs:
create-agent-session:
base: main
# Code Task Delegator
When an issue is labeled with "code-task", analyze the requirements and create a GitHub Copilot agent session with detailed instructions for implementing the requested changes.
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 session creation requires elevated permissions beyond the default GITHUB_TOKEN:
Required Permissions:
contents: write - To create branches and commitsissues: write - To create the agent session 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:
# In your repository settings, add secret:
# Name: COPILOT_GITHUB_TOKEN (recommended)
# Value: ghp_YourPersonalAccessToken
:::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+.
:::
Error: failed to create agent session
authentication required
Solution: Configure COPILOT_GITHUB_TOKEN or legacy GH_AW_GITHUB_TOKEN with a PAT.
Error: 403 Forbidden
Resource not accessible by integration
Solution: Ensure the token has contents: write, issues: write, and pull-requests: write permissions.
Error: repository not found
Solution: Verify the target repository exists and the token has access to it.
When safe-outputs.staged: true, agent sessions are previewed without creation:
safe-outputs:
staged: true
create-agent-session:
Staged Output:
## 🎭 Staged Mode: Create Agent Tasks Preview
The following agent sessions would be created if staged mode was disabled:
### Task 1
**Description:**
Refactor authentication to use async/await pattern
**Base Branch:** main
**Target Repository:** owner/repo
on:
issues:
types: [labeled]
engine: claude
safe-outputs:
create-agent-session:
When issue is labeled with "needs-implementation", create an agent session with implementation instructions.
on:
schedule:
- cron: "0 9 * * 1" # Monday 9AM
engine: copilot
safe-outputs:
create-agent-session:
base: develop
Analyze codebase for improvement opportunities and create agent sessions for top 3 improvements.
on: workflow_dispatch
engine: claude
safe-outputs:
create-agent-session:
target-repo: "organization/backend-repo"
base: main
Create agent session in backend repository to implement the API changes described in this issue.
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-session job provides outputs:
outputs:
task_number: "123"
task_url: "https://github.com/owner/repo/issues/123"
Usage in Dependent Jobs:
jobs:
follow_up:
needs: create_agent_task
steps:
- name: Notify team
run: |
echo "Agent session created: ${{ needs.create_agent_task.outputs.task_url }}"