docs: restructure website documentation with scenario-driven navigation

- Add version command page and fix commands index (missing check, trash, hub)
- Document target aliases and XDG base directory layout
- Rewrite all 9 section index pages with "What do you want to do?" tables
- Standardize all 24 command docs with "When to Use" and "See Also" sections
- Enhance intro with role-based paths (individual / team / migration)
- Add "What Just Happened?" explainer to first-sync getting-started page
- Add practical context callouts (:::tip) to all concept pages
- Add See Also cross-references to all guide and workflow pages

59 files changed, 547 insertions(+), 163 deletions(-)
This commit is contained in:
Willie
2026-02-16 17:01:06 +08:00
parent 692d87c4cc
commit f16a28d678
59 changed files with 547 additions and 163 deletions
+8 -1
View File
@@ -15,6 +15,13 @@ skillshare audit --json # JSON output
skillshare audit -p # Scan project skills
```
## When to Use
- Review security findings after installing a new skill
- Scan all skills for prompt injection, data exfiltration, or credential access patterns
- Customize audit rules for your organization's security policy
- Generate audit reports for compliance (with `--json`)
## What It Detects
### CRITICAL (blocks installation and counted as Failed)
@@ -304,7 +311,7 @@ Source of truth (full built-in definitions):
| `--init-rules` | Create a starter `audit-rules.yaml` (respects `-p`/`-g`) |
| `-h`, `--help` | Show help |
## Related
## See Also
- [install](/docs/commands/install) — Install skills (with automatic scanning)
- [doctor](/docs/commands/doctor) — Diagnose setup issues
+7 -1
View File
@@ -13,6 +13,12 @@ skillshare backup --list # List all backups
skillshare backup --cleanup # Remove old backups
```
## When to Use
- Create a manual backup before risky changes
- List existing backups to check recovery options
- Clean up old backups to free disk space
## Automatic Backups
Backups are created **automatically** before:
@@ -90,7 +96,7 @@ This means:
- In merge mode: Only local-only skills are backed up
- In symlink mode: Nothing is backed up (entire dir is symlink)
## Related
## See Also
- [restore](/docs/commands/restore) — Restore from backup
- [sync](/docs/commands/sync) — Auto-creates backups
+22 -22
View File
@@ -11,6 +11,27 @@ skillshare check # Check all repos and skills
skillshare check --json # Machine-readable output
```
## When to Use
### Before Updating
Preview what would change before running `update`:
```bash
skillshare check # See what has updates
skillshare update --all # Apply updates
skillshare sync # Distribute changes
```
### CI/CD Pipeline
Check for stale skills in CI:
```bash
result=$(skillshare check --json)
# Parse JSON to detect outdated skills
```
## What It Does
`check` inspects your source directory and reports update status for:
@@ -104,28 +125,7 @@ skillshare check -p # Check project skills
skillshare check -p --json # JSON output for project
```
## Use Cases
### Before Updating
Preview what would change before running `update`:
```bash
skillshare check # See what has updates
skillshare update --all # Apply updates
skillshare sync # Distribute changes
```
### CI/CD Pipeline
Check for stale skills in CI:
```bash
result=$(skillshare check --json)
# Parse JSON to detect outdated skills
```
## Related
## See Also
- [update](/docs/commands/update) — Apply updates
- [list](/docs/commands/list) — View installed skills
+1 -1
View File
@@ -111,7 +111,7 @@ skillshare sync
skillshare push -m "Add my-new-skill"
```
## Related
## See Also
- [sync](/docs/commands/sync) — Sync from source to targets
- [diff](/docs/commands/diff) — See local-only skills
+7 -1
View File
@@ -13,6 +13,12 @@ skillshare diff claude # Specific target
![diff demo](/img/diff-demo.png)
## When to Use
- See exactly what's different between source and a target before syncing
- Find skills that exist only in a target (local-only, not yet collected)
- Identify local copies that could be replaced by symlinks
## Example Output
```
@@ -81,7 +87,7 @@ skillshare diff claude # See exactly what's different
skillshare sync # Fix it
```
## Related
## See Also
- [sync](/docs/commands/sync) — Sync to targets
- [collect](/docs/commands/collect) — Import local skills
+8 -1
View File
@@ -14,6 +14,13 @@ skillshare doctor -g # Force global mode
![doctor demo](/img/doctor-demo.png)
## When to Use
- Something isn't working and you don't know why
- After upgrading skillshare or your OS
- Verify all targets, git, and symlinks are healthy
- First diagnostic step before filing a bug report
## What It Checks
```
@@ -167,7 +174,7 @@ Summary
✗ 1 error(s), 4 warning(s)
```
## Related
## See Also
- [status](/docs/commands/status) — Quick status check
- [sync](/docs/commands/sync) — Fix sync issues
+6
View File
@@ -6,6 +6,12 @@ sidebar_position: 8
Manage skill hubs — saved hub sources for search.
## When to Use
- Add a private or community skill hub for `search` to query
- Switch between multiple hubs (e.g., internal team vs public community)
- List or remove saved hub sources
## hub add
Save a hub source to config for reuse in [`search --hub`](./search.md).
+39 -4
View File
@@ -6,15 +6,32 @@ sidebar_position: 1
Complete reference for all skillshare commands.
## What do you want to do?
| I want to... | Command |
|--------------|---------|
| Set up skillshare for the first time | [`init`](./init.md) |
| Install a skill from GitHub | [`install`](./install.md) |
| Create my own skill | [`new`](./new.md) |
| Sync skills to all AI CLIs | [`sync`](./sync.md) |
| Check what's out of sync | [`status`](./status.md) / [`diff`](./diff.md) |
| Search for community skills | [`search`](./search.md) |
| Update installed skills | [`check`](./check.md) then [`update`](./update.md) |
| Sync across machines | [`push`](./push.md) / [`pull`](./pull.md) |
| Fix something broken | [`doctor`](./doctor.md) |
| Open the web dashboard | [`ui`](./ui.md) |
---
## Overview
| Category | Commands |
|----------|----------|
| **Core** | `init`, `install`, `uninstall`, `list`, `search`, `sync`, `status` |
| **Skill Management** | `new`, `update`, `upgrade` |
| **Skill Management** | `new`, `check`, `update`, `upgrade` |
| **Target Management** | `target`, `diff` |
| **Sync Operations** | `collect`, `backup`, `restore`, `push`, `pull` |
| **Utilities** | `audit`, `log`, `doctor`, `ui` |
| **Sync Operations** | `collect`, `backup`, `restore`, `trash`, `push`, `pull` |
| **Security & Utilities** | `audit`, `hub`, `log`, `doctor`, `ui`, `version` |
---
@@ -35,6 +52,7 @@ Complete reference for all skillshare commands.
| Command | Description |
|---------|-------------|
| [new](./new.md) | Create a new skill |
| [check](./check.md) | Check for available updates |
| [update](./update.md) | Update a skill or tracked repo |
| [upgrade](./upgrade.md) | Upgrade CLI or built-in skill |
@@ -52,10 +70,11 @@ Complete reference for all skillshare commands.
| [collect](./collect.md) | Collect skills from target to source |
| [backup](./backup.md) | Create backup of targets |
| [restore](./restore.md) | Restore targets from backup |
| [trash](./trash.md) | Manage uninstalled skills in trash |
| [push](./push.md) | Push to git remote |
| [pull](./pull.md) | Pull from git remote and sync |
## Utilities
## Security & Utilities
| Command | Description |
|---------|-------------|
@@ -63,6 +82,8 @@ Complete reference for all skillshare commands.
| [log](./log.md) | View operations and audit logs |
| [doctor](./doctor.md) | Diagnose issues |
| [ui](./ui.md) | Launch web dashboard |
| [hub](./hub.md) | Manage skill hub sources |
| [version](./version.md) | Show CLI version |
---
@@ -114,6 +135,20 @@ skillshare backup
# Web UI
skillshare ui
skillshare ui -p # Project mode
# Hub
skillshare hub list
skillshare hub add https://hub.example.com/index.json
# Check for updates
skillshare check
# Trash management
skillshare trash list
skillshare trash restore my-skill
# Version
skillshare version
```
---
+7
View File
@@ -11,6 +11,13 @@ skillshare init # Interactive setup
skillshare init --dry-run # Preview without changes
```
## When to Use
- First time setting up skillshare on a machine
- Migrating to a new computer (with `--remote` to connect to existing repo)
- Adding skillshare to a project (with `--project`)
- Discovering newly installed AI CLIs (with `--discover`)
## What Happens
```
+7 -1
View File
@@ -20,6 +20,12 @@ Add skills from GitHub repos, git URLs, or local paths.
└──────────────────────────────────────────────────────────────┘
```
## When to Use
- Add a new skill from GitHub, GitLab, Bitbucket, or a local path
- Install an organization's shared skill repository (with `--track`)
- Re-install or update an existing skill (with `--update` or `--force`)
---
## Quick Examples
@@ -332,7 +338,7 @@ skillshare install anthropics/skills/skills/pdf
skillshare sync # ← Don't forget!
```
## Related
## See Also
- [list](/docs/commands/list) — View installed skills
- [update](/docs/commands/update) — Update skills or tracked repos
+7 -1
View File
@@ -11,6 +11,12 @@ skillshare list # Compact view
skillshare list --verbose # Detailed view
```
## When to Use
- See what skills are installed and where they came from
- Check which skills are tracked repos vs local
- Audit your skill collection before a cleanup
![list demo](/img/list-demo.png)
## Example Output
@@ -181,7 +187,7 @@ Project list uses the same visual format as global list, with `(project)` label
| `✓` | Up-to-date, no local changes |
| `!` | Has uncommitted changes |
## Related
## See Also
- [install](/docs/commands/install) — Install skills
- [uninstall](/docs/commands/uninstall) — Remove skills
+7 -1
View File
@@ -18,6 +18,12 @@ skillshare log --clear # Clear operations log
skillshare log -p # Show project operations + audit logs
```
## When to Use
- Debug what happened during a failed operation
- Review the audit trail for compliance or troubleshooting
- Filter logs by command, status, or time range for investigation
## What Gets Logged
Every mutating CLI and Web UI operation is recorded as a JSONL entry with timestamp, command, status, duration, and contextual args.
@@ -176,7 +182,7 @@ The Log page provides:
- **Audit detail rows** showing failed/warning skill names when present
- **Clear** and **Refresh** controls
## Related
## See Also
- [audit](/docs/commands/audit) — Security scanning (logged to audit.log)
- [status](/docs/commands/status) — Show current sync state
+6 -1
View File
@@ -12,6 +12,11 @@ skillshare new <name> -p # Create in project (.skillshare/skills/)
skillshare new <name> --dry-run # Preview without creating
```
## When to Use
- Create a new skill from scratch with the recommended template structure
- Start with the correct SKILL.md format (name, description, frontmatter)
**What happens:**
```
┌─────────────────────────────────────────────────────────────────┐
@@ -198,7 +203,7 @@ After creating a skill:
---
## Related
## See Also
- [install](/docs/commands/install) — Install skills from repos
- [sync](/docs/commands/sync) — Sync skills to targets
+7 -1
View File
@@ -11,6 +11,12 @@ skillshare pull # Pull and sync
skillshare pull --dry-run # Preview
```
## When to Use
- Sync skills from another machine that pushed changes
- Get the latest skills after someone else pushed updates
- Start working on a new machine after `init --remote`
## What Happens
```
@@ -107,7 +113,7 @@ skillshare collect claude # If you created new skills
skillshare push -m "Add new skill"
```
## Related
## See Also
- [push](/docs/commands/push) — Push to remote
- [sync](/docs/commands/sync) — Manual sync without pull
+7 -1
View File
@@ -12,6 +12,12 @@ skillshare push -m "Add pdf" # Custom message
skillshare push --dry-run # Preview
```
## When to Use
- Share skill changes with your other machines via git
- Back up your skills to a remote repository
- After editing skills, commit and push in one command
## What Happens
```
@@ -110,7 +116,7 @@ skillshare push -m "Update my-skill"
skillshare pull # Gets changes and syncs
```
## Related
## See Also
- [pull](/docs/commands/pull) — Pull from remote
- [sync](/docs/commands/sync) — Sync to local targets
+6 -1
View File
@@ -12,6 +12,11 @@ skillshare restore claude --from 2026-01-19_10-00-00 # Specific backup
skillshare restore claude --dry-run # Preview
```
## When to Use
- A sync went wrong and you need to revert a target to its previous state
- You accidentally removed skills from a target
## What Happens
```
@@ -120,7 +125,7 @@ skillshare restore claude --from 2026-01-15_10-00-00
skillshare sync # Return to current state
```
## Related
## See Also
- [backup](/docs/commands/backup) — Create and manage backups
- [sync](/docs/commands/sync) — Re-sync after restore
+6
View File
@@ -6,6 +6,12 @@ sidebar_position: 5
Discover and install skills from GitHub repositories.
## When to Use
- Discover community skills from hub indexes
- Find skills by name, tag, or description
- Browse available skills before installing
## Quick Start
```bash
+8 -1
View File
@@ -10,6 +10,13 @@ Show the current state of skillshare: source, tracked repositories, targets, and
skillshare status
```
## When to Use
- Check if all targets are in sync after making changes
- See which targets need a `sync` run
- Verify tracked repos are up to date
- Check for CLI or skill updates
![status demo](/img/status-demo.png)
## Example Output
@@ -96,7 +103,7 @@ Remote Skills
Project status does not show Tracked Repositories or Version sections (these are global-only features).
## Related
## See Also
- [sync](/docs/commands/sync) — Sync skills to targets
- [diff](/docs/commands/diff) — Show detailed differences
+7 -1
View File
@@ -10,6 +10,12 @@ Push skills from source to all targets.
Operations like `install` and `uninstall` only modify source — sync propagates to targets. This lets you batch changes, preview with `--dry-run`, and control when targets update. See [Why Sync is a Separate Step](/docs/concepts/source-and-targets#why-sync-is-a-separate-step).
:::
## When to Use
- After installing, uninstalling, or editing skills — propagate changes to all targets
- After changing a target's sync mode — apply the new mode
- Periodically to ensure all targets are in sync
## Command Overview
| Type | Command | Direction |
@@ -436,7 +442,7 @@ skillshare restore claude --dry-run # Preview
---
## Related
## See Also
- [status](/docs/commands/status) — Show sync state
- [diff](/docs/commands/diff) — Show differences
+8 -1
View File
@@ -14,6 +14,13 @@ skillshare target <name> # Show target info
skillshare target <name> --mode merge # Change sync mode
```
## When to Use
- Add a new AI CLI target after installing a new tool
- Remove a target you no longer use
- Change sync mode (merge vs symlink) for a target
- Set up include/exclude filters for selective skill syncing
## Subcommands
### target add
@@ -201,7 +208,7 @@ Targets in project mode support:
- **Known target names** (e.g., `claude`, `cursor`) — resolved to project-local paths
- **Custom paths** — relative to project root or absolute with `~` expansion
## Related
## See Also
- [sync](/docs/commands/sync) — Sync skills to targets
- [status](/docs/commands/status) — Show target status
+7 -1
View File
@@ -14,6 +14,12 @@ skillshare trash delete my-skill # Permanently delete from trash
skillshare trash empty # Empty the trash
```
## When to Use
- Recover a skill you recently uninstalled (within 7 days)
- Permanently delete trashed skills to free space
- Check what's in the trash before it auto-expires
## Subcommands
### list
@@ -99,7 +105,7 @@ These two safety mechanisms protect different things:
Expired trash items (older than 7 days) are automatically cleaned up when you run `uninstall` or `sync`. No cron or scheduled task is needed.
## Related
## See Also
- [uninstall](/docs/commands/uninstall) — Remove skills (moves to trash)
- [backup](/docs/commands/backup) — Backup target directories
+8 -1
View File
@@ -12,6 +12,13 @@ skillshare ui
Opens `http://127.0.0.1:19420` in your default browser.
## When to Use
- Manage skills, targets, and sync through a visual web interface
- Browse and install skills without memorizing CLI flags
- Run security audits with a visual findings report
- Share a dashboard view with team members less comfortable with CLI
## Flags
| Flag | Default | Description |
@@ -171,7 +178,7 @@ skillshare ui
└── Browser opens http://127.0.0.1:19420
```
## Related
## See Also
- [status](/docs/commands/status) — CLI status check
- [sync](/docs/commands/sync) — CLI sync command
+6 -1
View File
@@ -12,6 +12,11 @@ skillshare uninstall team-repo # Remove tracked repository (_ prefix opt
skillshare uninstall my-skill --force # Skip confirmation
```
## When to Use
- Remove a skill you no longer need (it moves to trash for 7 days)
- Clean up a tracked repository you've stopped using
![uninstall demo](/img/uninstall-demo.png)
## What Happens
@@ -133,7 +138,7 @@ skillshare sync
git add .skillshare/ && git commit -m "Remove pdf skill"
```
## Related
## See Also
- [install](/docs/commands/install) — Install skills
- [list](/docs/commands/list) — List installed skills
+7 -1
View File
@@ -12,6 +12,12 @@ skillshare update team-skills # Update tracked repo
skillshare update --all # Update everything
```
## When to Use
- A tracked repository has new commits (found via `check`)
- An installed skill has a newer version available
- You want to re-download a skill from its original source
![update demo](/img/update-skilk-demo.png)
## What Happens
@@ -175,7 +181,7 @@ skillshare sync
git add .skillshare/ && git commit -m "Update remote skills"
```
## Related
## See Also
- [install](/docs/commands/install) — Install skills
- [upgrade](/docs/commands/upgrade) — Upgrade CLI and built-in skill
+7 -1
View File
@@ -12,6 +12,12 @@ skillshare upgrade --cli # CLI only
skillshare upgrade --skill # Skill only
```
## When to Use
- A new version of the skillshare CLI is available
- The built-in skillshare skill needs updating
- After `doctor` reports an available update
![upgrade demo](/img/upgrade-demo.png)
## What Happens
@@ -116,7 +122,7 @@ The built-in `skillshare` skill that adds the `/skillshare` command to AI CLIs.
~/.config/skillshare/skills/skillshare/SKILL.md
```
## Related
## See Also
- [update](/docs/commands/update) — Update other skills and repos
- [status](/docs/commands/status) — Check current versions
+33
View File
@@ -0,0 +1,33 @@
---
sidebar_position: 6
---
# version
Show the current skillshare version.
## When to Use
- Check which version you're running before reporting a bug
- Verify an upgrade was successful
- Compare your version against [the latest release](https://github.com/runkids/skillshare/releases)
## Synopsis
```bash
skillshare version
skillshare -v
skillshare --version
```
## Example Output
```
skillshare version 1.5.0
```
## See Also
- [upgrade](./upgrade.md) — Upgrade to latest version
- [doctor](./doctor.md) — Full environment diagnostics
- [status](./status.md) — Show sync state including version info
+10
View File
@@ -6,6 +6,16 @@ sidebar_position: 1
Understanding these concepts helps you get the most out of skillshare.
## What do you want to understand?
| Question | Read |
|----------|------|
| How does skillshare move skills around? | [Source & Targets](./source-and-targets.md) |
| What's the difference between merge and symlink? | [Sync Modes](./sync-modes.md) |
| How do I share organization-wide skills? | [Tracked Repositories](./tracked-repositories.md) |
| What goes inside a SKILL.md? | [Skill Format](./skill-format.md) |
| How do project-level skills work? | [Project Skills](./project-skills.md) |
## Overview
```
+8 -6
View File
@@ -6,6 +6,10 @@ sidebar_position: 6
Run skillshare at the project level — skills scoped to a single repository, shared via git.
:::tip When does this matter?
Use project skills when your team needs repo-specific AI instructions (coding standards, deployment guides, API conventions) that shouldn't be in your personal global skill collection.
:::
## Usage Scenarios
| Scenario | Example |
@@ -183,10 +187,8 @@ Project mode has some intentional limitations:
---
## Related
## See Also
- [Project Setup Guide](/docs/guides/project-setup) — Step-by-step setup tutorial
- [Project Workflow](/docs/workflows/project-workflow) — Daily operations
- [Organization-Wide Skills](/docs/guides/organization-sharing) — Organization-level sharing
- [Source & Targets](/docs/concepts/source-and-targets) — How source and targets work
- [Sync Modes](/docs/concepts/sync-modes) — Merge vs symlink
- [Project Setup](/docs/guides/project-setup) — Step-by-step setup guide
- [Project Workflow](/docs/workflows/project-workflow) — Day-to-day project mode usage
- [Organization-Wide Skills](/docs/guides/organization-sharing) — Team-wide sharing
+8 -4
View File
@@ -6,6 +6,10 @@ sidebar_position: 5
The structure and metadata of a skillshare skill.
:::tip When does this matter?
The SKILL.md format determines how AI CLIs discover and load your skill. The `description` field is especially critical — it's what the AI uses to decide when to activate your skill.
:::
## Overview
A skill is a directory containing at least a `SKILL.md` file:
@@ -253,8 +257,8 @@ Checks for:
---
## Related
## See Also
- [Creating Skills](/docs/guides/creating-skills) — Step-by-step guide
- [Commands: new](/docs/commands/new) — Create command
- [Commands: doctor](/docs/commands/doctor) — Diagnose issues
- [new](/docs/commands/new) — Create a skill with the correct template
- [Creating Skills](/docs/guides/creating-skills) — Full guide to writing skills
- [Best Practices](/docs/guides/best-practices) — Naming and organization tips
+9 -4
View File
@@ -6,6 +6,10 @@ sidebar_position: 2
The core model behind skillshare: one source, many targets.
:::tip When does this matter?
Understanding source vs targets helps you know where to edit skills (always in source — changes reflect via symlinks), why `sync` is a separate step, and how `collect` works in the reverse direction.
:::
## The Problem
Without skillshare, you manage skills separately for each AI CLI:
@@ -189,8 +193,9 @@ $EDITOR ~/.claude/skills/my-skill/SKILL.md
---
## Related
## See Also
- [Sync Modes](./sync-modes.md) — Merge vs symlink mode
- [Target Management](/docs/targets) — Managing targets
- [Configuration](/docs/targets/configuration) — Custom source path
- [sync](/docs/commands/sync) — Propagate changes from source to targets
- [collect](/docs/commands/collect) — Pull skills from targets back to source
- [Sync Modes](./sync-modes.md) — How files are linked (merge vs symlink)
- [Configuration](/docs/targets/configuration) — Target config reference
+9 -4
View File
@@ -6,6 +6,10 @@ sidebar_position: 3
How skillshare links source to targets.
:::tip When does this matter?
Choose merge mode (default) when you want per-skill symlinks and to preserve local skills in targets. Choose symlink mode when you want the entire directory linked and don't need local target skills.
:::
## Overview
| Mode | Behavior | Use Case |
@@ -150,8 +154,9 @@ $ skillshare sync
---
## Related
## See Also
- [Source & Targets](./source-and-targets.md) — Core model
- [Target Management](/docs/targets) — Managing targets
- [Commands: sync](/docs/commands/sync) — Sync command details
- [sync](/docs/commands/sync) — Run sync to apply mode changes
- [target](/docs/commands/target) — Change a target's sync mode
- [Source & Targets](./source-and-targets.md) — The core architecture
- [Configuration](/docs/targets/configuration) — Per-target settings
@@ -6,6 +6,10 @@ sidebar_position: 4
Git repos installed with `--track` for team sharing and easy updates.
:::tip When does this matter?
Tracked repos are how organizations distribute shared skills. Install once with `--track`, then update with a single command. Changes flow from the maintainer's repo to every team member.
:::
## Overview
Tracked repositories are git repos cloned into your source with their `.git` directory preserved. This enables:
@@ -254,9 +258,9 @@ See [Target Filters](/docs/targets/configuration#include--exclude-target-filters
---
## Related
## See Also
- [Organization-Wide Skills](/docs/guides/organization-sharing) — Full organization workflow
- [Project Skills](/docs/concepts/project-skills) — Project mode concepts
- [Commands: install](/docs/commands/install) — Install options
- [Commands: update](/docs/commands/update) — Update command
- [install](/docs/commands/install) — Install with `--track`
- [update](/docs/commands/update) — Pull latest changes
- [check](/docs/commands/check) — See available updates
- [Organization-Wide Skills](/docs/guides/organization-sharing) — Team sharing guide
@@ -106,3 +106,27 @@ You should see:
- [Create your own skill](/docs/guides/creating-skills)
- [Sync across machines](/docs/guides/cross-machine-sync)
- [Organization-wide skills](/docs/guides/organization-sharing)
## What Just Happened?
Here's what skillshare did behind the scenes:
1. **`init`** — Created `~/.config/skillshare/config.yaml` and `~/.config/skillshare/skills/`. Auto-detected your AI CLIs (Claude, Cursor, etc.) and added them as targets.
2. **`install`** — Cloned the skill from GitHub into your source directory (`~/.config/skillshare/skills/`). Ran a security audit automatically.
3. **`sync`** — Created symlinks from your source to each target. For example:
```
~/.claude/skills/pdf → ~/.config/skillshare/skills/pdf (symlink)
```
This means:
- **Edit once, reflect everywhere** — Editing the source file updates all targets instantly (via symlinks)
- **Non-destructive** — Your existing target skills are preserved (merge mode)
- **Reversible** — `skillshare backup` creates snapshots; `skillshare restore` reverts
## See Also
- [Core Concepts](/docs/concepts) — Understand source, targets, and sync modes
- [Daily Workflow](/docs/workflows/daily-workflow) — How to use skillshare day-to-day
- [Creating Skills](/docs/guides/creating-skills) — Write your own skills
@@ -10,6 +10,14 @@ Migrate your existing skills from various AI CLIs to skillshare.
If you already have skills in `~/.claude/skills/`, `~/.cursor/skills/`, or other locations, skillshare can consolidate them into a single source.
## Starting Scenarios
| Your situation | What to do |
|----------------|-----------|
| Skills in one CLI (e.g., Claude) | `skillshare init --copy-from claude` copies them to source |
| Skills in multiple CLIs | Init, then `skillshare collect --all` to gather from all targets |
| Skills in a git repo already | `skillshare init --remote <url>` connects to it |
```
BEFORE: AFTER:
─────────────────────────────────────────────────────────
@@ -135,8 +143,8 @@ skillshare restore cursor
---
## What's Next?
## See Also
- [Daily Workflow](/docs/workflows/daily-workflow) — Edit, sync, push/pull
- [Cross-Machine Sync](/docs/guides/cross-machine-sync) — Sync across computers
- [Concepts](/docs/concepts) — Understand source, targets, and sync modes
- [Daily Workflow](/docs/workflows/daily-workflow) — Your day-to-day after migration
- [Cross-Machine Sync](/docs/guides/cross-machine-sync) — Sync to other machines
- [Core Concepts](/docs/concepts) — How source and targets work
+22 -17
View File
@@ -4,32 +4,37 @@ sidebar_position: 1
# Getting Started
Choose your path based on your situation:
Get skillshare running in minutes. Choose your starting point:
## New User
## What's your situation?
Never used skillshare or any skill management tool before?
| I want to... | Start here |
|--------------|-----------|
| Set up skillshare from scratch | [First Sync](./first-sync.md) — install, init, and sync in 5 minutes |
| I already have skills in Claude/Cursor/etc. | [From Existing Skills](./from-existing-skills.md) — consolidate and unify |
| I know skillshare, just need command syntax | [Quick Reference](./quick-reference.md) — cheat sheet |
**→ [First Sync](./first-sync.md)** — Get synced in 5 minutes
## The 3-Step Pattern
## Migrating from Existing Skills
No matter which path you choose, skillshare follows a simple pattern:
Already have skills scattered across AI CLIs?
```bash
# 1. Install skillshare
curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh
**→ [From Existing Skills](./from-existing-skills.md)** — Consolidate and sync
# 2. Initialize (auto-detects your AI CLIs)
skillshare init
## Quick Reference
# 3. Sync skills to all targets
skillshare sync
```
Know what you're doing, just need command syntax?
**→ [Quick Reference](./quick-reference.md)** — Command cheat sheet
---
After setup, your skills are symlinked — edit once, reflect everywhere.
## What's Next?
After setup, explore:
After you're set up:
- [Core Concepts](/docs/concepts) — Understand how skillshare works
- [Workflows](/docs/workflows) — Daily usage patterns
- [Commands](/docs/commands) — Full command reference
- [Core Concepts](/docs/concepts) — Understand source, targets, and sync modes
- [Daily Workflow](/docs/workflows/daily-workflow) — How to use skillshare day-to-day
- [Commands Reference](/docs/commands) — Full command reference
@@ -25,7 +25,11 @@ Command cheat sheet for skillshare.
| `new <name>` | Create a new skill |
| `update <name>` | Update a skill (git pull) |
| `update --all` | Update all tracked repos |
| `check` | Check for skill updates |
| `check --json` | Check for updates (JSON output) |
| `upgrade` | Upgrade CLI and built-in skill |
| `hub list` | List configured skill hubs |
| `hub add <url>` | Add a skill hub |
## Target Management
@@ -49,6 +53,8 @@ Command cheat sheet for skillshare.
| `restore <target>` | Restore from backup |
| `push [-m "msg"]` | Push to git remote |
| `pull` | Pull from git and sync |
| `trash list` | List soft-deleted skills |
| `trash restore <name>` | Restore a soft-deleted skill |
## Utilities
@@ -57,6 +63,8 @@ Command cheat sheet for skillshare.
| `doctor` | Diagnose issues |
| `log` | View operations and audit logs |
| `ui` | Launch web dashboard on `localhost:19420` |
| `ui -p` | Launch web dashboard in project mode |
| `version` | Show CLI version |
| `mise run test:docker` | Run offline Docker sandbox tests |
| `mise run test:docker:online` | Run optional online Docker tests |
| `mise run sandbox:up` | Start persistent playground container |
+3 -3
View File
@@ -288,8 +288,8 @@ Before installing third-party skills:
---
## Related
## See Also
- [Creating Skills](./creating-skills.md) — Skill creation guide
- [Organization-Wide Skills](./organization-sharing.md) — Organization workflow
- [Skill Format](/docs/concepts/skill-format) — Format specification
- [Skill Format](/docs/concepts/skill-format) — SKILL.md reference
- [Organization-Wide Skills](./organization-sharing.md) — Team sharing patterns
+7
View File
@@ -161,3 +161,10 @@ Your existing skills are now managed from one place. For a detailed walkthrough,
- You want backup, restore, and version control for your skills
- You prefer a single binary with no runtime dependencies
- You don't want installation/download activity tracked outside your local workflow
---
## See Also
- [Migration](./migration.md) — Migration guide
- [Core Concepts](/docs/concepts) — How skillshare works
+5 -4
View File
@@ -302,8 +302,9 @@ Before publishing:
---
## Related
## See Also
- [Skill Format](/docs/concepts/skill-format) — Detailed format reference
- [Commands: new](/docs/commands/new) — Create command
- [Organization-Wide Skills](./organization-sharing.md) — Share across your organization
- [new](/docs/commands/new) — Create a skill with template
- [Skill Format](/docs/concepts/skill-format) — SKILL.md structure
- [Best Practices](./best-practices.md) — Naming and organization
- [Organizing Skills](./organizing-skills.md) — Folder structure
+5 -4
View File
@@ -245,8 +245,9 @@ skillshare pull 2>/dev/null
---
## Related
## See Also
- [Organization-Wide Skills](./organization-sharing.md) — Share across your organization
- [Commands: push](/docs/commands/push) — Push command details
- [Commands: pull](/docs/commands/pull) — Pull command details
- [push](/docs/commands/push) — Push to remote
- [pull](/docs/commands/pull) — Pull from remote
- [Organization-Wide Skills](./organization-sharing.md) — Team sharing
- [init](/docs/commands/init) — Init with `--remote`
+8
View File
@@ -325,3 +325,11 @@ On tag push (`v*`), the `docker-publish` GitHub Actions workflow builds and push
./scripts/test_docker.sh --cmd "go test -v ./tests/integration/..."
./scripts/sandbox_playground_shell.sh "skillshare list"
```
---
## See Also
- [Getting Started](/docs/getting-started) — Standard setup
- [Commands Reference](/docs/commands) — All commands
- [Troubleshooting](/docs/troubleshooting) — Common issues
+8
View File
@@ -253,3 +253,11 @@ Want to share your skills with the community? [Open a PR](https://github.com/run
- **Automate index generation** — Add `skillshare hub index` to your CI pipeline after skill changes
- **Use `--full` for auditing** — Full mode includes version, install date, and type information
- **Combine with project mode** — `skillshare hub index -p` indexes only project-level skills
---
## See Also
- [search](/docs/commands/search) — Search skills from hubs
- [hub](/docs/commands/hub) — Manage hub sources
- [install](/docs/commands/install) — Install discovered skills
+19 -3
View File
@@ -6,7 +6,22 @@ sidebar_position: 1
In-depth guides for specific use cases.
## Skills
## What do you want to do?
| I want to... | Read |
|--------------|------|
| Write my first skill | [Creating Skills](./creating-skills.md) |
| Organize a growing skill collection | [Organizing Skills](./organizing-skills.md) |
| Share skills with my team via a git repo | [Organization-Wide Skills](./organization-sharing.md) |
| Set up skills for a specific project | [Project Setup](./project-setup.md) |
| Sync skills across multiple machines | [Cross-Machine Sync](./cross-machine-sync.md) |
| Browse and discover community skills | [Hub Index](./hub-index.md) |
| Move from another tool or approach | [Migration](./migration.md) |
| Test skillshare in an isolated Docker sandbox | [Docker Sandbox](./docker-sandbox.md) |
## By Topic
### Skills
| Guide | Description |
|-------|-------------|
@@ -14,15 +29,16 @@ In-depth guides for specific use cases.
| [Organizing Skills](./organizing-skills.md) | Organize skills into folders with auto-flattening |
| [Best Practices](./best-practices.md) | Naming, organization, and versioning |
## Sharing
### Sharing
| Guide | Description |
|-------|-------------|
| [Project Setup](./project-setup.md) | Set up project-scoped skills for a repo |
| [Organization-Wide Skills](./organization-sharing.md) | Share skills across your organization |
| [Cross-Machine Sync](./cross-machine-sync.md) | Sync skills across computers |
| [Hub Index](./hub-index.md) | Browse and manage skill hubs |
## Advanced
### Advanced
| Guide | Description |
|-------|-------------|
+4 -4
View File
@@ -326,8 +326,8 @@ After migrating:
---
## Related
## See Also
- [Getting Started](/docs/getting-started/from-existing-skills) — Detailed migration walkthrough
- [Commands: collect](/docs/commands/collect) — Collect command
- [Organization-Wide Skills](./organization-sharing.md) — Organization migration
- [From Existing Skills](/docs/getting-started/from-existing-skills) — Quick migration path
- [collect](/docs/commands/collect) — Collect from targets
- [Comparison](./comparison.md) — Compare approaches
+6 -6
View File
@@ -282,10 +282,10 @@ Organization skills provide company-wide standards. Project skills provide repo-
---
## Related
## See Also
- [Tracked Repositories](/docs/concepts/tracked-repositories) — How tracked repos work
- [Project Skills](/docs/concepts/project-skills) — Project-level skills
- [Project Setup](/docs/guides/project-setup) — Project-level setup guide
- [Cross-Machine Sync](./cross-machine-sync.md) — Personal cross-machine sync
- [Commands: install](/docs/commands/install) — Install command details
- [Tracked Repositories](/docs/concepts/tracked-repositories) — Concept details
- [install](/docs/commands/install) — Install with `--track`
- [update](/docs/commands/update) — Update tracked repos
- [Project Setup](./project-setup.md) — Project-level sharing
- [Cross-Machine Sync](./cross-machine-sync.md) — Personal sync
+4 -4
View File
@@ -278,9 +278,9 @@ After `sync`, targets are updated automatically — old flat symlinks are cleane
---
## Related
## See Also
- [Source & Targets](/docs/concepts/source-and-targets#organize-with-folders-auto-flattening) — Auto-flattening concept
- [Tracked Repositories](/docs/concepts/tracked-repositories#nested-skills--auto-flattening) — Nested skills in tracked repos
- [Source & Targets](/docs/concepts/source-and-targets) — How flattening works
- [Tracked Repositories](/docs/concepts/tracked-repositories) — Nested skills in repos
- [Best Practices](./best-practices.md) — Naming conventions
- [Cross-Machine Sync](./cross-machine-sync.md) — Sync across computers
- [install](/docs/commands/install) — Install with `--into` for subdirectories
+5 -6
View File
@@ -265,10 +265,9 @@ Each project gets its own context, while organization standards apply globally.
---
## Related
## See Also
- [Project Skills](/docs/concepts/project-skills) — Core concepts
- [Project Workflow](/docs/workflows/project-workflow) — Daily operations
- [Organization-Wide Skills](/docs/guides/organization-sharing) — Organization sharing with tracked repos
- [Commands: init](/docs/commands/init) — Init command details
- [Commands: install](/docs/commands/install) — Install command details
- [Project Skills](/docs/concepts/project-skills) — Concept explanation
- [Project Workflow](/docs/workflows/project-workflow) — Day-to-day usage
- [Organization-Wide Skills](./organization-sharing.md) — Team sharing
- [init](/docs/commands/init) — Init with `--project`
+15 -7
View File
@@ -78,17 +78,25 @@ Edit in source → all targets update. Edit in target → changes go to source (
## Next Steps
**New to skillshare?**
- [First Sync](/docs/getting-started/first-sync) — Get synced in 5 minutes
### Individual Developer
1. [First Sync](/docs/getting-started/first-sync) — Get synced in 5 minutes
2. [Creating Skills](/docs/guides/creating-skills) — Write your first skill
3. [Cross-Machine Sync](/docs/guides/cross-machine-sync) — Keep skills in sync across machines
### Team Lead / Organization
1. [Organization-Wide Skills](/docs/guides/organization-sharing) — Share standards across the team
2. [Project Setup](/docs/guides/project-setup) — Set up project-scoped skills
3. [Security Audit](/docs/commands/audit) — Scan third-party skills before deployment
### Already Have Skills?
**Already have skills?**
- [From Existing Skills](/docs/getting-started/from-existing-skills) — Migrate and consolidate
**Project-level skills:**
- [Project Setup](/docs/guides/project-setup) — Set up project-scoped skills
### Explore More
**Learn more:**
- [Core Concepts](/docs/concepts) — Source, targets, sync modes
- [Commands Reference](/docs/commands) — All available commands
- [Docker Sandbox Guide](/docs/guides/docker-sandbox) — Isolated testing and playground
- [Docker Sandbox](/docs/guides/docker-sandbox) — Try skillshare in an isolated environment
- [FAQ](/docs/troubleshooting/faq) — Common questions
+24
View File
@@ -325,6 +325,30 @@ See [Environment Variables](./environment-variables.md#xdg_config_home) for deta
| UI cache | `%AppData%\skillshare\ui\{version}\` |
| Link type | NTFS Junctions |
## XDG Base Directory Layout
Skillshare follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir/latest/) on Unix systems:
| XDG Variable | Default Path | Skillshare Uses For |
|-------------|-------------|---------------------|
| `XDG_CONFIG_HOME` | `~/.config` | `skillshare/config.yaml`, `skillshare/skills/` |
| `XDG_DATA_HOME` | `~/.local/share` | `skillshare/backups/`, `skillshare/trash/` |
| `XDG_STATE_HOME` | `~/.local/state` | `skillshare/logs/` |
| `XDG_CACHE_HOME` | `~/.cache` | `skillshare/ui/` (downloaded web dashboard) |
### Windows Paths
| Purpose | Path |
|---------|------|
| Config + Skills | `%AppData%\skillshare\` |
| Data (backups, trash) | `%LocalAppData%\skillshare\` |
| State (logs) | `%LocalAppData%\skillshare\state\` |
| Cache (UI) | `%LocalAppData%\skillshare\cache\` |
### Migration Note
If upgrading from a version before the XDG split, skillshare automatically migrates data from the old location (`~/.config/skillshare/`) to the correct XDG directories on first run.
---
## Related
+13 -12
View File
@@ -6,24 +6,27 @@ sidebar_position: 1
Technical reference documentation for skillshare.
## Contents
## What are you looking for?
| Reference | Description |
|-----------|-------------|
| [Environment Variables](./environment-variables.md) | All environment variables |
| [File Structure](./file-structure.md) | Directory and file layout |
---
| Topic | Read |
|-------|------|
| Environment variables that affect skillshare | [Environment Variables](./environment-variables.md) |
| Where skillshare stores config, skills, logs, cache | [File Structure](./file-structure.md) |
| Config file format and options | [Configuration](/docs/targets/configuration) |
| All CLI commands | [Commands](/docs/commands) |
## Quick Reference
### Key Paths
### Key Paths (Unix)
| Path | Purpose |
|------|---------|
| `~/.config/skillshare/config.yaml` | Configuration file |
| `~/.config/skillshare/skills/` | Source directory |
| `~/.config/skillshare/skills/` | Source directory (your skills) |
| `~/.local/share/skillshare/backups/` | Backup directory |
| `~/.local/share/skillshare/trash/` | Soft-deleted skills |
| `~/.local/state/skillshare/logs/` | Operation and audit logs |
| `~/.cache/skillshare/ui/` | Downloaded web dashboard |
### Environment Variables
@@ -32,9 +35,7 @@ Technical reference documentation for skillshare.
| `SKILLSHARE_CONFIG` | Override config path |
| `GITHUB_TOKEN` | GitHub API authentication |
---
## Related
## See Also
- [Configuration](/docs/targets/configuration) — Config file details
- [Commands](/docs/commands) — All commands
+8
View File
@@ -25,6 +25,14 @@ Targets are AI CLI skill directories that skillshare syncs to.
└─────────────────────────────────────────────────────────────┘
```
## What do you want to do?
| I want to... | Read |
|--------------|------|
| See which AI CLIs are supported | [Supported Targets](./supported-targets.md) |
| Add a target not in the built-in list | [Adding Custom Targets](./adding-custom-targets.md) |
| Configure sync mode, filters, or paths | [Configuration](./configuration.md) |
## Quick Links
| Topic | Description |
+21
View File
@@ -105,6 +105,27 @@ These are auto-detected during `skillshare init`:
| xcode-codex | `~/Library/Developer/Xcode/CodingAssistant/codex/skills` | `.codex/skills` |
| zencoder | `~/.zencoder/skills` | `.zencoder/skills` |
## Aliases
Some targets have alternative names for backward compatibility or convenience:
| Alias | Resolves To | Notes |
|-------|-------------|-------|
| `claude-code` | `claude` | Legacy name |
| `command-code` | `commandcode` | Hyphenated variant |
| `github-copilot` | `copilot` | Full product name |
| `opencode-ai` | `opencode` | With suffix |
| `trae-cn` | `traecn` | Hyphenated variant |
You can use either the alias or the canonical name in all commands:
```bash
skillshare target add claude # canonical
skillshare target add claude-code # alias — same result
```
Aliases are resolved automatically. The canonical name is used in config files and status output.
---
## Check Target Path
+5 -4
View File
@@ -23,13 +23,14 @@ This checks:
---
## Choose Your Issue
## What's happening?
| Problem | Go To |
|---------|-------|
| Error messages | [Common Errors](./common-errors.md) |
| Windows problems | [Windows](./windows.md) |
| General questions | [FAQ](./faq.md) |
| I see an error message | [Common Errors](./common-errors.md) |
| Something isn't working on Windows | [Windows](./windows.md) |
| I need a step-by-step debugging process | [Troubleshooting Workflow](./troubleshooting-workflow.md) |
| I have a general question | [FAQ](./faq.md) |
---
+4 -3
View File
@@ -207,8 +207,9 @@ git checkout <commit-hash> -- specific-skill/
---
## Related
## See Also
- [Commands: backup](/docs/commands/backup) — Backup command details
- [Commands: restore](/docs/commands/restore) — Restore command details
- [backup](/docs/commands/backup) — Backup command reference
- [restore](/docs/commands/restore) — Restore command reference
- [trash](/docs/commands/trash) — Soft-delete management
- [Troubleshooting](/docs/troubleshooting) — When things go wrong
+5 -4
View File
@@ -170,8 +170,9 @@ skillshare doctor # Check for issues
---
## Related
## See Also
- [Cross-Machine Sync](/docs/guides/cross-machine-sync) — Full setup guide
- [Commands: sync](/docs/commands/sync) — Sync command details
- [Commands: status](/docs/commands/status) — Status command
- [sync](/docs/commands/sync) — Core sync command
- [status](/docs/commands/status) — Check sync state
- [push](/docs/commands/push) / [pull](/docs/commands/pull) — Cross-machine sync
- [Skill Discovery](/docs/workflows/skill-discovery) — Find new skills
+1
View File
@@ -13,6 +13,7 @@ Common usage patterns for skillshare.
| Use skills day-to-day | [Daily Workflow](./daily-workflow.md) |
| Find and install new skills | [Skill Discovery](./skill-discovery.md) |
| Protect my skills | [Backup & Restore](./backup-restore.md) |
| Manage project-scoped skills | [Project Workflow](./project-workflow.md) |
| Fix something broken | [Troubleshooting](/docs/troubleshooting) |
---
+3 -4
View File
@@ -254,9 +254,8 @@ skillshare sync --dry-run
---
## Related
## See Also
- [Project Skills](/docs/concepts/project-skills) — Core concepts
- [Project Skills](/docs/concepts/project-skills) — Concept explanation
- [Project Setup](/docs/guides/project-setup) — Initial setup guide
- [Daily Workflow](/docs/workflows/daily-workflow) — Global mode daily workflow
- [Commands: sync](/docs/commands/sync) — Sync command details
- [Daily Workflow](./daily-workflow.md) — Global mode daily usage
+5 -5
View File
@@ -177,9 +177,9 @@ skillshare update _team-skills
---
## Related
## See Also
- [Commands: search](/docs/commands/search) — Search command
- [Commands: install](/docs/commands/install) — Install command
- [Commands: check](/docs/commands/check) — Check for updates
- [Commands: list](/docs/commands/list) — List command
- [search](/docs/commands/search) — Search command reference
- [install](/docs/commands/install) — Install command reference
- [Hub Index](/docs/guides/hub-index) — Managing skill hubs
- [Daily Workflow](./daily-workflow.md) — After installing, use daily
+1
View File
@@ -129,6 +129,7 @@ const sidebars: SidebarsConfig = {
'commands/log',
'commands/doctor',
'commands/ui',
'commands/version',
],
},
],