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
npx skills add cli/cli --skill gh-skill -a claude-codeWhat 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/cliand installgh-skillfor 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-code2Manually: put the files in place
~/.claude/skills/gh-skill/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/gh-skill/
1Skills CLI (Vercel)
npx skills add cli/cli --skill gh-skill -a codex2Manually: put the files in place
.agents/skills/gh-skill/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add cli/cli --skill gh-skill -a cursor2Manually: put the files in place
.cursor/skills/gh-skill/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install cli/cli skills/gh-skill2Manually: put the files in place
.github/skills/gh-skill/SKILL.md1Skills CLI (Vercel)
npx skills add cli/cli --skill gh-skill -a gemini-cli2Platform CLI
gemini skills install https://github.com/cli/cli --path skills/gh-skillManually: put the files in place
.devin/skills/gh-skill/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add cli/cli --skill gh-skill -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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