Files
skillshare/website/docs/reference/commands/list.md
T
Willie 7a7cceefab feat(update): flag and protect skills edited since install (#622)
* feat(update): flag and protect skills edited since install

A skill installed from a repository and then edited by hand looked
exactly like an untouched one: check said up to date, and update either
reported it current or silently reinstalled it over the edit (#621).

Install already records each file's hash, so check now compares a
remote skill's files with those hashes and reports "modified", and
update skips such a skill until --force (CLI single, --all/--group,
dashboard). --force, the dashboard's Force Retry on the skipped row, or
the confirmation on the skill page discards the edit and reinstalls.

Two hash paths had to be made reliable for this to be trusted: the
dashboard's folder-wide target edit refreshed hashes by basename, so a
nested skill looked edited after skillshare's own change, and a skill
whose files cannot be hashed now counts as modified instead of being
overwritten.

* fix(server): keep earlier local edits when a target change rewrites SKILL.md

Changing a skill's targets in the dashboard rewrites its SKILL.md, and
both the folder-wide and the single-skill handler then re-hashed the
whole directory as the new baseline. An edit the user had already made
to any file in the skill was absorbed into that baseline, so the skill
stopped counting as modified and the next update overwrote the edit
without --force.

Both handlers now move only SKILL.md's recorded hash, and only when the
file still matched it before the rewrite. skillshare's own target edit
no longer reads as a local change, and an earlier edit still does. The
whole-directory refresh helpers lost their last callers and are removed.
2026-10-24 16:33:37 +08:00

11 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

With follow_source_links: true, unavailable first-level source links produce a warning naming the link while healthy skills remain listed. With --json, these warnings go to stderr and stdout remains valid JSON.

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 and installed skills with local changes until you press m again or update with --force, which 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 move + 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