GH-SKILL-INSTALL(1)

NAME
gh-skill-install - Install agent skills from a GitHub repository (preview)

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

DESCRIPTION
Install agent skills from a GitHub repository or local directory into your local environment. Skills are placed in a host-specific directory at either project scope (inside the current git repository) or user scope (in your home directory, available everywhere).

A wide range of AI coding agents are supported, including GitHub Copilot, Claude Code, Cursor, Codex, Gemini CLI, Antigravity, Amp, Goose, Junie, OpenCode, Windsurf, and many more.

Supported --agent values:

•   GitHub Copilot (github-copilot)

•   Claude Code (claude-code)

•   Cursor (cursor)

•   Codex (codex)

•   Gemini CLI (gemini-cli)

•   Antigravity (antigravity)

•   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)

•   Droid (droid)

•   Firebender (firebender)

•   Goose (goose)

•   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)

•   Windsurf (windsurf)

•   Zencoder (zencoder)

Use --agent and --scope to control placement, or --dir for 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. If you select multiple hosts that resolve to the same destination, each skill is installed there only once.

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.

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.

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.

Use --all to install every discovered skill from the repository without prompting for skill selection. When run non-interactively, repository and either a skill name or --all are required.

OPTIONS

--agent <string>
    Target agent (see supported values 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 (overrides --agent and --scope)

-f, --force
    Overwrite existing skills without prompting

--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
gh skill add, gh skills add

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
    # 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)