gh skill: GitHub CLI Agent Skills Management for Copilot, Claude Code, and Cursor

GitHub launched the gh skill command in public preview on April 16, 2026, and it quietly solves one of the messiest problems in AI-assisted development: how do you share and govern agent skills when every AI coding assistant has its own directory convention, its own install story, and its own idea of what an “skill” even is?

If you have been hand-copying SKILL.md files between .claude/skills, .agents/skills, and ~/.copilot/skills, or forking repositories just to pin a version your team trusts, gh skill is the command you have been waiting for. It treats agent skills the way npm treats JavaScript packages and the way pip treats Python libraries — with search, install, pin, preview, update, and publish as first-class verbs.

This guide walks through what gh skill actually does, the clean usage patterns you will reach for day to day, and the enterprise controls that matter if you plan to deploy skills across a team.

Key Takeaways

• gh skill is a package manager for AI agent skills. One command works across GitHub Copilot, Claude Code, Cursor, Codex, Gemini CLI, and Antigravity.
• Skills are a standard, not a GitHub product. They follow the open Agent Skills specification — a SKILL.md file with YAML frontmatter plus optional scripts/, references/, and assets/ directories.
• Provenance is built in. gh skill install writes source, ref, and tree SHA into the installed SKILL.md so gh skill update can detect upstream changes without guesswork.
• Version pinning is first-class. Pin to a tag (@v1.2.0), a commit SHA (@abc123def), or mark skills with --pin to protect them from routine updates.
• gh skill preview is your security gate. Read a skill’s contents, scripts, and allowed-tools before installing — especially before granting shell or bash access.
• Enterprise governance still matters. Tag protection, immutable releases, secret scanning, and code scanning should be on for every internal skills repository.

What Agent Skills Actually Are

An agent skill is a directory of instructions that teaches an AI agent how to do a specific job — generate a PR description, scaffold an OpenAPI spec, run a security review, enforce a coding standard. The ecosystem has converged on a simple structure:

my-skill/
├── SKILL.md              # required: YAML frontmatter + instructions
├── scripts/              # optional: executable helpers the agent can run
├── references/           # optional: supporting docs the agent can load
└── assets/               # optional: templates, prompts, fixtures

The SKILL.md file carries both the instructions and the metadata the agent needs to decide when to load the skill:

---
name: pr-description-writer
description: Writes structured GitHub pull request descriptions with summary, test plan, and risk sections. Use when opening or updating a PR.
license: MIT
allowed-tools:
  - read
  - write
---

# PR Description Writer

When invoked, read the current branch diff, identify the scope of changes,
and produce a pull request description with three sections:

1. **Summary** — 2-3 bullets describing the intent.
2. **Test plan** — checklist of how the change was verified.
3. **Risk** — one sentence on rollback and blast radius.

Use `scripts/format-diff.sh` if the diff exceeds 400 lines.

Two details matter here. The description field (up to 1024 characters) is what agents read when they decide whether to load the skill — so write it like a tool tooltip, not a README. And allowed-tools pre-approves tool invocations; leaving shell and bash off the list forces the agent to ask before running terminal commands, which is the posture you want for anything you have not fully audited.

Clean Usage Examples

These are the commands you will actually type. Every example assumes GitHub CLI v2.90.0 or newer with gh skill available.

Discover: Search the ecosystem

# Search across public repositories for skills matching a keyword
gh skill search mcp

# Browse curated collections directly
gh skill install github/awesome-copilot

Running gh skill install OWNER/REPO without a skill name drops you into an interactive picker that lists every skill in the repository. It is the fastest way to explore a new collection.

Inspect: Preview before installing

# Print a skill's SKILL.md without installing anything
gh skill preview github/awesome-copilot documentation-writer

# In an interactive terminal, preview opens a file picker so you
# can review scripts/ and references/ individually
gh skill preview github/awesome-copilot security-review

gh skill preview is the security gate. Use it before any install into a project that touches production code, and read allowed-tools carefully — a skill that pre-approves bash can run arbitrary commands the moment an agent invokes it.

Install: Project scope, user scope, specific versions

# Install the latest version to the current project (.agents/skills, .claude/skills, etc.)
gh skill install github/awesome-copilot documentation-writer

# Install to your user profile so it's available across every project
gh skill install github/awesome-copilot documentation-writer --scope user

# Pin to a specific release tag
gh skill install github/awesome-copilot documentation-writer@v1.2.0 --pin

# Pin to a specific commit SHA for maximum reproducibility
gh skill install github/awesome-copilot documentation-writer@abc123def --pin

# Install only for one agent host (useful when skills diverge per tool)
gh skill install github/awesome-copilot documentation-writer --agent claude-code

gh skill knows where each agent expects its skills. On install it writes to .agents/skills for Copilot and Cursor, .claude/skills for Claude Code, and the equivalent path for every other supported host — automatically, based on what is configured on the machine.

Update: Dry-run first, then roll forward

# Scan every installed skill and show which have upstream changes — no writes
gh skill update --dry-run

# Update interactively, prompting for each change
gh skill update

# Non-interactive update (use in CI/CD)
gh skill update --all

# Include skills that were previously pinned
gh skill update --all --unpin

The update mechanism reads the tree SHA that gh skill install wrote into each SKILL.md and compares it to the upstream repository. That is why provenance is not optional — it is the primitive that makes safe updates possible.

Publish: Ship your own skills

Starting from a repository that contains one or more skill directories:

# Validate everything against the agentskills.io spec without publishing
gh skill publish --dry-run

# Auto-fix common issues (strips install metadata from committed files, etc.)
gh skill publish --dry-run --fix

# Interactive publish: tags a release and opens GitHub Releases
gh skill publish

Publishing validates skill names (lowercase, hyphens, 64-character max), confirms required frontmatter is present, and checks that allowed-tools is the correct type. It also nudges you to enable the agent-skills repository topic and recommends tag protection, secret scanning, and code scanning — which are the minimum controls you want on any skills repository others will install from.

CI/CD: Install skills in a GitHub Actions workflow

name: Release notes with Copilot CLI

on:
  push:
    tags:
      - 'v*'

jobs:
  release-notes:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4

      - name: Install GitHub CLI skills
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh skill install github/awesome-copilot release-notes-writer@v1.2.0 --pin

      - name: Generate release notes
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh copilot run "Write release notes for $GITHUB_REF_NAME using the release-notes-writer skill" \
            --allow-all-paths \
            > RELEASE_NOTES.md

      - name: Publish release
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: gh release create "$GITHUB_REF_NAME" --notes-file RELEASE_NOTES.md

This pattern — pin the skill, invoke it through Copilot CLI, commit the output — generalises to changelog generation, security summaries, compliance reports, and onboarding scaffolding.

Enterprise: Bulk bootstrap a developer environment

#!/usr/bin/env bash
# bootstrap-skills.sh — run on new laptops or in Codespaces

set -euo pipefail

SKILLS=(
  "myorg/skills security-review@v2.1.0"
  "myorg/skills pr-description-writer@v1.4.0"
  "myorg/skills terraform-reviewer@v3.0.1"
  "github/awesome-copilot documentation-writer@v1.2.0"
)

for spec in "${SKILLS[@]}"; do
  gh skill install $spec --scope user --pin
done

gh skill update --dry-run

Pinning every skill and pinning again with --pin means the bootstrap script is deterministic: every developer gets exactly the versions your security team approved, and nothing silently changes until you update the script.

Why gh skill Matters for Enterprise Teams

Before gh skill, “sharing a skill” inside a large organisation usually looked like a Slack message, a zip file, or a forked repository with no release tags. That worked at the scale of one team and broke at the scale of one company. Here is what changes when you adopt gh skill as the canonical distribution mechanism.

The audit row is the one enterprise security teams care most about. Because the source repository, git ref, and tree SHA are written directly into the installed SKILL.md, you can walk a developer’s laptop and answer the question “what skills are installed, from where, at what version?” with a simple find command — no separate inventory system required.

Security Patterns That Travel Well

Three practices scale from a single developer to an enterprise without needing new tools.

1. Preview before install, every time. Make gh skill preview OWNER/REPO skill-name part of your review checklist. A two-minute read of SKILL.md plus the scripts/ directory catches most red flags — prompt injections, unexpected network calls, anything that writes outside the working tree.

2. Be ruthless about allowed-tools. Omit shell and bash from allowed-tools unless you have audited every script the skill references. Forcing the agent to ask before running a command is the single biggest control you have against an attacker-controlled skill or a prompt-injection payload.

3. Harden your internal skills repository. When gh skill publish nudges you to enable tag protection, secret scanning, and code scanning, say yes to all three. Tag protection in particular makes releases immutable, which is what lets downstream consumers trust a --pin to a tag.

If you want a broader frame for how these controls fit into an enterprise AI programme — including model governance, MCP server policies, and agent budget controls — see our guide on enterprise AI agent consulting and our write-up of the Copilot CLI enterprise harness. The same principles apply: skills are a new attack surface, and the answer is governance, not prohibition.

Where gh skill Fits in the Broader Ecosystem

gh skill is one piece of a fast-moving landscape. If you are building a skill strategy, these related pieces are worth understanding together:

• The Agent Skills specification at agentskills.io — the open standard gh skill validates against.
• Claude Code and Gemini CLI skill authoring — covered in our post on skill creation tools across Claude Code and Gemini CLI.
• Model Context Protocol (MCP) — skills and MCP servers are complementary. Skills carry instructions; MCP servers carry capabilities. The most powerful agent configurations use both.
• Windows 365 + Intune governance — when developer laptops are Cloud PCs, skill deployment becomes an Intune consulting problem, not just a developer-tooling problem.

The gh skill changelog explicitly notes that the command is subject to change during public preview, so expect the interface to evolve over the next few releases. The fundamentals — SKILL.md, provenance metadata, tag-and-SHA pinning — are stable bets.

Getting Started Checklist

1. Upgrade GitHub CLI to v2.90.0 or newer (gh --version).
2. Run gh skill --help to confirm the command is available.
3. Preview before installing. Make gh skill preview muscle memory.
4. Pin everything in production. Use --pin and specific tags or SHAs for any skill that runs in CI/CD.
5. Create an internal skills repository. Add the agent-skills topic, enable tag protection, enable secret and code scanning, and use gh skill publish to ship your first internal skill.
6. Document your governance model. Who approves new skills? Who owns the internal registry? Who reviews allowed-tools?

If your team wants help standing up skills governance as part of a broader enterprise AI rollout, Big Hat Group’s OpenClaw consulting practice covers the full stack — skills, MCP servers, agent governance, Windows 365 delivery, and Intune policy.

The broader story across GitHub’s April 2026 releases — built-in Copilot in VS Code 1.116, tighter individual plans, Claude Opus 4.7 rollouts, and gh skill itself — is covered in the latest Copilot Weekly.

Skills are finally a first-class artefact. Ship them like one.