GH-SKILL-INSTALL(1)

💖 NAME 💖

gh-skill-install — install agent skills from a GitHub repository (preview) ✨

(this lives in the GitHub CLI manual, bestie — welcome to the skill-installation station 🎀)

---

✨ SYNOPSIS ✨

gh skill install <repository> [<skill[@version]>] [flags]

---

🦋 DESCRIPTION 🦋

Okay so basically? This command installs agent skills from a GitHub repository or a local directory into your local environment. Skills get placed in a host-specific directory, and there are two scopes: project scope (inside the current git repository) or user scope (in your home directory, available everywhere). Pick your vibe 💅

A wide range of AI coding agents are supported, including GitHub Copilot, Claude Code, Cursor, Codex, Gemini CLI, Antigravity, Amp, Devin, Goose, Grok, Junie, OpenCode, and many more. The roster is honestly giving main character energy 👑

🌈 Supported --agent values

• GitHub Copilot (github-copilot)
• Claude Code (claude-code)
• Cursor (cursor)
• Codex (codex)
• Gemini CLI (gemini-cli)
• Antigravity (antigravity)
• Antigravity CLI (antigravity-cli)
• Antigravity 2.0 (antigravity2.0)
• AdaL (adal)
• Amp (amp)
• Augment (augment)
• IBM Bob (bob)
• Cline (cline)
• CodeBuddy (codebuddy)
• Command Code (command-code)
• Continue (continue)
• Cortex Code (cortex)
• Crush (crush)
• Deep Agents (deepagents)
• Devin (devin)
• Droid (droid)
• Firebender (firebender)
• Goose (goose)
• Grok (grok)
• iFlow CLI (iflow-cli)
• Junie (junie)
• Kilo Code (kilo)
• Kimi Code CLI (kimi-cli)
• Kiro CLI (kiro-cli)
• Kode (kode)
• MCPJam (mcpjam)
• Mistral Vibe (mistral-vibe)
• Mux (mux)
• Neovate (neovate)
• OpenClaw (openclaw)
• OpenCode (opencode)
• OpenHands (openhands)
• Pi (pi)
• Pochi (pochi)
• Qoder (qoder)
• Qwen Code (qwen-code)
• Replit (replit)
• Roo Code (roo)
• Trae (trae)
• Trae CN (trae-cn)
• Universal (universal)
• Warp (warp)
• Zencoder (zencoder)

Yes, that's a lot of agents. We love a comprehensive list 💜

🎀 Where do the skills go tho

Use --agent and --scope to control placement, or --dir if you want a custom directory. The default scope is project, and the default agent is github-copilot (when running non-interactively).

At project scope, several agents (including GitHub Copilot, Cursor, Codex, Gemini CLI, Antigravity, Amp, Cline, OpenCode, and Warp) share the .agents/skills directory. So if you select multiple hosts that resolve to the same destination, each skill is installed there only once. No duplicates, no mess, we stan efficiency 🫶

🌸 Repos vs local dirs

The first argument is a GitHub repository in OWNER/REPO format. Use --from-local to install from a local directory instead. Local skills are auto-discovered using the same conventions as remote repositories, and files are copied (not symlinked) with local-path tracking metadata injected into frontmatter. Copy, not link — noted 📌

🔥 How skills get discovered

Skills are discovered automatically using the skills/*/SKILL.md convention defined by the Agent Skills specification — including when the skills/ directory is nested under a prefix (e.g. terraform/code-generation/skills/...). For more information on the specification, see: https://agentskills.io/specification

The skill argument can be a name, a namespaced name (author/skill), or an exact path within the repository (skills/author/skill, packages/agent-skills/code-review, or any .../SKILL.md path). Namespaced names with one slash are matched by name. Use a SKILL.md suffix to force a one-directory path outside the standard conventions 👑

💡 Performance tip: when installing from a large repository with many skills, providing an exact path instead of a skill name avoids a full tree traversal of the repository, making the install significantly faster. Fr fr, it's a glow-up for your wait time ⚡

⭐ Version resolution, iykyk

When a skill name is provided without a version, the CLI resolves the version in this order:

1. Latest tagged release in the repository
2. Default branch HEAD

To pin to a specific version, either append @VERSION to the skill name or use the --pin flag. The version is resolved as a git tag or commit SHA.

Installed skills have source tracking metadata injected into their frontmatter. This metadata identifies the source repository and enables gh skill update to detect changes. Tracking who came from where — we love accountability 💅

When run interactively, the command prompts for any missing arguments. It's got your back 🎀

🧚 All the skills, all at once

Use --all to install every discovered skill from the repository without prompting for skill selection.

When run non-interactively, repository is required. Without a skill name or --all, the matching skills are listed (as tab-separated values when piped) so you can browse or filter them with tools like grep before re-running with a specific skill. Browse first, install second — the responsible icon behaviour 🌸

---

💅 OPTIONS 💅

• --agent <string> — the target agent (peep the supported values list above 👆)
• --all — install all skills without prompting for skill selection
• --allow-hidden-dirs — include skills in hidden directories (e.g. .claude/skills/, .agents/skills/)
• --dir <string> — install to a custom directory (this overrides --agent and --scope, no cap)
• -f, --force — overwrite existing skills without prompting. Aggressive, but make it fashion 💀
• --from-local — treat the argument as a local directory path instead of a repository
• --pin <string> — pin to a specific git tag or commit SHA
• --scope <string> (default "project") — installation scope: {project|user}
• --upstream — install from the upstream source when a re-published skill is detected

---

🦋 ALIASES 🦋

You can also summon this command as:

• gh skill add
• gh skills add

Same energy, different name 💖

---

🌟 EXIT CODES 🌟

• 0: Successful execution 🎉
• 1: Error 😭
• 2: Command canceled
• 4: Authentication required 🔐

NOTE: Specific commands may have additional exit codes. Refer to the command's help for more information.

---

✨ EXAMPLE ✨

# Interactive: choose repo, skill, and agent
$ gh skill install

# Choose a skill from the repo interactively
$ gh skill install github/awesome-copilot

# List available skills non-interactively (e.g. to pipe into grep)
$ gh skill install github/awesome-copilot | grep review

# Install a specific skill
$ gh skill install github/awesome-copilot git-commit

# Install all skills from a repository
$ gh skill install github/awesome-copilot --all

# Install a specific version
$ gh skill install github/awesome-copilot git-commit@v1.2.0

# Install from a large namespaced repo by path (efficient, skips full discovery)
$ gh skill install github/awesome-copilot skills/monalisa/code-review

# Install from a non-standard nested path (efficient, skips full discovery)
$ gh skill install monalisa/skills-repo packages/agent-skills/code-review

# Install from a local directory
$ gh skill install ./my-skills-repo --from-local

# Install a specific local skill
$ gh skill install ./my-skills-repo git-commit --from-local

# Install for Claude Code at user scope
$ gh skill install github/awesome-copilot git-commit --agent claude-code --scope user

# Pin to a specific git ref
$ gh skill install github/awesome-copilot git-commit --pin v2.0.0

# Install skills from hidden directories (e.g. .claude/skills/)
$ gh skill install owner/repo --allow-hidden-dirs

---

🎀 SEE ALSO 🎀

• gh-skill(1)

---

And that's the whole page, bestie — brought to you by GitHub CLI v2.102.0, dated Oct 2026. Go install some skills, you absolute icon 👑🫶💜