From 33789149b9def6b66ddf247438a79fac94e22074 Mon Sep 17 00:00:00 2001 From: Kynan Ware <47394200+BagToad@users.noreply.github.com> Date: Mon, 20 Apr 2026 13:38:59 -0600 Subject: [PATCH] docs(skills): add gh and gh-skill agent skills Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- skills/gh-skill/SKILL.md | 124 +++++++++++++++++++++++++++++++++++++++ skills/gh/SKILL.md | 75 +++++++++++++++++++++++ 2 files changed, 199 insertions(+) create mode 100644 skills/gh-skill/SKILL.md create mode 100644 skills/gh/SKILL.md diff --git a/skills/gh-skill/SKILL.md b/skills/gh-skill/SKILL.md new file mode 100644 index 000000000..59f58d325 --- /dev/null +++ b/skills/gh-skill/SKILL.md @@ -0,0 +1,124 @@ +--- +name: gh-skill +description: Manage agent skills with gh skill. Use this skill to discover, preview, install, update, and publish Agent Skills so an agent can self-manage the skills available in its environment. +--- + +# Managing skills with `gh skill` + +`gh skill` installs, previews, searches, updates, and publishes +[Agent Skills](https://agentskills.io). An agent can use it to keep its +own skill set in sync with one or more GitHub repositories. + +The command is also aliased as `gh skills`. Prefer the canonical singular +`gh skill` in scripts and docs. + +## Search + +```bash +gh skill search # free-text search +gh skill search --owner # restrict to one owner +gh skill search --limit 20 --page 2 +gh skill search --json skillName,repo,description +``` + +## Preview before installing + +```bash +gh skill preview / +gh skill preview / @v1.2.0 # pin a version +``` + +## Install + +```bash +gh skill install / +gh skill install / @v1.2.0 +gh skill install / skills// # exact path, fastest +gh skill install ./local-skills-repo --from-local +``` + +`/` and `` are both required. + +Useful flags: + +- `--agent ` - target host (e.g. `github-copilot`, `claude-code`, + `cursor`, `codex`, `gemini-cli`). Repeat for multiple. Default is + `github-copilot` when non-interactive. You should know what agent you are, + so set this appropriately to install for yourself. +- `--scope project|user` - `project` (default) writes inside the current + git repo; `user` writes to the home directory and applies everywhere. +- `--pin ` - pin to a tag, branch, or commit SHA. Mutually exclusive + with `--from-local` and with inline `@version` syntax. +- `--allow-hidden-dirs` - also discover skills under dot-directories such + as `.claude/skills/`. Don't use this unless you need to, it comes with risks. +- `--force` - overwrite an existing install. + +## Update + +```bash +gh skill update --all # update every installed skill +gh skill update # update one +gh skill update --force +gh skill update --unpin # drop the pin and move to latest +``` + +## Publish + +Publishing turns a repo into a discoverable skill source. Skills are +discovered with these conventions: + +- `skills//SKILL.md` +- `skills///SKILL.md` +- `/SKILL.md` (root-level) +- `plugins//skills//SKILL.md` + +Each `SKILL.md` needs YAML frontmatter: + +```yaml +--- +name: my-skill # must equal the directory name +description: One sentence... # required, recommended <= 1024 chars +license: MIT # optional but recommended +--- +``` + +Naming rules (enforced by `publish`): + +- Lowercase alphanumeric and hyphens only, 1–64 chars. +- Must start and end with `[a-z0-9]`. +- No double hyphens (`--`). +- `allowed-tools`, if present, must be a string (space-delimited), not a + YAML array. + +### Validate, then publish + +```bash +gh skill publish --dry-run # validate only, no release +gh skill publish --dry-run ./path/to/repo # validate a specific dir +gh skill publish --fix # auto-strip install metadata +gh skill publish --tag v1.0.0 # non-interactive publish +gh skill publish # interactive publish flow +``` + +`--fix` and `--dry-run` are mutually exclusive. `--fix` only rewrites +install-injected `metadata.github-*` keys and does not publish; commit +the result and re-run `publish`. + +The publish flow will: + +1. Add the `agent-skills` topic to the repo (so search can find it). +2. Use `--tag` (or prompt for one in a TTY). +3. Auto-push any unpushed commits. +4. Create a GitHub release with auto-generated notes. + +Always pass `--tag` so it doesn't fall through to the interactive flow. + +## Self-management pattern for agents + +A reasonable loop: + +1. `gh skill search --json name,repository` +2. `gh skill preview ` to inspect the SKILL.md. +3. `gh skill install --agent --pin ` for a + reproducible install. +4. Periodically `gh skill update --all` to refresh. \ No newline at end of file diff --git a/skills/gh/SKILL.md b/skills/gh/SKILL.md new file mode 100644 index 000000000..e37dafdba --- /dev/null +++ b/skills/gh/SKILL.md @@ -0,0 +1,75 @@ +--- +name: gh +description: Patterns for invoking the GitHub CLI (gh) from agents. Covers structured output, pagination, repo targeting, search vs list, gh api fallback. +--- + +# Reference + +## Interactivity policy + +`gh` already does the right thing in non-TTY contexts: it skips the pager, +strips ANSI color, and errors out fast with a helpful message instead of +prompting (e.g. `must provide --title and --body when not running interactively`). +You don't need to defensively set `GH_PAGER` or pass `--no-pager` (no such +flag exists). + +## Parsing JSON + +Human output from `gh` is column-formatted. If you want structured data: + +- Add `--json field1,field2,...` for structured output. +- Run a command with `--json` and **no field list** to print the full set of + available fields, then pick what you need. +- Use `--jq ''` for filtering without piping through a separate `jq`. +- Use `--template ''` when you want shaped text output. + +## Pagination and silent truncation + +List commands cap results. + +- `gh issue list`, `gh pr list`, `gh search ...`: pass `-L N` (`--limit N`). + The default is usually 30. +- Use `--json totalCount` to get the total number of items. This helps you know + if you need to paginate. +- For raw API calls use `gh api --paginate `. Combine with + `--jq` and (optionally) `--slurp` to assemble one array. + +## Repo targeting + +`gh` infers the repo from the cwd's git remotes. + +Pass `--repo OWNER/REPO` (`-R`) to override the resolved CWD repo. + +## Search vs list + +- `gh search issues|prs|code|repos|commits|users` uses GitHub's search + index and accepts the full search syntax (`is:open`, `author:`, + `label:`, `repo:owner/name`, `in:title`, ...). Prefer it for anything + cross-repo or filtered by author/label. +- `gh issue list --search "..."` and `gh pr list --search "..."` accept + the same syntax but are scoped to one repo. + +## Fall back to `gh api` for anything `--json` doesn't expose + +Sometimes useful data isn't on the typed commands. Examples: + +- Review-thread comments on a PR: `gh api repos/{owner}/{repo}/pulls/{n}/comments` + (the `--comments` flag on `gh pr view` shows issue-level comments only). +- Arbitrary GraphQL: `gh api graphql -f query='...' -F var=value`. +- REST shortcuts: `gh api repos/{owner}/{repo}/...` - note the + `{owner}/{repo}` placeholder is filled in for you when run from a repo + with detected remotes; pass them literally if you want determinism. + +## Authentication + +- `gh auth status` prints the active host(s), user, and which env var (if + any) is being honored. +- `gh auth status --json` is supported. + +## Other notes + +- `gh pr checkout ` switches branches. Use `gh pr diff ` or + `gh pr view ` if you only need to read. +- `NO_COLOR`, `CLICOLOR_FORCE`, and `GH_FORCE_TTY` are honored. Set + `GH_FORCE_TTY=1` if you want TTY-style output (colors, tables, the + pager, interactivity) inside an agent harness; leave it unset unless needed.