gh-skill-manager

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:

1. Keep local/manual install.
2. Use a fork branch that exposes skills/<name>/SKILL.md.
3. Ask upstream to support gh skill layout.
4. File or reference a GitHub CLI issue for root SKILL.md support.

Migration/audit workflow

1. List installed dirs:

find "$HOME/.codex/skills" -mindepth 1 -maxdepth 1 -type d -printf "%f\n" | sort

2. Check managed vs orphan:

gh skill update --dir "$HOME/.codex/skills" --dry-run

3. For orphan skills, search exact upstream:

gh skill search "skill-name" --limit 10 --json repo,skillName,path,stars,description

4. If compatible source exists, backup then reinstall with gh skill install --force.

5. 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.