New `gh skill list` to inventory installed agent skills by tommaso-moro · Pull Request #13418 · cli/cli · GitHub
Skip to content

New gh skill list to inventory installed agent skills#13418

Merged
BagToad merged 19 commits into
trunkfrom
tommy/skills-list
Jun 4, 2026
Merged

New gh skill list to inventory installed agent skills#13418
BagToad merged 19 commits into
trunkfrom
tommy/skills-list

Conversation

@tommaso-moro

@tommaso-moro tommaso-moro commented May 13, 2026

Copy link
Copy Markdown
Contributor

Closes #13245

Summary

Adds gh skill list to inventory installed agent skills across known agent host directories.

  • Scans project and user skill install paths for all registered agent hosts
  • Deduplicates shared install directories like .agents/skills
  • Supports filtering with --agent, --scope, and custom scanning with --dir
  • Renders a concise table with NAME, AGENT, SCOPE, and SOURCE
  • Supports parseable output via --json, --jq, and --template with fields for skillName, hosts, scope, sourceURL, version, pinned, and path
  • Records privacy-safe skill_list telemetry with filters, output format, and result count

Testing

  • go test ./pkg/cmd/skills/list/...
  • go test ./pkg/cmd/skills/...

@tommaso-moro tommaso-moro marked this pull request as ready for review May 18, 2026 09:45
@tommaso-moro tommaso-moro requested review from a team as code owners May 18, 2026 09:45
@tommaso-moro tommaso-moro requested review from BagToad and Copilot May 18, 2026 09:45

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds a new gh skill list subcommand that scans known agent host directories (project and user scope) for installed skills and renders them as a table or JSON, with filtering via --agent, --scope, and --dir, plus privacy-safe telemetry.

Changes:

  • New pkg/cmd/skills/list/list.go implementing target discovery (deduping shared dirs like .agents/skills), SKILL.md frontmatter parsing, sort/render, JSON export, and skill_list telemetry.
  • New pkg/cmd/skills/list/list_test.go covering flag parsing, mutual exclusivity, table/JSON output, and namespaced source-path skill name recovery.
  • Wires the list subcommand into the skills command and adds an example to its help text.
Show a summary per file
File Description
pkg/cmd/skills/skills.go Registers skilllist.NewCmdList and adds a help example.
pkg/cmd/skills/list/list.go New list command: scan targets, parse skills, render table/JSON, record telemetry.
pkg/cmd/skills/list/list_test.go Tests for flag handling, run-time behavior, and table header.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

  • Files reviewed: 3/3 changed files
  • Comments generated: 0

harder added a commit to harder/gh-skillview that referenced this pull request May 18, 2026
cli/cli#13245 is being closed by cli/cli#13418 (Tommy/skills list), which
adds `gh skill list` with the canonical shape:

  { skillName, hosts[], scope, sourceURL, version, pinned, path }

Where scope ∈ {project, user, custom}, hosts is always an array (empty for
--dir / custom scans, multi-valued for shared install dirs like
.agents/skills), and sourceURL is a full GitHub URL or local filesystem
path. The PR is still open, so this change keeps SkillView's tolerant
parser tolerant — upstream-canonical keys take priority but every legacy /
alternate key our adapter previously recognized stays as a fallback.

Adapter changes:
- GhSkillListRecord adds SourceUrl (string) and Hosts (ImmutableArray) as
  first-class fields; the existing Agents property is now an alias of
  Hosts so any call site that references it continues to work.
- ReadRecord reads `skillName` → fallback `name`/`skill_name`; `hosts` →
  fallback `agents`; `sourceURL` → fallback `repo`/`repository`. New
  ReadStringArray helper deduplicates the loop body.
- CapabilityProbeParser re-enables the `list` probe with the actual
  upstream flag set (`--json --agent --scope --dir`). When the gh binary
  doesn't ship the subcommand the probe is a no-op — ListSubcommandPresent
  stays false and SkillView's filesystem scan stays in charge.
- CapabilityProfile.SupportsListDir lights up automatically once the gh
  binary exposes the flag — unused today but available to any future tab
  that wants to scan a custom dir via gh.

Merge changes:
- CliList-only InstalledSkill records propagate SourceUrl into
  FrontMatter.Upstream so detail panes can render a clickable source link
  for skills that gh knows about but the filesystem scan hasn't seen.
- Agent membership is built from Hosts (upstream-canonical) instead of
  Agents; the legacy singular `agent` field still seeds a single
  membership when no array is present.

Tests:
- GhSkillListAdapterTests adds canonical-payload, multi-host, custom-dir,
  and precedence cases (hosts beats agents, skillName beats name).
- CapabilityProbeParserTests asserts the list-probe flag set instead of
  asserting the subcommand absent.

393/393 unit + 1/1 integration green. Nothing changes behaviorally on a
gh that doesn't ship `gh skill list` yet — the alignment lands now so when
PR #13418 merges, SkillView picks the canonical fields up automatically.

@SamMorrowDrums SamMorrowDrums left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems clean, I hope it helps to increase visibility of what's there (or expected to be there) for people.

@BagToad BagToad changed the title Tommy/skills list New gh skill list to inventory installed agent skills May 20, 2026

@BagToad BagToad left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry for the delay! This looks great. There's some things I think we should change before merging - this is my first pass and probably the only pressing things - I'm working on second pass.

Comment thread pkg/cmd/skills/list/list_test.go Outdated
Comment thread pkg/cmd/skills/list/list_test.go Outdated
Comment thread pkg/cmd/skills/list/list.go Outdated
Comment thread pkg/cmd/skills/list/list.go Outdated
Comment thread pkg/cmd/skills/list/list.go Outdated
Comment thread pkg/cmd/skills/list/list_test.go Outdated
Comment thread pkg/cmd/skills/list/list.go
Comment thread pkg/cmd/skills/list/list.go Outdated
Comment thread pkg/cmd/skills/list/list.go Outdated
Comment thread pkg/cmd/skills/list/list_test.go
@BagToad

BagToad commented May 20, 2026

Copy link
Copy Markdown
Member

Not from this PR, but a thing I bumped into while acceptance-testing it. Running gh skill list in the cli/cli checkout itself surfaces phantom OpenClaw skills:

gh        openclaw  project  -
gh-skill  openclaw  project  -

Cause is in internal/skills/registry/registry.go:229-234:

{
    ID:         "openclaw",
    Name:       "OpenClaw",
    ProjectDir: "skills",            // bare top-level "skills"
    UserDir:    ".openclaw/skills",
},

OpenClaw's project dir is just skills/ at the repo root, so any repo with a top-level skills/ folder (like cli/cli itself, or anyone using this dir convention) gets its contents falsely attributed to OpenClaw. Maybe it should be a special published or generic Agent Host?

Could we fix that in this PR (or a quick follow up before this ships) since this is being exposed to the user now? 🙏

@tommaso-moro tommaso-moro requested a review from BagToad May 22, 2026 14:19
BagToad and others added 4 commits May 28, 2026 15:50
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@BagToad

BagToad commented May 28, 2026

Copy link
Copy Markdown
Member

@tommaso-moro I pushed some changes I found during a deeper review - hope that is okay! 🙏

  • ecdbd6f Sanitize ANSI escapes in name/source columns via our asciisanitizer.
  • 989ee0c Stat + IsRegular check before reading SKILL.md, so reading not normal files won't hang. I think it's probably not a usual thing but it's a better experience this way if it does somehow happen.
  • ea42d46 JSON field hosts renamed to agentHosts, plus renaming the matching helpers. Sorry for harping on the naming, but I really want agent host disambiguated from host in this codebase in all contexts.
  • 69e6ecc Tests + help text use github-copilot instead of claude-code, since we ❤️ copilot

Would love to confirm you're okay with these changes and then we should ship this 🙏

@tommaso-moro

Copy link
Copy Markdown
Contributor Author

@BagToad BagToad merged commit 674e02a into trunk Jun 4, 2026
11 checks passed
@BagToad BagToad deleted the tommy/skills-list branch June 4, 2026 21:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

New subcommand, gh skill list to show installed skills

4 participants