Install agent skills safely with GitHub CLI
Use gh skill to inspect a package before installation, place it in the intended agent and scope, pin the revision you reviewed, and check updates without silently replacing it.
Upgrade to GitHub CLI 2.90.0 or later. Preview the exact release, inspect every bundled file, install to project scope unless broader reach is necessary, and pin the approved tag or commit. Use a dry-run before updating. GitHub explicitly warns that skills are not verified, so the CLI improves provenance and version control; it does not replace package review.
Copy-paste safe starting point
This example uses the free, read-only Robots Sitemap Validator from the public JustHandled Labs repository. Replace the repository, skill, agent, and reviewed version for another package.
gh --version gh skill preview justhandledlabs/skills robots-sitemap-validator@v1.0.1 gh skill install justhandledlabs/skills robots-sitemap-validator \ --agent codex \ --scope project \ --pin v1.0.1 gh skill update --dry-run
The @v1.0.1 form previews that version. The install uses --pin v1.0.1. GitHub documents these as alternative version selectors, so do not combine @VERSION and --pin in the same install command.
What gh skill changes
gh skill is GitHub CLI's public-preview workflow for searching, previewing, installing, updating, and publishing Agent Skills. It discovers repositories that use standard SKILL.md folder conventions and installs a selected package into a host-specific directory.
The useful security improvement is provenance. A GitHub CLI install adds source repository, path, ref, pin, and tree-SHA metadata to the installed SKILL.md. That gives the update command something concrete to compare later.
It does not make community code trustworthy. GitHub's own installation documentation warns that skills may contain prompt injections, hidden instructions, or malicious scripts and tells users to preview before installing.
The six-step workflow
Confirm the CLI supports the command
GitHub documents gh skill for version 2.90.0 or later. Because the feature remains in public preview, verify both the installed version and the live help output.
gh --version gh skill --help
Resolve the real repository and exact skill
Search can help with discovery, but it is not publisher verification. Confirm the repository owner, listing link, license, release history, and exact skill path. A repository may contain several skills or duplicate plugin mirrors.
gh skill search "robots sitemap" gh skill preview justhandledlabs/skills robots-sitemap-validator@v1.0.1
Preview before the package reaches an agent directory
Preview renders the file tree and SKILL.md without installing. Read the scripts and referenced files too. Ask whether the requested filesystem, shell, browser, credential, and network access is necessary for the promised task.
For a deeper review, use the nine-step SKILL.md security checklist: provenance, instructions, executable code, permissions, data sources, consequential actions, sandbox testing, and update control.
Choose the agent and the smallest useful scope
Non-interactive installs default to GitHub Copilot and project scope. Pass both flags when the intended target matters. Project scope limits the installation to one repository. User scope makes it available across projects.
| Target | Flag | Use when |
|---|---|---|
| Codex | --agent codex | You want the skill available to Codex in the chosen scope. |
| Claude Code | --agent claude-code | The workflow is for Claude Code rather than a shared default. |
| Cursor | --agent cursor | The repository is used through Cursor's agent workflow. |
| GitHub Copilot | --agent github-copilot | You want GitHub Copilot's project or user skill location. |
| One repository | --scope project | Default and usually the safer starting point. |
| Every project | --scope user | You deliberately accept broader availability and update impact. |
Pin the revision you actually reviewed
Without a version, GitHub CLI prefers the latest tagged release and then the default branch. An explicit pin turns an implicit moving choice into a reviewable dependency.
gh skill install justhandledlabs/skills robots-sitemap-validator \ --agent codex \ --scope project \ --pin v1.0.1
A tag is useful only if the publisher protects it from mutation. For sensitive work, record the resolved commit or tree SHA as well and keep the package test evidence beside the installation decision.
Check updates before applying them
The update dry-run compares installed provenance with the upstream source without changing the local package. Pinned skills are skipped by design. Review a newer release and its diff first, then reinstall with a new pin if it passes.
gh skill update --dry-run # After reviewing a newer release: gh skill install OWNER/REPOSITORY SKILL --pin NEW_VERSION --force
--force overwrites the installed skill, so use it only after confirming the exact target and preserving intentional local changes.
Evidence from a real pinned install
On July 23, 2026, this workflow was tested with GitHub CLI 2.92.0 against justhandledlabs/skills release v1.0.1 in a disposable custom directory.
Observed results
- Preview returned the complete Robots Sitemap Validator tree:
SKILL.md, two references, and one Python script. - The pinned install resolved public commit
78165cbband reported the package source asjusthandledlabs/skills@v1.0.1. - GitHub CLI injected repository, skill path, release ref, pin, and tree-SHA provenance into the installed frontmatter.
gh skill update --dry-runskipped the pinned package and reported all skills up to date.- The disposable install directory was removed after verification; no user-scoped skill was added.
What the CLI does not audit
| Control | What it gives you | What remains your job |
|---|---|---|
| Search | Repository and skill discovery | Publisher identity, duplication, popularity manipulation, and fit |
| Preview | File tree and readable package content before install | Intent, hidden behavior, dependency risk, and permission necessity |
| Pin | A stable selected ref for that installation | Whether the tag is protected and whether the reviewed revision is safe |
| Provenance metadata | Source repository, path, ref, and tree SHA | Authenticity of the publisher and review of future diffs |
| Update dry-run | A read-only upstream comparison | Reviewing and testing the proposed update before replacement |
Need a repeatable pre-install scan?
Skill Injection Scanner flags prompt-injection language, exfiltration wording, concealment, unsafe commands, encoded blobs, and overbroad tool requests without executing the package. It is heuristic and does not certify safety.
Troubleshooting
gh skill is not a command
Upgrade GitHub CLI to 2.90.0 or later, then run gh skill --help. Package-manager versions may lag the current GitHub release.
The skill installed for the wrong agent
Non-interactive installs default to github-copilot. Re-run with the intended --agent and scope. Do not leave an unwanted copy in another host directory.
GitHub CLI cannot find the skill
Pass the exact skill name or repository path. Large or namespaced repositories may resolve faster with a path such as skills/owner/skill. Confirm the repository uses a supported SKILL.md convention.
Update says the skill is pinned
That is expected. The pin prevents automatic replacement. Preview and review the newer version, then deliberately select a new pin.
Common questions
What version of GitHub CLI includes gh skill?
GitHub documents gh skill for GitHub CLI 2.90.0 or later. It remains a public-preview feature, so check gh skill --help after upgrading.
Should I install at project or user scope?
Start with project scope when one repository needs the skill. Use user scope only when you want the same reviewed skill available across projects and accept the larger reach.
Does gh skill preview prove a skill is safe?
No. Preview is a read-before-install control that exposes the file tree and SKILL.md. You still need to inspect scripts, references, permissions, network access, and the exact revision.
Why is gh skill update skipping a skill?
Pinned skills are intentionally skipped. Review the newer release, then reinstall with a new pin if you decide to approve it.
Can I use gh skill with Codex, Claude Code, or Cursor?
Yes. Current GitHub CLI releases support explicit agent hosts including codex, claude-code, cursor, and github-copilot. Pass the intended host with --agent.