Files
skillshare/website/docs/reference/commands/list.md
T
Willie d759a7e8ee docs: add agent support to all command reference and getting-started pages
Command pages updated (7 files):
- list: 'skillshare list agents', [A] badge
- install: --kind agent, -a flag, auto-detection
- sync: agent sync with all three modes, supported targets
- check: 'skillshare check agents' drift detection
- audit: 'skillshare audit agents'
- enable: --kind agent routes to .agentignore
- uninstall: --kind agent flag

Getting started updated:
- first-sync: link to agents concepts in What's Next
- quick-reference: agent management command table + agents source path

Commands index: added agents row to What do you want to do table.
2026-04-07 18:05:40 +08:00

9.3 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

list demo

Interactive TUI

On a TTY, skillshare list launches an interactive terminal UI with:

  • 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

    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".

  • Keyboard navigation — arrow keys to browse, q to quit

  • Detail panel — shows description, disk path, files, and synced targets for the selected skill

  • Enable/disable toggle — press E to toggle the selected skill's enabled/disabled state. Writes to .skillignore immediately without leaving the TUI. Disabled skills show a red disabled badge in the detail panel.

  • Content viewer — press Enter to open a dual-pane viewer with a file tree on the left and Markdown-rendered content on the right. j/k browse files (auto-preview), l/Enter expand directories, h collapse. Ctrl+d/u scroll content half-page, g/G jump to top/bottom. Mouse wheel and click are also supported.

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 react --sort newest       # Sort by install date
skillshare list --json | jq '.[].name'   # JSON for scripting

:::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:

Installed 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 repositories
─────────────────────────────────────────
  ✓ _team-skills          3 skills, up-to-date

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
Installed 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 - no metadata)

  commit-commands
    Source:      github.com/user/skills
    Type:        github
    Installed:   2026-01-15

Tracked repositories
─────────────────────────────────────────
  ✓ _team-skills          3 skills, up-to-date
  ! _other-repo           5 skills, has changes

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           # → Installed skills (project)

cd ~
skillshare list           # → Installed skills (global)

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

Installed skills (project)
─────────────────────────────────────────

  tools/
    → pdf               anthropic/skills/pdf
    → review            github.com/team/tools

  → my-skill            local

→ 3 skill(s): 2 remote, 1 local

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
--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

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