Files
skillshare/website/docs/reference/commands/extras.md
T
Willie 405a2f907a feat(extras): add mode command for CLI, TUI, and Web UI
Add ability to change sync mode of an extra's target across all three
interfaces: CLI (`extras mode`/shorthand `extras <name> --mode`),
TUI (`M` key with mode picker overlay), and Web UI (inline Select
dropdown per target with PATCH /api/extras/{name}/mode endpoint).

Fix sync behavior so symlinks from a previous mode are auto-replaced
without --force, while regular files still require explicit --force.

Consolidate sync mode list into config.ExtraSyncModes single source
of truth. Fix Select component missing disabled prop and add viewport
collision detection with useLayoutEffect.

Includes 8 integration tests covering mode command happy path, error
cases, shorthand syntax, and mode-switch sync behavior.
2026-03-12 16:45:02 +08:00

6.9 KiB

sidebar_position
sidebar_position
2

extras

Manage non-skill resources (rules, commands, prompts, etc.) that are synced alongside skills.

Overview

Extras are additional resource types managed by skillshare — think of them as "skills for non-skill content." Common use cases include syncing AI rules, editor commands, or prompt templates across tools.

Each extra has:

  • A name (e.g., rules, prompts, commands)
  • A source directory under ~/.config/skillshare/extras/<name>/ (global) or .skillshare/extras/<name>/ (project)
  • One or more targets where files are synced to

Commands

extras init

Create a new extra resource type.

# Interactive wizard
skillshare extras init

# CLI flags
skillshare extras init <name> --target <path> [--target <path2>] [--mode <mode>]

Options:

Flag Description
--target <path> Target directory path (repeatable)
--mode <mode> Sync mode: merge (default), copy, or symlink
--project, -p Create in project config (.skillshare/)
--global, -g Create in global config

Examples:

# Sync rules to Claude and Cursor
skillshare extras init rules --target ~/.claude/rules --target ~/.cursor/rules

# Project-scoped extra with copy mode
skillshare extras init prompts --target .claude/prompts --mode copy -p

extras list

List all configured extras and their sync status. Launches an interactive TUI by default.

skillshare extras list [--json] [--no-tui] [-p|-g]

Options:

Flag Description
--json JSON output
--no-tui Disable interactive TUI, use plain text output
--project, -p Use project-mode extras (.skillshare/)
--global, -g Use global extras (~/.config/skillshare/)

Interactive TUI

The TUI provides a split-pane interface with extras list on the left and detail panel on the right. Key bindings:

Key Action
↑↓ Navigate list
/ Filter by name
Enter Content viewer (browse source files)
N Create new extra
X Remove extra (with confirmation)
S Sync extra to target(s)
C Collect from target(s)
M Change sync mode of a target
Ctrl+U/D Scroll detail panel
q / Ctrl+C Quit

The color bar on each row reflects aggregate sync status: cyan = all synced, yellow = drift, red = not synced, gray = no source.

For extras with multiple targets, S, C, and M open a target sub-menu. S and C allow selecting all targets at once; M requires picking a specific target.

The TUI can be permanently disabled with skillshare tui off.

Plain text output

When TUI is disabled (via --no-tui, skillshare tui off, or piped output):

$ skillshare extras list --no-tui

Rules            ~/.config/skillshare/extras/rules/  (2 files)
  ✔ ~/.claude/rules   merge   synced
  ✔ ~/.cursor/rules   copy    synced

Prompts          ~/.config/skillshare/extras/prompts/  (1 file)
  ✔ ~/.claude/prompts  merge  synced

extras mode

Change the sync mode of an extra's target.

skillshare extras mode <name> --mode <mode> [--target <path>] [-p|-g]
# Shorthand (no "mode" subcommand):
skillshare extras <name> --mode <mode> [--target <path>]

Options:

Flag Description
--mode <mode> New sync mode: merge, copy, or symlink (required)
--target <path> Target directory path (optional if extra has only one target)
--project, -p Use project-mode extras (.skillshare/)
--global, -g Use global extras (~/.config/skillshare/)

Examples:

# Change rules mode (single target — auto-resolved)
skillshare extras rules --mode copy

# Specify target explicitly (required for multi-target extras)
skillshare extras mode rules --target ~/.claude/rules --mode copy

# Change to symlink in project mode
skillshare extras mode commands --target ~/.cursor/commands --mode symlink -p

Also available via the TUI (M key) and Web UI (mode dropdown on each target).

extras remove

Remove an extra from configuration.

skillshare extras remove <name> [--force] [-p|-g]

Source files and synced targets are not deleted — only the config entry is removed.

extras collect

Collect local files from a target back into the extras source directory. Files are copied to source and replaced with symlinks.

skillshare extras collect <name> [--from <path>] [--dry-run] [-p|-g]

Options:

Flag Description
--from <path> Target directory to collect from (required if multiple targets)
--dry-run Show what would be collected without making changes

Example:

# Collect rules from Claude back to source
skillshare extras collect rules --from ~/.claude/rules

# Preview what would be collected
skillshare extras collect rules --from ~/.claude/rules --dry-run

Sync Modes

Mode Behavior
merge (default) Per-file symlinks from target to source
copy Per-file copies
symlink Entire directory symlink

When switching modes (e.g., from merge to copy), the next sync automatically replaces existing symlinks with the new mode's format. No --force is needed — symlinks are always safe to replace. Regular files created locally require --force to overwrite.


Directory Structure

~/.config/skillshare/
├── config.yaml          # extras config lives here
├── skills/              # skill source
└── extras/              # extras source root
    ├── rules/           # extras/rules/ source files
    │   ├── coding.md
    │   └── testing.md
    └── prompts/
        └── review.md

Configuration

In config.yaml:

extras:
  - name: rules
    targets:
      - path: ~/.claude/rules
      - path: ~/.cursor/rules
        mode: copy
  - name: prompts
    targets:
      - path: ~/.claude/prompts

Syncing

Extras are synced with:

skillshare sync extras        # sync extras only
skillshare sync --all         # sync skills + extras together

See sync extras for full sync documentation including --json, --dry-run, and --force options.


Workflow

# 1. Create a new extra
skillshare extras init rules --target ~/.claude/rules --target ~/.cursor/rules

# 2. Add files to the source directory
# (edit ~/.config/skillshare/extras/rules/coding.md)

# 3. Sync to targets
skillshare sync extras

# 4. List status
skillshare extras list

# 5. Collect a file edited in a target back to source
skillshare extras collect rules --from ~/.claude/rules

See Also

  • sync — Sync extras to targets
  • status — Show extras file and target counts
  • Configuration — Extras config reference