Files
skillshare/website/docs/reference/commands/list.md
T
Willie 355b42ee57 feat(cli): one frame and keymap for every TUI, inline prompts, file viewer (#370)
* chore(devcontainer): add a TUI screenshot kit

Recreating the devcontainer wipes vhs and the browser it drives, so
every TUI review started with a manual reinstall. The start script now
installs the recording tools when they are missing and skips straight
through when they are present.

record-tui.sh screenshots each full-screen TUI in its own fresh ssenv,
filled by tui-fixture.sh through real commands, so the TUI redesign can
compare before and after on the same data.

Refs #200

* feat(cli): ask small choices inline instead of full screen

The restore source, new-skill wizard, install skill picker and the
other checklist prompts each took over the whole screen for a handful
of options, and the answer vanished once chosen. They now use the same
inline prompt as init: the question appears in place, collapses into a
"✓ label value" line, and stays in the scrollback.

Lists longer than the visible rows can be narrowed with /, and esc
inside the filter only leaves the filter. Every inline prompt shows
one key line in the wording the full-screen TUIs will share. The new
wizard drops its esc-goes-back steps: esc cancels, as in init.

Refs #200

* feat(cli): give the list TUI the shared frame and keymap

The full-screen TUIs each had their own header, footer and key letters,
so the same action used different keys per screen and the help line
listed everything at once. list is the first screen on a shared frame:
one title line with scope, counts and tabs, the list and details side
by side without dividers, and one key line with the common keys and
the position. Everything else moves under ?, and confirmations ask on
the key line so the list stays visible.

Keys follow one lowercase letter per action (u update, d uninstall,
t enable/disable, m manual only, ! audit). The All tab and the s
status cycle are gone: tab switches skills and agents, and status:
in the filter or --status covers enabled/disabled. Rows drop the
group prefix that the heading above them already shows.

Refs #200

* docs: drop key-by-key TUI instructions from command pages

The command pages carried key tables, screen mock-ups and one bullet
per key for every full-screen TUI, in five languages. The TUIs now show
their keys on screen, so these pages repeated what the screen says and
went stale with every key change (several already listed keys that no
longer exist). Each TUI section is now one paragraph on what the screen
shows and what it can do. What the screen does not explain stays: the
filter tag syntax, what manual only does to SKILL.md, the analyze color
thresholds, when audit opens its TUI, and that target changes are saved
to config immediately.

Refs #200

* feat(cli): move the trash TUI onto the shared frame

The trash TUI replaced the whole screen with a confirmation and a
spinner, so you lost sight of what you had selected, and r/d did
nothing until something was ticked. It now uses the shared frame:
checkbox rows with size and age, details beside them, and the
confirmation, the names it covers, the running operation and its
result on the bottom lines. With nothing selected, r and d act on the
row under the cursor.

Refs #200

* feat(cli): move the log TUI onto the shared frame

Log rows were two-line "[date] COMMAND — status" blocks, stats lived
behind s as a separate screen, and delete swapped the help bar for a
prompt you could miss. Rows are now one line with time, command and a
status mark; Entries and Stats are tabs on the title line next to the
count and success rate; and the delete confirmation takes over the key
line. With nothing selected, d deletes the entry under the cursor.

Row delegates no longer force a 40-column minimum, which wrapped every
row in lists narrower than that.

Refs #200

* feat(cli): move the audit TUI onto the shared frame

The audit TUI had its own tab bar, a divider column and a two-line
summary footer, and esc quit even with a filter typed. It now uses the
shared frame: scan counts and the Skills / Agents tabs on the title
line, the worst severity at the right of each row, the scan-wide
severity, threat and policy summary on the note line, and esc clears
the filter before quitting. Rows under a group no longer repeat the
group's name.

Colored title facts keep their color instead of being dimmed.

Refs #200

* feat(cli): move the audit rules TUI onto the shared frame

The rules browser used keys no other screen shared: s for severity,
space to toggle and R pressed twice to reset. It now follows the
shared keymap: t turns a rule or pattern on or off, e asks for the new
severity on the key line, and R asks yes/no before deleting
audit-rules.yaml. The severity tabs sit on the title line, rows show
the rule count or "off" at the right, and rule rows drop the pattern
prefix the group row already shows. Space still toggles.

When the title line is too narrow for every tab, it shows only the
active one instead of clipping them.

Refs #200

* feat(cli): move the analyze TUI onto the shared frame

Analyze put the target switcher, a stats line and the help text in a
three-line footer and sorted with s, which means sync everywhere else.
It now uses the shared frame: skill count and always-loaded and
on-demand tokens on the title line, one tab per target group, o to
sort with the current order on the key line, and esc clears the
filter before quitting. The details follow the list layout, and lint
warnings use the ! mark the CLI uses.

renderDetailSection and renderFactRow had no other callers and are
removed.

Refs #200

* feat(cli): move the diff TUI onto the shared frame

The diff browser drew ruled separators, "── Next Steps ──" banners and
an arrow before every suggested command, and esc quit with a filter
typed. It now uses the shared frame: target, extra and difference
counts on the title line, what differs at the right of each row, group
rows like the list's, plain headings in the details, and esc clears
the filter before quitting.

Refs #200

* feat(cli): move the restore TUI onto the shared frame

Restore replaced the whole screen for the confirmation, the running
operation and the result, rendered two-line rows, and esc quit even
with a filter typed. It now uses the shared frame: the target or the
chosen target and its backup count on the title line, one-line rows
with backup count and age or skill count and size at the right, and
the confirmation, what it covers, the spinner and the result on the
bottom lines. Esc clears the filter, then goes back, then quits.

Refs #200

* feat(cli): move the MCP manager onto the shared frame and keymap

The MCP manager used its own letters (a add, x remove, b backups, r
refresh), hid the details behind Enter, and printed two help bars.
It now uses the shared frame and the keys every other TUI uses: n
add, i import, e edit, d remove, s sync, r restore, with the details
of the selected server beside the list and ? for all keys. Refresh is
gone because the manager reloads after every action. Command docs drop
the key table, and the how-to page and built-in skill name the new
keys.

Refs #200

* feat(cli): move the search selector onto the shared frame

The search selector rendered two-line checkbox rows, put the details
under the list, used s for "search again" although s means sync
everywhere else, and Enter with nothing selected silently cancelled.
It now uses the shared frame with the keyword and counts on the title
line, one-line rows with stars or risk at the right, and the details
beside the list. Esc clears the filter, then goes back to the keyword
prompt; Enter with nothing selected installs the row under the cursor,
as r and d do in other TUIs. The command page drops its screen mock-up
and key list, and no longer claims the search restarts after an
install.

Refs #200

* feat(cli): move the target TUI onto the shared frame and keymap

The target TUI had five uppercase keys (M, N, I, E, R), a separate
skills-or-agents picker before three of them, and full-screen pickers
and remove confirmation. e now opens one menu of every setting the
target has (skills mode, naming, include, exclude; agents mode,
include, exclude, with agent filters marked as ignored in symlink
mode), and the pickers and pattern editor open beside the list. d asks
on the key line with the command it will run and what removal does.
Patterns are added with n, as everywhere else. Also drops the filter
style helper the MCP change left unused.

Refs #200

* feat(cli): move the extras TUI onto the shared frame and keymap

The extras TUI used six uppercase keys (N, X, S, C, M, F), each with
its own full-screen menu, and a full-screen confirmation. It now uses
the shared frame and keys: n new, d remove, s sync, c collect, and e
for one menu with the mode and flatten setting of every target. The
target menu and mode picker open beside the list, and confirmations
ask on the key line with what the action does. The picker row helper
moves to the shared frame, and the split and scroll-hint helpers no
TUI uses any more are removed.

Refs #200

* feat(cli): share one framed file viewer between list and extras

The list and extras file viewers were two copies of the same layout
with the old look: an indented title, a │ column between the tree and
the file, and a hard-coded yellow cursor. Both now draw through one
renderer in the shared frame: the skill or extra and the open file on
the title line, the tree beside the file without a divider, and the
scroll position at the end of the key line.

Refs #200

* feat(cli): ask for a large repo's folder inline

Installing from a repo with 50+ skills opened a full-screen folder
browser with its own filter bar and key line, then dropped back to an
inline skill checklist. The folder question is now an inline select
like every other install prompt: the first choice installs everything
below the current folder, esc goes up one level, and the chosen folder
collapses into a "✓ folder" line before the skill list appears.

The screenshot fixture gains a 60-skill repo so the picker can be
recorded, and the filter-bar and page-info helpers that only the old
picker used are removed.

Refs #200

* feat(cli): ask for MCP and plugin values inline

MCP and plugin values were typed into a separate textarea program that
submitted on ctrl+d, a key no other prompt uses. They now go through a
new ui.Text prompt drawn like the other inline questions: enter
submits, alt+enter starts a new line, and the box grows with the value.
The MCP name is a single line, so it uses ui.Input. Answers are not
echoed afterwards because a value can hold a secret.

Refs #200

* feat(cli): drop the full-screen MCP change preview

Every MCP add, edit, remove, restore and sync already prints its plan
inline and then asks whether to apply it. The full-screen preview in
between showed the same changes again and needed one more enter, so it
is removed along with the review step of the prompts interface. The
confirm question loses its "Review complete" prefix, and a blank line
now separates it from the plan.

Refs #200

* feat(cli): ask extras init questions inline

`extras init` without arguments ran its own full-screen wizard with a
hand-drawn cursor and a different key line on every step. It now asks
the same questions inline, like `init`: each answer collapses into a
"✓" line, the target line shows where the file lands, and esc cancels
with "Nothing was created".

A new ui.InputValid keeps a question open and shows the error under it
until the answer passes, which the name, file name and per-target file
name questions need.

Refs #200

* fix(cli): drop stale key hints from MCP prompts and help

`mcp --help` still listed the manager keys from before its redesign
(a add, x remove, b backups, r refresh), and several MCP and plugin
questions repeated "Esc cancels" or claimed `a` selects all, while the
key line under every prompt already shows the real keys (ctrl+a for
all). The help now just says where the keys are, and the questions keep
only what the key line cannot say. The MCP command page drops the same
key list in all five locales.

Refs #200

* feat(cli): open a skill's files at its audit findings

The audit TUI listed each finding's file, line and one-line snippet, but
judging whether a finding is real needs the lines around it, and that
meant leaving the TUI to open the file by hand. Enter now opens the
selected skill's files at its most severe finding, with the raw text
numbered and the flagged line marked; n/N steps through the findings in
the order the details number them, and the line above the keys says
which finding is shown.

The viewer state lives in a new fileBrowser so analyze and trash can
open skills the same way. Long lines wrap under their text instead of
being cut, since the evidence is often at the end of a line.

Refs #200

* feat(cli): open a skill's files from analyze

Analyze flags lint issues such as a description that is too short, but
the screen only showed the description text, so fixing a skill meant
finding its folder first. Enter now opens the selected skill's files,
including local ones that live only in a target, as raw numbered text
with the front matter, and the line above the keys repeats the first
lint issue so it can be checked against what is written.

Refs #200

* feat(cli): open a trashed item's files before restoring

The trash TUI showed only the first fifteen lines of SKILL.md, which is
not enough to tell two trashed versions apart or to see a skill's other
files. Enter now opens the item's files in the same viewer as list and
analyze, rendered as Markdown, and esc returns to the trash.

Refs #200

* fix(cli): leave front matter out of the agent viewer in list

Opening an agent in the list TUI rendered its whole file as Markdown,
so the front matter came out as a horizontal rule and a "## name: ..."
heading. Skills already drop it because the details panel shows the
name and description; agents now read their body the same way.

Refs #200

* test(cli): compare trash restore destinations home-relative

The trash TUI shows restore destinations through shortenPath, so with
HOME=/tmp, as in the offline Docker sandbox job, /tmp/skills prints as
~/skills and the tests that expected the absolute path failed. They now
expect whatever shortenPath gives for the same path.

Refs #200

* fix(cli): show control characters in viewed files as symbols

The file viewers in list, extras, audit, analyze and trash wrote a
file's bytes to the terminal as they were. Audit and analyze exist to
inspect skills that may not be trusted, and a SKILL.md with an ESC or
OSC sequence could rewrite the screen or the window title instead of
being shown. Control characters are now replaced with same-width
symbols such as ␛ before rendering, which keeps line numbers and the
marked finding line in place; newlines and tabs are kept and CRLF is
read as LF.

Refs #200

* fix(cli): open audit findings in files the tree leaves out

The file tree skips dotfiles and stops at three levels and 200 entries,
but the audit scan reads root dotfiles and goes deeper. A finding in
such a file, like a root .env, left the viewer on the previous file
with the new finding's note above unrelated text. Opening a finding now
adds its file to the top of the tree under its full relative path when
it is missing, so the marked line is always the one reported.

Refs #200

* fix(devcontainer): exit nonzero when a TUI screenshot fails to record

record-tui.sh printed FAIL for a screen whose vhs run failed but still
exited 0, so an unattended run looked like every screenshot was taken.
It now remembers a failure, keeps cleaning up and recording the other
screens, and exits 1 at the end.

Refs #200

* fix(cli): keep other files' front matter and fit text to the pane

Two problems in the shared file viewer:

- It dropped YAML front matter from every Markdown file, so a trashed
  skill's README or template lost its metadata, which nothing else in
  the trash view shows. Only SKILL.md and a single-file agent drop it
  now, since their name and description appear in the details.
- The open file was wrapped to at least 40 columns. In a narrow
  terminal that is wider than the right pane, so the layout wrapped
  each row a second time, breaking lines apart and moving the marked
  finding line. Text now wraps to the pane's real width.

Refs #200

* fix(cli): keep frame lines within the terminal width

joinEnds padded the title, confirm and filter lines but never cut them,
so a long search query, path or command made the line wrap. Every TUI
sizes its body for a fixed four lines of frame, so the wrap pushed the
bottom of the body off the screen. Long text is now cut from the left
side, keeping the status or tabs on the right. Lines are left alone
until the terminal has reported its width.

Refs #200

* fix(cli): show a nested skill's folder when no group heading names it

List rows dropped the first path segment for every skill on the grounds
that the group heading above shows it. With a single group, or a filter
that leaves one, there is no heading, so frontend/react showed as just
react and same-named skills from two folders looked alike. Rows now
drop it only under a heading; a tracked skill's repo dir is still
dropped as before.

Refs #200

* fix(ui): let esc leave a prompt's filter after enter found nothing

The inline prompt guessed the filter state from key presses and treated
enter as leaving the filter. huh's Select stays in the filter when enter
has no match, so the next esc, meant to leave the filter, cancelled the
question instead: one folder level back in the large-repo picker, or the
whole install at the top. The prompt now asks the field whether it is
filtering.

Refs #200

* fix(cli): show control characters in the trash preview as symbols

The trash details panel prints the first lines of a trashed SKILL.md,
and it wrote them to the terminal as they were. The file viewers already
pass text through printableText so an ESC or OSC sequence in a skill is
shown instead of acted on; the preview now does the same.

Refs #200

* fix(cli): scroll an agent's text with the wheel anywhere in list

An open agent has no file tree, but the wheel still treated the left
quarter of the screen as the tree, so scrolling there did nothing. The
whole screen now scrolls the agent's text.

Refs #200

* fix(ui): read prompt answers after the prompt has run

The prompt helpers returned "value, runPrompt(..., &value)". The Go spec
leaves the order between reading value and the call unspecified, so a
compiler may return the value from before the user answered. gc 1.25
runs the call first, so answers arrive today, but nothing guarantees it.
Each helper now runs the prompt into err and then returns the value.

Refs #200

* fix(cli): name hidden Unicode and skip oversized files in the viewer

Two gaps in the file viewer used to inspect untrusted skills:

- Zero-width and bidirectional characters passed through unchanged,
  although the audit reports them as HIGH (Trojan Source). Opening such
  a finding reordered or hid the text instead of showing the cause.
  They now appear as <U+202E> and the like.
- Moving onto a file read all of it, then copied it again while
  numbering and wrapping, with no size limit. The audit skips files
  over 1 MB; the viewer now does too and says the file is too large.

Refs #200

* fix(cli): show control characters in viewed file names as symbols

File contents in the viewer already pass through printableText, but the
tree and the title printed file and skill names as they were. A file
named with an ESC sequence, a newline or a bidirectional character in a
skill under review could still reach the terminal, or break the frame
across lines. Names now go through printableName, which also shows a
newline or tab as a symbol so the name stays on one line.

Refs #200
2026-10-04 04:14:47 +08:00

10 KiB

sidebar_position
sidebar_position
4

list

List all installed skills in the source directory.

skillshare list              # Interactive TUI (default on TTY)
skillshare list --verbose    # Detailed plain text view
skillshare list --json       # JSON output for CI/scripts

When to Use

  • See what skills are installed and where they came from
  • Search and filter skills interactively
  • Check which skills are tracked repos vs local
  • Audit your skill collection before a cleanup
skillshare list --no-tui

Skills
  _superpowers/skills/
    brainstorming                tracked: _superpowers
    dispatching-parallel-agents  tracked: _superpowers
    systematic-debugging         tracked: _superpowers
    …
  frontend/
    react-components             local
  web/
    accessibility                github.com/addyosmani/web-quality-skills/skills...
    core-web-vitals              github.com/addyosmani/web-quality-skills/skills...
    …
  docx                           github.com/anthropics/skills/skills/docx
  frontend-design                github.com/anthropics/skills/skills/frontend-de...
  pdf                            github.com/anthropics/skills/skills/pdf
  skill-creator                  github.com/anthropics/skills/skills/skill-creator
  skillshare                     github.com/runkids/skillshare/skills/skillshare
  …

Tracked repos
✓ _superpowers  up to date · 15 skills

28 skills · 15 tracked, 9 remote, 4 local
  Add -v for sources and install dates

Interactive TUI

On a TTY, skillshare list opens an interactive view with skills and agents in two tabs: the list on the left, and details for the selected item on the right. From there you can update, uninstall or audit a skill, turn it on or off (written to .skillignore right away), and read its files. The common keys are at the bottom of the screen; press ? for all of them.

  • Smart filtering — press / to filter by name, path, or source. Supports tag syntax for precise filtering:

    Tag Short Values Example
    type: t: tracked, remote, local, github t:tracked
    group: g: any directory name g:security
    repo: r: any repo name r:team
    kind: k: skill, agent k:agent
    status: s: enabled, disabled s:disabled

    Tags can be combined with free text (AND logic):

    t:tracked g:security audit
    

    This shows only tracked skills in the "security" group whose name contains "audit".

  • Manual only toggle — press m to toggle disable-model-invocation in the selected skill's SKILL.md. The skill stays installed and you can still invoke it by name, but the model stops loading it on its own; the detail panel shows manual only. Unlike t, this edits the skill file itself: for a tracked or installed skill the TUI asks first, because skillshare update skips tracked repos with local changes and reinstalling a skill drops the edit. Pressing m again removes the line and restores the file exactly. Agents are not affected. The dashboard shows the same manual only tag and has the switch in its skill editor.

Use --no-tui to skip the TUI and print plain text instead:

skillshare list --no-tui          # Plain text output
skillshare list --no-tui | less   # Pipe to pager manually

Search and Filter

Filter skills without entering the TUI:

skillshare list react                     # Filter by name/path/source
skillshare list --type local              # Only local skills
skillshare list --type github             # Only GitHub-sourced skills
skillshare list --status disabled         # Only skills disabled via .skillignore
skillshare list --status enabled --json   # Enabled skills, as JSON
skillshare list react --sort newest       # Sort by install date
skillshare list --json | jq '.[].name'   # JSON for scripting

The default view (--status all) includes entries marked disabled. --status combines with the pattern and --type using AND semantics, works in project mode and for list agents / list --all, and narrows the TUI the same way; its top line then says, for example, disabled only. Inside the TUI, type s:disabled in the filter instead.

:::tip AI Usage Use --json mode when inspecting skills programmatically:

skillshare list --json | jq '.[] | {name, source, type}'

:::

Example Output

Compact View

Skills are automatically grouped by directory when you use folders to organize them:

Skills
  frontend/
    react-helper   github.com/user/skills
    vue-helper     github.com/user/skills
  my-skill         local
  commit-commands  github.com/user/skills
  old-draft        local · disabled

Tracked repos
✓ _team-skills  up to date · 3 skills

8 skills · 3 tracked, 3 remote, 2 local
  Add -v for sources and install dates

If all skills are at the top level (no folders), the output is a flat list — identical to previous versions.

Verbose View

skillshare list --verbose
Skills
  frontend/
    react-helper
      Source     github.com/user/skills
      Type       github
      Installed  2026-01-15
    vue-helper
      Source     github.com/user/skills
      Type       github
      Installed  2026-01-15
  my-skill
    Source     local
  commit-commands
    Source     github.com/user/skills
    Type       github
    Installed  2026-01-15

Tracked repos
✓ _team-skills  up to date · 3 skills
! _other-repo   has changes · 5 skills

12 skills · 8 tracked, 3 remote, 1 local

Global vs Project

skillshare operates at two levels. The list command shows skills from the active level:

flowchart TD
    subgraph GLOBAL["GLOBAL"]
        G_SRC["~/.config/skillshare/skills/"]
        G_CMD["list / list -g"]
        G_CMD --> G_SRC
    end
    subgraph PROJECT["PROJECT"]
        P_SRC[".skillshare/skills/"]
        P_CMD["list -p"]
        P_CMD --> P_SRC
    end
Global Project
Source ~/.config/skillshare/skills/ .skillshare/skills/
Flag -g or default -p or auto-detected
Scope All projects on machine Single repository
Shared via push / pull git commit

Auto-Detection

When you run skillshare list without flags, skillshare automatically detects the mode:

flowchart LR
    CMD["skillshare list"] --> CHECK{".skillshare/config.yaml exists?"}
    CHECK -- YES --> PROJ["Project mode"]
    CHECK -- NO --> GLOB["Global mode"]
cd my-project/            # Has .skillshare/config.yaml
skillshare list           # → Skills · project

cd ~
skillshare list           # → Skills

Use -p or -g to override auto-detection:

skillshare list -g        # Force global, even inside a project
skillshare list -p        # Force project, even without auto-detection

Project Mode

skillshare list          # Auto-detected if .skillshare/ exists
skillshare list -p       # Explicit project mode

Example Output

Skills · project
  tools/
    pdf     anthropic/skills/pdf
    review  github.com/team/tools
  my-skill  local

3 skills · 2 remote, 1 local
  Add -v for sources and install dates

Project list uses the same visual format as global list, with · project label in the header. Skills are grouped by directory and categorized as local (no metadata) or by source URL (remote).

Options

Flag Description
[pattern] Filter skills by name, path, or source (case-insensitive)
--verbose, -v Show detailed information (source, type, install date)
--json, -j Output as JSON (useful for CI/scripts)
--no-tui Disable interactive TUI, use plain text output
--type, -t <type> Filter by type: tracked, local, github
--status <status> Filter by status: all (default), enabled, disabled
--sort, -s <order> Sort order: name (default), newest, oldest
--project, -p List project skills
--global, -g List global skills
--help, -h Show help

Directory Grouping

When skills are organized into folders (via --into during install or manual mv + sync), list automatically groups them by directory:

  frontend/
    react-helper  github.com/user/skills
    vue-helper    github.com/user/skills
  my-skill        local
  • Skills under the same folder share a group header (e.g., frontend/)
  • Within each group, only the base name is shown (not the full path)
  • Top-level skills (no parent folder) appear ungrouped at the bottom
  • If all skills are top-level, the output is a flat list — no group headers

Grouping is based on the directory structure inside your source directory, not a flag. To start using it, organize skills with --into:

skillshare install owner/repo -s react-patterns --into frontend
skillshare install owner/repo -s vue-patterns --into frontend

For more details, see Organizing Skills with Folders.

Understanding the Output

Skill Sources

Label Meaning
local Created locally, no metadata
github.com/... Installed from GitHub
tracked: <repo> Part of a tracked repository
[disabled] Skill is excluded via .skillignore (see enable/disable)

Repository Status

Icon Meaning
✓ Up-to-date, no local changes
! Has uncommitted changes
! + warning Git status unknown (could not be read); a warning line names the repo and error

Agent Support

skillshare list agents filters to agents only, showing .md files from the agents source directory (~/.config/skillshare/agents/ or .skillshare/agents/).

skillshare list agents              # List agents only
skillshare list agents --json       # JSON output for agents
skillshare list agents --verbose    # Detailed agent list

In the interactive TUI, agents display an [A] badge to distinguish them from skills. All TUI features (filtering, detail panel, enable/disable toggle) work the same way.

Without the agents argument, list shows skills only (default behavior). See Agents for background.

See Also