Skip to main content
skill CX Codex

gh-skill — Claude Code skill: manage Agent Skills

gh-skill is a Claude Code skill for finding, previewing, installing, updating, and publishing Agent Skills. It lets an agent manage skills sourced from GitHub repositories.

MIT 164 installs ★ 47,132 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add cli/cli --skill gh-skill -a claude-code
Open on GitHub

What gh-skill does

gh-skill teaches agents to use gh skill to search GitHub for skills, inspect one before installation, and install or update it. The command can target a host with --agent, write to project or user scope, and pin a chosen version with --pin.

It also covers publishing a repository as a skill source. The publish flow adds the agent-skills topic and can push unpushed commits before creating a GitHub release. In non-interactive installs, the default target is github-copilot; other hosts need an explicit --agent value.

Local installs use --from-local, which cannot be combined with --pin. The skill also explains validation with --dry-run and metadata cleanup with --fix before publishing.

What it helps with

  • search GitHub for skills by topic
  • inspect a skill before installing it
  • install a skill for a selected agent and pin its version
  • update installed skills
  • validate and publish a skill repository

Example prompts for the agent

  • Search GitHub for testing skills and return the results as JSON.
  • Inspect cli/cli and install gh-skill for Claude Code at a pinned version.
  • Validate my skills repository and publish it with the tag v1.0.0.

How to install gh-skill

1Skills CLI (Vercel)

npx skills add cli/cli --skill gh-skill -a claude-code

2Manually: put the files in place

~/.claude/skills/gh-skill/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/gh-skill/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about gh-skill

How do I install gh-skill in Claude Code?

Run npx skills add cli/cli --skill gh-skill -a claude-code. The skill file is installed at ~/.claude/skills/gh-skill/SKILL.md.

What does gh-skill do?

It guides an agent through searching, inspecting, installing, and updating Agent Skills from GitHub, as well as publishing repositories as skill sources.

How do I choose the target agent for an install?

Set the host with --agent, such as --agent claude-code or --agent cursor. Non-interactive installs default to github-copilot when the flag is omitted.

Source text

SKILL.md · MIT
---
name: gh-skill
description: Manage agent skills with gh skill. Use this skill to discover, preview, install, update, and publish Agent Skills so an agent can self-manage the skills available in its environment.
---

# Managing skills with `gh skill`

`gh skill` installs, previews, searches, updates, and publishes
[Agent Skills](https://agentskills.io). An agent can use it to keep its
own skill set in sync with one or more GitHub repositories.

The command is also aliased as `gh skills`. Prefer the canonical singular
`gh skill` in scripts and docs.

## Search

```bash
gh skill search <query>                                  # free-text search
gh skill search <query> --owner <org>                    # restrict to one owner
gh skill search <query> --limit 20 --page 2
gh skill search <query> --json skillName,repo,description
```

## Preview before installing

```bash
gh skill preview <owner>/<repo> <skill-name>
gh skill preview <owner>/<repo> <skill-name>@v1.2.0   # pin a version
```

## Install

```bash
gh skill install <owner>/<repo> <skill-name>
gh skill install <owner>/<repo> <skill-name>@v1.2.0
gh skill install <owner>/<repo> skills/<scope>/<skill-name>   # exact path, fastest
gh skill install ./local-skills-repo --from-local
```

`<owner>/<repo>` and `<skill-name>` are both required.

Useful flags:

- `--agent <id>` - target host (e.g. `github-copilot`, `claude-code`,
  `cursor`, `codex`, `gemini-cli`). Repeat for multiple. Default is
  `github-copilot` when non-interactive. You should know what agent you are,
  so set this appropriately to install for yourself.
- `--scope project|user` - `project` (default) writes inside the current
  git repo; `user` writes to the home directory and applies everywhere.
- `--pin <ref>` - pin to a tag, branch, or commit SHA. Mutually exclusive
  with `--from-local` and with inline `@version` syntax.
- `--allow-hidden-dirs` - also discover skills under dot-directories such
  as `.claude/skills/`. Don't use this unless you need to, it comes with risks.
- `--force` - overwrite an existing install.

## Update

```bash
gh skill update --all          # update every installed skill
gh skill update <skill>        # update one
gh skill update <skill> --force
gh skill update --unpin        # drop the pin and move to latest
```

## Publish

Publishing turns a repo into a discoverable skill source. Skills are
discovered with these conventions:

- `skills/<name>/SKILL.md`
- `skills/<scope>/<name>/SKILL.md`
- `<name>/SKILL.md` (root-level)
- `plugins/<scope>/skills/<name>/SKILL.md`

Each `SKILL.md` needs YAML frontmatter:

```yaml
---
name: my-skill                # must equal the directory name
description: One sentence...  # required, recommended <= 1024 chars
license: MIT                  # optional but recommended
---
```

### Validate, then publish

```bash
gh skill publish --dry-run                 # validate only, no release
gh skill publish --dry-run ./path/to/repo  # validate a specific dir
gh skill publish --fix                     # auto-strip install metadata
gh skill publish --tag v1.0.0              # non-interactive publish
gh skill publish                           # interactive publish flow
```

`--fix` and `--dry-run` are mutually exclusive. `--fix` only rewrites
install-injected `metadata.github-*` keys and does not publish; commit
the result and re-run `publish`.

The publish flow will:

1. Add the `agent-skills` topic to the repo (so search can find it).
2. Use `--tag` (or prompt for one in a TTY).
3. Auto-push any unpushed commits.
4. Create a GitHub release with auto-generated notes.

Always pass `--tag` so it doesn't fall through to the interactive flow.

## Self-management pattern for agents

A reasonable loop:

1. `gh skill search <topic> --json skillName,repo,namespace`
2. `gh skill preview <repo> <skill>` to inspect the `SKILL.md`.
3. `gh skill install <repo> <skill> --agent <host> --pin <ref>` for a
   reproducible install.
4. Periodically `gh skill update --all` to refresh.

© cli · MIT · cli/cli

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set2

Project sponsors

Companies that keep this analytics open