* docs(proposals): propose agent-specific skill variants Tracked repositories can ship different files for the same skill across agents. Counting and syncing each copy independently sends incompatible instructions to every target unless users maintain routing filters. Propose repository-scoped logical identity and exact variant routing while preserving source files, explicit controls, and existing naming behavior. Leave activation and compatibility decisions for maintainer review. Refs #648 * docs(proposals): clarify variant routing compatibility Explain how recognition affects universal-only targets and how existing per-variant overrides preserve the desired routing. Fix the precedence between variant identity and generic host-style path inference. Include analyze, move, and catalog consumers while preserving physical identifiers and actual context-cost accounting. Refs #648 * docs(proposals): clarify activation assumptions and scope Make acceptance cases conditional on maintainer-approved recognition being enabled for the tracked source. Separate the provisional implementation estimate from this proposal-only PR so its size is clear. Refs #648 * docs(proposals): qualify naming and opt-in assumptions State that the reproduced routing behavior uses default flat target naming. Leave any opt-in surface with the maintainer's activation decision without ruling out future CLI or config fields. Refs #648 * feat: recognize and route tracked agent skill variants Count tracked variants as logical skills in source and repository summaries, while preserving physical paths, sync operations, and context costs. Select matching canonical agent variants, including account targets, through shared discovery and selection with existing explicit routing precedence. Refs #648 * fix: count logical skills in sync inventory summaries Use shared logical and physical inventory counts in global and project sync closing lines while preserving each target's operation totals. Refs #648 * fix: preserve variant routing diagnostics across previews Resolve target selections once so CLI and server previews keep ambiguity reasons and physical skip counts. Explain managed variants removed by automatic agent routing, and report logical inventory in doctor. Keep warning rows read-only, document upgrade recovery in translated filtering references, and remove the optional README-only addition. Refs #648 * fix: align sync matrix previews with shared variant selection Classify the full source selection once per target so matrix previews honor canonical aliases, account identity, exact-agent routing, and ambiguous variant skips. Preserve each rejected physical path's existing diagnostic and draft filter disambiguation; skipped preview rows remain read-only. Refs #648 * test: expect singular skill wording in doctor source checks Keep the undiscovered-link count assertion aligned with logical source inventory formatting for one skill in global and project mode. Refs #648 * fix: retain selection diagnostics in catalog and diff verdicts Report warning-only diff targets as requiring attention while preserving local-only folder semantics. Reuse shared per-path selection diagnostics in target-scoped catalogs without applying target naming to served paths. Compute source counts once in summary callers and require variant counts in the source status formatter. Refs #648 * test: tighten tracked variant preview fixtures Use a real committed tracked repository for status counts, verify sync preview banners retain server warnings, and use emitted ambiguity reason text in target preview fixtures. Refs #648 * fix(sync): keep agent variants in shared target folders Compatible targets sharing a skills folder need a combined selection so Codex and universal do not prune one another in merge or copy mode. Carry every shared reader through selection, pruning and previews, including project targets, account identities and path aliases. Require a matching skill suffix under two distinct agents before inferring variants, keeping ordinary agent-named categories unrestricted. Separate naming warnings from ambiguous selection in diff and explain ambiguous removals. Add global/project regression coverage for repeated sync, target-only sync, status JSON, diff and API consumers. * fix(variants): align consumer counts, hints and diagnostics Use logical source counts in list, tracked install and init summaries while matching audit caches against physical variants. Restore localized dashboard skip hints and explain symlink routing limits in status and doctor, including project and JSON output. Document paired-agent detection and compatible shared-folder selection in the proposal, built-in skill and English plus translated command pages. Add focused regressions for the affected consumers. * fix(sync): cover initial sync and ignored variant diagnostics Init syncs a fresh in-memory config, so resolve shared target identities before its first sync as well as when loading saved configuration. A whole-directory symlink exposes ignored skills too. Diagnose agent variants using physical inventory when active discovery has none, while keeping logical counts and merge/copy selection restricted to enabled skills. Cover global/project JSON status and doctor with regressions. Reuse sourcewalk directory and canonical-path helpers so traversal guards remain enforced and path resolution has a single existing owner. * fix(variants): address conversion, counts and selection diagnostics Ignore runtime agent identities when comparing convertible project targets and count logical skills during init. Keep selection warnings separate from naming warnings and preserve agent-named parent skills as ordinary skills. Cover account sync/prune, project ambiguity and overrides in merge/copy modes, and init/status agreement. Focused verification ran in an isolated Linux Codex container, not the devcontainer, as authorized. * refactor(variants): remove obsolete selection helpers Remove the unused FilterSkillsByTarget wrapper and prune agent parameter, cache canonical target aliases once, and restore catalog skip ordering to avoid an unrelated behavior change. Completes the optional cleanup from PR 649 review. * fix(ui): expose localized variant selection diagnostics Show target warnings with source paths, localize ambiguity across preview and detail consumers, and let skipped preview rows add a physical exclude pattern. Show tracked repository variant counts alongside logical skills. Drop display-only rendered cases while retaining mutation protection and plain TypeScript logic coverage. Inspect target states in Clean/Playful light/dark and Traditional Chinese. * docs(variants): explain diagnostics and add sync runbook Document doctor variant_routing and logical/physical counts, diff selection skips, and the nested parent-skill boundary. Keep all four command translations aligned and add isolated account/project E2E scenarios. Both runbook steps passed in the authorized Linux Codex container with separate HOME/XDG/TMPDIR fixtures. Website typecheck and all five locale builds passed. * test(config): use native paths in project conversion fixture The shared-agent regression fixture appended slash-separated suffixes to Windows temporary paths, so project path matching returned no candidates. Build each path with filepath.Join and preserve all conversion assertions. Focused project configuration tests passed in the authorized isolated Linux Codex container, not the devcontainer. Windows CI verifies the platform-specific fixture correction. * fix(ui): recompute shared skill routing for filter previews Evaluate edited include/exclude settings in the complete target map before classifying the draft, so a formerly shared folder no longer keeps its old union when the filters differ. Preserve the saved target configuration. * fix(mcp): keep parent skills when peer variants route elsewhere Do not treat an otherwise eligible variant for another agent as an unserved nested skill. Continue blocking parent publication for explicitly filtered, disabled, ambiguous, or invalid children so filters still hide their files. * fix(ui): distinguish agent selection from naming skips Expose separate naming and selection skip counts on target summaries. Show each applicable remedy in target details and sync previews so ambiguity keeps its filter/override guidance alongside naming and collision hints. * fix(list): include disabled rows in tracked repository counts Count the complete inventory that list displays, including ignored skills and physical variants, without changing the enabled counts used by status, install, or sync. Clone rows before counting to preserve disabled state. * docs: align variant counts and routing recovery guidance Show logical skill and physical variant counts in list/install documentation and keep the four translations aligned with the filtering examples. Explain that agent-named skill parents keep ordinary nested skills and retain the devcontainer-only runbook environment. Removal warnings now recommend a source-local override, since include filters cannot undo agent routing. * fix(mcp): preserve explicit target restrictions on nested variants Limit the differently routed child exemption to automatic layout inference. Frontmatter targets and dashboard source-local overrides must still prevent a parent from publishing files explicitly restricted to another target. * fix(ui): fill target name in naming warning guidance Pass the current target name when rendering localized warning hints so the same naming guidance shown beside the controls does not expose a placeholder in the warning banner. Verified in the populated target preview. --------- Co-authored-by: Willie <egg358358@gmail.com>
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,githubt:trackedgroup:g:any directory name g:securityrepo:r:any repo name r:teamkind:k:skill,agentk:agentstatus:s:enabled,disableds:disabledTags can be combined with free text (AND logic):
t:tracked g:security auditThis shows only tracked skills in the "security" group whose name contains "audit".
-
Manual only toggle — press
mto toggledisable-model-invocationin the selected skill'sSKILL.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. Unliket, this edits the skill file itself: for a tracked or installed skill the TUI asks first, becauseskillshare updateskips tracked repos and installed skills with local changes until you pressmagain or update with--force, which drops the edit. Pressingmagain 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, 5 variants
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, 5 variants
! _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
- enable / disable — Toggle skills without removing
- install — Install skills
- uninstall — Remove skills
- status — Show sync status
- Agents — Agent concepts