GitHub CLI gh skill: Manage Claude Code, Codex, and Copilot Skills

GitHub CLI’s gh skill command handles the part of agent skills that quickly becomes tedious: finding a skill, inspecting it, copying it into the right host directory, and tracking where it came from. Developers who switch between Claude Code, Codex, and GitHub Copilot no longer have to memorize three sets of paths.

It is not a complete package manager. In GitHub CLI 2.99.0, gh skill is still a public preview and has no remove command. GitHub also does not verify the skills it installs. This guide focuses on the workflow that is useful today and the gaps worth knowing before you adopt it.

The short version

GitHub documents gh skill for GitHub CLI 2.90.0 or later. The commands in this guide were verified with 2.99.0.
Version 2.99.0 provides six subcommands: install, list, preview, search, update, and publish.
Its help output lists 48 agent hosts, including GitHub Copilot, Claude Code, Codex, Cursor, Gemini CLI, and OpenCode.
Noninteractive installs default to GitHub Copilot at project scope.
There is no gh skill remove or gh skill uninstall. You must locate the installed directory and remove it yourself.

What `gh skill` fixes

An agent skill is a directory built around SKILL.md. The file contains YAML frontmatter and Markdown instructions. Scripts, references, and assets can sit beside it. The format is portable, but each agent host looks in its own project and user directories. A manual copy also loses useful context unless you separately record the repository, ref, and update policy.

gh skill adds that missing management layer. It can discover skills in a GitHub repository, show their contents before installation, copy them to a host-aware path, and inject source metadata into the installed SKILL.md. The update command compares that metadata with the upstream tree SHA. Local installation is supported too; the files are copied rather than symlinked, with the local source path recorded in frontmatter.

Check or upgrade GitHub CLI

Start by checking the installed version and command help.

gh --version
gh skill --help

Upgrade through the official package for your operating system if the version is older than 2.90.0. For an exact 2.99.0 reproduction, download the release archive and its official checksums file, then verify the archive’s SHA-256 digest before extracting it.

The verified binary reported:

gh version 2.99.0 (2026-09-01)

Version 2.99.0 did not introduce gh skill; the feature was already available in 2.90.0. The relevant 2.99.0 release change fixes the Codex user-scope destination so that it uses ~/.agents/skills.

Search, preview, then install

Search public repositories by topic:

gh skill search terraform --limit 5

Search uses GitHub’s Code Search API. In a logged-out 2.99.0 test, it returned HTTP 401 and suggested gh auth login. Public repository preview and install worked without authentication in the same environment. You still need credentials for private repositories and for publishing a release.

Do not treat search ranking as a trust signal. Preview the skill first:

GH_PAGER=cat gh skill preview github/awesome-copilot documentation-writer

Preview renders the file tree and SKILL.md without installing anything. In an interactive terminal, it can also open additional files from a multi-file skill.

Install a reviewed skill for Copilot at project scope:

gh skill install github/awesome-copilot documentation-writer --agent github-copilot --scope project

For a user-scoped Claude Code installation:

gh skill install github/awesome-copilot git-commit --agent claude-code --scope user

The Codex form is similar:

gh skill install github/awesome-copilot git-commit --agent codex --scope user

When no version is supplied, install tries the repository’s latest tag first and falls back to the default branch HEAD. Use --pin when the installed skill must remain on a particular ref during updates:

gh skill install cli/cli gh --pin v2.99.0 --agent codex --scope project

There is a subtle reason to prefer --pin over merely appending @v2.99.0. In the 2.99.0 test, gh@v2.99.0 installed that exact ref, but gh skill list reported pinned: false. Installing with --pin v2.99.0 reported pinned: true, and update --dry-run skipped it. Use the flag when update exclusion matters.

You can also test a locally authored skill without touching any agent’s normal directories:

gh skill install ./my-skills-repo demo-skill --from-local --dir ./sandbox-skills

A custom --dir overrides both agent and scope. It is a useful staging area for review and automation tests.

Project and user scope paths

Project scope resolves from the current Git repository root. User scope resolves from the home directory and makes the skill available across projects.

Agent host	Project scope	User scope
GitHub Copilot	`.agents/skills`	`~/.copilot/skills`
Claude Code	`.claude/skills`	`~/.claude/skills`
Codex	`.agents/skills`	`~/.agents/skills`

Claude Code honors CLAUDE_CONFIG_DIR; when it is set, user-scoped skills go into that directory’s skills folder. Several hosts share .agents/skills at project scope, so selecting hosts that resolve to the same destination does not create duplicate copies.

Project scope is the safer default for a skill tied to one repository or maintained with the team’s code. User scope is convenient for personal tools used everywhere, but its reach makes source review more important.

List, update, and uninstall

Use structured output when auditing installed skills:

gh skill list --json skillName,sourceURL,scope,version,pinned,path

Check for updates without changing files:

gh skill update --dry-run

Apply all available updates without a prompt:

gh skill update --all

Pinned skills are skipped. --unpin clears that state and includes them in the update. --force --all downloads skills again even when their remote tree matches; it overwrites locally modified source files but leaves extra files that you added to the directory.

GitHub CLI 2.99.0 has no uninstall subcommand. Locate the exact directory first:

gh skill list --json skillName,path

Review that path and delete only the selected skill directory with your normal file-management tool. That gap keeps gh skill from managing the full lifecycle.

Validate and publish a skill

Repository maintainers can validate locally before creating a release:

gh skill publish --dry-run

The validator checks skill naming rules, directory and name agreement, required name and description fields, the allowed-tools format, and installed source metadata that should not be republished. A valid test repository passed dry run without a remote or GitHub login. Actual publishing needs authentication and repository permission because it checks remote settings and creates a GitHub Release.

Use --fix to strip fixable installation metadata without publishing:

gh skill publish --fix

Publish interactively or provide a release tag:

gh skill publish --tag v1.0.0

How it compares with manual copies and other managers

Manual copying remains the smallest solution. It has no new dependency, works offline, and is easy to audit when you own one skill. You must track host directories, source URLs, refs, and updates yourself.

gh skill is a good fit when GitHub already holds your skills and the team already uses gh. Discovery, preview, source tracking, updates, and release validation stay in one familiar CLI. A dedicated skill manager may be better if you need several Git hosts, a private registry, dependency resolution, automatic removal, or signed artifacts. GitHub CLI does not provide those controls here.

Security and preview limitations

GitHub warns that skills are not verified and can contain prompt injections, hidden instructions, or malicious scripts. Read more than SKILL.md. Inspect scripts, references, and assets, and pay special attention to allowed-tools. Pre-approving shell access can remove the confirmation step before commands run.

Version 2.99.0 still has several practical limits:

The command group is a public preview and may change without notice.
Search and real publishing require GitHub authentication.
There is no remove command, dependency solver, or cryptographic trust verification.
Forced updates can overwrite local edits to installed files.
Project scope requires a detectable Git repository root. Use the correct repository, --scope user, or an explicit --dir when that is not available.

Who should use it

Use gh skill if you manage Claude Code, Codex, or Copilot skills from GitHub and want source and update information visible from the command line. It also works well for teams that keep project-scoped skills beside repository code.

Skip it for now if one hand-maintained skill is enough, GitHub authentication is unavailable, or your organization requires signed packages and automated uninstall. Manual copying or an existing manager remains reasonable while this command is in preview.

Verified on 2026-09-16. The test used the official GitHub CLI 2.99.0 Linux amd64 archive after its SHA-256 checksum passed. Help, local install, public repository preview/install, list, update dry run, and publish dry run were exercised without modifying existing user-scoped agent skills.