mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-20 20:34:19 +00:00
526 lines
20 KiB
Markdown
526 lines
20 KiB
Markdown
---
|
|
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** — configurable via `extras_source` or per-extra `source`, defaults to `~/.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.
|
|
|
|
```bash
|
|
# 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` |
|
|
| `--flatten` | Sync files from subdirectories directly into the target root (cannot be used with `symlink` mode) |
|
|
| `--source <path>` | Custom source directory for this extra (overrides `extras_source` and default; **global mode only**) |
|
|
| `--force` | Overwrite if extra already exists |
|
|
| `--no-tui` | Skip interactive wizard, use CLI flags only |
|
|
| `--project, -p` | Create in project config (`.skillshare/`) |
|
|
| `--global, -g` | Create in global config |
|
|
|
|
:::note
|
|
`--source` is only supported in global mode. Project mode always uses `.skillshare/extras/<name>/` as the source directory.
|
|
:::
|
|
|
|
**Examples:**
|
|
|
|
```bash
|
|
# Sync rules to Claude and Cursor
|
|
skillshare extras init rules --target ~/.claude/rules --target ~/.cursor/rules
|
|
|
|
# Use a custom source directory
|
|
skillshare extras init rules --target ~/.claude/rules --source ~/company-shared/rules
|
|
|
|
# Overwrite an existing extra with new targets
|
|
skillshare extras init rules --target ~/.cursor/rules --force
|
|
|
|
# Project-scoped extra with copy mode
|
|
skillshare extras init prompts --target .claude/prompts --mode copy -p
|
|
|
|
# Sync agents flat (tools like Claude Code only discover flat files)
|
|
skillshare extras init agents --target ~/.claude/agents --flatten
|
|
```
|
|
|
|
### `extras list`
|
|
|
|
List all configured extras and their sync status. Launches an interactive TUI by default.
|
|
|
|
```bash
|
|
skillshare extras list [--json] [--no-tui] [-p|-g]
|
|
```
|
|
|
|
**Options:**
|
|
|
|
| Flag | Description |
|
|
|------|-------------|
|
|
| `--json` | JSON output (includes `source_type`: `per-extra` / `extras_source` / `default`, and a per-target `extension` field when set) |
|
|
| `--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 |
|
|
| `F` | Toggle flatten on/off for 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`, `M`, and `F` open a target sub-menu. `S` and `C` allow selecting all targets at once; `M` and `F` require 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
|
|
|
|
Extras
|
|
─────────────────────────────────────────
|
|
→ rules ~/.config/skillshare/extras/rules/ · 2 files
|
|
✓ ~/.claude/rules merge
|
|
✓ ~/.cursor/rules copy
|
|
|
|
→ codex-agents ~/.config/skillshare/agents · 3 files
|
|
✓ ~/.codex/agents extension: codex-agents
|
|
```
|
|
|
|
A synced row shows only its icon, path, and mode; non-synced rows append a status word (`drift`, `not synced`, `no source`). Targets with a transform extension are labeled `extension: <name>` in place of the sync mode (their underlying mode is always `copy`).
|
|
|
|
### `extras source`
|
|
|
|
Show or set the global `extras_source` directory. This is the default parent directory where extras source files are stored.
|
|
|
|
```bash
|
|
skillshare extras source # show current value
|
|
skillshare extras source <path> # set new value
|
|
```
|
|
|
|
Without arguments, displays the current `extras_source` path (with `(default)` if auto-detected). With a path argument, updates `extras_source` in the global config.
|
|
|
|
:::note
|
|
This command is global-only. Project mode always uses `.skillshare/extras/` and does not support `extras_source`.
|
|
:::
|
|
|
|
**Examples:**
|
|
|
|
```bash
|
|
# Show current extras_source
|
|
skillshare extras source
|
|
|
|
# Set to a shared directory
|
|
skillshare extras source ~/company-shared/extras
|
|
```
|
|
|
|
### Operating on an existing extra
|
|
|
|
Change a target's sync mode or flatten setting, or add/remove a target — all via flags on `extras <name>`. These are config-only; run `skillshare sync extras` afterward to apply changes on disk.
|
|
|
|
```bash
|
|
skillshare extras <name> --mode <mode> [--target <path>] [-p|-g]
|
|
skillshare extras <name> --flatten | --no-flatten [--target <path>]
|
|
skillshare extras <name> --add-target <path> [--mode <mode>] [--flatten] [-p|-g]
|
|
skillshare extras <name> --remove-target <path> [--prune] [-p|-g]
|
|
```
|
|
|
|
**Options:**
|
|
|
|
| Flag | Description |
|
|
|------|-------------|
|
|
| `--mode <mode>` | New sync mode: `merge`, `copy`, or `symlink` |
|
|
| `--flatten` | Enable flatten (sync subdirectory files into target root) |
|
|
| `--no-flatten` | Disable flatten |
|
|
| `--add-target <path>` | Add a new target to the extra |
|
|
| `--remove-target <path>` | Remove a target from the extra (config-only by default) |
|
|
| `--prune` | With `--remove-target`: also delete skillshare-managed files under that target |
|
|
| `--target <path>` | Target directory path (required for `--mode` with multi-target extras; `--flatten`/`--no-flatten` applies to all targets when omitted) |
|
|
| `--project, -p` | Use project-mode extras (`.skillshare/`) |
|
|
| `--global, -g` | Use global extras (`~/.config/skillshare/`) |
|
|
|
|
**Examples:**
|
|
|
|
```bash
|
|
# Change rules mode (single target — auto-resolved)
|
|
skillshare extras rules --mode copy
|
|
|
|
# Specify target explicitly (required for multi-target extras)
|
|
skillshare extras rules --mode copy --target ~/.claude/rules
|
|
|
|
# Enable / disable flatten on all targets at once
|
|
skillshare extras agents --flatten
|
|
skillshare extras agents --no-flatten
|
|
|
|
# Add a new target to an existing extra (then sync)
|
|
skillshare extras rules --add-target ~/.cursor/rules
|
|
skillshare extras commands --add-target ~/.config/opencode/commands --mode copy
|
|
|
|
# Remove a target (leaves synced files in place)
|
|
skillshare extras rules --remove-target ~/.cursor/rules
|
|
|
|
# Remove a target and delete its synced files
|
|
skillshare extras rules --remove-target ~/.cursor/rules --prune
|
|
```
|
|
|
|
Also available via the TUI (`M` key) and Web UI (mode dropdown and flatten checkbox on each target).
|
|
|
|
### `extras remove`
|
|
|
|
Remove an extra from configuration.
|
|
|
|
```bash
|
|
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. Copy-mode targets keep their files as regular copies.
|
|
|
|
Files that already exist in source are skipped. Use `--force` to overwrite them with the target version — for example, to pull back edits made directly in a copy-mode target. Files whose content already matches source are still skipped.
|
|
|
|
```bash
|
|
skillshare extras collect <name> [--from <path>] [--force] [--dry-run] [-p|-g]
|
|
```
|
|
|
|
**Options:**
|
|
|
|
| Flag | Description |
|
|
|------|-------------|
|
|
| `--from <path>` | Target directory to collect from (required if multiple targets) |
|
|
| `--force`, `-f` | Overwrite files that already exist in source |
|
|
| `--dry-run` | Show what would be collected without making changes |
|
|
|
|
**Example:**
|
|
|
|
```bash
|
|
# 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
|
|
|
|
# Pull target edits back over existing source files
|
|
skillshare extras collect rules --force
|
|
```
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
---
|
|
|
|
## Flatten
|
|
|
|
Some AI tools (e.g., Claude Code's `/agents`) only discover files at the **top level** of their config directory — they do not recurse into subdirectories. If your extras source uses subdirectories for organization, synced files will be invisible to the tool.
|
|
|
|
The `flatten` option solves this by syncing all files directly into the target root, regardless of their subdirectory depth in the source:
|
|
|
|
```yaml
|
|
extras:
|
|
- name: agents
|
|
targets:
|
|
- path: ~/.claude/agents
|
|
flatten: true
|
|
```
|
|
|
|
**Behavior:**
|
|
- `flatten: true`: `source/curriculum/tactician.md` → `target/tactician.md`
|
|
- `flatten: false` (default): `source/curriculum/tactician.md` → `target/curriculum/tactician.md`
|
|
|
|
**Filename collisions:** When two files in different subdirectories share the same name (e.g., `team-a/agent.md` and `team-b/agent.md`), the first file wins (sorted alphabetically by path). Subsequent collisions are skipped with a warning.
|
|
|
|
**Constraints:**
|
|
- Only works with `merge` and `copy` modes — cannot be used with `symlink` mode
|
|
- `collect` places newly collected files in the source root (no subdirectory mapping for new files)
|
|
|
|
---
|
|
|
|
## Extension transforms
|
|
|
|
Some tools do not read markdown. Gemini CLI expects TOML commands; Codex CLI expects TOML agents. The `extension` field on a target runs an external script that converts each source file into the target's native format during sync.
|
|
|
|
```yaml
|
|
extras:
|
|
- name: commands
|
|
targets:
|
|
- path: .claude/commands # no extension — synced as-is
|
|
- path: .gemini/commands
|
|
extension: gemini-commands # transform during sync
|
|
```
|
|
|
|
**Resolution** — a bare name resolves under the extensions directory (`~/.config/skillshare/extensions/<name>` global, `.skillshare/extensions/<name>` project); a path (`./x.sh`, `/abs/x`) is used directly.
|
|
|
|
**Copy semantics** — `extension` implies `copy` mode. Setting `mode: merge` or `mode: symlink` on a target with an `extension` is an error.
|
|
|
|
**One-way** — transforms run source → target only. `extras collect` skips extension targets.
|
|
|
|
**Overwrite safety** — generated output follows the same conflict rules as `copy` mode. A leftover symlink at an output path is replaced automatically; an existing regular file or directory you created locally is left untouched and skipped unless you pass `--force` (with `--force`, a conflicting directory is replaced wholesale by the generated file).
|
|
|
|
### Extension layout
|
|
|
|
A single executable, or a directory with a manifest:
|
|
|
|
```
|
|
.skillshare/extensions/gemini-commands/
|
|
├── extension.yaml
|
|
├── convert.js # mapping rules you edit
|
|
└── md-toml.js # helper for markdown/frontmatter/TOML
|
|
```
|
|
|
|
`extension.yaml`:
|
|
|
|
```yaml
|
|
run: ["node", "convert.js"] # explicit command (argv), execed directly
|
|
output_ext: toml # .md → .toml; omit to keep the source extension
|
|
description: "Markdown command → Gemini CLI TOML"
|
|
```
|
|
|
|
A bare single-file executable (no manifest) is execed directly (relies on the shebang on Unix) and keeps the source extension. Transforms that rename the extension must use the directory form.
|
|
|
|
### Execution contract
|
|
|
|
- Source file content is passed on **stdin**; the script writes the converted content to **stdout**.
|
|
- Environment variables: `SS_SRC_PATH`, `SS_REL_PATH` (path relative to the source root — useful for Gemini's `/namespace:command` naming), `SS_TARGET_DIR`, `SS_MODE`.
|
|
- A non-zero exit code marks that file as failed; other files continue.
|
|
|
|
### Cross-platform
|
|
|
|
The mechanism is cross-platform; whether an extension runs depends on its interpreter. Because `run` is an explicit command, an extension written for `node` or `python3` works on Windows, macOS, and Linux. Pure `bash` scripts only run where a shell is available (Unix, or Windows with Git Bash). Node is the preferred interpreter for reference extensions because it ships uniformly across platforms.
|
|
|
|
### Reference extensions
|
|
|
|
The skillshare repo ships example extensions under `extensions/` (`gemini-commands`, `codex-agents`, `opencode-agents`). Copy one into your extensions directory and adapt it — they are references, not installed automatically. Each reference extension keeps `convert.js` short so you edit only the field mapping; `md-toml.js` handles reading markdown, parsing simple frontmatter, and writing TOML.
|
|
|
|
### Recipe: Codex agents
|
|
|
|
Codex CLI expects TOML agents rather than markdown. Because a `source` can point at any directory, you can reuse your agents source as an extras source and transform it with `codex-agents`:
|
|
|
|
```yaml
|
|
extras:
|
|
- name: codex-agents
|
|
source: ~/.config/skillshare/agents # reuse the agents source
|
|
targets:
|
|
- path: ~/.codex/agents
|
|
extension: codex-agents
|
|
```
|
|
|
|
`skillshare sync extras` converts each `<agent>.md` into `~/.codex/agents/<agent>.toml`, mapping frontmatter `name`, `description`, and `model` and folding the markdown body into `developer_instructions` (other frontmatter keys are dropped). The [Codex custom agent schema](https://developers.openai.com/codex/subagents#custom-agent-file-schema) requires `name`, `description`, and `developer_instructions`, so the reference transform reports a clear error when the resolved name, description, or Markdown body is blank. No separate copy of the agents is needed.
|
|
|
|
Agent targets can also take `extension` directly, without an extra. See [Converting agents with an extension](/docs/understand/agents#extensions).
|
|
|
|
---
|
|
|
|
## Recipe: shared instructions across agents
|
|
|
|
Most coding agents now read an `AGENTS.md` for standing instructions, but each
|
|
one keeps its user-level copy in a different directory. One extra with several
|
|
targets distributes a single source file to all of them:
|
|
|
|
```bash
|
|
skillshare extras init instructions \
|
|
--target ~/.codex \
|
|
--target ~/.config/opencode \
|
|
--target ~/.claude \
|
|
--target ~/.gemini \
|
|
--no-tui
|
|
```
|
|
|
|
Put your `AGENTS.md` in the resolved source directory
|
|
(`~/.config/skillshare/extras/instructions/` by default), then
|
|
`skillshare sync extras`.
|
|
|
|
| Agent | Global path | Reads `AGENTS.md` |
|
|
|-------|-------------|-------------------|
|
|
| Codex CLI | `~/.codex/AGENTS.md` | Directly |
|
|
| opencode | `~/.config/opencode/AGENTS.md` | Directly |
|
|
| Claude Code | `~/.claude/AGENTS.md` | Through a `CLAUDE.md` import |
|
|
| Antigravity | `~/.gemini/AGENTS.md` | Through a `GEMINI.md` import |
|
|
|
|
Two agents read a fixed filename of their own at the user level, so each needs a
|
|
one-line file next to the synced one. Write these once; skillshare never touches
|
|
them again:
|
|
|
|
```markdown title="~/.claude/CLAUDE.md"
|
|
@AGENTS.md
|
|
```
|
|
|
|
```markdown title="~/.gemini/GEMINI.md"
|
|
@AGENTS.md
|
|
```
|
|
|
|
Claude Code reads `CLAUDE.md` and not `AGENTS.md`, and the import is the approach
|
|
its [memory documentation](https://code.claude.com/docs/en/memory) recommends for
|
|
sharing one file with other agents. Antigravity keeps its global rules in
|
|
`~/.gemini/GEMINI.md` and resolves a relative `@filename` against the rules file's
|
|
own directory, so the same one-liner picks up the synced `AGENTS.md`. The
|
|
`~/.gemini` target also covers Antigravity CLI, which reads the same global file.
|
|
|
|
Keep the source file named `AGENTS.md`. A neutral name such as `memory.md` syncs
|
|
just as well but stops being read: Codex concatenates `AGENTS.md` files by name
|
|
and has no import syntax, so it recognises the file only by that name.
|
|
|
|
Because targets are directories, every target receives each file under its source
|
|
name. Keep the source directory to the files you want everywhere — an extra file
|
|
lands in all four targets.
|
|
|
|
:::note
|
|
This recipe shares the instructions you write, not the memory an agent writes for
|
|
itself. Agents store their own learnings in private formats — a directory of
|
|
Markdown for Claude Code, a database for Codex, non-file storage for Cursor — and
|
|
those are not portable by copying files between targets.
|
|
:::
|
|
|
|
---
|
|
|
|
## 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`:
|
|
|
|
```yaml
|
|
# Optional: set a global default extras source directory
|
|
extras_source: ~/my-extras
|
|
|
|
extras:
|
|
- name: rules
|
|
source: ~/company-shared/rules # optional per-extra override
|
|
targets:
|
|
- path: ~/.claude/rules
|
|
- path: ~/.cursor/rules
|
|
mode: copy
|
|
- name: agents
|
|
targets:
|
|
- path: ~/.claude/agents
|
|
flatten: true # sync subdirectory files flat
|
|
- name: prompts
|
|
targets:
|
|
- path: ~/.claude/prompts
|
|
```
|
|
|
|
### Source Resolution Priority
|
|
|
|
The source directory for each extra is resolved with three-level priority:
|
|
|
|
1. **Per-extra `source`** (highest) — exact path, used as-is
|
|
2. **`extras_source`** — `<extras_source>/<name>/`
|
|
3. **Default** — `~/.config/skillshare/extras/<name>/` (global) or `.skillshare/extras/<name>/` (project)
|
|
|
|
The `extras list --json` output includes a `source_type` field (`per-extra`, `extras_source`, or `default`) indicating which level resolved the path.
|
|
|
|
:::tip Auto-populated
|
|
`extras_source` is automatically set to the default path (`~/.config/skillshare/extras/`) when you run `skillshare init` or create your first extra with `extras init`. To change it later, use `skillshare extras source <path>`.
|
|
:::
|
|
|
|
---
|
|
|
|
## Syncing
|
|
|
|
Extras are synced with:
|
|
|
|
```bash
|
|
skillshare sync extras # sync extras only
|
|
skillshare sync --all # sync skills + extras together
|
|
```
|
|
|
|
See [sync extras](/docs/reference/commands/sync#sync-extras) for full sync documentation including `--json`, `--dry-run`, and `--force` options.
|
|
|
|
---
|
|
|
|
## Workflow
|
|
|
|
```bash
|
|
# 1. Create a new extra
|
|
skillshare extras init rules --target ~/.claude/rules --target ~/.cursor/rules
|
|
|
|
# 1b. Or with a custom source directory
|
|
skillshare extras init rules --target ~/.claude/rules --source ~/my-rules
|
|
|
|
# 1c. Reconfigure an existing extra (overwrite)
|
|
skillshare extras init rules --target ~/.cursor/rules --force
|
|
|
|
# 2. Add files to the source directory
|
|
# (edit the resolved source dir — check with: skillshare extras list --json)
|
|
|
|
# 3. Sync to targets
|
|
skillshare sync extras
|
|
|
|
# 4. List status (source_type shows where each extra's source is resolved from)
|
|
skillshare extras list
|
|
|
|
# 5. Collect a file edited in a target back to source
|
|
skillshare extras collect rules --from ~/.claude/rules
|
|
|
|
# 6. Change the global extras source directory
|
|
skillshare extras source ~/company-shared/extras
|
|
```
|
|
|
|
---
|
|
|
|
## See Also
|
|
|
|
- [sync](/docs/reference/commands/sync#sync-extras) — Sync extras to targets
|
|
- [status](/docs/reference/commands/status) — Show extras file and target counts
|
|
- [Configuration](/docs/reference/targets/configuration#extras) — Extras config reference
|