From 2c3003e04f6b7b291ebc19dd3fd717f9a5f0a1df Mon Sep 17 00:00:00 2001 From: Willie Date: Thu, 26 Feb 2026 04:32:03 +0800 Subject: [PATCH] =?UTF-8?q?feat(website):=20complete=20website=20revamp=20?= =?UTF-8?q?=E2=80=94=20Di=C3=A1taxis=20IA,=20blog,=20recipes,=20quickstart?= =?UTF-8?q?s?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Restructure the entire documentation site following the Diátaxis framework (Learn / How-to / Understand / Reference) with new content across 110 files. ## Information Architecture (M1) - Move all docs to Diátaxis directory structure (learn/, how-to/, understand/, reference/) - Add client-redirects plugin for old URL compatibility - Rewrite sidebar, navbar, and footer to match new IA - Update all internal cross-references ## Homepage + Quickstarts (M2) - Add scenario entry cards to homepage with hand-drawn design - 5 quickstart pages: Claude Code, GitHub Copilot (with copy mode recommendation), Codex, Multiple Tools, Dev Containers, Playground ## Blog + Changelog (M3) - Enable Docusaurus blog plugin with authors.yml - 5 blog posts: 5-min tutorial, managing 50+ skills, skillshare vs vercel/skills comparison, team sharing patterns, write your first skill - Static /changelog page from CHANGELOG.md ## Recipes + Philosophy (M4) - 5 recipe pages: CI/CD validation, enterprise skills, project setup, cross-machine sync, team onboarding - 3 philosophy pages: why-local-first, security-first, sync-modes-explained ## Content Polish - Cross-validate all content against CLI source (19 inaccuracies fixed) - Lowercase "skillshare" throughout (avoid brand conflict with Skillshare Inc.) - Add registry.yaml to file structure and Key Paths docs - Highlight multi-platform git support (GitHub, GitLab, Bitbucket, Gitea, Azure DevOps, AtomGit, Codeberg) - Standardize brew install command - Add AsciinemaPlayer component (cast recordings pending) --- README.md | 14 +- scripts/record-casts.sh | 90 + website/blog/2019-05-28-first-blog-post.md | 12 - website/blog/2019-05-29-long-blog-post.md | 44 - website/blog/2021-08-01-mdx-blog-post.mdx | 24 - website/blog/2021-08-26-welcome/index.md | 29 - .../2026-02-26-5-min-claude-code-skills.md | 119 + website/blog/2026-02-26-managing-50-skills.md | 139 + .../2026-02-26-migrate-from-vercel-skills.md | 119 + .../blog/2026-02-26-team-sharing-patterns.md | 140 + .../blog/2026-02-26-write-your-first-skill.md | 197 + website/blog/authors.yml | 30 +- website/blog/tags.yml | 19 - website/docs/getting-started/first-sync.md | 22 +- .../getting-started/from-existing-skills.md | 6 +- website/docs/getting-started/index.md | 8 +- .../docs/getting-started/quick-reference.md | 5 +- website/docs/guides/index.md | 51 - .../advanced}/docker-sandbox.md | 2 +- .../advanced}/local-first.md | 10 +- .../{guides => how-to/advanced}/migration.md | 4 +- .../{guides => how-to/advanced}/security.md | 14 +- .../daily-tasks}/backup-restore.md | 8 +- .../daily-tasks}/best-practices.md | 10 +- .../daily-tasks}/creating-skills.md | 12 +- .../daily-tasks}/daily-workflow.md | 10 +- .../daily-tasks}/index.md | 0 .../daily-tasks}/organizing-skills.md | 10 +- .../daily-tasks}/project-workflow.md | 4 +- .../daily-tasks}/skill-discovery.md | 6 +- website/docs/how-to/index.md | 54 + .../how-to/recipes/ci-cd-skill-validation.md | 101 + .../recipes/cross-machine-sync-recipe.md | 79 + website/docs/how-to/recipes/index.md | 19 + .../recipes/private-enterprise-skills.md | 79 + .../recipes/skill-per-project-workflow.md | 80 + .../how-to/recipes/team-onboarding-recipe.md | 98 + .../sharing}/cross-machine-sync.md | 8 +- .../{guides => how-to/sharing}/hub-index.md | 6 +- .../sharing}/organization-sharing.md | 18 +- .../sharing}/project-setup.md | 6 +- website/docs/intro.md | 20 +- website/docs/learn/with-claude-code.md | 62 + website/docs/learn/with-codex.md | 60 + website/docs/learn/with-copilot.md | 79 + website/docs/learn/with-devcontainer.md | 63 + website/docs/learn/with-multiple-tools.md | 81 + website/docs/learn/with-playground.md | 114 + .../{ => appendix}/environment-variables.md | 4 +- .../{ => appendix}/file-structure.md | 47 +- website/docs/reference/appendix/index.md | 43 + .../reference/{ => appendix}/url-formats.md | 2 +- .../docs/{ => reference}/commands/audit.md | 14 +- .../docs/{ => reference}/commands/backup.md | 6 +- .../docs/{ => reference}/commands/check.md | 6 +- .../docs/{ => reference}/commands/collect.md | 6 +- website/docs/{ => reference}/commands/diff.md | 6 +- .../docs/{ => reference}/commands/doctor.md | 8 +- website/docs/{ => reference}/commands/hub.md | 2 +- .../docs/{ => reference}/commands/index.md | 2 +- website/docs/{ => reference}/commands/init.md | 2 +- .../docs/{ => reference}/commands/install.md | 24 +- website/docs/{ => reference}/commands/list.md | 12 +- website/docs/{ => reference}/commands/log.md | 6 +- website/docs/{ => reference}/commands/new.md | 6 +- website/docs/{ => reference}/commands/pull.md | 6 +- website/docs/{ => reference}/commands/push.md | 6 +- .../docs/{ => reference}/commands/restore.md | 4 +- .../docs/{ => reference}/commands/search.md | 2 +- .../docs/{ => reference}/commands/status.md | 8 +- website/docs/{ => reference}/commands/sync.md | 16 +- .../docs/{ => reference}/commands/target.md | 14 +- .../docs/{ => reference}/commands/trash.md | 6 +- website/docs/{ => reference}/commands/ui.md | 8 +- .../{ => reference}/commands/uninstall.md | 10 +- .../docs/{ => reference}/commands/update.md | 8 +- .../docs/{ => reference}/commands/upgrade.md | 8 +- .../docs/{ => reference}/commands/version.md | 0 website/docs/reference/index.md | 41 +- .../targets/adding-custom-targets.md | 4 +- .../{ => reference}/targets/configuration.md | 12 +- website/docs/{ => reference}/targets/index.md | 6 +- .../targets/supported-targets.md | 4 +- website/docs/troubleshooting/common-errors.md | 8 +- website/docs/troubleshooting/faq.md | 12 +- website/docs/troubleshooting/index.md | 2 +- .../troubleshooting-workflow.md | 2 +- website/docs/troubleshooting/windows.md | 8 +- .../declarative-manifest.md | 4 +- .../docs/{concepts => understand}/index.md | 18 +- .../philosophy}/comparison.md | 8 +- .../understand/philosophy/security-first.md | 105 + .../philosophy}/skill-design.md | 8 +- .../philosophy/sync-modes-explained.md | 153 + .../understand/philosophy/why-local-first.md | 63 + .../project-skills.md | 8 +- .../{concepts => understand}/skill-format.md | 12 +- .../source-and-targets.md | 10 +- .../{concepts => understand}/sync-modes.md | 8 +- .../tracked-repositories.md | 18 +- website/docusaurus.config.ts | 156 +- website/package-lock.json | 21136 ++++++++++++++++ website/package.json | 2 + website/pnpm-lock.yaml | 118 + website/sidebars.ts | 262 +- website/src/components/AsciinemaPlayer.tsx | 58 + website/src/pages/changelog.md | 594 + website/src/pages/index.module.css | 136 + website/src/pages/index.tsx | 66 +- website/static/casts/.gitkeep | 0 110 files changed, 24844 insertions(+), 675 deletions(-) create mode 100755 scripts/record-casts.sh delete mode 100644 website/blog/2019-05-28-first-blog-post.md delete mode 100644 website/blog/2019-05-29-long-blog-post.md delete mode 100644 website/blog/2021-08-01-mdx-blog-post.mdx delete mode 100644 website/blog/2021-08-26-welcome/index.md create mode 100644 website/blog/2026-02-26-5-min-claude-code-skills.md create mode 100644 website/blog/2026-02-26-managing-50-skills.md create mode 100644 website/blog/2026-02-26-migrate-from-vercel-skills.md create mode 100644 website/blog/2026-02-26-team-sharing-patterns.md create mode 100644 website/blog/2026-02-26-write-your-first-skill.md delete mode 100644 website/blog/tags.yml delete mode 100644 website/docs/guides/index.md rename website/docs/{guides => how-to/advanced}/docker-sandbox.md (99%) rename website/docs/{guides => how-to/advanced}/local-first.md (87%) rename website/docs/{guides => how-to/advanced}/migration.md (97%) rename website/docs/{guides => how-to/advanced}/security.md (92%) rename website/docs/{workflows => how-to/daily-tasks}/backup-restore.md (90%) rename website/docs/{guides => how-to/daily-tasks}/best-practices.md (93%) rename website/docs/{guides => how-to/daily-tasks}/creating-skills.md (92%) rename website/docs/{workflows => how-to/daily-tasks}/daily-workflow.md (86%) rename website/docs/{workflows => how-to/daily-tasks}/index.md (100%) rename website/docs/{guides => how-to/daily-tasks}/organizing-skills.md (95%) rename website/docs/{workflows => how-to/daily-tasks}/project-workflow.md (96%) rename website/docs/{workflows => how-to/daily-tasks}/skill-discovery.md (93%) create mode 100644 website/docs/how-to/index.md create mode 100644 website/docs/how-to/recipes/ci-cd-skill-validation.md create mode 100644 website/docs/how-to/recipes/cross-machine-sync-recipe.md create mode 100644 website/docs/how-to/recipes/index.md create mode 100644 website/docs/how-to/recipes/private-enterprise-skills.md create mode 100644 website/docs/how-to/recipes/skill-per-project-workflow.md create mode 100644 website/docs/how-to/recipes/team-onboarding-recipe.md rename website/docs/{guides => how-to/sharing}/cross-machine-sync.md (95%) rename website/docs/{guides => how-to/sharing}/hub-index.md (97%) rename website/docs/{guides => how-to/sharing}/organization-sharing.md (92%) rename website/docs/{guides => how-to/sharing}/project-setup.md (96%) create mode 100644 website/docs/learn/with-claude-code.md create mode 100644 website/docs/learn/with-codex.md create mode 100644 website/docs/learn/with-copilot.md create mode 100644 website/docs/learn/with-devcontainer.md create mode 100644 website/docs/learn/with-multiple-tools.md create mode 100644 website/docs/learn/with-playground.md rename website/docs/reference/{ => appendix}/environment-variables.md (97%) rename website/docs/reference/{ => appendix}/file-structure.md (87%) create mode 100644 website/docs/reference/appendix/index.md rename website/docs/reference/{ => appendix}/url-formats.md (98%) rename website/docs/{ => reference}/commands/audit.md (98%) rename website/docs/{ => reference}/commands/backup.md (91%) rename website/docs/{ => reference}/commands/check.md (96%) rename website/docs/{ => reference}/commands/collect.md (90%) rename website/docs/{ => reference}/commands/diff.md (93%) rename website/docs/{ => reference}/commands/doctor.md (94%) rename website/docs/{ => reference}/commands/hub.md (98%) rename website/docs/{ => reference}/commands/index.md (98%) rename website/docs/{ => reference}/commands/init.md (98%) rename website/docs/{ => reference}/commands/install.md (95%) rename website/docs/{ => reference}/commands/list.md (92%) rename website/docs/{ => reference}/commands/log.md (96%) rename website/docs/{ => reference}/commands/new.md (95%) rename website/docs/{ => reference}/commands/pull.md (92%) rename website/docs/{ => reference}/commands/push.md (91%) rename website/docs/{ => reference}/commands/restore.md (94%) rename website/docs/{ => reference}/commands/search.md (99%) rename website/docs/{ => reference}/commands/status.md (90%) rename website/docs/{ => reference}/commands/sync.md (94%) rename website/docs/{ => reference}/commands/target.md (92%) rename website/docs/{ => reference}/commands/trash.md (91%) rename website/docs/{ => reference}/commands/ui.md (96%) rename website/docs/{ => reference}/commands/uninstall.md (95%) rename website/docs/{ => reference}/commands/update.md (97%) rename website/docs/{ => reference}/commands/upgrade.md (90%) rename website/docs/{ => reference}/commands/version.md (100%) rename website/docs/{ => reference}/targets/adding-custom-targets.md (95%) rename website/docs/{ => reference}/targets/configuration.md (96%) rename website/docs/{ => reference}/targets/index.md (89%) rename website/docs/{ => reference}/targets/supported-targets.md (98%) rename website/docs/{concepts => understand}/declarative-manifest.md (95%) rename website/docs/{concepts => understand}/index.md (80%) rename website/docs/{guides => understand/philosophy}/comparison.md (96%) create mode 100644 website/docs/understand/philosophy/security-first.md rename website/docs/{guides => understand/philosophy}/skill-design.md (97%) create mode 100644 website/docs/understand/philosophy/sync-modes-explained.md create mode 100644 website/docs/understand/philosophy/why-local-first.md rename website/docs/{concepts => understand}/project-skills.md (95%) rename website/docs/{concepts => understand}/skill-format.md (91%) rename website/docs/{concepts => understand}/source-and-targets.md (92%) rename website/docs/{concepts => understand}/sync-modes.md (96%) rename website/docs/{concepts => understand}/tracked-repositories.md (91%) create mode 100644 website/package-lock.json create mode 100644 website/src/components/AsciinemaPlayer.tsx create mode 100644 website/src/pages/changelog.md create mode 100644 website/static/casts/.gitkeep diff --git a/README.md b/README.md index e4dae2679..ba6b7a6d2 100644 --- a/README.md +++ b/README.md @@ -82,7 +82,7 @@ skillshare uses a **declarative** approach: define your targets once in `config. | **Runtime dependency** | Node.js + npm | None (single Go binary) | > [!TIP] -> Coming from another tool? See the [Migration Guide](https://skillshare.runkids.cc/docs/guides/migration) and [detailed comparison](https://skillshare.runkids.cc/docs/guides/comparison). +> Coming from another tool? See the [Migration Guide](https://skillshare.runkids.cc/docs/how-to/advanced/migration) and [detailed comparison](https://skillshare.runkids.cc/docs/understand/philosophy/comparison). ## How It Works - macOS / Linux: `~/.config/skillshare/skills/` @@ -107,10 +107,10 @@ skillshare uses a **declarative** approach: define your targets once in `config. | Windows | `%AppData%\skillshare\skills\` | NTFS Junctions (no admin required) | > Targets that can't follow symlinks? Use `skillshare target --mode copy` to sync as real files instead. -> You can mix modes by target. See the [Sync Modes guide](https://skillshare.runkids.cc/docs/concepts/sync-modes) and [`target` command docs](https://skillshare.runkids.cc/docs/commands/target). +> You can mix modes by target. See the [Sync Modes guide](https://skillshare.runkids.cc/docs/understand/sync-modes) and [`target` command docs](https://skillshare.runkids.cc/docs/reference/commands/target). > [!TIP] -> Skills can be organized in folders (e.g. `frontend/react/react-best-practices/`) — they're auto-flattened on sync. See the [Organizing Guide](https://skillshare.runkids.cc/docs/guides/organizing-skills) and [runkids/my-skills](https://github.com/runkids/my-skills) for a real-world example. +> Skills can be organized in folders (e.g. `frontend/react/react-best-practices/`) — they're auto-flattened on sync. See the [Organizing Guide](https://skillshare.runkids.cc/docs/how-to/daily-tasks/organizing-skills) and [runkids/my-skills](https://github.com/runkids/my-skills) for a real-world example. ## CLI and UI Preview @@ -281,7 +281,7 @@ The generated `skillshare-hub.json` follows a versioned schema (`schemaVersion: The public hub at [runkids/skillshare-hub](https://github.com/runkids/skillshare-hub) is the built-in default. Fork it to bootstrap your organization's internal hub — CI validation and `skillshare audit` security scans are included out of the box. > [!TIP] -> See the [Hub Index Guide](https://skillshare.runkids.cc/docs/guides/hub-index) for schema details and hosting options. +> See the [Hub Index Guide](https://skillshare.runkids.cc/docs/how-to/sharing/hub-index) for schema details and hosting options. ## Web Dashboard @@ -327,7 +327,7 @@ Skills are also scanned automatically during `skillshare install` and `skillshar - Audit output shows both **block decision** (severity threshold) and **risk score** (label/score). Risk score does not by itself block installs or updates. > [!TIP] -> See the [Securing Your Skills](https://skillshare.runkids.cc/docs/guides/security) guide for a complete security workflow, or the [audit command reference](https://skillshare.runkids.cc/docs/commands/audit) for the full list of detection patterns. +> See the [Securing Your Skills](https://skillshare.runkids.cc/docs/how-to/advanced/security) guide for a complete security workflow, or the [audit command reference](https://skillshare.runkids.cc/docs/reference/commands/audit) for the full list of detection patterns. ## Docker @@ -428,8 +428,8 @@ ssrm demo # Delete environment ## Documentation - Docs home: https://skillshare.runkids.cc/docs/ -- Commands: https://skillshare.runkids.cc/docs/commands -- Guides: https://skillshare.runkids.cc/docs/guides/ +- Reference: https://skillshare.runkids.cc/docs/reference/commands +- How-To: https://skillshare.runkids.cc/docs/how-to/ - Troubleshooting: https://skillshare.runkids.cc/docs/troubleshooting/faq ## Contributing diff --git a/scripts/record-casts.sh b/scripts/record-casts.sh new file mode 100755 index 000000000..09ea51e67 --- /dev/null +++ b/scripts/record-casts.sh @@ -0,0 +1,90 @@ +#!/usr/bin/env bash +# record-casts.sh — Record asciinema casts inside playground container. +# +# Usage: +# 1. Start playground: make playground (or: ./scripts/sandbox.sh up) +# 2. Enter shell: ./scripts/sandbox.sh shell +# 3. Run this script: ./scripts/record-casts.sh +# 4. Copy casts out: docker cp skillshare-playground:/tmp/casts/ website/static/casts/ +# +# Prerequisites (inside container): +# pip3 install asciinema (or: apt-get install -y asciinema) +# +# Each recording runs a pre-defined command sequence with controlled timing. +set -euo pipefail + +CAST_DIR="/tmp/casts" +COLS=120 +ROWS=30 +mkdir -p "$CAST_DIR" + +# Ensure asciinema is available +if ! command -v asciinema &>/dev/null; then + echo "Installing asciinema..." + pip3 install asciinema 2>/dev/null || { + apt-get update -qq && apt-get install -y -qq asciinema + } +fi + +record_command() { + local name="$1" + local cmd="$2" + local desc="${3:-}" + + echo "Recording: $name ($desc)" + + # Use asciinema in non-interactive mode + asciinema rec "$CAST_DIR/$name.cast" \ + --cols "$COLS" --rows "$ROWS" \ + --title "$desc" \ + --command "$cmd" \ + --overwrite + + echo " → $CAST_DIR/$name.cast" +} + +echo "=== Skillshare Cast Recorder ===" +echo "Output: $CAST_DIR/" +echo "" + +# 1. Init +record_command "init" \ + "skillshare init --no-copy --all-targets --no-git --skill" \ + "skillshare init" + +# 2. Install a skill +record_command "install" \ + "skillshare install runkids/my-skills 2>&1 || true" \ + "skillshare install" + +# 3. List skills (plain mode — TUI doesn't work in non-interactive) +record_command "list" \ + "skillshare list --no-tui" \ + "skillshare list" + +# 4. Sync +record_command "sync" \ + "skillshare sync" \ + "skillshare sync" + +# 5. Status +record_command "status" \ + "skillshare status" \ + "skillshare status" + +# 6. Audit +record_command "audit" \ + "skillshare audit" \ + "skillshare audit" + +# 7. Check for updates +record_command "check" \ + "skillshare check 2>&1 || true" \ + "skillshare check" + +echo "" +echo "=== Done ===" +echo "Recorded $(ls "$CAST_DIR"/*.cast 2>/dev/null | wc -l) casts in $CAST_DIR/" +echo "" +echo "To copy to website:" +echo " docker cp skillshare-playground:$CAST_DIR/. website/static/casts/" diff --git a/website/blog/2019-05-28-first-blog-post.md b/website/blog/2019-05-28-first-blog-post.md deleted file mode 100644 index d3032efb3..000000000 --- a/website/blog/2019-05-28-first-blog-post.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -slug: first-blog-post -title: First Blog Post -authors: [slorber, yangshun] -tags: [hola, docusaurus] ---- - -Lorem ipsum dolor sit amet... - - - -...consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet diff --git a/website/blog/2019-05-29-long-blog-post.md b/website/blog/2019-05-29-long-blog-post.md deleted file mode 100644 index eb4435de5..000000000 --- a/website/blog/2019-05-29-long-blog-post.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -slug: long-blog-post -title: Long Blog Post -authors: yangshun -tags: [hello, docusaurus] ---- - -This is the summary of a very long blog post, - -Use a `` comment to limit blog post size in the list view. - - - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet diff --git a/website/blog/2021-08-01-mdx-blog-post.mdx b/website/blog/2021-08-01-mdx-blog-post.mdx deleted file mode 100644 index 0c4b4a48b..000000000 --- a/website/blog/2021-08-01-mdx-blog-post.mdx +++ /dev/null @@ -1,24 +0,0 @@ ---- -slug: mdx-blog-post -title: MDX Blog Post -authors: [slorber] -tags: [docusaurus] ---- - -Blog posts support [Docusaurus Markdown features](https://docusaurus.io/docs/markdown-features), such as [MDX](https://mdxjs.com/). - -:::tip - -Use the power of React to create interactive blog posts. - -::: - -{/* truncate */} - -For example, use JSX to create an interactive button: - -```js - -``` - - diff --git a/website/blog/2021-08-26-welcome/index.md b/website/blog/2021-08-26-welcome/index.md deleted file mode 100644 index 349ea075f..000000000 --- a/website/blog/2021-08-26-welcome/index.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -slug: welcome -title: Welcome -authors: [slorber, yangshun] -tags: [facebook, hello, docusaurus] ---- - -[Docusaurus blogging features](https://docusaurus.io/docs/blog) are powered by the [blog plugin](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog). - -Here are a few tips you might find useful. - - - -Simply add Markdown files (or folders) to the `blog` directory. - -Regular blog authors can be added to `authors.yml`. - -The blog post date can be extracted from filenames, such as: - -- `2019-05-30-welcome.md` -- `2019-05-30-welcome/index.md` - -A blog post folder can be convenient to co-locate blog post images: - -![Docusaurus Plushie](./docusaurus-plushie-banner.jpeg) - -The blog supports tags as well! - -**And if you don't want a blog**: just delete this directory, and use `blog: false` in your Docusaurus config. diff --git a/website/blog/2026-02-26-5-min-claude-code-skills.md b/website/blog/2026-02-26-5-min-claude-code-skills.md new file mode 100644 index 000000000..1f4eaf7f2 --- /dev/null +++ b/website/blog/2026-02-26-5-min-claude-code-skills.md @@ -0,0 +1,119 @@ +--- +slug: 5-min-claude-code-skills +title: 5 Minutes to Manage Your Claude Code Skills +authors: [runkids] +tags: [tutorial, claude-code] +--- + +Getting Claude Code skills organized shouldn't take more than a coffee break. Here's how to go from zero to a fully managed skill library in under 5 minutes. + + + +## The Problem + +Claude Code stores skills in `~/.claude/skills/`. Over time, you accumulate skills from different sources — some you wrote, some from teammates, some from GitHub. Without structure, it becomes hard to track what's installed, what's outdated, and what conflicts with what. + +## Step 1: Install skillshare + +```bash +curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh +``` + +Or via Homebrew (macOS/Linux): + +```bash +brew install skillshare +``` + +:::note +Homebrew releases may lag behind the latest version by a few days. For the newest release, use the install script above. +::: + +Verify: + +```bash +skillshare version +``` + +## Step 2: Initialize + +```bash +skillshare init +``` + +This creates a source directory at `~/.config/skillshare/skills/` and auto-detects Claude Code as a sync target. + +## Step 3: Import Your Existing Skills + +Already have skills in `~/.claude/skills/`? Collect them into your source: + +```bash +skillshare collect +``` + +skillshare copies each skill from Claude Code's directory into your source. Now you have a single place that holds everything. + +## Step 4: Install a Skill from GitHub + +Let's add a popular skill set: + +```bash +skillshare install anthropics/courses/prompt-eng +``` + +This clones the repository and places skills in your source directory. Run `skillshare list` to see everything: + +```bash +skillshare list +``` + +## Step 5: Sync + +```bash +skillshare sync +``` + +By default, skillshare uses **merge mode** — creating per-skill symlinks from your source into `~/.claude/skills/`. Your original local skills are preserved — only new ones are added. + +## Step 6: Verify + +Open Claude Code and check that your skills are available: + +```bash +claude +# Inside Claude Code, your skills should be loaded +``` + +## Symlink Not Working? Use Copy Mode + +Some platforms and tools have inconsistent symlink support — WSL, certain Docker setups, or AI tools that don't follow symlinks. If you run into issues: + +```bash +skillshare target claude --mode copy +skillshare sync +``` + +Copy mode physically copies skill files instead of symlinking. The trade-off: + +| | Merge (symlink) | Copy | +|---|---|---| +| Source changes reflected | Instantly | After `sync` | +| Cross-platform compatibility | May have issues | Works everywhere | +| Local skill preservation | Yes | Yes | + +See [Sync Modes](/docs/understand/sync-modes) for the full comparison. + +## What You Get + +After these steps: + +- **Single source of truth** — all skills live in `~/.config/skillshare/skills/` +- **Non-destructive sync** — local Claude Code skills are untouched +- **Version tracking** — installed repos are tracked for updates via `skillshare check` +- **Backup ready** — `skillshare backup` snapshots your entire skill library + +## Next Steps + +- [Set up multi-tool sync](/docs/learn/with-multiple-tools) if you also use Cursor, Codex, or other tools +- [Create your first custom skill](/docs/how-to/daily-tasks/creating-skills) +- [Share skills with your team](/docs/how-to/sharing/organization-sharing) diff --git a/website/blog/2026-02-26-managing-50-skills.md b/website/blog/2026-02-26-managing-50-skills.md new file mode 100644 index 000000000..744ab909b --- /dev/null +++ b/website/blog/2026-02-26-managing-50-skills.md @@ -0,0 +1,139 @@ +--- +slug: managing-50-skills +title: How I Manage 50+ Skills Across 3 AI Tools +authors: [runkids] +tags: [tutorial, advanced] +--- + +When you use Claude Code, Cursor, and Codex daily, skill management gets chaotic fast. Here's how I keep 50+ skills organized across all three tools with a single workflow. + + + +## The Setup + +My daily toolkit: +- **Claude Code** — primary coding assistant +- **Cursor** — IDE-integrated AI +- **Codex** — quick prototyping and script generation + +Each tool has its own skill directory, its own format quirks, and its own update cycle. Without skillshare, I was manually copying files between three locations every time I changed a skill. + +## Directory Structure + +After `skillshare init`, my source looks like this: + +``` +~/.config/skillshare/skills/ +├── _anthropics__courses__prompt-eng/ # tracked repo +├── _team__frontend/ # team shared +├── code-review/ # my custom skill +├── commit-message/ # my custom skill +├── debugging/ # organized into folders +├── testing/ +└── frontend/ + ├── react-patterns/ + ├── css-guidelines/ + └── accessibility/ +``` + +Skills prefixed with `_` are tracked repositories. The rest are local skills organized into logical groups. + +## Organizing with `--into` + +The `--into` flag places installed skills into subdirectories: + +```bash +skillshare install user/repo --into frontend +skillshare install another/repo --into backend +``` + +This creates a clean hierarchy without flat-file chaos. + +## Multi-Target Sync + +Global config targets use a map format: + +```yaml +targets: + claude: + path: ~/.claude/skills + cursor: + path: ~/.cursor/skills + codex: + path: ~/.codex/skills +``` + +One `skillshare sync` pushes all 50+ skills to all three tools simultaneously. Each target gets per-skill symlinks, so tool-specific local skills remain untouched. + +## Per-Target Mode and Filtering + +You can set a different sync mode per target, and use `include`/`exclude` patterns to control which skills go where: + +```yaml +targets: + claude: + path: ~/.claude/skills + mode: merge + cursor: + path: ~/.cursor/skills + mode: copy # copy mode for better compatibility + exclude: + - "_experimental*" + codex: + path: ~/.codex/skills + mode: merge + include: + - "coding-*" +``` + +## Daily Workflow + +My morning routine takes about 30 seconds: + +```bash +# Check for upstream updates +skillshare check + +# If updates available +skillshare update --all + +# Sync to all targets +skillshare sync +``` + +That's it. Three tools, 50+ skills, one command chain. + +## Handling Conflicts + +Occasionally, a tool creates a skill with the same name as one in my source. skillshare handles this gracefully: + +- In **merge mode**, the symlink points to your source skill +- The target's original file is not deleted — it's simply overshadowed by the symlink +- Running `skillshare diff` shows exactly what differs between source and target + +## Backup Strategy + +Before major changes, I snapshot: + +```bash +skillshare backup +``` + +Backups are stored in `~/.local/share/skillshare/backups/` with timestamps. To restore a specific target: + +```bash +skillshare restore claude +``` + +## Key Takeaways + +1. **One source, many targets** — the fundamental principle +2. **Use `--into` for organization** — avoid flat directory sprawl +3. **Check + update + sync** — the daily three-command chain +4. **Backup before experiments** — it takes 2 seconds and saves hours + +## Resources + +- [Multi-tool quickstart](/docs/learn/with-multiple-tools) +- [Organizing skills guide](/docs/how-to/daily-tasks/organizing-skills) +- [Backup & restore guide](/docs/how-to/daily-tasks/backup-restore) diff --git a/website/blog/2026-02-26-migrate-from-vercel-skills.md b/website/blog/2026-02-26-migrate-from-vercel-skills.md new file mode 100644 index 000000000..2c62e557a --- /dev/null +++ b/website/blog/2026-02-26-migrate-from-vercel-skills.md @@ -0,0 +1,119 @@ +--- +slug: migrate-from-vercel-skills +title: skillshare vs. vercel/skills — When to Use Which +authors: [runkids] +tags: [comparison] +--- + +[vercel/skills](https://github.com/vercel-labs/skills) and skillshare are both CLI tools for managing AI coding skills across multiple agents. If you're choosing between them — or considering a migration — here's an honest comparison. + + + +## What They Have in Common + +Both tools solve the same core problem: managing AI skill files across 40+ coding agents (Claude Code, Cursor, Codex, etc.). Both offer: + +- Install skills from Git repositories +- Sync to multiple AI tool targets +- Support for symlink and copy modes +- Project-level and global skill management + +## Where vercel/skills Shines + +**Best for quick, curated installs:** + +- Runs via `npx skills` — no binary installation needed if you have Node.js +- Curated skill discovery via `npx skills find` with interactive selection +- Strong Vercel/Next.js ecosystem integration +- Familiar npm-based workflow for JavaScript developers + +**Use vercel/skills when:** +- You're already in the Node.js ecosystem +- All your skill repos are on GitHub (it currently only supports GitHub) +- You want a curated, community-driven skill catalog +- You prefer `npx`-based tooling with no permanent install +- Your workflow is primarily single-machine, single-project + +## Where skillshare Shines + +**Best for multi-tool sync, multi-platform, and team workflows:** + +- Single binary — no Node.js, npm, or runtime dependencies +- **Any Git host** — GitHub, GitLab, Bitbucket, Gitea, Azure DevOps, AtomGit, Codeberg, self-hosted, and any HTTPS/SSH git server +- Bidirectional sync: collect skills from targets back to source +- Cross-machine sync via `push`/`pull` +- Built-in security audit (15+ detection patterns, auto-block on install) +- Backup/restore with timestamped snapshots +- Web dashboard (`skillshare ui`) +- Organization-wide skill distribution via tracked repos +- Works offline (core operations need no network) + +**Use skillshare when:** +- You use multiple AI tools and need one source of truth +- Your skills live on GitLab, Bitbucket, Azure DevOps, or self-hosted Git — not just GitHub +- You work across multiple machines +- Your team needs standardized skills via git +- You need security scanning for untrusted skill sources +- You want zero runtime dependencies (CI/CD, Docker, air-gapped environments) + +## Feature Comparison + +| Feature | vercel/skills | skillshare | +|---------|--------------|------------| +| Install method | `npx` (Node.js) | Single binary | +| Git platform support | GitHub only | GitHub, GitLab, Bitbucket, Gitea, GHE, Azure DevOps, AtomGit, Codeberg, any HTTPS/SSH host | +| Sync modes | Symlink, copy | Merge (per-skill symlink), symlink, copy | +| Multi-tool sync | Yes | Yes | +| Collect (target → source) | No | Yes | +| Cross-machine sync | No | Yes (`push`/`pull`) | +| Security audit | No | Yes (15+ patterns) | +| Backup/restore | No | Yes | +| Web UI | No | Yes | +| Hub/registry | Community catalog | Self-hosted hub index | +| Offline operation | Needs npm | Yes (core operations) | +| Project skills | Yes | Yes | + +## Migrating from vercel/skills + +If you decide to switch, the process is straightforward: + +### Step 1: Install skillshare + +```bash +curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh +skillshare init +``` + +### Step 2: Collect existing skills + +If vercel/skills already synced skills to your AI tool directories: + +```bash +skillshare collect +``` + +This copies skills from your target directories into skillshare's source. + +### Step 3: Sync + +```bash +skillshare sync +``` + +### Step 4: Ongoing updates + +```bash +skillshare check # Detect upstream changes +skillshare update --all # Apply updates +skillshare sync # Push to all tools +``` + +## Can They Coexist? + +Yes. Both tools use symlinks (or copies) to the same target directories. However, running both simultaneously on the same targets may cause conflicts — one tool's symlinks may be overwritten by the other. If you're evaluating both, use them on separate targets or test one at a time. + +## Resources + +- [Migration guide](/docs/how-to/advanced/migration) +- [Install command reference](/docs/reference/commands/install) +- [Security audit guide](/docs/how-to/advanced/security) diff --git a/website/blog/2026-02-26-team-sharing-patterns.md b/website/blog/2026-02-26-team-sharing-patterns.md new file mode 100644 index 000000000..4ec6c4aec --- /dev/null +++ b/website/blog/2026-02-26-team-sharing-patterns.md @@ -0,0 +1,140 @@ +--- +slug: team-sharing-patterns +title: 3 Patterns for Team Skill Sharing +authors: [runkids] +tags: [team, tutorial] +--- + +Every team eventually faces the question: "How do we share AI skills across the team?" Here are three patterns, from simplest to most structured, with skillshare handling the mechanics. + + + +## Pattern 1: Shared Git Repository + +**Best for:** Small teams (2-5 people) who want a quick start. + +Create a Git repository with your team's skills: + +``` +team-skills/ +├── code-review/ +│ └── SKILL.md +├── pr-description/ +│ └── SKILL.md +└── testing-standards/ + └── SKILL.md +``` + +Each team member installs it: + +```bash +skillshare install your-org/team-skills +skillshare sync +``` + +When someone updates a skill, others pull changes: + +```bash +skillshare check # "team-skills: 2 skills updated" +skillshare update --all # Apply all available updates +skillshare sync +``` + +**Pros:** Simple, familiar Git workflow, works with any Git host. + +**Cons:** Everyone gets all skills, no per-project customization. + +## Pattern 2: Organization-Wide + Project-Scoped + +**Best for:** Medium teams (5-20 people) with different projects. + +Split skills into two layers: + +### Organization Layer (global) + +Shared standards that apply everywhere: + +```bash +skillshare install your-org/org-skills +``` + +These live in `~/.config/skillshare/skills/` and sync to all tools on every machine. + +### Project Layer (scoped) + +Project-specific skills committed to the project repo: + +```bash +cd your-project +skillshare init -p +skillshare install your-org/frontend-skills -p +git add .skillshare/ +git commit -m "Add project skills" +``` + +Team members get project skills automatically when they clone and run: + +```bash +skillshare sync -p +``` + +**Pros:** Organization standards + project flexibility. Skills travel with the code. + +**Cons:** Two sync commands (global + project). Requires project setup. + +## Pattern 3: Hub Index (Registry) + +**Best for:** Large teams or open-source communities. + +Generate a hub index from your source skills: + +```bash +skillshare hub index --source ./skills --output ./skillshare-hub.json +``` + +This creates a JSON file listing all available skills with metadata. Host it on GitHub Pages or any HTTPS URL, then register it: + +```bash +skillshare hub add https://your-org.github.io/skillshare-hub.json --label team +skillshare hub default team +``` + +Team members can then browse and install: + +```bash +skillshare search --hub https://your-org.github.io/skillshare-hub.json +skillshare install your-org/skills --skill code-review +``` + +**Pros:** Discoverable, self-service, scales to hundreds of skills. + +**Cons:** Requires maintaining the index. More setup upfront. + +## Choosing a Pattern + +| Factor | Pattern 1 | Pattern 2 | Pattern 3 | +|--------|-----------|-----------|-----------| +| Setup time | 5 min | 15 min | 30 min | +| Team size | 2-5 | 5-20 | 20+ | +| Per-project skills | No | Yes | Yes | +| Self-service discovery | No | No | Yes | +| Maintenance | Low | Medium | Medium | + +Most teams start with Pattern 1 and evolve to Pattern 2 when they need project-specific skills. Pattern 3 is for organizations that want a curated skill catalog. + +## Getting Started + +Regardless of pattern, the workflow is the same: + +```bash +skillshare install # Add skills +skillshare sync # Push to tools +skillshare check # Detect updates +skillshare update --all # Apply updates +``` + +## Resources + +- [Organization sharing guide](/docs/how-to/sharing/organization-sharing) +- [Project setup guide](/docs/how-to/sharing/project-setup) +- [Hub index guide](/docs/how-to/sharing/hub-index) diff --git a/website/blog/2026-02-26-write-your-first-skill.md b/website/blog/2026-02-26-write-your-first-skill.md new file mode 100644 index 000000000..2ee8077f6 --- /dev/null +++ b/website/blog/2026-02-26-write-your-first-skill.md @@ -0,0 +1,197 @@ +--- +slug: write-your-first-skill +title: "Writing Your First Skill: A Step-by-Step Guide" +authors: [runkids] +tags: [skill-authoring, tutorial] +--- + +Skills are just Markdown files with frontmatter. If you can write a README, you can write a skill. Here's how to create one from scratch, audit it, and share it. + + + +## What Is a Skill? + +A skill is a `SKILL.md` file inside a named directory. It contains instructions that AI coding tools (Claude Code, Cursor, Codex, etc.) load as context when working on your code. + +``` +my-skill/ +└── SKILL.md +``` + +That's the minimum. The `SKILL.md` file has two parts: frontmatter (metadata) and body (the actual instructions). + +## Step 1: Scaffold with `skillshare new` + +```bash +skillshare new my-code-review +``` + +This creates `~/.config/skillshare/skills/my-code-review/SKILL.md` with a template: + +```markdown +--- +name: my-code-review +description: >- + Describe what this skill does. Use when user asks to + "trigger phrase 1", "trigger phrase 2", or needs help + with a specific task. +# targets: [] # e.g. [claude, cursor] — omit for all targets +# metadata: +# author: Your Name +# version: 1.0.0 +--- + +# My Code Review + +Brief overview of what this skill does and its value. +``` + +## Step 2: Write the Instructions + +Replace the template body with clear, actionable instructions. Good skills are: + +- **Specific** — tell the AI exactly what to do, not vague guidelines +- **Scoped** — one skill, one concern (code review, testing, commit messages) +- **Contextual** — explain when to apply the instructions + +Here's an example code review skill: + +```markdown +--- +name: my-code-review +description: >- + Enforce team code review standards. Check for security, + error handling, input validation, and style compliance. +targets: [claude, cursor] +--- + +# Code Review Standards + +When reviewing code (PR reviews, code suggestions, refactoring): + +## Must Check +- No hardcoded secrets or credentials +- Error handling for all external calls (API, DB, file I/O) +- Input validation at system boundaries +- Tests for new public functions + +## Style +- Functions under 30 lines +- No more than 3 parameters per function +- Early returns over nested conditionals +- Descriptive variable names (no single letters except loop counters) + +## Response Format +- List issues by severity: critical > warning > suggestion +- Include file path and line number for each issue +- Suggest fixes, don't just flag problems +``` + +## Step 3: Security Scan + +Before sharing, audit your skill: + +```bash +skillshare audit +``` + +This checks for patterns that could be harmful: prompt injection, data exfiltration, destructive commands. Even well-intentioned skills can accidentally trigger these patterns. + +## Step 4: Sync and Test + +```bash +skillshare sync +``` + +Now open your AI tool and test the skill. Ask it to review some code and check whether it follows your instructions. + +## Step 5: Share + +### Option A: Commit to a shared repo + +```bash +# Copy to a team repository +cp -r ~/.config/skillshare/skills/my-code-review /path/to/team-skills/ +cd /path/to/team-skills +git add my-code-review/ +git commit -m "Add code review skill" +git push +``` + +Team members install with: + +```bash +skillshare install your-org/team-skills --skill my-code-review +``` + +### Option B: Project-scoped skill + +```bash +cd your-project +skillshare init -p +cp -r ~/.config/skillshare/skills/my-code-review .skillshare/skills/ +git add .skillshare/ +git commit -m "Add project code review skill" +``` + +Anyone who clones the repo gets the skill automatically. + +## Controlling Where Skills Sync + +### Per-skill target restriction + +Add a `targets` field to SKILL.md frontmatter to limit which AI tools receive this skill: + +```yaml +--- +name: claude-only-skill +description: Only syncs to Claude Code +targets: [claude] +--- +``` + +Skills without a `targets` field sync to **all** configured targets. + +### Per-target filtering + +In your config, use `include`/`exclude` patterns to control which skills each target receives: + +```yaml +targets: + claude: + path: ~/.claude/skills + exclude: + - "experimental-*" + cursor: + path: ~/.cursor/skills + include: + - "coding-*" + - "review-*" +``` + +### `.skillignore` for repositories + +If you publish a skill repository, add a `.skillignore` file to exclude internal/test skills from installation: + +``` +# .skillignore — skills to exclude during install +internal-testing +experimental +debug-* +``` + +Patterns support exact names, group prefixes, and trailing wildcards. + +## Tips for Effective Skills + +1. **Keep the description under 1024 characters** — Codex enforces this limit +2. **Use headers for structure** — AI tools parse Markdown headers for context +3. **Be imperative** — "Check for X" not "It would be good to check for X" +4. **Include examples** — Show the AI what good output looks like +5. **Use `targets` to scope** — Not every skill makes sense for every tool + +## Resources + +- [Creating skills guide](/docs/how-to/daily-tasks/creating-skills) +- [Skill format reference](/docs/understand/skill-format) +- [Best practices](/docs/how-to/daily-tasks/best-practices) diff --git a/website/blog/authors.yml b/website/blog/authors.yml index 0fd398733..60ed05ab3 100644 --- a/website/blog/authors.yml +++ b/website/blog/authors.yml @@ -1,25 +1,5 @@ -yangshun: - name: Yangshun Tay - title: Ex-Meta Staff Engineer, Co-founder GreatFrontEnd - url: https://linkedin.com/in/yangshun - image_url: https://github.com/yangshun.png - page: true - socials: - x: yangshunz - linkedin: yangshun - github: yangshun - newsletter: https://www.greatfrontend.com - -slorber: - name: Sébastien Lorber - title: Docusaurus maintainer - url: https://sebastienlorber.com - image_url: https://github.com/slorber.png - page: - # customize the url of the author page at /blog/authors/ - permalink: '/all-sebastien-lorber-articles' - socials: - x: sebastienlorber - linkedin: sebastienlorber - github: slorber - newsletter: https://thisweekinreact.com +runkids: + name: runkids + title: Creator of skillshare + url: https://github.com/runkids + image_url: https://github.com/runkids.png diff --git a/website/blog/tags.yml b/website/blog/tags.yml deleted file mode 100644 index bfaa778fb..000000000 --- a/website/blog/tags.yml +++ /dev/null @@ -1,19 +0,0 @@ -facebook: - label: Facebook - permalink: /facebook - description: Facebook tag description - -hello: - label: Hello - permalink: /hello - description: Hello tag description - -docusaurus: - label: Docusaurus - permalink: /docusaurus - description: Docusaurus tag description - -hola: - label: Hola - permalink: /hola - description: Hola tag description diff --git a/website/docs/getting-started/first-sync.md b/website/docs/getting-started/first-sync.md index 288c063af..91a530316 100644 --- a/website/docs/getting-started/first-sync.md +++ b/website/docs/getting-started/first-sync.md @@ -15,11 +15,15 @@ Get your skills synced in 5 minutes. ## Step 1: Install skillshare -**Homebrew:** +**Homebrew (macOS / Linux):** ```bash brew install skillshare ``` +:::note +Homebrew releases may lag behind the latest version by a few days. For the newest release, use the install script below. +::: + :::note All install methods include the web dashboard. `skillshare ui` automatically downloads UI assets on first launch — no extra setup needed. ::: @@ -127,9 +131,9 @@ You should see: ## What's Next? -- [Create your own skill](/docs/guides/creating-skills) -- [Sync across machines](/docs/guides/cross-machine-sync) -- [Organization-wide skills](/docs/guides/organization-sharing) +- [Create your own skill](/docs/how-to/daily-tasks/creating-skills) +- [Sync across machines](/docs/how-to/sharing/cross-machine-sync) +- [Organization-wide skills](/docs/how-to/sharing/organization-sharing) ## What Just Happened? @@ -137,7 +141,7 @@ 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. +2. **`install`** — Cloned the skill from the Git repository into your source directory (`~/.config/skillshare/skills/`). Ran a security audit automatically. Works with GitHub, GitLab, Bitbucket, Gitea, Azure DevOps, and any HTTPS/SSH Git host. 3. **`sync`** — Applied each target's configured sync mode (default is merge, which creates per-skill symlinks). For example: ``` @@ -156,10 +160,10 @@ skillshare target --mode copy skillshare sync ``` -See [Sync Modes](/docs/concepts/sync-modes) for the decision matrix and trade-offs. +See [Sync Modes](/docs/understand/sync-modes) for the decision matrix and trade-offs. ## 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 +- [Core Concepts](/docs/understand) — Understand source, targets, and sync modes +- [Daily Workflow](/docs/how-to/daily-tasks/daily-workflow) — How to use skillshare day-to-day +- [Creating Skills](/docs/how-to/daily-tasks/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 841e25001..a64d6f822 100644 --- a/website/docs/getting-started/from-existing-skills.md +++ b/website/docs/getting-started/from-existing-skills.md @@ -145,6 +145,6 @@ skillshare restore cursor ## See Also -- [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 +- [Daily Workflow](/docs/how-to/daily-tasks/daily-workflow) — Your day-to-day after migration +- [Cross-Machine Sync](/docs/how-to/sharing/cross-machine-sync) — Sync to other machines +- [Core Concepts](/docs/understand) — How source and targets work diff --git a/website/docs/getting-started/index.md b/website/docs/getting-started/index.md index cd3e8b596..b2f169ce2 100644 --- a/website/docs/getting-started/index.md +++ b/website/docs/getting-started/index.md @@ -13,7 +13,7 @@ Get skillshare running in minutes. Choose your starting point: | 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 | -| Try without installing anything | [Docker Playground](/docs/guides/docker-sandbox#playground) — `make playground` in cloned repo | +| Try without installing anything | [Docker Playground](/docs/how-to/advanced/docker-sandbox#playground) — `make playground` in cloned repo | ## The 3-Step Pattern @@ -38,6 +38,6 @@ After setup, behavior depends on mode: After you're set up: -- [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 +- [Core Concepts](/docs/understand) — Understand source, targets, and sync modes +- [Daily Workflow](/docs/how-to/daily-tasks/daily-workflow) — How to use skillshare day-to-day +- [Commands Reference](/docs/reference/commands) — Full command reference diff --git a/website/docs/getting-started/quick-reference.md b/website/docs/getting-started/quick-reference.md index fba0e40c0..f15eab81b 100644 --- a/website/docs/getting-started/quick-reference.md +++ b/website/docs/getting-started/quick-reference.md @@ -143,6 +143,7 @@ make playground-down # stop container | Path | Description | |------|-------------| | `~/.config/skillshare/config.yaml` | Configuration file | +| `~/.config/skillshare/registry.yaml` | Installed skill registry (auto-managed) | | `~/.config/skillshare/skills/` | Source directory | | `~/.local/state/skillshare/logs/` | Operation and audit logs | | `~/.local/share/skillshare/backups/` | Backup directory | @@ -160,5 +161,5 @@ make playground-down # stop container ## See Also -- [Commands Reference](/docs/commands) — Full command documentation -- [Concepts](/docs/concepts) — Core concepts explained +- [Commands Reference](/docs/reference/commands) — Full command documentation +- [Concepts](/docs/understand) — Core concepts explained diff --git a/website/docs/guides/index.md b/website/docs/guides/index.md deleted file mode 100644 index a72ebfe7f..000000000 --- a/website/docs/guides/index.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Guides - -In-depth guides for specific use cases. - -## What do you want to do? - -| I want to... | Read | -|--------------|------| -| Write my first skill | [Creating Skills](./creating-skills.md) | -| Design reliable, deterministic skills | [Skill Design](./skill-design.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) | -| Secure my skill supply chain | [Securing Your Skills](./security.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 | -|-------|-------------| -| [Creating Skills](./creating-skills.md) | Create and publish your own skills | -| [Skill Design](./skill-design.md) | Complexity levels, determinism, CLI wrapper pattern | -| [Organizing Skills](./organizing-skills.md) | Organize skills into folders with auto-flattening | -| [Best Practices](./best-practices.md) | Naming, organization, and versioning | - -### 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 - -| Guide | Description | -|-------|-------------| -| [Migration](./migration.md) | Migrate from other tools or between modes | -| [Comparison](./comparison.md) | Compare skill management approaches | -| [Docker Sandbox](./docker-sandbox.md) | Isolated test sandbox and interactive playground | -| [Securing Your Skills](./security.md) | Security scanning, custom rules, and organizational policy | diff --git a/website/docs/guides/docker-sandbox.md b/website/docs/how-to/advanced/docker-sandbox.md similarity index 99% rename from website/docs/guides/docker-sandbox.md rename to website/docs/how-to/advanced/docker-sandbox.md index 142010025..3dc23678a 100644 --- a/website/docs/guides/docker-sandbox.md +++ b/website/docs/how-to/advanced/docker-sandbox.md @@ -428,5 +428,5 @@ On tag push (`v*`), the `docker-publish` GitHub Actions workflow builds and push ## See Also - [Getting Started](/docs/getting-started) — Standard setup -- [Commands Reference](/docs/commands) — All commands +- [Commands Reference](/docs/reference/commands) — All commands - [Troubleshooting](/docs/troubleshooting) — Common issues diff --git a/website/docs/guides/local-first.md b/website/docs/how-to/advanced/local-first.md similarity index 87% rename from website/docs/guides/local-first.md rename to website/docs/how-to/advanced/local-first.md index 1275a2f40..f3eaa5516 100644 --- a/website/docs/guides/local-first.md +++ b/website/docs/how-to/advanced/local-first.md @@ -7,7 +7,7 @@ sidebar_position: 10 Skill management tools generally follow one of two architectural approaches: **centralized platforms** or **local-first**. Neither is universally better — each comes with trade-offs. This page walks through both so you can decide which fits your workflow. :::tip This is not a feature comparison -For feature-level differences (install flow, config format, etc.), see [Comparing Skill Management Approaches](./comparison.md). This page focuses on **architectural trade-offs** — where your data lives, how discovery works, and what you control. +For feature-level differences (install flow, config format, etc.), see [Comparing Skill Management Approaches](/docs/understand/philosophy/comparison). This page focuses on **architectural trade-offs** — where your data lives, how discovery works, and what you control. ::: ## Two Approaches @@ -66,7 +66,7 @@ skillshare search --hub ./skillshare-hub.json Hubs are independent — anyone can create one, and users can connect to multiple hubs simultaneously. This makes them well-suited for organizations that need to maintain private skill catalogs alongside public ones. -See the [Hub Index Guide](/docs/guides/hub-index) for a detailed walkthrough. +See the [Hub Index Guide](/docs/how-to/sharing/hub-index) for a detailed walkthrough. ### Self-Hosted Metrics @@ -95,7 +95,7 @@ This lets skill authors or organizations measure adoption on their own terms. ## See Also -- [Comparing Skill Management Approaches](./comparison.md) — Feature-level comparison -- [Hub Index Guide](/docs/guides/hub-index) — Building and using skill hubs -- [hub command](/docs/commands/hub) — Hub command reference +- [Comparing Skill Management Approaches](/docs/understand/philosophy/comparison) — Feature-level comparison +- [Hub Index Guide](/docs/how-to/sharing/hub-index) — Building and using skill hubs +- [hub command](/docs/reference/commands/hub) — Hub command reference - [Security Guide](./security.md) — Skill security scanning diff --git a/website/docs/guides/migration.md b/website/docs/how-to/advanced/migration.md similarity index 97% rename from website/docs/guides/migration.md rename to website/docs/how-to/advanced/migration.md index 47025f4bd..a67e24201 100644 --- a/website/docs/guides/migration.md +++ b/website/docs/how-to/advanced/migration.md @@ -329,5 +329,5 @@ After migrating: ## See Also - [From Existing Skills](/docs/getting-started/from-existing-skills) — Quick migration path -- [collect](/docs/commands/collect) — Collect from targets -- [Comparison](./comparison.md) — Compare approaches +- [collect](/docs/reference/commands/collect) — Collect from targets +- [Comparison](/docs/understand/philosophy/comparison) — Compare approaches diff --git a/website/docs/guides/security.md b/website/docs/how-to/advanced/security.md similarity index 92% rename from website/docs/guides/security.md rename to website/docs/how-to/advanced/security.md index b05d98ecc..c896170b3 100644 --- a/website/docs/guides/security.md +++ b/website/docs/how-to/advanced/security.md @@ -6,7 +6,7 @@ sidebar_position: 10 AI skills are powerful — they instruct AI assistants to read files, run commands, and interact with your system. This guide helps you build a security workflow around skill installation and maintenance. -For the full command reference, see [`audit`](/docs/commands/audit). +For the full command reference, see [`audit`](/docs/reference/commands/audit). ## The Risk: AI Skill Supply Chain @@ -21,7 +21,7 @@ Unlike traditional packages that run in sandboxed runtimes, AI skills operate th A single malicious skill can access anything your AI assistant can — environment variables, SSH keys, cloud credentials, source code. Automated scanning catches known patterns, but **human review remains essential**. -For a detailed threat model and detection rules, see [Why Security Scanning Matters](/docs/commands/audit#why-security-scanning-matters). +For a detailed threat model and detection rules, see [Why Security Scanning Matters](/docs/reference/commands/audit#why-security-scanning-matters). ::: @@ -169,7 +169,7 @@ rules: regex: '(?i)\bsudo\s+' ``` -For the full custom rules reference (merge semantics, disabling rules, exclude patterns), see [`audit` — Custom Rules](/docs/commands/audit#custom-rules). +For the full custom rules reference (merge semantics, disabling rules, exclude patterns), see [`audit` — Custom Rules](/docs/reference/commands/audit#custom-rules). ### Periodic Scanning @@ -221,10 +221,10 @@ jobs: For the full workflow (including PR comment reporting and artifact upload), see the [validate-pr.yml source](https://github.com/runkids/skillshare-hub/blob/main/.github/workflows/validate-pr.yml). -For more CI/CD patterns (JSON output with `jq`, GitHub Actions with artifact upload), see [`audit` — CI/CD Integration](/docs/commands/audit#cicd-integration). +For more CI/CD patterns (JSON output with `jq`, GitHub Actions with artifact upload), see [`audit` — CI/CD Integration](/docs/reference/commands/audit#cicd-integration). ## See Also -- [`audit`](/docs/commands/audit) — Full command reference (detection rules, risk scoring, custom rules) -- [Best Practices](./best-practices.md) — Naming, organization, and security hygiene -- [Project Setup](./project-setup.md) — Project-scoped skill configuration +- [`audit`](/docs/reference/commands/audit) — Full command reference (detection rules, risk scoring, custom rules) +- [Best Practices](/docs/how-to/daily-tasks/best-practices) — Naming, organization, and security hygiene +- [Project Setup](/docs/how-to/sharing/project-setup) — Project-scoped skill configuration diff --git a/website/docs/workflows/backup-restore.md b/website/docs/how-to/daily-tasks/backup-restore.md similarity index 90% rename from website/docs/workflows/backup-restore.md rename to website/docs/how-to/daily-tasks/backup-restore.md index 123baf5a2..bfeb381e1 100644 --- a/website/docs/workflows/backup-restore.md +++ b/website/docs/how-to/daily-tasks/backup-restore.md @@ -8,7 +8,7 @@ Protect your skills and recover from mistakes. ## Overview -Skillshare maintains automatic backups and provides manual backup/restore commands. +skillshare maintains automatic backups and provides manual backup/restore commands. ```mermaid flowchart LR @@ -190,7 +190,7 @@ git checkout -- specific-skill/ ## See Also -- [backup](/docs/commands/backup) — Backup command reference -- [restore](/docs/commands/restore) — Restore command reference -- [trash](/docs/commands/trash) — Soft-delete management +- [backup](/docs/reference/commands/backup) — Backup command reference +- [restore](/docs/reference/commands/restore) — Restore command reference +- [trash](/docs/reference/commands/trash) — Soft-delete management - [Troubleshooting](/docs/troubleshooting) — When things go wrong diff --git a/website/docs/guides/best-practices.md b/website/docs/how-to/daily-tasks/best-practices.md similarity index 93% rename from website/docs/guides/best-practices.md rename to website/docs/how-to/daily-tasks/best-practices.md index f3ac47522..5717a87d2 100644 --- a/website/docs/guides/best-practices.md +++ b/website/docs/how-to/daily-tasks/best-practices.md @@ -13,7 +13,7 @@ Naming conventions, organization, and version control for skills. **Do:** - Use lowercase with hyphens: `code-review`, `pdf-tools` - Be descriptive: `react-component-generator` not `rcg` -- Namespace for teams: `acme:code-review` +- Namespace for teams: `acme-code-review` **Don't:** - Use spaces or special characters @@ -292,7 +292,7 @@ Before installing third-party skills: - Read the SKILL.md - Use `--dry-run` first -For a comprehensive security workflow, see the [Securing Your Skills](./security.md) guide. +For a comprehensive security workflow, see the [Securing Your Skills](/docs/how-to/advanced/security) guide. --- @@ -321,6 +321,6 @@ For a comprehensive security workflow, see the [Securing Your Skills](./security ## See Also - [Creating Skills](./creating-skills.md) — Skill creation guide -- [Skill Design](./skill-design.md) — Complexity levels, determinism, CLI wrapper pattern -- [Skill Format](/docs/concepts/skill-format) — SKILL.md reference -- [Organization-Wide Skills](./organization-sharing.md) — Team sharing patterns +- [Skill Design](/docs/understand/philosophy/skill-design) — Complexity levels, determinism, CLI wrapper pattern +- [Skill Format](/docs/understand/skill-format) — SKILL.md reference +- [Organization-Wide Skills](/docs/how-to/sharing/organization-sharing) — Team sharing patterns diff --git a/website/docs/guides/creating-skills.md b/website/docs/how-to/daily-tasks/creating-skills.md similarity index 92% rename from website/docs/guides/creating-skills.md rename to website/docs/how-to/daily-tasks/creating-skills.md index 31981eadd..7b515a38c 100644 --- a/website/docs/guides/creating-skills.md +++ b/website/docs/how-to/daily-tasks/creating-skills.md @@ -267,7 +267,7 @@ See the example in `examples/sample.py` for reference. Avoid collisions with namespaced names: ```yaml -name: acme:code-review +name: acme-code-review ``` ### Version tracking @@ -295,7 +295,7 @@ license: MIT --- ``` -When present, `skillshare install` displays the license in the selection prompt and confirmation screen. This helps corporate users with compliance decisions. See [Skill Format](/docs/concepts/skill-format#license) for details. +When present, `skillshare install` displays the license in the selection prompt and confirmation screen. This helps corporate users with compliance decisions. See [Skill Format](/docs/understand/skill-format#license) for details. ### Controlling discovery with .skillignore @@ -315,7 +315,7 @@ prompt-eval-* Patterns match against skill paths, so a group name like `internal-tools` excludes **all** skills under that directory. Use a precise path like `internal-tools/helper` to exclude only a specific skill within a group. -Skills matching these patterns won't appear in `skillshare install ` discovery. This is applied server-side (in the repo), so all users benefit automatically. See [`runkids/my-skills`](https://github.com/runkids/my-skills) for a real-world example, and [install --exclude](/docs/commands/install#excluding-skills) for user-side exclusion. +Skills matching these patterns won't appear in `skillshare install ` discovery. This is applied server-side (in the repo), so all users benefit automatically. See [`runkids/my-skills`](https://github.com/runkids/my-skills) for a real-world example, and [install --exclude](/docs/reference/commands/install#excluding-skills) for user-side exclusion. --- @@ -334,8 +334,8 @@ Before publishing: ## See Also -- [new](/docs/commands/new) — Create a skill with template -- [Skill Format](/docs/concepts/skill-format) — SKILL.md structure -- [Skill Design](./skill-design.md) — Complexity levels, determinism, CLI wrapper pattern +- [new](/docs/reference/commands/new) — Create a skill with template +- [Skill Format](/docs/understand/skill-format) — SKILL.md structure +- [Skill Design](/docs/understand/philosophy/skill-design) — Complexity levels, determinism, CLI wrapper pattern - [Best Practices](./best-practices.md) — Naming and organization - [Organizing Skills](./organizing-skills.md) — Folder structure diff --git a/website/docs/workflows/daily-workflow.md b/website/docs/how-to/daily-tasks/daily-workflow.md similarity index 86% rename from website/docs/workflows/daily-workflow.md rename to website/docs/how-to/daily-tasks/daily-workflow.md index 45b0abd73..6348ee0d0 100644 --- a/website/docs/workflows/daily-workflow.md +++ b/website/docs/how-to/daily-tasks/daily-workflow.md @@ -53,7 +53,7 @@ skillshare sync ``` :::tip Why is sync a separate step? -Sync is intentionally decoupled from install/update/uninstall. This lets you batch multiple changes (e.g., install 3 skills → sync once), preview with `--dry-run` before propagating, and keep full control of when targets update. See [Source & Targets: Why Sync is a Separate Step](/docs/concepts/source-and-targets#why-sync-is-a-separate-step) for details. +Sync is intentionally decoupled from install/update/uninstall. This lets you batch multiple changes (e.g., install 3 skills → sync once), preview with `--dry-run` before propagating, and keep full control of when targets update. See [Source & Targets: Why Sync is a Separate Step](/docs/understand/source-and-targets#why-sync-is-a-separate-step) for details. ::: ### Preview first @@ -165,7 +165,7 @@ skillshare doctor # Check for issues ## See Also -- [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 +- [sync](/docs/reference/commands/sync) — Core sync command +- [status](/docs/reference/commands/status) — Check sync state +- [push](/docs/reference/commands/push) / [pull](/docs/reference/commands/pull) — Cross-machine sync +- [Skill Discovery](/docs/how-to/daily-tasks/skill-discovery) — Find new skills diff --git a/website/docs/workflows/index.md b/website/docs/how-to/daily-tasks/index.md similarity index 100% rename from website/docs/workflows/index.md rename to website/docs/how-to/daily-tasks/index.md diff --git a/website/docs/guides/organizing-skills.md b/website/docs/how-to/daily-tasks/organizing-skills.md similarity index 95% rename from website/docs/guides/organizing-skills.md rename to website/docs/how-to/daily-tasks/organizing-skills.md index a8ff254d6..1b898d4d0 100644 --- a/website/docs/guides/organizing-skills.md +++ b/website/docs/how-to/daily-tasks/organizing-skills.md @@ -63,7 +63,7 @@ See [runkids/my-skills](https://github.com/runkids/my-skills) for a complete org ## How Auto-Flattening Works -Skillshare converts folder paths to flat names using `__` (double underscore) as separator: +skillshare converts folder paths to flat names using `__` (double underscore) as separator: | Source path | Synced target name | |---|---| @@ -245,7 +245,7 @@ This gives you: - **History** of skill changes across machines - **Backup** via GitHub/GitLab - **Sharing** — others can browse and fork your collection -- **Cross-machine sync** via `skillshare pull` (see [Cross-Machine Sync](./cross-machine-sync.md)) +- **Cross-machine sync** via `skillshare pull` (see [Cross-Machine Sync](/docs/how-to/sharing/cross-machine-sync)) --- @@ -280,7 +280,7 @@ After `sync`, targets are updated automatically — old flat symlinks are cleane ## See Also -- [Source & Targets](/docs/concepts/source-and-targets) — How flattening works -- [Tracked Repositories](/docs/concepts/tracked-repositories) — Nested skills in repos +- [Source & Targets](/docs/understand/source-and-targets) — How flattening works +- [Tracked Repositories](/docs/understand/tracked-repositories) — Nested skills in repos - [Best Practices](./best-practices.md) — Naming conventions -- [install](/docs/commands/install) — Install with `--into` for subdirectories +- [install](/docs/reference/commands/install) — Install with `--into` for subdirectories diff --git a/website/docs/workflows/project-workflow.md b/website/docs/how-to/daily-tasks/project-workflow.md similarity index 96% rename from website/docs/workflows/project-workflow.md rename to website/docs/how-to/daily-tasks/project-workflow.md index d1c9b4737..86442c2ac 100644 --- a/website/docs/workflows/project-workflow.md +++ b/website/docs/how-to/daily-tasks/project-workflow.md @@ -249,6 +249,6 @@ skillshare sync --dry-run ## See Also -- [Project Skills](/docs/concepts/project-skills) — Concept explanation -- [Project Setup](/docs/guides/project-setup) — Initial setup guide +- [Project Skills](/docs/understand/project-skills) — Concept explanation +- [Project Setup](/docs/how-to/sharing/project-setup) — Initial setup guide - [Daily Workflow](./daily-workflow.md) — Global mode daily usage diff --git a/website/docs/workflows/skill-discovery.md b/website/docs/how-to/daily-tasks/skill-discovery.md similarity index 93% rename from website/docs/workflows/skill-discovery.md rename to website/docs/how-to/daily-tasks/skill-discovery.md index 5c9ec554e..c272e9dae 100644 --- a/website/docs/workflows/skill-discovery.md +++ b/website/docs/how-to/daily-tasks/skill-discovery.md @@ -175,7 +175,7 @@ skillshare update _team-skills ## See Also -- [search](/docs/commands/search) — Search command reference -- [install](/docs/commands/install) — Install command reference -- [Hub Index](/docs/guides/hub-index) — Managing skill hubs +- [search](/docs/reference/commands/search) — Search command reference +- [install](/docs/reference/commands/install) — Install command reference +- [Hub Index](/docs/how-to/sharing/hub-index) — Managing skill hubs - [Daily Workflow](./daily-workflow.md) — After installing, use daily diff --git a/website/docs/how-to/index.md b/website/docs/how-to/index.md new file mode 100644 index 000000000..ca821a22d --- /dev/null +++ b/website/docs/how-to/index.md @@ -0,0 +1,54 @@ +--- +sidebar_position: 1 +--- + +# How-To Guides + +Practical guides for specific tasks and use cases. + +## What do you want to do? + +| I want to... | Read | +|--------------|------| +| Write my first skill | [Creating Skills](/docs/how-to/daily-tasks/creating-skills) | +| Design reliable, deterministic skills | [Skill Design](/docs/understand/philosophy/skill-design) | +| Organize a growing skill collection | [Organizing Skills](/docs/how-to/daily-tasks/organizing-skills) | +| Share skills with my team via a git repo | [Organization-Wide Skills](/docs/how-to/sharing/organization-sharing) | +| Set up skills for a specific project | [Project Setup](/docs/how-to/sharing/project-setup) | +| Sync skills across multiple machines | [Cross-Machine Sync](/docs/how-to/sharing/cross-machine-sync) | +| Browse and discover community skills | [Hub Index](/docs/how-to/sharing/hub-index) | +| Secure my skill supply chain | [Securing Your Skills](/docs/how-to/advanced/security) | +| Move from another tool or approach | [Migration](/docs/how-to/advanced/migration) | +| Test skillshare in an isolated Docker sandbox | [Docker Sandbox](/docs/how-to/advanced/docker-sandbox) | + +## By Topic + +### Daily Tasks + +| Guide | Description | +|-------|-------------| +| [Creating Skills](/docs/how-to/daily-tasks/creating-skills) | Create and publish your own skills | +| [Organizing Skills](/docs/how-to/daily-tasks/organizing-skills) | Organize skills into folders with auto-flattening | +| [Best Practices](/docs/how-to/daily-tasks/best-practices) | Naming, organization, and versioning | +| [Daily Workflow](/docs/how-to/daily-tasks/daily-workflow) | Day-to-day skill management workflow | +| [Skill Discovery](/docs/how-to/daily-tasks/skill-discovery) | Find and evaluate skills | +| [Backup & Restore](/docs/how-to/daily-tasks/backup-restore) | Back up and restore your skills | +| [Project Workflow](/docs/how-to/daily-tasks/project-workflow) | Project-level skill workflow | + +### Sharing & Teams + +| Guide | Description | +|-------|-------------| +| [Project Setup](/docs/how-to/sharing/project-setup) | Set up project-scoped skills for a repo | +| [Organization-Wide Skills](/docs/how-to/sharing/organization-sharing) | Share skills across your organization | +| [Cross-Machine Sync](/docs/how-to/sharing/cross-machine-sync) | Sync skills across computers | +| [Hub Index](/docs/how-to/sharing/hub-index) | Browse and manage skill hubs | + +### Advanced + +| Guide | Description | +|-------|-------------| +| [Migration](/docs/how-to/advanced/migration) | Migrate from other tools or between modes | +| [Local-First](/docs/how-to/advanced/local-first) | Local-first architecture details | +| [Docker Sandbox](/docs/how-to/advanced/docker-sandbox) | Isolated test sandbox and interactive playground | +| [Securing Your Skills](/docs/how-to/advanced/security) | Security scanning, custom rules, and organizational policy | diff --git a/website/docs/how-to/recipes/ci-cd-skill-validation.md b/website/docs/how-to/recipes/ci-cd-skill-validation.md new file mode 100644 index 000000000..c81abb9f3 --- /dev/null +++ b/website/docs/how-to/recipes/ci-cd-skill-validation.md @@ -0,0 +1,101 @@ +--- +sidebar_position: 2 +--- + +# Recipe: CI/CD Skill Validation + +> Audit and sync skills automatically in your CI pipeline. + +## Scenario + +You have a team skill repository and want to ensure every PR: +- Passes security audit (no prompt injection, credential theft, etc.) +- Validates SKILL.md format +- Syncs without errors + +## Solution + +### GitHub Actions + +Create `.github/workflows/skill-validation.yml`: + +```yaml +name: Skill Validation +on: + pull_request: + paths: + - 'skills/**' + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Install skillshare + run: curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh + + - name: Initialize + run: skillshare init + + - name: Install skills from this repo + run: skillshare install . --into ci-check + + - name: Security audit + run: skillshare audit --json + + - name: Dry-run sync + run: skillshare sync --dry-run +``` + +### GitLab CI + +Create `.gitlab-ci.yml`: + +```yaml +skill-validation: + image: ghcr.io/runkids/skillshare:latest + stage: test + script: + - skillshare init + - skillshare install . --into ci-check + - skillshare audit --json + - skillshare sync --dry-run + rules: + - changes: + - skills/**/* +``` + +### Using the CI Docker Image + +For faster pipeline startup, use the pre-built CI image: + +```yaml +# GitHub Actions +jobs: + validate: + runs-on: ubuntu-latest + container: + image: ghcr.io/runkids/skillshare-ci:latest + steps: + - uses: actions/checkout@v4 + - run: skillshare init && skillshare audit --json +``` + +## Verification + +- PR check passes: audit exits 0 (no CRITICAL findings) +- Audit JSON output can be parsed by downstream tools +- Sync dry-run shows expected symlink operations + +## Variations + +- **Block on HIGH severity**: Add `--threshold HIGH` (or `-T HIGH`) to `audit` — any HIGH+ finding exits non-zero +- **Parallel validation**: Run audit and sync in separate CI jobs for faster feedback +- **Scheduled audits**: Run nightly to catch newly detected patterns in existing skills + +## Related + +- [Security audit guide](/docs/how-to/advanced/security) +- [`audit` command reference](/docs/reference/commands/audit) +- [Docker sandbox guide](/docs/how-to/advanced/docker-sandbox) diff --git a/website/docs/how-to/recipes/cross-machine-sync-recipe.md b/website/docs/how-to/recipes/cross-machine-sync-recipe.md new file mode 100644 index 000000000..9b6d56ceb --- /dev/null +++ b/website/docs/how-to/recipes/cross-machine-sync-recipe.md @@ -0,0 +1,79 @@ +--- +sidebar_position: 5 +--- + +# Recipe: Cross-Machine Sync + +> Keep skills in sync across multiple machines using git push/pull. + +## Scenario + +You work on a desktop and a laptop (or home and office machines). You want the same skill library available everywhere without re-running install commands on each machine. + +## Solution + +### Initial Setup (Machine A) + +```bash +# Initialize skillshare +skillshare init + +# Install your skills +skillshare install your-org/team-skills +skillshare install another/repo --into tools + +# Push source to a git remote +skillshare push +``` + +`skillshare push` commits your source directory to a git-tracked branch and pushes to the configured remote. + +### Setup on New Machine (Machine B) + +```bash +# Install skillshare +curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh + +# Initialize +skillshare init + +# Pull from remote +skillshare pull + +# Sync to local targets +skillshare sync +``` + +### Daily Sync Workflow + +On any machine: + +```bash +# Pull latest changes from other machines +skillshare pull + +# Sync to local AI tools +skillshare sync + +# After making changes locally +skillshare push +``` + +## Verification + +- `skillshare push` exits 0 and reports committed changes +- `skillshare pull` on another machine shows received changes +- `skillshare list` shows identical skills on both machines +- `skillshare sync` creates symlinks on the target machine + +## Variations + +- **Auto-sync on login**: Add `skillshare pull && skillshare sync` to your shell profile (`.bashrc` / `.zshrc`) +- **Conflict resolution**: If two machines modify the same skill, `pull` uses git merge — resolve conflicts in the source directory +- **Selective sync**: Use the `ignore` field in `config.yaml` to exclude machine-specific skills from sync + +## Related + +- [Cross-machine sync guide](/docs/how-to/sharing/cross-machine-sync) +- [`push` command reference](/docs/reference/commands/push) +- [`pull` command reference](/docs/reference/commands/pull) diff --git a/website/docs/how-to/recipes/index.md b/website/docs/how-to/recipes/index.md new file mode 100644 index 000000000..3476b66de --- /dev/null +++ b/website/docs/how-to/recipes/index.md @@ -0,0 +1,19 @@ +--- +sidebar_position: 1 +--- + +# Recipes + +> Copy-paste solutions for common skillshare scenarios. + +Each recipe follows the same structure: **Scenario** (when/why), **Solution** (step-by-step), **Verification** (how to confirm), and **Variations** (alternatives). + +## Available Recipes + +| Recipe | Scenario | +|--------|----------| +| [CI/CD Skill Validation](ci-cd-skill-validation) | Audit + sync in GitHub Actions / GitLab CI | +| [Private Enterprise Skills](private-enterprise-skills) | Private repo install with token auth | +| [Project Mode Workflow](skill-per-project-workflow) | Full project-scoped skill lifecycle | +| [Cross-Machine Sync](cross-machine-sync-recipe) | Push/pull skills across machines | +| [Team Onboarding](team-onboarding-recipe) | New hire skill environment setup | diff --git a/website/docs/how-to/recipes/private-enterprise-skills.md b/website/docs/how-to/recipes/private-enterprise-skills.md new file mode 100644 index 000000000..0b3d17709 --- /dev/null +++ b/website/docs/how-to/recipes/private-enterprise-skills.md @@ -0,0 +1,79 @@ +--- +sidebar_position: 3 +--- + +# Recipe: Private Enterprise Skills + +> Install skills from private repositories using token authentication. + +## Scenario + +Your organization hosts internal skills in a private GitHub/GitLab repository. You need to install and update these skills without exposing credentials in config files. + +## Solution + +### Step 1: Set up authentication + +skillshare uses the same token resolution as `git`: + +```bash +# Option A: GitHub CLI (recommended) +gh auth login + +# Option B: Environment variable +export GITHUB_TOKEN=ghp_xxxxxxxxxxxxx + +# Option C: For Azure DevOps +export AZURE_DEVOPS_TOKEN=your-pat-here +``` + +### Step 2: Install from private repo + +```bash +skillshare install your-org/internal-skills +``` + +skillshare detects the token automatically from `gh auth token`, `GITHUB_TOKEN`, `GH_TOKEN`, or `AZURE_DEVOPS_TOKEN`. + +### Step 3: Verify tracking + +```bash +skillshare list +``` + +The installed repo appears with the `_` prefix (tracked repository): + +``` +_your-org__internal-skills/ +├── code-review/ +├── testing-standards/ +└── deployment-checklist/ +``` + +### Step 4: Update cycle + +```bash +skillshare check # Detect upstream changes +skillshare update # Pull latest +skillshare sync # Push to targets +``` + +## Verification + +- `skillshare list` shows the tracked repo +- `skillshare check` can reach the remote and compare hashes +- `skillshare sync` creates symlinks in all targets + +## Variations + +- **Selective install**: `skillshare install your-org/internal-skills --skill code-review` installs only one skill +- **CI/CD token**: In pipelines, use `GITHUB_TOKEN` from CI secrets +- **Self-hosted GitLab**: Use HTTPS URL directly: `skillshare install https://gitlab.internal.com/team/skills.git` +- **Gitee / AtomGit**: Supported via HTTPS URLs with token auth + +## Related + +- [`install` command reference](/docs/reference/commands/install) +- [`update` command reference](/docs/reference/commands/update) +- [Organization sharing guide](/docs/how-to/sharing/organization-sharing) +- [URL formats reference](/docs/reference/appendix/url-formats) diff --git a/website/docs/how-to/recipes/skill-per-project-workflow.md b/website/docs/how-to/recipes/skill-per-project-workflow.md new file mode 100644 index 000000000..9c66e44d5 --- /dev/null +++ b/website/docs/how-to/recipes/skill-per-project-workflow.md @@ -0,0 +1,80 @@ +--- +sidebar_position: 4 +--- + +# Recipe: Project Mode Workflow + +> Manage project-scoped skills that travel with your codebase. + +## Scenario + +You want specific skills committed to your project repository so that: +- Every contributor gets the same AI instructions +- Skills are versioned alongside the code +- No manual setup beyond cloning the repo + +## Solution + +### Step 1: Initialize project mode + +```bash +cd your-project +skillshare init -p +``` + +This creates `.skillshare/config.yaml` in your project root. + +### Step 2: Install project-scoped skills + +```bash +skillshare install anthropics/courses/prompt-eng -p +skillshare install your-org/team-skills --skill code-review -p +``` + +Skills are placed in `.skillshare/skills/`. + +### Step 3: Sync to project targets + +```bash +skillshare sync -p +``` + +This creates symlinks from `.skillshare/skills/` into project-level target directories (e.g., `.claude/skills/`, `.cursor/skills/`). + +### Step 4: Commit to version control + +```bash +git add .skillshare/ +git commit -m "Add project skills" +``` + +### Step 5: Teammate setup + +When a teammate clones the repo: + +```bash +git clone your-org/your-project +cd your-project +skillshare sync -p +``` + +One command syncs all project skills to their local AI tools. + +## Verification + +- `.skillshare/config.yaml` exists in project root +- `.skillshare/skills/` contains installed skills +- `skillshare list -p` shows project skills +- After `sync -p`, target directories contain symlinks + +## Variations + +- **Dev container auto-sync**: Add `skillshare sync -p` to `.devcontainer/devcontainer.json` `postCreateCommand` +- **Mixed mode**: Use global skills for personal preferences + project skills for team standards +- **CI validation**: Add `skillshare audit -p` to CI pipeline to validate project skills + +## Related + +- [Project setup guide](/docs/how-to/sharing/project-setup) +- [Understanding project skills](/docs/understand/project-skills) +- [Dev container guide](/docs/learn/with-devcontainer) diff --git a/website/docs/how-to/recipes/team-onboarding-recipe.md b/website/docs/how-to/recipes/team-onboarding-recipe.md new file mode 100644 index 000000000..113e1137f --- /dev/null +++ b/website/docs/how-to/recipes/team-onboarding-recipe.md @@ -0,0 +1,98 @@ +--- +sidebar_position: 6 +--- + +# Recipe: Team Onboarding + +> Set up a new team member's AI skill environment in under 5 minutes. + +## Scenario + +A new developer joins your team. They need: +- Organization-wide skills (coding standards, review guidelines) +- Project-specific skills (domain knowledge, architecture rules) +- Everything working across their AI tools (Claude Code, Cursor, etc.) + +## Solution + +### Step 1: Create an onboarding script + +Save as `scripts/setup-skills.sh` in your team wiki or repo: + +```bash +#!/bin/bash +set -e + +echo "Installing skillshare..." +curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh + +echo "Initializing..." +skillshare init + +echo "Installing organization skills..." +skillshare install your-org/org-skills + +echo "Running security audit..." +skillshare audit + +echo "Syncing to all AI tools..." +skillshare sync + +echo "Done! Run 'skillshare list' to see installed skills." +``` + +### Step 2: New hire runs the script + +```bash +curl -fsSL https://your-org.github.io/setup-skills.sh | sh +``` + +Or if the script is in the team repo: + +```bash +git clone your-org/team-tools +./team-tools/scripts/setup-skills.sh +``` + +### Step 3: Project-specific setup + +When the new hire clones a project: + +```bash +cd your-project +skillshare sync -p +``` + +This picks up project-scoped skills automatically. + +### Step 4: Verify everything works + +```bash +# Check global skills +skillshare list + +# Check project skills +skillshare list -p + +# Check sync status +skillshare status +``` + +## Verification + +- `skillshare list` shows organization skills +- `skillshare status` shows all targets are synced +- Opening Claude Code / Cursor shows skills are loaded + +## Variations + +- **Dev container onboarding**: If your team uses dev containers, add skillshare to `.devcontainer/Dockerfile` and `postCreateCommand` — skills are ready when the container starts +- **Homebrew-based install**: Replace `curl | sh` with `brew install skillshare` for macOS/Linux teams +- **Hub discovery**: Point new hires to your hub: `skillshare search --hub https://your-org.github.io/skillshare-hub.json` + +## Related + +- [Getting started guide](/docs/getting-started) +- [Organization sharing](/docs/how-to/sharing/organization-sharing) +- [Project setup](/docs/how-to/sharing/project-setup) +- [Dev container guide](/docs/learn/with-devcontainer) diff --git a/website/docs/guides/cross-machine-sync.md b/website/docs/how-to/sharing/cross-machine-sync.md similarity index 95% rename from website/docs/guides/cross-machine-sync.md rename to website/docs/how-to/sharing/cross-machine-sync.md index c83517f78..7cf680045 100644 --- a/website/docs/guides/cross-machine-sync.md +++ b/website/docs/how-to/sharing/cross-machine-sync.md @@ -297,8 +297,8 @@ skillshare sync ## See Also -- [push](/docs/commands/push) — Push to remote -- [pull](/docs/commands/pull) — Pull from remote -- [install](/docs/commands/install#install-from-config-no-arguments) — Install from config +- [push](/docs/reference/commands/push) — Push to remote +- [pull](/docs/reference/commands/pull) — Pull from remote +- [install](/docs/reference/commands/install#install-from-config-no-arguments) — Install from config - [Organization-Wide Skills](./organization-sharing.md) — Team sharing -- [init](/docs/commands/init) — Init with `--remote` +- [init](/docs/reference/commands/init) — Init with `--remote` diff --git a/website/docs/guides/hub-index.md b/website/docs/how-to/sharing/hub-index.md similarity index 97% rename from website/docs/guides/hub-index.md rename to website/docs/how-to/sharing/hub-index.md index 2606611bd..c59624d98 100644 --- a/website/docs/guides/hub-index.md +++ b/website/docs/how-to/sharing/hub-index.md @@ -324,6 +324,6 @@ Want to build an internal hub for your team? Fork the repo, replace the skills w ## See Also -- [search](/docs/commands/search) — Search skills from hubs -- [hub](/docs/commands/hub) — Manage hub sources -- [install](/docs/commands/install) — Install discovered skills +- [search](/docs/reference/commands/search) — Search skills from hubs +- [hub](/docs/reference/commands/hub) — Manage hub sources +- [install](/docs/reference/commands/install) — Install discovered skills diff --git a/website/docs/guides/organization-sharing.md b/website/docs/how-to/sharing/organization-sharing.md similarity index 92% rename from website/docs/guides/organization-sharing.md rename to website/docs/how-to/sharing/organization-sharing.md index 0a796966f..782da5d5a 100644 --- a/website/docs/guides/organization-sharing.md +++ b/website/docs/how-to/sharing/organization-sharing.md @@ -55,7 +55,7 @@ mkdir -p frontend/ui backend/api devops/deploy # Add skills echo "--- -name: acme:ui +name: acme-ui description: Frontend UI patterns --- # UI Skill @@ -140,7 +140,7 @@ _org-skills/ - AI CLIs see flat structure they expect - Flattened names preserve origin path for traceability -See [Tracked Repositories](/docs/concepts/tracked-repositories#nested-skills--auto-flattening) for details. +See [Tracked Repositories](/docs/understand/tracked-repositories#nested-skills--auto-flattening) for details. --- @@ -168,7 +168,7 @@ Rename one in SKILL.md or adjust include/exclude filters ```yaml # Option 1: Namespace in SKILL.md -name: team-a:ui +name: team-a-ui # Option 2: Route with filters (global config) targets: @@ -189,7 +189,7 @@ targets: include: [codex-*] ``` -See [Target Filters](/docs/targets/configuration#include--exclude-target-filters) for full syntax and examples. +See [Target Filters](/docs/reference/targets/configuration#include--exclude-target-filters) for full syntax and examples. --- @@ -275,7 +275,7 @@ install-skills: BITBUCKET_TOKEN: $BITBUCKET_TOKEN ``` -See [Environment Variables](/docs/reference/environment-variables#git-authentication) for all supported tokens. +See [Environment Variables](/docs/reference/appendix/environment-variables#git-authentication) for all supported tokens. --- @@ -314,7 +314,7 @@ Organization skills provide company-wide standards. Project skills provide repo- ### For Team Leads 1. **Use clear structure**: Organize by function (frontend, backend, devops) -2. **Namespace skills**: `org:skill-name` to avoid collisions +2. **Namespace skills**: `org-skill-name` to avoid collisions 3. **Document requirements**: README with setup instructions 4. **Version control**: Use tags for stable releases @@ -328,8 +328,8 @@ Organization skills provide company-wide standards. Project skills provide repo- ## See Also -- [Tracked Repositories](/docs/concepts/tracked-repositories) — Concept details -- [install](/docs/commands/install) — Install with `--track` -- [update](/docs/commands/update) — Update tracked repos +- [Tracked Repositories](/docs/understand/tracked-repositories) — Concept details +- [install](/docs/reference/commands/install) — Install with `--track` +- [update](/docs/reference/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/project-setup.md b/website/docs/how-to/sharing/project-setup.md similarity index 96% rename from website/docs/guides/project-setup.md rename to website/docs/how-to/sharing/project-setup.md index 301a4bb4c..19a48d710 100644 --- a/website/docs/guides/project-setup.md +++ b/website/docs/how-to/sharing/project-setup.md @@ -245,7 +245,7 @@ Each project gets its own context, while organization standards apply globally. ## See Also -- [Project Skills](/docs/concepts/project-skills) — Concept explanation -- [Project Workflow](/docs/workflows/project-workflow) — Day-to-day usage +- [Project Skills](/docs/understand/project-skills) — Concept explanation +- [Project Workflow](/docs/how-to/daily-tasks/project-workflow) — Day-to-day usage - [Organization-Wide Skills](./organization-sharing.md) — Team sharing -- [init](/docs/commands/init) — Init with `--project` +- [init](/docs/reference/commands/init) — Init with `--project` diff --git a/website/docs/intro.md b/website/docs/intro.md index 39f311669..6078870df 100644 --- a/website/docs/intro.md +++ b/website/docs/intro.md @@ -9,7 +9,7 @@ slug: / ## Why skillshare? -Install tools get skills onto agents. **Skillshare keeps them in sync.** +Install tools get skills onto agents. **skillshare keeps them in sync.** | | Install-once tools | skillshare | |---|-------------------|------------| @@ -42,7 +42,7 @@ skillshare sync Done. Your skills are now synced across all AI CLI tools. :::tip[Try without installing] -Want to explore first? Use the [Docker Playground](/docs/guides/docker-sandbox#playground) — one command, no local install needed: +Want to explore first? Use the [Docker Playground](/docs/how-to/advanced/docker-sandbox#playground) — one command, no local install needed: ```bash git clone https://github.com/runkids/skillshare.git && cd skillshare @@ -85,14 +85,14 @@ Edit in source → all targets update. Edit in target → changes go to source ( ### 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 +2. [Creating Skills](/docs/how-to/daily-tasks/creating-skills) — Write your first skill +3. [Cross-Machine Sync](/docs/how-to/sharing/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 +1. [Organization-Wide Skills](/docs/how-to/sharing/organization-sharing) — Share standards across the team +2. [Project Setup](/docs/how-to/sharing/project-setup) — Set up project-scoped skills +3. [Security Audit](/docs/reference/commands/audit) — Scan third-party skills before deployment ### Already Have Skills? @@ -100,7 +100,7 @@ Edit in source → all targets update. Edit in target → changes go to source ( ### Explore More -- [Core Concepts](/docs/concepts) — Source, targets, sync modes -- [Commands Reference](/docs/commands) — All available commands -- [Docker Sandbox](/docs/guides/docker-sandbox) — Try skillshare in an isolated environment +- [Core Concepts](/docs/understand) — Source, targets, sync modes +- [Commands Reference](/docs/reference/commands) — All available commands +- [Docker Sandbox](/docs/how-to/advanced/docker-sandbox) — Try skillshare in an isolated environment - [FAQ](/docs/troubleshooting/faq) — Common questions diff --git a/website/docs/learn/with-claude-code.md b/website/docs/learn/with-claude-code.md new file mode 100644 index 000000000..523e6f892 --- /dev/null +++ b/website/docs/learn/with-claude-code.md @@ -0,0 +1,62 @@ +--- +sidebar_position: 1 +--- + +# Using skillshare with Claude Code + +> From install to first sync — 5 minutes. + +## Prerequisites + +- [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) installed and working +- macOS, Linux, or Windows (WSL) + +## Step 1: Install skillshare + +```bash +curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh +``` + +## Step 2: Initialize + +```bash +skillshare init +``` + +This detects Claude Code's skill directory (`~/.claude/skills/`) and adds it as a target automatically. + +## Step 3: Install Your First Skill + +```bash +skillshare install anthropics/courses/prompt-eng +``` + +The skill is downloaded, audited for security, and added to your source directory. + +## Step 4: Sync + +```bash +skillshare sync +``` + +This creates symlinks from your source to `~/.claude/skills/`. Claude Code picks up the skills immediately — no restart needed. + +## Step 5: Verify + +```bash +ls ~/.claude/skills/ +``` + +You should see your installed skill symlinked. + +## Claude Code Integration Details + +- **Skill path**: `~/.claude/skills/` (global) or `.claude/skills/` (project) +- **CLAUDE.md**: skillshare skills use `SKILL.md` format, which Claude Code reads natively +- **Project mode**: Run `skillshare init -p` inside a repo to manage `.claude/skills/` per-project + +## What's Next? + +- [Manage multiple skills →](/docs/how-to/daily-tasks/organizing-skills) +- [Share with your team →](/docs/how-to/sharing/organization-sharing) +- [Explore more skills →](/docs/reference/commands/search) diff --git a/website/docs/learn/with-codex.md b/website/docs/learn/with-codex.md new file mode 100644 index 000000000..31b34c9e7 --- /dev/null +++ b/website/docs/learn/with-codex.md @@ -0,0 +1,60 @@ +--- +sidebar_position: 3 +--- + +# Using skillshare with Codex + +> From install to first sync — 5 minutes. + +## Prerequisites + +- [OpenAI Codex CLI](https://github.com/openai/codex) installed and working +- macOS, Linux, or Windows + +## Step 1: Install skillshare + +```bash +curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh +``` + +## Step 2: Initialize + +```bash +skillshare init +``` + +This detects Codex's skill directory (`~/.codex/skills/`) and adds it as a target automatically. + +## Step 3: Install Your First Skill + +```bash +skillshare install runkids/my-skills +``` + +## Step 4: Sync + +```bash +skillshare sync +``` + +Skills are symlinked to `~/.codex/skills/`. + +## Step 5: Verify + +```bash +ls ~/.codex/skills/ +``` + +You should see your installed skill symlinked. + +## Codex-Specific Notes + +- **Skill path**: `~/.codex/skills/` (global) or `.agents/skills/` (project) +- **Description limit**: Codex has a 1024-character limit on skill descriptions. Keep the `description` field in `SKILL.md` frontmatter concise +- **Project mode**: Run `skillshare init -p` to manage project-level Codex skills + +## What's Next? + +- [Manage multiple skills →](/docs/how-to/daily-tasks/organizing-skills) +- [Share with your team →](/docs/how-to/sharing/organization-sharing) +- [Explore more skills →](/docs/reference/commands/search) diff --git a/website/docs/learn/with-copilot.md b/website/docs/learn/with-copilot.md new file mode 100644 index 000000000..74d07993f --- /dev/null +++ b/website/docs/learn/with-copilot.md @@ -0,0 +1,79 @@ +--- +sidebar_position: 2 +--- + +# Using skillshare with GitHub Copilot + +> From install to first sync — 5 minutes. + +## Prerequisites + +- [GitHub Copilot](https://github.com/features/copilot) coding agent enabled in VS Code or JetBrains +- macOS, Linux, or Windows + +## Step 1: Install skillshare + +```bash +curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh +``` + +## Step 2: Initialize + +```bash +skillshare init +``` + +This detects Copilot's skill directory (`~/.copilot/skills/`) and adds it as a target automatically. + +## Step 3: Switch to Copy Mode (Recommended) + +We've received reports that Copilot sometimes fails to follow symlinks correctly. To avoid issues, switch the Copilot target to **copy mode**: + +```bash +skillshare target copilot --mode copy +``` + +Copy mode physically copies skill files into `~/.copilot/skills/` instead of creating symlinks. The trade-off is that source edits aren't reflected instantly — you need to run `skillshare sync` to propagate changes. But it's more reliable across platforms. + +:::tip When to use merge (symlink) mode +If you're on macOS or Linux and Copilot reads symlinks correctly on your machine, the default merge mode works fine. You can always switch back: + +```bash +skillshare target copilot --mode merge +``` +::: + +## Step 4: Install Your First Skill + +```bash +skillshare install runkids/my-skills +``` + +## Step 5: Sync + +```bash +skillshare sync +``` + +Skills are copied to `~/.copilot/skills/`. Copilot picks them up as custom instructions. + +## Step 6: Verify + +```bash +ls ~/.copilot/skills/ +``` + +You should see your installed skills as real directories (in copy mode) or symlinks (in merge mode). + +## Copilot-Specific Notes + +- **Skill path**: `~/.copilot/skills/` (global) or `.github/skills/` (project) +- **Project mode**: Run `skillshare init -p` to manage project-level Copilot skills — they go into `.github/skills/` alongside your codebase +- **Symlink issues**: If Copilot doesn't pick up your skills, check if your target is in merge mode (`skillshare status`) and switch to copy mode as described above +- **`.github/copilot-instructions.md`**: If you have an existing instructions file, skillshare skills complement it — they don't replace it + +## What's Next? + +- [Manage multiple skills →](/docs/how-to/daily-tasks/organizing-skills) +- [Share with your team →](/docs/how-to/sharing/organization-sharing) +- [Explore more skills →](/docs/reference/commands/search) diff --git a/website/docs/learn/with-devcontainer.md b/website/docs/learn/with-devcontainer.md new file mode 100644 index 000000000..3f2531b5c --- /dev/null +++ b/website/docs/learn/with-devcontainer.md @@ -0,0 +1,63 @@ +--- +sidebar_position: 5 +--- + +# Using skillshare in Dev Containers + +> Open in VS Code, skills are ready — no local install needed. + +## Prerequisites + +- [VS Code](https://code.visualstudio.com/) with [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) + +## How It Works + +VS Code Dev Containers let you develop inside a Docker container. You define the environment in `.devcontainer/`, and VS Code handles the rest — open the project, click "Reopen in Container", and everything is ready. + +skillshare fits naturally into this workflow. Add it to `postCreateCommand` and skills are installed and synced when the container starts. + +## Setup + +Add two things to your `.devcontainer/devcontainer.json`: + +```json +{ + "postCreateCommand": "curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh && skillshare init && skillshare sync" +} +``` + +That's it. When a team member opens the project in VS Code and clicks "Reopen in Container": + +1. skillshare is installed automatically +2. `init` detects AI CLIs in the container and sets up targets +3. `sync` delivers skills to all targets + +## Adding Project Skills + +For team-shared skills, commit a `.skillshare/` config to the repo: + +```bash +# Inside the container +skillshare init -p +skillshare install your-org/team-skills -p +``` + +Then commit and update `postCreateCommand` to also sync project skills: + +```json +{ + "postCreateCommand": "curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh && skillshare init && skillshare sync && skillshare sync -p" +} +``` + +Now every team member gets the same skills when they open the container. + +## GitHub Codespaces + +The same `.devcontainer/` config works in Codespaces with no changes. Codespaces runs `postCreateCommand` the same way VS Code does. + +## What's Next? + +- [Project skill setup →](/docs/how-to/sharing/project-setup) +- [Team sharing →](/docs/how-to/sharing/organization-sharing) +- [Sync modes explained →](/docs/understand/philosophy/sync-modes-explained) diff --git a/website/docs/learn/with-multiple-tools.md b/website/docs/learn/with-multiple-tools.md new file mode 100644 index 000000000..f4a36115c --- /dev/null +++ b/website/docs/learn/with-multiple-tools.md @@ -0,0 +1,81 @@ +--- +sidebar_position: 4 +--- + +# Using skillshare with Multiple AI Tools + +> One source of truth, synced to every AI CLI you use. + +## The Problem + +You use Claude Code at work, Cursor for side projects, and Codex for experiments. Each has its own skill directory. Keeping them in sync manually is tedious and error-prone. + +## The Solution + +skillshare maintains a single source directory and syncs to all your targets with one command. + +## Step 1: Install and Initialize + +```bash +curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh +skillshare init +``` + +`init` auto-detects all installed AI tools and adds them as targets. + +## Step 2: Check Your Targets + +```bash +skillshare target list +``` + +Example output: + +``` +TARGET MODE PATH +claude merge ~/.claude/skills +cursor merge ~/.cursor/skills +codex merge ~/.codex/skills +opencode merge ~/.opencode/skills +``` + +## Step 3: Install Skills + +```bash +skillshare install runkids/my-skills +skillshare install anthropics/courses/prompt-eng +``` + +## Step 4: Sync Everything + +```bash +skillshare sync +``` + +One command pushes all skills to every target. Each target gets symlinks pointing back to your single source. + +## Step 5: Verify + +```bash +skillshare status +``` + +Shows sync status across all targets — which skills are synced, missing, or out of date. + +## Per-Target Mode Control + +Different tools have different needs. You can set sync mode per target: + +```bash +# Cursor follows symlinks fine (default) +skillshare target cursor --mode merge + +# Some tools need real files +skillshare target opencode --mode copy +``` + +## What's Next? + +- [Understand sync modes →](/docs/understand/sync-modes) +- [Cross-machine sync →](/docs/how-to/sharing/cross-machine-sync) +- [Team sharing →](/docs/how-to/sharing/organization-sharing) diff --git a/website/docs/learn/with-playground.md b/website/docs/learn/with-playground.md new file mode 100644 index 000000000..c218e7c50 --- /dev/null +++ b/website/docs/learn/with-playground.md @@ -0,0 +1,114 @@ +--- +sidebar_position: 6 +--- + +# Try skillshare in the Playground + +> A pre-configured Docker sandbox with demo skills, audit rules, and a project — ready to explore in seconds. + +## Prerequisites + +- Docker and Docker Compose installed +- Clone the skillshare repo: `git clone https://github.com/runkids/skillshare.git` + +## Start the Playground + +```bash +cd skillshare +make playground +``` + +This single command: + +1. Builds the sandbox Docker image (Go toolchain included) +2. Compiles the `skillshare` binary inside the container +3. Initializes global mode with all targets auto-detected +4. Creates demo skills (clean, warning, critical) across categories +5. Sets up a demo project with project-level skills and custom audit rules +6. Drops you into an interactive shell — ready to explore + +## What's Inside + +### Demo Skills (Global) + +| Skill | Category | Audit Findings | +|-------|----------|----------------| +| `audit-demo-clean` | root | None (clean baseline) | +| `deploy-checklist` | `devops/` | None | +| `audit-demo-ci-release` | `security/` | HIGH + MEDIUM (sudo, external URLs) | +| `audit-demo-debug-exfil` | `security/` | CRITICAL (credential exfiltration) | +| `audit-demo-external-link` | `security/` | LOW (external URLs) | +| `audit-demo-dangling-link` | `security/` | LOW (broken local links) | + +### Demo Project (`~/demo-project`) + +A pre-configured `.skillshare/` project with: +- `hello-world` — clean project skill +- `demos/audit-demo-release` — release helper with audit warnings +- `guides/code-review` — nested code review guide +- Custom `audit-rules.yaml` with a TODO/FIXME policy rule + +### Custom Audit Rules + +Both global and project level `audit-rules.yaml` are pre-configured so you can see how rule customization works — enable/disable rules, add custom patterns, set allowlists. + +## Things to Try + +```bash +# Check what's installed +skillshare status +skillshare list + +# Run a security audit — see findings across severity levels +skillshare audit + +# Try project mode +cd ~/demo-project +skillshare status # auto-detects project mode +skillshare audit # project-level scan with custom rules + +# Launch the web dashboard (port 19420) +skillshare-ui # global mode +skillshare-ui-p # project mode + +# Explore nested skills +ls ~/.config/skillshare/skills/security/ +ls ~/.config/skillshare/skills/devops/ +``` + +## Bare Mode + +Start with a clean slate — no auto-init, no demo content: + +```bash +./scripts/sandbox_playground_up.sh --bare +./scripts/sandbox_playground_shell.sh +``` + +Useful for testing `skillshare init` from scratch. + +## Stop the Playground + +```bash +make playground-down +``` + +Data persists in a Docker volume (`playground-home`). Next `make playground` picks up where you left off. + +## Architecture + +The playground runs in a **read-only** Docker container with security hardening: + +- `read_only: true` — filesystem is immutable except for designated volumes +- `cap_drop: ALL` — no Linux capabilities +- `no-new-privileges` — prevents privilege escalation +- Writable volumes: `/sandbox-home` (persistent), `/tmp` (tmpfs, 256 MB) +- Port `19420` forwarded for the web dashboard + +The workspace is mounted read-only from the host repo — you can edit code on your machine and rebuild inside the container. + +## What's Next? + +- [Getting started →](/docs/getting-started) +- [Security audit guide →](/docs/how-to/advanced/security) +- [Docker sandbox guide →](/docs/how-to/advanced/docker-sandbox) diff --git a/website/docs/reference/environment-variables.md b/website/docs/reference/appendix/environment-variables.md similarity index 97% rename from website/docs/reference/environment-variables.md rename to website/docs/reference/appendix/environment-variables.md index 5e0a7990d..4eb9687c5 100644 --- a/website/docs/reference/environment-variables.md +++ b/website/docs/reference/appendix/environment-variables.md @@ -127,7 +127,7 @@ $env:GITHUB_TOKEN = "ghp_your_token" These variables enable HTTPS authentication for private repositories. When set, skillshare automatically injects the token during `install` and `update` — no URL modification needed. -See [Private Repositories](/docs/commands/install#private-repositories) for details and CI/CD examples. +See [Private Repositories](/docs/reference/commands/install#private-repositories) for details and CI/CD examples. ### GITLAB_TOKEN @@ -276,5 +276,5 @@ export GITHUB_TOKEN="ghp_your_token_here" ## Related -- [Configuration](/docs/targets/configuration) — Config file reference +- [Configuration](/docs/reference/targets/configuration) — Config file reference - [Windows Issues](/docs/troubleshooting/windows) — Windows environment setup diff --git a/website/docs/reference/file-structure.md b/website/docs/reference/appendix/file-structure.md similarity index 87% rename from website/docs/reference/file-structure.md rename to website/docs/reference/appendix/file-structure.md index d7f87560d..43b748095 100644 --- a/website/docs/reference/file-structure.md +++ b/website/docs/reference/appendix/file-structure.md @@ -11,6 +11,7 @@ Directory layout and file locations for skillshare. ``` ~/.config/skillshare/ # XDG_CONFIG_HOME ├── config.yaml # Configuration file +├── registry.yaml # Installed skill registry (auto-managed) ├── audit-rules.yaml # Custom audit rules (optional) └── skills/ # Source directory ├── my-skill/ # Regular skill @@ -84,15 +85,37 @@ targets: path: ~/.claude/skills cursor: path: ~/.cursor/skills -skills: # auto-managed by install/uninstall - - name: pdf - source: anthropics/skills/skills/pdf ignore: - "**/.DS_Store" - "**/.git/**" ``` -See [Configuration](/docs/targets/configuration) for full reference. +See [Configuration](/docs/reference/targets/configuration) for full reference. + +--- + +## Registry File + +### Location + +``` +~/.config/skillshare/registry.yaml +``` + +Stores metadata about installed and tracked skills. **Auto-managed** by `install`, `uninstall`, and `update` — don't edit manually. + +### Contents + +```yaml +# yaml-language-server: $schema=https://raw.githubusercontent.com/runkids/skillshare/main/schemas/registry.schema.json +skills: + - name: pdf + source: anthropics/skills/skills/pdf + - name: _team-skills + source: github.com/team/skills +``` + +Each entry records the skill name and its install source. Tracked repos (prefixed with `_`) include the full repository URL for `update` and `check` operations. --- @@ -145,7 +168,7 @@ description: Brief description Instructions for the AI... ``` -See [Skill Format](/docs/concepts/skill-format) for details. +See [Skill Format](/docs/understand/skill-format) for details. ### .skillignore (Optional, repo-level) @@ -332,6 +355,7 @@ See [Environment Variables](./environment-variables.md#xdg_config_home) for deta | Item | Path | |------|------| | Config | `~/.config/skillshare/config.yaml` | +| Registry | `~/.config/skillshare/registry.yaml` | | Source | `~/.config/skillshare/skills/` | | Backups | `~/.local/share/skillshare/backups/` | | Trash | `~/.local/share/skillshare/trash/` | @@ -345,6 +369,7 @@ See [Environment Variables](./environment-variables.md#xdg_config_home) for deta | Item | Path | |------|------| | Config | `%AppData%\skillshare\config.yaml` | +| Registry | `%AppData%\skillshare\registry.yaml` | | Source | `%AppData%\skillshare\skills\` | | Backups | `%AppData%\skillshare\backups\` | | Trash | `%AppData%\skillshare\trash\` | @@ -355,11 +380,11 @@ See [Environment Variables](./environment-variables.md#xdg_config_home) for deta ## XDG Base Directory Layout -Skillshare follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir/latest/) on Unix systems: +skillshare follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir/latest/) on Unix systems: -| XDG Variable | Default Path | Skillshare Uses For | +| XDG Variable | Default Path | skillshare Uses For | |-------------|-------------|---------------------| -| `XDG_CONFIG_HOME` | `~/.config` | `skillshare/config.yaml`, `skillshare/skills/` | +| `XDG_CONFIG_HOME` | `~/.config` | `skillshare/config.yaml`, `skillshare/registry.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) | @@ -381,6 +406,6 @@ If upgrading from a version before the XDG split, skillshare automatically migra ## Related -- [Configuration](/docs/targets/configuration) — Config file details -- [Skill Format](/docs/concepts/skill-format) — SKILL.md format -- [Tracked Repositories](/docs/concepts/tracked-repositories) — Tracked repos +- [Configuration](/docs/reference/targets/configuration) — Config file details +- [Skill Format](/docs/understand/skill-format) — SKILL.md format +- [Tracked Repositories](/docs/understand/tracked-repositories) — Tracked repos diff --git a/website/docs/reference/appendix/index.md b/website/docs/reference/appendix/index.md new file mode 100644 index 000000000..41e362f6b --- /dev/null +++ b/website/docs/reference/appendix/index.md @@ -0,0 +1,43 @@ +--- +sidebar_position: 1 +--- + +# Appendix + +Technical reference appendix for skillshare. + +## What are you looking for? + +| Topic | Read | +|-------|------| +| Environment variables that affect skillshare | [Environment Variables](/docs/reference/appendix/environment-variables) | +| Where skillshare stores config, skills, logs, cache | [File Structure](/docs/reference/appendix/file-structure) | +| Supported git URL formats | [URL Formats](/docs/reference/appendix/url-formats) | +| Config file format and options | [Configuration](/docs/reference/targets/configuration) | +| All CLI commands | [Commands](/docs/reference/commands) | + +## Quick Reference + +### Key Paths (Unix) + +| Path | Purpose | +|------|---------| +| `~/.config/skillshare/config.yaml` | Configuration file | +| `~/.config/skillshare/registry.yaml` | Installed skill registry (auto-managed) | +| `~/.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 + +| Variable | Purpose | +|----------|---------| +| `SKILLSHARE_CONFIG` | Override config path | +| `GITHUB_TOKEN` | GitHub API authentication | + +## See Also + +- [Configuration](/docs/reference/targets/configuration) — Config file details +- [Commands](/docs/reference/commands) — All commands diff --git a/website/docs/reference/url-formats.md b/website/docs/reference/appendix/url-formats.md similarity index 98% rename from website/docs/reference/url-formats.md rename to website/docs/reference/appendix/url-formats.md index ea80b06be..968f43df9 100644 --- a/website/docs/reference/url-formats.md +++ b/website/docs/reference/appendix/url-formats.md @@ -149,7 +149,7 @@ skillshare install https://github.com/company/private-repo ``` :::tip Private Repos -If you get an authentication error with HTTPS, switch to SSH URLs. Skillshare sets `GIT_TERMINAL_PROMPT=0` to prevent hanging credential prompts, so interactive HTTPS auth won't work. +If you get an authentication error with HTTPS, switch to SSH URLs. skillshare sets `GIT_TERMINAL_PROMPT=0` to prevent hanging credential prompts, so interactive HTTPS auth won't work. ::: ## Platform Support diff --git a/website/docs/commands/audit.md b/website/docs/reference/commands/audit.md similarity index 98% rename from website/docs/commands/audit.md rename to website/docs/reference/commands/audit.md index 25e5f5de7..d9fa278d1 100644 --- a/website/docs/commands/audit.md +++ b/website/docs/reference/commands/audit.md @@ -270,7 +270,7 @@ In other words, block decisions are **severity-threshold based**, while aggregat ### Blocking vs Risk: Decision Algorithms -Skillshare computes two related but independent decisions: +skillshare computes two related but independent decisions: 1. **Block decision (policy gate)** ```text @@ -358,7 +358,7 @@ If both are provided, `--skip-audit` effectively wins because audit is not execu ### Update-time -`skillshare update` runs a security audit after pulling tracked repos. Findings at or above the active threshold (`audit.block_threshold` by default, or `--audit-threshold` / `--threshold` / `-T` override) trigger rollback. See [`update --skip-audit`](/docs/commands/update#security-audit-gate) for details. +`skillshare update` runs a security audit after pulling tracked repos. Findings at or above the active threshold (`audit.block_threshold` by default, or `--audit-threshold` / `--threshold` / `-T` override) trigger rollback. See [`update --skip-audit`](/docs/reference/commands/update#security-audit-gate) for details. When updating tracked repos via install (`skillshare install --track --update`), the gate uses the same threshold policy (`audit.block_threshold` or `--audit-threshold` / `--threshold` / `-T`). @@ -773,8 +773,8 @@ Source of truth for regex-based rules: ## See Also -- [install](/docs/commands/install) — Install skills (with automatic scanning) -- [check](/docs/commands/check) — Verify skill integrity and sync status -- [doctor](/docs/commands/doctor) — Diagnose setup issues -- [list](/docs/commands/list) — List installed skills -- [Securing Your Skills](/docs/guides/security) — Security guide for teams and organizations +- [install](/docs/reference/commands/install) — Install skills (with automatic scanning) +- [check](/docs/reference/commands/check) — Verify skill integrity and sync status +- [doctor](/docs/reference/commands/doctor) — Diagnose setup issues +- [list](/docs/reference/commands/list) — List installed skills +- [Securing Your Skills](/docs/how-to/advanced/security) — Security guide for teams and organizations diff --git a/website/docs/commands/backup.md b/website/docs/reference/commands/backup.md similarity index 91% rename from website/docs/commands/backup.md rename to website/docs/reference/commands/backup.md index 15aad8ada..28f7f7437 100644 --- a/website/docs/commands/backup.md +++ b/website/docs/reference/commands/backup.md @@ -98,6 +98,6 @@ This means: ## See Also -- [restore](/docs/commands/restore) — Restore from backup -- [sync](/docs/commands/sync) — Auto-creates backups -- [target remove](/docs/commands/target) — Auto-creates backups +- [restore](/docs/reference/commands/restore) — Restore from backup +- [sync](/docs/reference/commands/sync) — Auto-creates backups +- [target remove](/docs/reference/commands/target) — Auto-creates backups diff --git a/website/docs/commands/check.md b/website/docs/reference/commands/check.md similarity index 96% rename from website/docs/commands/check.md rename to website/docs/reference/commands/check.md index 4fbcdd066..3e922f8e2 100644 --- a/website/docs/commands/check.md +++ b/website/docs/reference/commands/check.md @@ -166,6 +166,6 @@ skillshare check -p --json # JSON output for project ## See Also -- [update](/docs/commands/update) — Apply updates -- [list](/docs/commands/list) — View installed skills -- [status](/docs/commands/status) — Show sync status +- [update](/docs/reference/commands/update) — Apply updates +- [list](/docs/reference/commands/list) — View installed skills +- [status](/docs/reference/commands/status) — Show sync status diff --git a/website/docs/commands/collect.md b/website/docs/reference/commands/collect.md similarity index 90% rename from website/docs/commands/collect.md rename to website/docs/reference/commands/collect.md index 1365ddbd0..2b7d66bde 100644 --- a/website/docs/commands/collect.md +++ b/website/docs/reference/commands/collect.md @@ -92,6 +92,6 @@ skillshare push -m "Add my-new-skill" ## See Also -- [sync](/docs/commands/sync) — Sync from source to targets -- [diff](/docs/commands/diff) — See local-only skills -- [push](/docs/commands/push) — Push to git remote +- [sync](/docs/reference/commands/sync) — Sync from source to targets +- [diff](/docs/reference/commands/diff) — See local-only skills +- [push](/docs/reference/commands/push) — Push to git remote diff --git a/website/docs/commands/diff.md b/website/docs/reference/commands/diff.md similarity index 93% rename from website/docs/commands/diff.md rename to website/docs/reference/commands/diff.md index a61284adb..184606547 100644 --- a/website/docs/commands/diff.md +++ b/website/docs/reference/commands/diff.md @@ -105,6 +105,6 @@ skillshare sync # Fix it ## See Also -- [sync](/docs/commands/sync) — Sync to targets -- [collect](/docs/commands/collect) — Import local skills -- [status](/docs/commands/status) — Quick overview +- [sync](/docs/reference/commands/sync) — Sync to targets +- [collect](/docs/reference/commands/collect) — Import local skills +- [status](/docs/reference/commands/status) — Quick overview diff --git a/website/docs/commands/doctor.md b/website/docs/reference/commands/doctor.md similarity index 94% rename from website/docs/commands/doctor.md rename to website/docs/reference/commands/doctor.md index e13e12403..331db1d29 100644 --- a/website/docs/commands/doctor.md +++ b/website/docs/reference/commands/doctor.md @@ -72,7 +72,7 @@ For each target: ### Version - CLI version -- Skillshare skill version +- skillshare skill version - Checks for available updates ### Other @@ -177,6 +177,6 @@ Summary ## See Also -- [status](/docs/commands/status) — Quick status check -- [sync](/docs/commands/sync) — Fix sync issues -- [upgrade](/docs/commands/upgrade) — Update CLI and skill +- [status](/docs/reference/commands/status) — Quick status check +- [sync](/docs/reference/commands/sync) — Fix sync issues +- [upgrade](/docs/reference/commands/upgrade) — Update CLI and skill diff --git a/website/docs/commands/hub.md b/website/docs/reference/commands/hub.md similarity index 98% rename from website/docs/commands/hub.md rename to website/docs/reference/commands/hub.md index abde2c878..090b01d19 100644 --- a/website/docs/commands/hub.md +++ b/website/docs/reference/commands/hub.md @@ -206,7 +206,7 @@ A typical private hub workflow: 4. Teammates search → skillshare search --hub [path-or-url] ``` -For more details, see the [Hub Index Guide](../guides/hub-index.md). +For more details, see the [Hub Index Guide](/docs/how-to/sharing/hub-index). ## Config Format diff --git a/website/docs/commands/index.md b/website/docs/reference/commands/index.md similarity index 98% rename from website/docs/commands/index.md rename to website/docs/reference/commands/index.md index bc4d1c31c..3e794e855 100644 --- a/website/docs/commands/index.md +++ b/website/docs/reference/commands/index.md @@ -156,4 +156,4 @@ skillshare version ## Related - [Quick Reference](/docs/getting-started/quick-reference) — Command cheat sheet -- [Workflows](/docs/workflows) — Common usage patterns +- [Workflows](/docs/how-to/daily-tasks) — Common usage patterns diff --git a/website/docs/commands/init.md b/website/docs/reference/commands/init.md similarity index 98% rename from website/docs/commands/init.md rename to website/docs/reference/commands/init.md index 9479ff096..0fa532046 100644 --- a/website/docs/commands/init.md +++ b/website/docs/reference/commands/init.md @@ -53,7 +53,7 @@ flowchart TD TITLE --> S1 --> S2 --> S3 --> S4 ``` -After init, commit `.skillshare/` to git. See [Project Setup](/docs/guides/project-setup) for the full guide. +After init, commit `.skillshare/` to git. See [Project Setup](/docs/how-to/sharing/project-setup) for the full guide. ## Discover Mode diff --git a/website/docs/commands/install.md b/website/docs/reference/commands/install.md similarity index 95% rename from website/docs/commands/install.md rename to website/docs/reference/commands/install.md index 1b5259c32..9a4bc6bce 100644 --- a/website/docs/commands/install.md +++ b/website/docs/reference/commands/install.md @@ -177,7 +177,7 @@ skillshare sync Skills with `tracked: true` are cloned with full git history (same as `--track`), so `skillshare update` works correctly. Skills already present on disk are skipped. :::tip push/pull vs install from config -`push`/`pull` syncs actual skill **files** via git. `install` from config re-downloads from **source URLs**. They're complementary — see [Cross-Machine Sync](/docs/guides/cross-machine-sync#alternative-install-from-config) for when to use which. +`push`/`pull` syncs actual skill **files** via git. `install` from config re-downloads from **source URLs**. They're complementary — see [Cross-Machine Sync](/docs/how-to/sharing/cross-machine-sync#alternative-install-from-config) for when to use which. ::: When using no-arg install, `--name`, `--into`, `--track`, `--skill`, `--exclude`, `--all`, `--yes`, and `--update` are not supported (they require a source argument). `--dry-run`, `--force`, `--skip-audit`, and threshold overrides (`--audit-threshold` / `--threshold` / `-T`) work as expected. @@ -214,7 +214,7 @@ skillshare install github.com/team/skills --track -p skillshare sync ``` -See [Project Setup](/docs/guides/project-setup) for the full guide. +See [Project Setup](/docs/how-to/sharing/project-setup) for the full guide. ## Options @@ -282,7 +282,7 @@ skillshare install anthropics/skills -s pdf --into frontend/react # After sync, target shows flat name: frontend__my-skill, frontend__react__pdf ``` -See [Organizing Skills](/docs/guides/organizing-skills) for folder strategies. +See [Organizing Skills](/docs/how-to/daily-tasks/organizing-skills) for folder strategies. **Install team repo (tracked):** ```bash @@ -310,7 +310,7 @@ skillshare install git@github.com:org/skills.git//frontend-react ### HTTPS with Token -Set the appropriate environment variable and use a regular HTTPS URL. Skillshare automatically detects the token and injects it during clone: +Set the appropriate environment variable and use a regular HTTPS URL. skillshare automatically detects the token and injects it during clone: ```bash export GITHUB_TOKEN=ghp_your_token @@ -406,7 +406,7 @@ skillshare install suspicious-skill --threshold high skillshare install suspicious-skill -T h ``` -Use `--force` to override block decisions, or `--skip-audit` to bypass scanning entirely. See [audit](/docs/commands/audit) for scanning details. +Use `--force` to override block decisions, or `--skip-audit` to bypass scanning entirely. See [audit](/docs/reference/commands/audit) for scanning details. The install decision uses **finding severity vs threshold**. Risk score/label is reported for context and does not by itself block installs. By default, audit findings are shown as a compact summary (grouped by severity and message). Use `--audit-verbose` to see the full list. @@ -421,7 +421,7 @@ Tracked repos use the same threshold model, but the scan scope and failure handl Tracked repo updates through install (`skillshare install --track --update`) are audited after `git pull`: -- Skillshare captures a pre-pull commit hash first +- skillshare captures a pre-pull commit hash first - If hash capture fails, update aborts immediately (fail-closed) - If findings at/above threshold are detected, update is rolled back to the pre-pull commit - If rollback fails, command exits with a warning that malicious content may remain @@ -538,9 +538,9 @@ skillshare sync # ← Don't forget! ## See Also -- [list](/docs/commands/list) — View installed skills -- [update](/docs/commands/update) — Update skills or tracked repos -- [upgrade](/docs/commands/upgrade) — Upgrade CLI and built-in skill -- [uninstall](/docs/commands/uninstall) — Remove skills -- [sync](/docs/commands/sync) — Sync skills to targets -- [Organization-Wide Skills](/docs/guides/organization-sharing) — Organization sharing with tracked repos +- [list](/docs/reference/commands/list) — View installed skills +- [update](/docs/reference/commands/update) — Update skills or tracked repos +- [upgrade](/docs/reference/commands/upgrade) — Upgrade CLI and built-in skill +- [uninstall](/docs/reference/commands/uninstall) — Remove skills +- [sync](/docs/reference/commands/sync) — Sync skills to targets +- [Organization-Wide Skills](/docs/how-to/sharing/organization-sharing) — Organization sharing with tracked repos diff --git a/website/docs/commands/list.md b/website/docs/reference/commands/list.md similarity index 92% rename from website/docs/commands/list.md rename to website/docs/reference/commands/list.md index 3d2010d61..28c58a6ee 100644 --- a/website/docs/commands/list.md +++ b/website/docs/reference/commands/list.md @@ -116,7 +116,7 @@ Tracked repositories ## Global vs Project -Skillshare operates at two levels. The `list` command shows skills from the active level: +skillshare operates at two levels. The `list` command shows skills from the active level: ```mermaid flowchart TD @@ -205,7 +205,7 @@ Project list uses the same visual format as global list, with `(project)` label ## Directory Grouping -When skills are organized into folders (via [`--into`](/docs/commands/install) during install or manual `mv` + `sync`), `list` automatically groups them by directory: +When skills are organized into folders (via [`--into`](/docs/reference/commands/install) during install or manual `mv` + `sync`), `list` automatically groups them by directory: ``` frontend/ @@ -227,7 +227,7 @@ skillshare install owner/repo -s react-patterns --into frontend skillshare install owner/repo -s vue-patterns --into frontend ``` -For more details, see [Organizing Skills with Folders](/docs/guides/organizing-skills). +For more details, see [Organizing Skills with Folders](/docs/how-to/daily-tasks/organizing-skills). ## Understanding the Output @@ -248,6 +248,6 @@ For more details, see [Organizing Skills with Folders](/docs/guides/organizing-s ## See Also -- [install](/docs/commands/install) — Install skills -- [uninstall](/docs/commands/uninstall) — Remove skills -- [status](/docs/commands/status) — Show sync status +- [install](/docs/reference/commands/install) — Install skills +- [uninstall](/docs/reference/commands/uninstall) — Remove skills +- [status](/docs/reference/commands/status) — Show sync status diff --git a/website/docs/commands/log.md b/website/docs/reference/commands/log.md similarity index 96% rename from website/docs/commands/log.md rename to website/docs/reference/commands/log.md index 90496a25b..bc8891f85 100644 --- a/website/docs/commands/log.md +++ b/website/docs/reference/commands/log.md @@ -205,6 +205,6 @@ The Log page provides: ## See Also -- [audit](/docs/commands/audit) — Security scanning (logged to audit.log) -- [status](/docs/commands/status) — Show current sync state -- [doctor](/docs/commands/doctor) — Diagnose setup issues +- [audit](/docs/reference/commands/audit) — Security scanning (logged to audit.log) +- [status](/docs/reference/commands/status) — Show current sync state +- [doctor](/docs/reference/commands/doctor) — Diagnose setup issues diff --git a/website/docs/commands/new.md b/website/docs/reference/commands/new.md similarity index 95% rename from website/docs/commands/new.md rename to website/docs/reference/commands/new.md index 18fd24b12..1bc4508d5 100644 --- a/website/docs/commands/new.md +++ b/website/docs/reference/commands/new.md @@ -190,6 +190,6 @@ After creating a skill: ## See Also -- [install](/docs/commands/install) — Install skills from repos -- [sync](/docs/commands/sync) — Sync skills to targets -- [Configuration](/docs/targets/configuration) — Config reference +- [install](/docs/reference/commands/install) — Install skills from repos +- [sync](/docs/reference/commands/sync) — Sync skills to targets +- [Configuration](/docs/reference/targets/configuration) — Config reference diff --git a/website/docs/commands/pull.md b/website/docs/reference/commands/pull.md similarity index 92% rename from website/docs/commands/pull.md rename to website/docs/reference/commands/pull.md index eab69b67e..07402085a 100644 --- a/website/docs/commands/pull.md +++ b/website/docs/reference/commands/pull.md @@ -125,6 +125,6 @@ skillshare push -m "Add new skill" ## See Also -- [push](/docs/commands/push) — Push to remote -- [sync](/docs/commands/sync) — Manual sync without pull -- [Cross-Machine Sync](/docs/guides/cross-machine-sync) — Full setup +- [push](/docs/reference/commands/push) — Push to remote +- [sync](/docs/reference/commands/sync) — Manual sync without pull +- [Cross-Machine Sync](/docs/how-to/sharing/cross-machine-sync) — Full setup diff --git a/website/docs/commands/push.md b/website/docs/reference/commands/push.md similarity index 91% rename from website/docs/commands/push.md rename to website/docs/reference/commands/push.md index 805849348..5602a79e5 100644 --- a/website/docs/commands/push.md +++ b/website/docs/reference/commands/push.md @@ -106,6 +106,6 @@ skillshare pull # Gets changes and syncs ## See Also -- [pull](/docs/commands/pull) — Pull from remote -- [sync](/docs/commands/sync) — Sync to local targets -- [Cross-Machine Sync](/docs/guides/cross-machine-sync) — Full setup +- [pull](/docs/reference/commands/pull) — Pull from remote +- [sync](/docs/reference/commands/sync) — Sync to local targets +- [Cross-Machine Sync](/docs/how-to/sharing/cross-machine-sync) — Full setup diff --git a/website/docs/commands/restore.md b/website/docs/reference/commands/restore.md similarity index 94% rename from website/docs/commands/restore.md rename to website/docs/reference/commands/restore.md index ab472b8b2..994210f07 100644 --- a/website/docs/commands/restore.md +++ b/website/docs/reference/commands/restore.md @@ -112,5 +112,5 @@ skillshare sync # Return to current state ## See Also -- [backup](/docs/commands/backup) — Create and manage backups -- [sync](/docs/commands/sync) — Re-sync after restore +- [backup](/docs/reference/commands/backup) — Create and manage backups +- [sync](/docs/reference/commands/sync) — Re-sync after restore diff --git a/website/docs/commands/search.md b/website/docs/reference/commands/search.md similarity index 99% rename from website/docs/commands/search.md rename to website/docs/reference/commands/search.md index 2f046d0f3..d451d7056 100644 --- a/website/docs/commands/search.md +++ b/website/docs/reference/commands/search.md @@ -247,7 +247,7 @@ skillshare search --hub ./skillshare-hub.json # Search it `skillshare search --hub` (without a URL) defaults to the community [skillshare-hub](https://github.com/runkids/skillshare-hub) index, so you don't need to type the full URL every time. Or set your own default with `skillshare hub default