Copilot, skills, and agent-task

Active contributors: Sam Morrow, tommaso-moro, William Martin, Sam Coe

Purpose

The newest cluster of commands in cli/cli is the AI/agent surface:

• gh copilot - thin entry point for GitHub Copilot CLI suggestions.
• gh skill - install, update, search, preview, and publish "skills" (natural-language workflows packaged as YAML/Markdown bundles).
• gh agent-task - manage long-running agent tasks against a repository.
• gh accessibility - settings and helpers for accessible terminal output.

These commands move quickly: internal/skills/ and pkg/cmd/skills/ together account for the majority of churn in the last 90 days (78 commits, plus 18 in pkg/cmd/skills/install/install.go alone).

Directory layout

pkg/cmd/copilot/        # gh copilot (single command)
pkg/cmd/skills/
  skills.go             # NewCmdSkills: registers subcommands
  install/install.go    # ~42 KB: clone/copy/discover skills
  update/update.go      # update installed skills
  preview/preview.go    # preview a skill before installing
  publish/publish.go    # ~35 KB: validate + publish to a registry
  search/search.go      # registry search

internal/skills/
  installer/            # Filesystem placement and lockfile updates
  discovery/            # ~33 KB: walks repos to find skill manifests
  registry/             # Remote registry client (search, download)
  source/               # Source repo abstractions (github + local)
  frontmatter/          # YAML frontmatter parsing for SKILL.md
  lockfile/             # Per-host installed-skills lockfile

pkg/cmd/agent-task/
  agent_task.go         # NewCmdAgentTask
  create/  list/  view/
  capi/                 # GitHub Copilot API client
  shared/               # task formatting and rendering

pkg/cmd/accessibility/  # gh accessibility (single subcommand)

Key abstractions

Symbol	File	Role
NewCmdSkills	pkg/cmd/skills/skills.go	Registers install, update, preview, publish, search. Aliased as skills.
installRun	pkg/cmd/skills/install/install.go	Largest skill subcommand: source resolution, frontmatter validation, lockfile update, file copy.
Discovery	internal/skills/discovery/discovery.go	Walks a source repo to enumerate skill manifests; ~33 KB.
Registry	internal/skills/registry/	Remote registry client.
Lockfile	internal/skills/lockfile/	Tracks installed skills per agent host.
Frontmatter	internal/skills/frontmatter/	YAML frontmatter parser used by skill manifests.
NewCmdAgentTask	pkg/cmd/agent-task/agent_task.go	Registers the agent-task tree.
capi.Client	pkg/cmd/agent-task/capi/	Talks to the Copilot API for task lifecycle.

How it works

gh skill install github/awesome-copilot documentation-writer flow:

graph TD
    A[gh skill install] --> B[Resolve source via internal/skills/source]
    B --> C[discovery walks the source repo]
    C --> D[frontmatter parses SKILL.md]
    D --> E[installer copies to agent skill dir]
    E --> F[lockfile records the entry]
    F --> G[Telemetry SAMPLE_ALL flush]

The agent-aware install path supports multiple agent layouts (Codex, Claude Code, Copilot CLI, Gemini, Amp, OpenCode). internal/agents/detect.go is reused at runtime to decide where to place the skill.

gh agent-task create --repo cli/cli "fix the bug" posts a task to the Copilot API and returns the task ID; gh agent-task view <id> polls the API and renders status.

Integration points

• The skills tree opts into SAMPLE_ALL telemetry (it sets the rate in its PersistentPreRunE) so usage signal flows back to the team.
• Agent attribution (which agent invoked gh) flows through the User-Agent header courtesy of internal/agents/detect.go.
• gh copilot is currently a thin wrapper that, if the Copilot extension is not installed, prompts to install it. See pkg/cmd/root/official_extension_stub.go.
• gh accessibility configures rendering preferences (e.g. screen-reader-friendly output). Its config is read by pkg/iostreams.

Entry points for modification

• New skill subcommand: add pkg/cmd/skills/<name>/<name>.go, register in skills.go.
• New skill source backend: add a struct under internal/skills/source/. Cover with a unit test.
• Frontmatter schema change: edit internal/skills/frontmatter/ and the validators in both install and publish.
• Agent detection update: append a heuristic to internal/agents/detect.go and add a row to the table-driven test.

Key source files

File	Purpose
pkg/cmd/skills/skills.go	Skills subcommand registration.
pkg/cmd/skills/install/install.go	Skill installer.
pkg/cmd/skills/publish/publish.go	Skill publisher / validator.
pkg/cmd/skills/search/search.go	Registry search.
internal/skills/discovery/discovery.go	Skill enumeration.
internal/skills/registry/registry.go	Registry client.
internal/agents/detect.go	AI agent detection.
pkg/cmd/agent-task/agent_task.go	Agent-task root.
pkg/cmd/agent-task/create/create.go	Task creation.
pkg/cmd/agent-task/capi/capi.go	Copilot API client.

Related pages

• Telemetry and skills (system view).
• Lore for the historical context on this era.
• Patterns and conventions.