From f16a28d6782d0090690a44604b9c587985180a4e Mon Sep 17 00:00:00 2001 From: Willie Date: Mon, 16 Feb 2026 16:56:03 +0800 Subject: [PATCH] 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(-) --- website/docs/commands/audit.md | 9 +++- website/docs/commands/backup.md | 8 +++- website/docs/commands/check.md | 44 +++++++++---------- website/docs/commands/collect.md | 2 +- website/docs/commands/diff.md | 8 +++- website/docs/commands/doctor.md | 9 +++- website/docs/commands/hub.md | 6 +++ website/docs/commands/index.md | 43 ++++++++++++++++-- website/docs/commands/init.md | 7 +++ website/docs/commands/install.md | 8 +++- website/docs/commands/list.md | 8 +++- website/docs/commands/log.md | 8 +++- website/docs/commands/new.md | 7 ++- website/docs/commands/pull.md | 8 +++- website/docs/commands/push.md | 8 +++- website/docs/commands/restore.md | 7 ++- website/docs/commands/search.md | 6 +++ website/docs/commands/status.md | 9 +++- website/docs/commands/sync.md | 8 +++- website/docs/commands/target.md | 9 +++- website/docs/commands/trash.md | 8 +++- website/docs/commands/ui.md | 9 +++- website/docs/commands/uninstall.md | 7 ++- website/docs/commands/update.md | 8 +++- website/docs/commands/upgrade.md | 8 +++- website/docs/commands/version.md | 33 ++++++++++++++ website/docs/concepts/index.md | 10 +++++ website/docs/concepts/project-skills.md | 14 +++--- website/docs/concepts/skill-format.md | 12 +++-- website/docs/concepts/source-and-targets.md | 13 ++++-- website/docs/concepts/sync-modes.md | 13 ++++-- website/docs/concepts/tracked-repositories.md | 14 +++--- website/docs/getting-started/first-sync.md | 24 ++++++++++ .../getting-started/from-existing-skills.md | 16 +++++-- website/docs/getting-started/index.md | 39 +++++++++------- .../docs/getting-started/quick-reference.md | 8 ++++ website/docs/guides/best-practices.md | 6 +-- website/docs/guides/comparison.md | 7 +++ website/docs/guides/creating-skills.md | 9 ++-- website/docs/guides/cross-machine-sync.md | 9 ++-- website/docs/guides/docker-sandbox.md | 8 ++++ website/docs/guides/hub-index.md | 8 ++++ website/docs/guides/index.md | 22 ++++++++-- website/docs/guides/migration.md | 8 ++-- website/docs/guides/organization-sharing.md | 12 ++--- website/docs/guides/organizing-skills.md | 8 ++-- website/docs/guides/project-setup.md | 11 +++-- website/docs/intro.md | 22 +++++++--- website/docs/reference/file-structure.md | 24 ++++++++++ website/docs/reference/index.md | 25 ++++++----- website/docs/targets/index.md | 8 ++++ website/docs/targets/supported-targets.md | 21 +++++++++ website/docs/troubleshooting/index.md | 9 ++-- website/docs/workflows/backup-restore.md | 7 +-- website/docs/workflows/daily-workflow.md | 9 ++-- website/docs/workflows/index.md | 1 + website/docs/workflows/project-workflow.md | 7 ++- website/docs/workflows/skill-discovery.md | 10 ++--- website/sidebars.ts | 1 + 59 files changed, 547 insertions(+), 163 deletions(-) create mode 100644 website/docs/commands/version.md diff --git a/website/docs/commands/audit.md b/website/docs/commands/audit.md index 14b5017a0..dac204280 100644 --- a/website/docs/commands/audit.md +++ b/website/docs/commands/audit.md @@ -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 diff --git a/website/docs/commands/backup.md b/website/docs/commands/backup.md index 3649ce29d..658584375 100644 --- a/website/docs/commands/backup.md +++ b/website/docs/commands/backup.md @@ -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 diff --git a/website/docs/commands/check.md b/website/docs/commands/check.md index 21d08258f..26f60a77b 100644 --- a/website/docs/commands/check.md +++ b/website/docs/commands/check.md @@ -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 diff --git a/website/docs/commands/collect.md b/website/docs/commands/collect.md index 76ffabc84..3c49193e0 100644 --- a/website/docs/commands/collect.md +++ b/website/docs/commands/collect.md @@ -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 diff --git a/website/docs/commands/diff.md b/website/docs/commands/diff.md index ff258ac45..bb7077b9d 100644 --- a/website/docs/commands/diff.md +++ b/website/docs/commands/diff.md @@ -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 diff --git a/website/docs/commands/doctor.md b/website/docs/commands/doctor.md index 04a13226d..ec7b4097b 100644 --- a/website/docs/commands/doctor.md +++ b/website/docs/commands/doctor.md @@ -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 diff --git a/website/docs/commands/hub.md b/website/docs/commands/hub.md index 0fa946bef..62c1377f8 100644 --- a/website/docs/commands/hub.md +++ b/website/docs/commands/hub.md @@ -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). diff --git a/website/docs/commands/index.md b/website/docs/commands/index.md index 4a2feb679..bc4d1c31c 100644 --- a/website/docs/commands/index.md +++ b/website/docs/commands/index.md @@ -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 ``` --- diff --git a/website/docs/commands/init.md b/website/docs/commands/init.md index a9667166e..fac60aa31 100644 --- a/website/docs/commands/init.md +++ b/website/docs/commands/init.md @@ -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 ``` diff --git a/website/docs/commands/install.md b/website/docs/commands/install.md index c076c52e1..2e703c72e 100644 --- a/website/docs/commands/install.md +++ b/website/docs/commands/install.md @@ -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 diff --git a/website/docs/commands/list.md b/website/docs/commands/list.md index 2e6668cef..436abfa69 100644 --- a/website/docs/commands/list.md +++ b/website/docs/commands/list.md @@ -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 diff --git a/website/docs/commands/log.md b/website/docs/commands/log.md index fd8d9e272..3b45bb2bc 100644 --- a/website/docs/commands/log.md +++ b/website/docs/commands/log.md @@ -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 diff --git a/website/docs/commands/new.md b/website/docs/commands/new.md index a7a32fc87..b8febfbff 100644 --- a/website/docs/commands/new.md +++ b/website/docs/commands/new.md @@ -12,6 +12,11 @@ skillshare new -p # Create in project (.skillshare/skills/) skillshare new --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 diff --git a/website/docs/commands/pull.md b/website/docs/commands/pull.md index db9d90005..5d1184d09 100644 --- a/website/docs/commands/pull.md +++ b/website/docs/commands/pull.md @@ -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 diff --git a/website/docs/commands/push.md b/website/docs/commands/push.md index 9a6346c8d..df72ab7bb 100644 --- a/website/docs/commands/push.md +++ b/website/docs/commands/push.md @@ -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 diff --git a/website/docs/commands/restore.md b/website/docs/commands/restore.md index c6e7069cf..7e805568d 100644 --- a/website/docs/commands/restore.md +++ b/website/docs/commands/restore.md @@ -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 diff --git a/website/docs/commands/search.md b/website/docs/commands/search.md index 6497eea76..2f046d0f3 100644 --- a/website/docs/commands/search.md +++ b/website/docs/commands/search.md @@ -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 diff --git a/website/docs/commands/status.md b/website/docs/commands/status.md index fe6586fad..9164395eb 100644 --- a/website/docs/commands/status.md +++ b/website/docs/commands/status.md @@ -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 diff --git a/website/docs/commands/sync.md b/website/docs/commands/sync.md index eb2e60d15..2111aeccf 100644 --- a/website/docs/commands/sync.md +++ b/website/docs/commands/sync.md @@ -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 diff --git a/website/docs/commands/target.md b/website/docs/commands/target.md index b7084d2a1..b0455c4b1 100644 --- a/website/docs/commands/target.md +++ b/website/docs/commands/target.md @@ -14,6 +14,13 @@ skillshare target # Show target info skillshare target --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 diff --git a/website/docs/commands/trash.md b/website/docs/commands/trash.md index f1ee03587..e6c257cea 100644 --- a/website/docs/commands/trash.md +++ b/website/docs/commands/trash.md @@ -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 diff --git a/website/docs/commands/ui.md b/website/docs/commands/ui.md index 5e15720a6..89a4bb52b 100644 --- a/website/docs/commands/ui.md +++ b/website/docs/commands/ui.md @@ -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 diff --git a/website/docs/commands/uninstall.md b/website/docs/commands/uninstall.md index 345d28d19..63cedf2b5 100644 --- a/website/docs/commands/uninstall.md +++ b/website/docs/commands/uninstall.md @@ -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 diff --git a/website/docs/commands/update.md b/website/docs/commands/update.md index 099ce2211..b29af0180 100644 --- a/website/docs/commands/update.md +++ b/website/docs/commands/update.md @@ -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 diff --git a/website/docs/commands/upgrade.md b/website/docs/commands/upgrade.md index 66af31271..f0fbc4327 100644 --- a/website/docs/commands/upgrade.md +++ b/website/docs/commands/upgrade.md @@ -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 diff --git a/website/docs/commands/version.md b/website/docs/commands/version.md new file mode 100644 index 000000000..ff5395aa6 --- /dev/null +++ b/website/docs/commands/version.md @@ -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 diff --git a/website/docs/concepts/index.md b/website/docs/concepts/index.md index 9742b4f74..e5962e5b1 100644 --- a/website/docs/concepts/index.md +++ b/website/docs/concepts/index.md @@ -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 ``` diff --git a/website/docs/concepts/project-skills.md b/website/docs/concepts/project-skills.md index 0c074ed50..29a80e7a9 100644 --- a/website/docs/concepts/project-skills.md +++ b/website/docs/concepts/project-skills.md @@ -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 diff --git a/website/docs/concepts/skill-format.md b/website/docs/concepts/skill-format.md index a94ffd8f8..58699252e 100644 --- a/website/docs/concepts/skill-format.md +++ b/website/docs/concepts/skill-format.md @@ -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 diff --git a/website/docs/concepts/source-and-targets.md b/website/docs/concepts/source-and-targets.md index 81e03a50c..f60195590 100644 --- a/website/docs/concepts/source-and-targets.md +++ b/website/docs/concepts/source-and-targets.md @@ -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 diff --git a/website/docs/concepts/sync-modes.md b/website/docs/concepts/sync-modes.md index 5eeb2a4cf..83c614245 100644 --- a/website/docs/concepts/sync-modes.md +++ b/website/docs/concepts/sync-modes.md @@ -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 diff --git a/website/docs/concepts/tracked-repositories.md b/website/docs/concepts/tracked-repositories.md index fc1e41c68..d203ab0e2 100644 --- a/website/docs/concepts/tracked-repositories.md +++ b/website/docs/concepts/tracked-repositories.md @@ -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 diff --git a/website/docs/getting-started/first-sync.md b/website/docs/getting-started/first-sync.md index 4ad7e4380..c33315f76 100644 --- a/website/docs/getting-started/first-sync.md +++ b/website/docs/getting-started/first-sync.md @@ -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 diff --git a/website/docs/getting-started/from-existing-skills.md b/website/docs/getting-started/from-existing-skills.md index 1c617f275..841e25001 100644 --- a/website/docs/getting-started/from-existing-skills.md +++ b/website/docs/getting-started/from-existing-skills.md @@ -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 ` 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 diff --git a/website/docs/getting-started/index.md b/website/docs/getting-started/index.md index 8774954d0..d084ccdcf 100644 --- a/website/docs/getting-started/index.md +++ b/website/docs/getting-started/index.md @@ -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 diff --git a/website/docs/getting-started/quick-reference.md b/website/docs/getting-started/quick-reference.md index 1f14d4a10..3be3ff1b2 100644 --- a/website/docs/getting-started/quick-reference.md +++ b/website/docs/getting-started/quick-reference.md @@ -25,7 +25,11 @@ Command cheat sheet for skillshare. | `new ` | Create a new skill | | `update ` | 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 ` | Add a skill hub | ## Target Management @@ -49,6 +53,8 @@ Command cheat sheet for skillshare. | `restore ` | Restore from backup | | `push [-m "msg"]` | Push to git remote | | `pull` | Pull from git and sync | +| `trash list` | List soft-deleted skills | +| `trash restore ` | 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 | diff --git a/website/docs/guides/best-practices.md b/website/docs/guides/best-practices.md index 064487858..f6bf3df75 100644 --- a/website/docs/guides/best-practices.md +++ b/website/docs/guides/best-practices.md @@ -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 diff --git a/website/docs/guides/comparison.md b/website/docs/guides/comparison.md index 9bd7a4598..80e853095 100644 --- a/website/docs/guides/comparison.md +++ b/website/docs/guides/comparison.md @@ -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 diff --git a/website/docs/guides/creating-skills.md b/website/docs/guides/creating-skills.md index a8fb6ef9e..dbbe692ec 100644 --- a/website/docs/guides/creating-skills.md +++ b/website/docs/guides/creating-skills.md @@ -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 diff --git a/website/docs/guides/cross-machine-sync.md b/website/docs/guides/cross-machine-sync.md index af278f597..0143a8a07 100644 --- a/website/docs/guides/cross-machine-sync.md +++ b/website/docs/guides/cross-machine-sync.md @@ -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` diff --git a/website/docs/guides/docker-sandbox.md b/website/docs/guides/docker-sandbox.md index 247375f16..b26793cab 100644 --- a/website/docs/guides/docker-sandbox.md +++ b/website/docs/guides/docker-sandbox.md @@ -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 diff --git a/website/docs/guides/hub-index.md b/website/docs/guides/hub-index.md index 456994f3c..f31c4f312 100644 --- a/website/docs/guides/hub-index.md +++ b/website/docs/guides/hub-index.md @@ -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 diff --git a/website/docs/guides/index.md b/website/docs/guides/index.md index 75f3cb339..129b03821 100644 --- a/website/docs/guides/index.md +++ b/website/docs/guides/index.md @@ -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 | |-------|-------------| diff --git a/website/docs/guides/migration.md b/website/docs/guides/migration.md index 761805ee7..47025f4bd 100644 --- a/website/docs/guides/migration.md +++ b/website/docs/guides/migration.md @@ -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 diff --git a/website/docs/guides/organization-sharing.md b/website/docs/guides/organization-sharing.md index 93ad7b651..f1615e07a 100644 --- a/website/docs/guides/organization-sharing.md +++ b/website/docs/guides/organization-sharing.md @@ -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 diff --git a/website/docs/guides/organizing-skills.md b/website/docs/guides/organizing-skills.md index 060654208..a8ff254d6 100644 --- a/website/docs/guides/organizing-skills.md +++ b/website/docs/guides/organizing-skills.md @@ -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 diff --git a/website/docs/guides/project-setup.md b/website/docs/guides/project-setup.md index e2d3adbfd..c98c7e179 100644 --- a/website/docs/guides/project-setup.md +++ b/website/docs/guides/project-setup.md @@ -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` diff --git a/website/docs/intro.md b/website/docs/intro.md index 8930525ea..dcede2ccf 100644 --- a/website/docs/intro.md +++ b/website/docs/intro.md @@ -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 diff --git a/website/docs/reference/file-structure.md b/website/docs/reference/file-structure.md index 17ebf5c9d..7067b5358 100644 --- a/website/docs/reference/file-structure.md +++ b/website/docs/reference/file-structure.md @@ -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 diff --git a/website/docs/reference/index.md b/website/docs/reference/index.md index 38801c9ca..c7670bee5 100644 --- a/website/docs/reference/index.md +++ b/website/docs/reference/index.md @@ -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 diff --git a/website/docs/targets/index.md b/website/docs/targets/index.md index ddef16b3a..b742ea4ea 100644 --- a/website/docs/targets/index.md +++ b/website/docs/targets/index.md @@ -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 | diff --git a/website/docs/targets/supported-targets.md b/website/docs/targets/supported-targets.md index c9498a15c..918cc923f 100644 --- a/website/docs/targets/supported-targets.md +++ b/website/docs/targets/supported-targets.md @@ -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 diff --git a/website/docs/troubleshooting/index.md b/website/docs/troubleshooting/index.md index 8599a992f..3a6480362 100644 --- a/website/docs/troubleshooting/index.md +++ b/website/docs/troubleshooting/index.md @@ -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) | --- diff --git a/website/docs/workflows/backup-restore.md b/website/docs/workflows/backup-restore.md index 27fa14a46..d02fcb3fb 100644 --- a/website/docs/workflows/backup-restore.md +++ b/website/docs/workflows/backup-restore.md @@ -207,8 +207,9 @@ git checkout -- 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 diff --git a/website/docs/workflows/daily-workflow.md b/website/docs/workflows/daily-workflow.md index 3d204240f..93d33335a 100644 --- a/website/docs/workflows/daily-workflow.md +++ b/website/docs/workflows/daily-workflow.md @@ -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 diff --git a/website/docs/workflows/index.md b/website/docs/workflows/index.md index 24a01280f..9105ee4ba 100644 --- a/website/docs/workflows/index.md +++ b/website/docs/workflows/index.md @@ -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) | --- diff --git a/website/docs/workflows/project-workflow.md b/website/docs/workflows/project-workflow.md index 73e63bc70..bd89451e6 100644 --- a/website/docs/workflows/project-workflow.md +++ b/website/docs/workflows/project-workflow.md @@ -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 diff --git a/website/docs/workflows/skill-discovery.md b/website/docs/workflows/skill-discovery.md index 1b3ad9890..851a2f203 100644 --- a/website/docs/workflows/skill-discovery.md +++ b/website/docs/workflows/skill-discovery.md @@ -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 diff --git a/website/sidebars.ts b/website/sidebars.ts index a20b2297f..08fa8cd08 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -129,6 +129,7 @@ const sidebars: SidebarsConfig = { 'commands/log', 'commands/doctor', 'commands/ui', + 'commands/version', ], }, ],