| name | gh-skill-manager |
| description | Use when installing, updating, previewing, searching, migrating, or auditing agent skills with GitHub CLI `gh skill`; especially for Codex, Claude Code, OpenCode, project/user scope, pinned skills, orphan skills, and GitHub skill repository layout checks. |
GitHub Skill Manager
Use GitHub CLI gh skill to manage agent skills. Focus only on skill install/update/audit workflows; do not handle generic GitHub PR, issue, release, or repo tasks here.
Rules
- Prefer
gh skill over manual copy, curl, or ad hoc git clone when source is GitHub.
- Preview unknown skills before install when practical.
- Use exact skill paths when known; avoids slow repo traversal and wrong skill selection.
- Choose agent and scope explicitly. Do not rely on defaults.
- For shared Codex/OpenCode/Claude user skills, use explicit
--dir $HOME/.agents/skills; do not use --agent universal --scope user, because local testing showed it installs to $HOME/.config/agents/skills. Codex and OpenCode load $HOME/.agents/skills directly; Claude Code loads it when $HOME/.claude/skills is a symlink to $HOME/.agents/skills.
- Run update checks with
--dry-run before applying updates.
- Treat root-level
SKILL.md repos as incompatible with gh skill unless they also expose a skills/<name>/SKILL.md path.
- Do not install the same skill into other agents unless user asks.
- Do not overwrite local modified skills blindly. Backup first if using
--force.
Common commands
Search:
gh skill search "query" --limit 10 --json repo,skillName,path,stars,description
Preview:
gh skill preview OWNER/REPO path/to/skill
Install user-level skill:
gh skill install OWNER/REPO path/to/skill --agent codex --scope user
Install project-level skill:
cd /path/to/repo
gh skill install OWNER/REPO path/to/skill --agent codex --scope project
Update check:
gh skill update --dir "$HOME/.codex/skills" --dry-run
Update all managed skills in a directory:
gh skill update --dir "$HOME/.codex/skills" --all
Install from local repo:
gh skill install ./my-skill-repo skills/my-skill --from-local --agent codex --scope user
Agent values
Use these common --agent values:
codex
claude-code
opencode
gemini-cli
cursor
github-copilot
universal
Common user skill dirs:
Codex: ~/.codex/skills
Claude: ~/.claude/skills
OpenCode: ~/.config/opencode/skills
Shared: ~/.agents/skills (Codex/OpenCode direct; Claude via `~/.claude/skills` symlink; use `--dir`)
Claude shared-skill bridge
Claude Code user-scope skills live under ~/.claude/skills. Local testing with Claude Code 2.1.91 showed it does not directly load ~/.agents/skills, but it does load the directory when ~/.claude/skills is a symlink to ~/.agents/skills. To keep one shared source for all non-agent-specific skills:
rm -rf "$HOME/.claude/skills"
ln -s "$HOME/.agents/skills" "$HOME/.claude/skills"
Do not put agent-specific skills in the shared directory. For example, Codex-only caveman*, cavecrew, and codex-history should stay under ~/.codex/skills.
Scope choice
Use --scope user for general reusable skills.
Use --scope project for repo-specific workflows, project conventions, private docs, or skills that should travel with that repository.
At project scope, many agents use .agents/skills. Confirm the resulting path in gh skill install output.
Repository layout check
Compatible layouts usually look like:
skills/<skill-name>/SKILL.md
prefix/skills/<skill-name>/SKILL.md
plugins/<plugin-name>/skills/<skill-name>/SKILL.md
Hidden Claude layouts need explicit opt-in:
gh skill install OWNER/REPO .claude/skills/name --allow-hidden-dirs --agent claude-code --scope user
Root-only layout is usually not installable by gh skill:
SKILL.md
scripts/
If repo is root-only, options:
- Keep local/manual install.
- Use a fork branch that exposes
skills/<name>/SKILL.md.
- Ask upstream to support
gh skill layout.
- File or reference a GitHub CLI issue for root
SKILL.md support.
Migration/audit workflow
- List installed dirs:
find "$HOME/.codex/skills" -mindepth 1 -maxdepth 1 -type d -printf "%f\n" | sort
- Check managed vs orphan:
gh skill update --dir "$HOME/.codex/skills" --dry-run
- For orphan skills, search exact upstream:
gh skill search "skill-name" --limit 10 --json repo,skillName,path,stars,description
-
If compatible source exists, backup then reinstall with gh skill install --force.
-
If no compatible source exists, leave as orphan or create/fork a compatible layout.
Safety notes
gh skill update --dry-run is read-only.gh skill install --force overwrites matching files but may leave extra local files. Backup first for important skills.- Pinned skills are skipped by update unless unpinned.
- Skill contents are not verified by GitHub. Inspect unfamiliar skills before use.
