gh-skill

name	gh-skill
license	MIT
metadata	{"version":"0.0.1"}
description	Use this skill whenever the user asks about gh skill commands, managing Agent Skills via the GitHub CLI, publishing skills, installing skills from GitHub, updating installed skills, or structuring a skills repository. Triggers include: "gh skill", "publish a skill", "スキルをpublishしたい", "install a skill from GitHub", "gh skill publish", "gh skill install", "gh skill update", "gh skill search", "Agent Skillsのバージョニング", "skills repoの構成", or any mention of the agentskills.io ecosystem. Use this skill proactively — don't attempt to answer gh skill questions from training data alone; the version resolution behavior and monorepo conventions require this skill.

gh skill

Manage Agent Skills via the GitHub CLI (gh skill / gh skills). This skill captures behavior confirmed by reading the cli/cli source — the parts that matter most are not obvious from the docs alone.

Commands at a Glance

Command	What it does
gh skill search <query>	Search public repos for skills by keyword
gh skill install <owner/repo> [skill]	Install a skill locally
gh skill preview <owner/repo> [skill]	Read a skill's SKILL.md without installing
gh skill publish [--tag v0.0.1]	Validate + create GitHub Release
gh skill update [skill…]	Update installed skills to latest

gh skill list does not exist. To see installed skills, use gh skill update --dry-run.

---

Skill Discovery Conventions

gh skill publish and gh skill install discover skills using these path patterns, checked in order:

skills/*/SKILL.md               ← standard: skill name = directory name
skills/{scope}/*/SKILL.md       ← namespaced: install with "scope/skill"
{prefix}/skills/*/SKILL.md      ← prefix variant (e.g. meta/skills/wiki)
*/SKILL.md                      ← root-level single-skill repos
plugins/*/skills/*/SKILL.md     ← plugins convention

For a monorepo like takymt/skills, use skills/*/SKILL.md. The install command is then:

gh skill install takymt/skills wiki          # by skill name
gh skill install takymt/skills meta/wiki     # namespaced (skills/{scope}/{name})

---

SKILL.md Frontmatter

Required: name, description. Recommended: license (SPDX string, e.g. MIT). Useful: metadata.version (per-skill semantic version, for human reference only).

---
name: my-skill
license: MIT
metadata:
  version: "0.0.1"
description: >
  What this skill does and when to use it. Be specific and pushy —
  Claude tends to under-trigger skills, so include explicit phrases
  users would say.
---

metadata.github-* keys are injected by gh skill install for update tracking. gh skill publish strips only those github-* keys — metadata.version is preserved.

---

Publishing Workflow

# 1. Validate first (always)
gh skill publish --dry-run

# 2. Publish with a version tag
gh skill publish --tag v0.0.1

publish will:

1. Validate all skills against the agentskills.io spec
2. Offer to add the agent-skills topic to the repo (enables gh skill search discovery)
3. Create a GitHub Release at the given tag

To replace an existing release:

gh release delete v1.0.0 --cleanup-tag --yes
gh skill publish --tag v0.0.1

Common warnings that are safe to ignore:

• no active tag protection rulesets found — irrelevant for personal repos

---

Versioning Strategy for Monorepos

Critical constraint: gh skill install (without --pin) resolves version via GET /repos/{owner}/{repo}/releases/latest — this is one repo-wide pointer. There is no per-skill "latest release" filtering. Source: internal/skills/discovery/discovery.go.

Recommended: unified v0.0.x release line

Use a single version line for the whole repo. This matches gh skill's native model and ensures no-pin installs always work correctly.

Each skill's individual semantic version goes in its metadata.version field (human-facing, not used for resolution). Example: repo is at v0.0.3, but wiki/SKILL.md has metadata.version: "0.0.5" because the wiki skill iterated faster.

gh skill update is per-skill smart — it compares each installed skill's tree SHA (from metadata.github-tree-sha in the installed SKILL.md) against the remote. A unified version bump only re-downloads skills whose files actually changed.

Pin a specific version:

gh skill install takymt/skills wiki --pin v0.0.2
# or using @ syntax:
gh skill install takymt/skills wiki@v0.0.2

---

Installing Skills

# Basic install (latest release, default agent, project scope)
gh skill install takymt/skills wiki

# For Claude Code, user scope (available in all projects)
gh skill install takymt/skills wiki --agent claude-code --scope user

# From a local repo (development / testing)
gh skill install ./my-skills-repo wiki --from-local

# Install to a custom directory
gh skill install takymt/skills wiki --dir ~/.claude/skills/

# Pin to a specific version
gh skill install takymt/skills wiki --pin v0.0.1

# Force overwrite an existing install
gh skill install takymt/skills wiki --force

Performance tip: in large repos, provide the exact path to skip full tree traversal:

gh skill install takymt/skills skills/wiki

---

Updating Installed Skills

# Check for updates (dry run — also shows installed skills list)
gh skill update --dry-run

# Update specific skills
gh skill update wiki gh-skill

# Update all without prompting
gh skill update --all

# Unpin and update pinned skills
gh skill update --unpin --all

---

Searching for Skills

gh skill search terraform
gh skill search --owner hashicorp terraform
gh skill search wiki --limit 5

Interactive mode lets you select a result and install directly.

---

Preview Before Installing

# Preview a skill's SKILL.md (and browse bundled files interactively)
gh skill preview takymt/skills wiki

# Preview a specific version
gh skill preview takymt/skills wiki@v0.0.1

---

Supported Agents

Key agent IDs for --agent:

Agent	ID
Claude Code	claude-code
GitHub Copilot	github-copilot (default)
Cursor	cursor
Codex	codex
Gemini CLI	gemini-cli

Full list: gh skill install --help.

--scope project (default) installs into the current git repo. --scope user installs into your home directory, available everywhere.