gh skill install

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

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). Supported hosts and their storage directories are (project, user):

  • GitHub Copilot (.agents/skills, ~/.copilot/skills)
  • Claude Code (.claude/skills, ~/.claude/skills)
  • Cursor (.agents/skills, ~/.cursor/skills)
  • Codex (.agents/skills, ~/.codex/skills)
  • Gemini CLI (.agents/skills, ~/.gemini/skills)
  • Antigravity (.agents/skills, ~/.gemini/antigravity/skills)

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, GitHub Copilot, Cursor, Codex, Gemini CLI, and Antigravity all use the shared .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. 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 or skills/author/skill/SKILL.md).

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.

When run interactively, the command prompts for any missing arguments. When run non-interactively, repository and a skill name are required.

Options

--agent <string>
Target agent: {github-copilot|claude-code|cursor|codex|gemini|antigravity}
--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}

ALIASES

gh skills add, gh skill add

Examples

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

See also