mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-19 02:17:09 +00:00
feat(website): complete website revamp — Diátaxis IA, blog, recipes, quickstarts
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)
This commit is contained in:
@@ -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 <name> --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
|
||||
|
||||
Executable
+90
@@ -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/"
|
||||
@@ -1,12 +0,0 @@
|
||||
---
|
||||
slug: first-blog-post
|
||||
title: First Blog Post
|
||||
authors: [slorber, yangshun]
|
||||
tags: [hola, docusaurus]
|
||||
---
|
||||
|
||||
Lorem ipsum dolor sit amet...
|
||||
|
||||
<!-- truncate -->
|
||||
|
||||
...consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
|
||||
@@ -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 `<!--` `truncate` `-->` comment to limit blog post size in the list view.
|
||||
|
||||
<!-- truncate -->
|
||||
|
||||
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
|
||||
@@ -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
|
||||
<button onClick={() => alert('button clicked!')}>Click me!</button>
|
||||
```
|
||||
|
||||
<button onClick={() => alert('button clicked!')}>Click me!</button>
|
||||
@@ -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.
|
||||
|
||||
<!-- truncate -->
|
||||
|
||||
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:
|
||||
|
||||

|
||||
|
||||
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.
|
||||
@@ -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.
|
||||
|
||||
<!-- truncate -->
|
||||
|
||||
## 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)
|
||||
@@ -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.
|
||||
|
||||
<!-- truncate -->
|
||||
|
||||
## 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)
|
||||
@@ -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.
|
||||
|
||||
<!-- truncate -->
|
||||
|
||||
## 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)
|
||||
@@ -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.
|
||||
|
||||
<!-- truncate -->
|
||||
|
||||
## 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 <repo> # 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)
|
||||
@@ -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.
|
||||
|
||||
<!-- truncate -->
|
||||
|
||||
## 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)
|
||||
@@ -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>
|
||||
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
|
||||
|
||||
@@ -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
|
||||
@@ -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 <name> --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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 |
|
||||
+1
-1
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
+4
-4
@@ -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 <commit-hash> -- 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
|
||||
+5
-5
@@ -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
|
||||
+6
-6
@@ -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 <repo>` 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 <repo>` 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
|
||||
+5
-5
@@ -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
|
||||
+5
-5
@@ -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
|
||||
+2
-2
@@ -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
|
||||
+3
-3
@@ -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
|
||||
@@ -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 |
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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 |
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
+4
-4
@@ -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`
|
||||
@@ -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
|
||||
+9
-9
@@ -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
|
||||
@@ -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`
|
||||
+10
-10
@@ -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
|
||||
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
+2
-2
@@ -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
|
||||
+36
-11
@@ -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
|
||||
@@ -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
|
||||
+1
-1
@@ -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
|
||||
@@ -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 <repo> --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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
@@ -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
|
||||
|
||||
@@ -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 <repo> --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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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 <label>`.
|
||||
:::
|
||||
|
||||
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).
|
||||
|
||||
## Tips
|
||||
|
||||
@@ -107,7 +107,7 @@ Project status does not show Tracked Repositories or Version sections (these are
|
||||
|
||||
## See Also
|
||||
|
||||
- [sync](/docs/commands/sync) — Sync skills to targets
|
||||
- [diff](/docs/commands/diff) — Show detailed differences
|
||||
- [doctor](/docs/commands/doctor) — Diagnose issues
|
||||
- [Project Skills](/docs/concepts/project-skills) — Project mode concepts
|
||||
- [sync](/docs/reference/commands/sync) — Sync skills to targets
|
||||
- [diff](/docs/reference/commands/diff) — Show detailed differences
|
||||
- [doctor](/docs/reference/commands/doctor) — Diagnose issues
|
||||
- [Project Skills](/docs/understand/project-skills) — Project mode concepts
|
||||
@@ -7,7 +7,7 @@ sidebar_position: 2
|
||||
Push skills from source to all targets.
|
||||
|
||||
:::info Why is sync a separate command?
|
||||
Operations like `install` and `uninstall` only modify source — sync propagates to targets. This lets you batch changes, preview with `--dry-run`, and control when targets update. See [Why Sync is a Separate Step](/docs/concepts/source-and-targets#why-sync-is-a-separate-step).
|
||||
Operations like `install` and `uninstall` only modify source — sync propagates to targets. This lets you batch changes, preview with `--dry-run`, and control when targets update. See [Why Sync is a Separate Step](/docs/understand/source-and-targets#why-sync-is-a-separate-step).
|
||||
:::
|
||||
|
||||
## When to Use
|
||||
@@ -213,7 +213,7 @@ When `sync` prints a compatibility hint, the example target is chosen in this pr
|
||||
`cursor` → `antigravity` → `copilot` → `opencode`.
|
||||
If none of these targets exist (or they already run `copy`), no compatibility hint is shown.
|
||||
|
||||
See [Sync Modes](/docs/concepts/sync-modes) for a neutral decision matrix.
|
||||
See [Sync Modes](/docs/understand/sync-modes) for a neutral decision matrix.
|
||||
|
||||
### Per-target include/exclude filters
|
||||
|
||||
@@ -236,7 +236,7 @@ targets:
|
||||
- In copy mode, filters work the same way as merge mode
|
||||
- `sync` removes existing source-linked or managed entries that are now excluded
|
||||
|
||||
See [Configuration](/docs/targets/configuration#include--exclude-target-filters) for full details.
|
||||
See [Configuration](/docs/reference/targets/configuration#include--exclude-target-filters) for full details.
|
||||
|
||||
### Filter behavior examples
|
||||
|
||||
@@ -414,8 +414,8 @@ flowchart TD
|
||||
|
||||
## See Also
|
||||
|
||||
- [status](/docs/commands/status) — Show sync state
|
||||
- [diff](/docs/commands/diff) — Show differences
|
||||
- [Targets](/docs/targets) — Manage targets
|
||||
- [Cross-Machine Sync](/docs/guides/cross-machine-sync) — Sync across computers
|
||||
- [install](/docs/commands/install) — Install skills
|
||||
- [status](/docs/reference/commands/status) — Show sync state
|
||||
- [diff](/docs/reference/commands/diff) — Show differences
|
||||
- [Targets](/docs/reference/targets) — Manage targets
|
||||
- [Cross-Machine Sync](/docs/how-to/sharing/cross-machine-sync) — Sync across computers
|
||||
- [install](/docs/reference/commands/install) — Install skills
|
||||
@@ -131,7 +131,7 @@ After changing filters, run `skillshare sync` to apply.
|
||||
|
||||
Filters work in **merge and copy modes**. Patterns use Go `filepath.Match` syntax (`*`, `?`, `[...]`). In symlink mode, filters are ignored.
|
||||
|
||||
See [Configuration](/docs/targets/configuration#include--exclude-target-filters) for pattern cheat sheet and scenarios.
|
||||
See [Configuration](/docs/reference/targets/configuration#include--exclude-target-filters) for pattern cheat sheet and scenarios.
|
||||
|
||||
## Options
|
||||
|
||||
@@ -158,7 +158,7 @@ No additional options.
|
||||
|
||||
## Supported AI CLIs
|
||||
|
||||
Skillshare auto-detects these during `init`:
|
||||
skillshare auto-detects these during `init`:
|
||||
|
||||
| CLI | Default Path |
|
||||
|-----|-------------|
|
||||
@@ -169,7 +169,7 @@ Skillshare auto-detects these during `init`:
|
||||
| Codex | `~/.openai-codex/skills` |
|
||||
| Gemini CLI | `~/.gemini/skills` |
|
||||
| Amp | `~/.amp/skills` |
|
||||
| ... and 45+ more | See [supported targets](/docs/targets/supported-targets) |
|
||||
| ... and 45+ more | See [supported targets](/docs/reference/targets/supported-targets) |
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -235,7 +235,7 @@ Targets in project mode support:
|
||||
|
||||
## See Also
|
||||
|
||||
- [sync](/docs/commands/sync) — Sync skills to targets
|
||||
- [status](/docs/commands/status) — Show target status
|
||||
- [Targets](/docs/targets) — Target management guide
|
||||
- [Project Skills](/docs/concepts/project-skills) — Project mode concepts
|
||||
- [sync](/docs/reference/commands/sync) — Sync skills to targets
|
||||
- [status](/docs/reference/commands/status) — Show target status
|
||||
- [Targets](/docs/reference/targets) — Target management guide
|
||||
- [Project Skills](/docs/understand/project-skills) — Project mode concepts
|
||||
@@ -107,6 +107,6 @@ Expired trash items (older than 7 days) are automatically cleaned up when you ru
|
||||
|
||||
## See Also
|
||||
|
||||
- [uninstall](/docs/commands/uninstall) — Remove skills (moves to trash)
|
||||
- [backup](/docs/commands/backup) — Backup target directories
|
||||
- [restore](/docs/commands/restore) — Restore targets from backup
|
||||
- [uninstall](/docs/reference/commands/uninstall) — Remove skills (moves to trash)
|
||||
- [backup](/docs/reference/commands/backup) — Backup target directories
|
||||
- [restore](/docs/reference/commands/restore) — Restore targets from backup
|
||||
@@ -179,7 +179,7 @@ skillshare ui
|
||||
|
||||
## See Also
|
||||
|
||||
- [status](/docs/commands/status) — CLI status check
|
||||
- [sync](/docs/commands/sync) — CLI sync command
|
||||
- [Project Setup](/docs/guides/project-setup) — Project mode setup guide
|
||||
- [Docker Sandbox](/docs/guides/docker-sandbox) — Run UI in Docker
|
||||
- [status](/docs/reference/commands/status) — CLI status check
|
||||
- [sync](/docs/reference/commands/sync) — CLI sync command
|
||||
- [Project Setup](/docs/how-to/sharing/project-setup) — Project mode setup guide
|
||||
- [Docker Sandbox](/docs/how-to/advanced/docker-sandbox) — Run UI in Docker
|
||||
@@ -69,7 +69,7 @@ skillshare uninstall --all -n # Preview what would be removed
|
||||
`--all` cannot be combined with skill names or `--group`.
|
||||
|
||||
:::tip Shell glob protection
|
||||
Running `skillshare uninstall *` without quotes causes your shell to expand `*` into file names in the current directory. Skillshare detects this and suggests using `--all` instead. Always quote the wildcard (`"*"`) or use `--all`.
|
||||
Running `skillshare uninstall *` without quotes causes your shell to expand `*` into file names in the current directory. skillshare detects this and suggests using `--all` instead. Always quote the wildcard (`"*"`) or use `--all`.
|
||||
:::
|
||||
|
||||
## Group Removal
|
||||
@@ -251,7 +251,7 @@ git add .skillshare/ && git commit -m "Remove pdf skill"
|
||||
|
||||
## See Also
|
||||
|
||||
- [install](/docs/commands/install) — Install skills
|
||||
- [list](/docs/commands/list) — List installed skills
|
||||
- [trash](/docs/commands/trash) — Manage trashed skills
|
||||
- [Project Skills](/docs/concepts/project-skills) — Project mode concepts
|
||||
- [install](/docs/reference/commands/install) — Install skills
|
||||
- [list](/docs/reference/commands/list) — List installed skills
|
||||
- [trash](/docs/reference/commands/trash) — Manage trashed skills
|
||||
- [Project Skills](/docs/understand/project-skills) — Project mode concepts
|
||||
@@ -311,7 +311,7 @@ git add .skillshare/ && git commit -m "Update remote skills"
|
||||
|
||||
## See Also
|
||||
|
||||
- [install](/docs/commands/install) — Install skills
|
||||
- [upgrade](/docs/commands/upgrade) — Upgrade CLI and built-in skill
|
||||
- [sync](/docs/commands/sync) — Sync to targets
|
||||
- [Project Skills](/docs/concepts/project-skills) — Project mode concepts
|
||||
- [install](/docs/reference/commands/install) — Install skills
|
||||
- [upgrade](/docs/reference/commands/upgrade) — Upgrade CLI and built-in skill
|
||||
- [sync](/docs/reference/commands/sync) — Sync to targets
|
||||
- [Project Skills](/docs/understand/project-skills) — Project mode concepts
|
||||
@@ -95,7 +95,7 @@ After upgrading, skillshare pre-downloads the Web UI frontend assets for the new
|
||||
|
||||
If the pre-download fails (e.g. network issues), the assets will be downloaded on the next `skillshare ui` launch instead.
|
||||
|
||||
### Skillshare Skill
|
||||
### skillshare Skill
|
||||
|
||||
The built-in `skillshare` skill that adds the `/skillshare` command to AI CLIs. Located at:
|
||||
```
|
||||
@@ -104,6 +104,6 @@ The built-in `skillshare` skill that adds the `/skillshare` command to AI CLIs.
|
||||
|
||||
## See Also
|
||||
|
||||
- [update](/docs/commands/update) — Update other skills and repos
|
||||
- [status](/docs/commands/status) — Check current versions
|
||||
- [doctor](/docs/commands/doctor) — Diagnose issues
|
||||
- [update](/docs/reference/commands/update) — Update other skills and repos
|
||||
- [status](/docs/reference/commands/status) — Check current versions
|
||||
- [doctor](/docs/reference/commands/doctor) — Diagnose issues
|
||||
@@ -6,36 +6,17 @@ sidebar_position: 1
|
||||
|
||||
Technical reference documentation for skillshare.
|
||||
|
||||
## What are you looking for?
|
||||
## Sections
|
||||
|
||||
| Topic | Read |
|
||||
|-------|------|
|
||||
| Environment variables that affect skillshare | [Environment Variables](./environment-variables.md) |
|
||||
| Where skillshare stores config, skills, logs, cache | [File Structure](./file-structure.md) |
|
||||
| Config file format and options | [Configuration](/docs/targets/configuration) |
|
||||
| All CLI commands | [Commands](/docs/commands) |
|
||||
| Section | Description |
|
||||
|---------|-------------|
|
||||
| [Commands](/docs/reference/commands) | All CLI commands with usage, flags, and examples |
|
||||
| [Targets](/docs/reference/targets) | Supported AI tools and target configuration |
|
||||
| [Appendix](/docs/reference/appendix) | Environment variables, file structure, URL formats |
|
||||
|
||||
## Quick Reference
|
||||
## Quick Links
|
||||
|
||||
### Key Paths (Unix)
|
||||
|
||||
| Path | Purpose |
|
||||
|------|---------|
|
||||
| `~/.config/skillshare/config.yaml` | Configuration file |
|
||||
| `~/.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/targets/configuration) — Config file details
|
||||
- [Commands](/docs/commands) — All commands
|
||||
- [Configuration](/docs/reference/targets/configuration) — Config file format and options
|
||||
- [Environment Variables](/docs/reference/appendix/environment-variables) — Variables that affect skillshare
|
||||
- [File Structure](/docs/reference/appendix/file-structure) — Where skillshare stores config, skills, logs, cache
|
||||
- [URL Formats](/docs/reference/appendix/url-formats) — Supported git URL formats
|
||||
|
||||
+2
-2
@@ -116,7 +116,7 @@ skillshare target myapp --mode symlink
|
||||
skillshare sync
|
||||
```
|
||||
|
||||
See [Sync Modes](/docs/concepts/sync-modes) for details.
|
||||
See [Sync Modes](/docs/understand/sync-modes) for details.
|
||||
|
||||
---
|
||||
|
||||
@@ -170,4 +170,4 @@ skillshare target add myapp /correct/path/skills
|
||||
|
||||
- [Supported Targets](./supported-targets.md) — Built-in targets
|
||||
- [Configuration](./configuration.md) — Edit config directly
|
||||
- [Sync Modes](/docs/concepts/sync-modes) — Merge, copy, symlink
|
||||
- [Sync Modes](/docs/understand/sync-modes) — Merge, copy, symlink
|
||||
+6
-6
@@ -269,7 +269,7 @@ skillshare sync # Apply changes
|
||||
|
||||
Duplicate patterns are silently ignored. Invalid glob patterns return an error.
|
||||
|
||||
See [target command](/docs/commands/target#target-filters-includeexclude) for full reference.
|
||||
See [target command](/docs/reference/commands/target#target-filters-includeexclude) for full reference.
|
||||
|
||||
#### Skill-level targets {#skill-level-targets}
|
||||
|
||||
@@ -302,7 +302,7 @@ Source Skills
|
||||
|
||||
Both layers must pass (AND relationship). Config filters always take priority — even if a skill declares `targets: [claude]`, a config `exclude: [claude-*]` will still exclude it.
|
||||
|
||||
**Cross-mode matching:** `targets: [claude]` matches both the global target `claude` and the project target `claude`, because they refer to the same AI CLI. See [supported targets](/docs/targets/supported-targets).
|
||||
**Cross-mode matching:** `targets: [claude]` matches both the global target `claude` and the project target `claude`, because they refer to the same AI CLI. See [supported targets](/docs/reference/targets/supported-targets).
|
||||
|
||||
:::tip
|
||||
Use config filters (`include`/`exclude`) when the **consumer** wants to control what goes where. Use skill-level `targets` when the **author** knows the skill only works with specific AI CLIs.
|
||||
@@ -497,7 +497,7 @@ skillshare audit --init-rules # Global
|
||||
skillshare audit --init-rules -p # Project
|
||||
```
|
||||
|
||||
See [audit command](/docs/commands/audit) for full details.
|
||||
See [audit command](/docs/reference/commands/audit) for full details.
|
||||
|
||||
---
|
||||
|
||||
@@ -573,6 +573,6 @@ Uses NTFS junctions (no admin required).
|
||||
|
||||
## Related
|
||||
|
||||
- [Source & Targets](/docs/concepts/source-and-targets) — Core concepts
|
||||
- [Sync Modes](/docs/concepts/sync-modes) — Merge vs copy vs symlink
|
||||
- [Environment Variables](/docs/reference/environment-variables) — All variables
|
||||
- [Source & Targets](/docs/understand/source-and-targets) — Core concepts
|
||||
- [Sync Modes](/docs/understand/sync-modes) — Merge vs copy vs symlink
|
||||
- [Environment Variables](/docs/reference/appendix/environment-variables) — All variables
|
||||
@@ -88,6 +88,6 @@ Only paths that exist are added. See [Supported Targets](./supported-targets.md)
|
||||
|
||||
## Related
|
||||
|
||||
- [Source & Targets](/docs/concepts/source-and-targets) — Core concepts
|
||||
- [Sync Modes](/docs/concepts/sync-modes) — Merge, copy, symlink
|
||||
- [Commands: target](/docs/commands/target) — Target command details
|
||||
- [Source & Targets](/docs/understand/source-and-targets) — Core concepts
|
||||
- [Sync Modes](/docs/understand/sync-modes) — Merge, copy, symlink
|
||||
- [Commands: target](/docs/reference/commands/target) — Target command details
|
||||
+2
-2
@@ -8,7 +8,7 @@ Complete list of AI CLIs that skillshare supports out of the box.
|
||||
|
||||
## Overview
|
||||
|
||||
Skillshare supports **49+ AI CLI tools**. When you run `skillshare init`, it automatically detects and configures any installed tools.
|
||||
skillshare supports **49+ AI CLI tools**. When you run `skillshare init`, it automatically detects and configures any installed tools.
|
||||
|
||||
---
|
||||
|
||||
@@ -176,4 +176,4 @@ See [Adding Custom Targets](./adding-custom-targets.md) for details.
|
||||
|
||||
- [Adding Custom Targets](./adding-custom-targets.md) — Add unsupported tools
|
||||
- [Configuration](./configuration.md) — Config file reference
|
||||
- [Commands: target](/docs/commands/target) — Target command
|
||||
- [Commands: target](/docs/reference/commands/target) — Target command
|
||||
@@ -151,7 +151,7 @@ skillshare sync
|
||||
|
||||
### `Git identity not configured`
|
||||
|
||||
**Cause:** No `user.name` / `user.email` in git config. Skillshare uses a local fallback (`skillshare@local`) so init can complete, but you should set your own.
|
||||
**Cause:** No `user.name` / `user.email` in git config. skillshare uses a local fallback (`skillshare@local`) so init can complete, but you should set your own.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
@@ -227,7 +227,7 @@ git credential approve # or platform-specific credential manager
|
||||
Only **Personal Access Token** (`glpat-`) works for git operations. Feed Tokens (`glft-`) do **not** have git access.
|
||||
:::
|
||||
|
||||
See [Environment Variables](/docs/reference/environment-variables#git-authentication) and [Private Repositories](/docs/commands/install#private-repositories).
|
||||
See [Environment Variables](/docs/reference/appendix/environment-variables#git-authentication) and [Private Repositories](/docs/reference/commands/install#private-repositories).
|
||||
|
||||
### `invalid skill: SKILL.md not found`
|
||||
|
||||
@@ -307,7 +307,7 @@ skillshare doctor
|
||||
**Solution:** Rename one in SKILL.md or use `include`/`exclude` filters to route them to different targets:
|
||||
```yaml
|
||||
# Option 1: Namespace in SKILL.md
|
||||
name: team-a:skill-name
|
||||
name: team-a-skill-name
|
||||
|
||||
# Option 2: Route with filters (global config)
|
||||
targets:
|
||||
@@ -328,7 +328,7 @@ targets:
|
||||
|
||||
:::tip
|
||||
If filters already isolate the duplicates, sync shows an info message instead of a warning — no action needed.
|
||||
See [Target Filters](/docs/targets/configuration#include--exclude-target-filters) for full syntax.
|
||||
See [Target Filters](/docs/reference/targets/configuration#include--exclude-target-filters) for full syntax.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
@@ -71,7 +71,7 @@ This lets you:
|
||||
|
||||
**Note:** `pull` is the only command that auto-syncs, because its intent is "bring everything up to date."
|
||||
|
||||
See [Why Sync is a Separate Step](/docs/concepts/source-and-targets#why-sync-is-a-separate-step) for the full design rationale.
|
||||
See [Why Sync is a Separate Step](/docs/understand/source-and-targets#why-sync-is-a-separate-step) for the full design rationale.
|
||||
|
||||
### How do I sync across multiple machines?
|
||||
|
||||
@@ -85,7 +85,7 @@ skillshare push -m "Add new skill"
|
||||
skillshare pull
|
||||
```
|
||||
|
||||
See [Cross-Machine Sync](/docs/guides/cross-machine-sync) for full setup.
|
||||
See [Cross-Machine Sync](/docs/how-to/sharing/cross-machine-sync) for full setup.
|
||||
|
||||
### What if I accidentally delete a skill through a symlink?
|
||||
|
||||
@@ -176,7 +176,7 @@ targets:
|
||||
include: [skill-b, skill-c]
|
||||
```
|
||||
|
||||
Both approaches can be combined — config filters are applied first, then the skill-level `targets` field. See [Skill Format — `targets`](/docs/concepts/skill-format#targets) and [Configuration — filters](/docs/targets/configuration#skill-level-targets).
|
||||
Both approaches can be combined — config filters are applied first, then the skill-level `targets` field. See [Skill Format — `targets`](/docs/understand/skill-format#targets) and [Configuration — filters](/docs/reference/targets/configuration#skill-level-targets).
|
||||
|
||||
---
|
||||
|
||||
@@ -256,7 +256,7 @@ description: Brief description
|
||||
Instructions for the AI...
|
||||
```
|
||||
|
||||
See [Skill Format](/docs/concepts/skill-format) for full details.
|
||||
See [Skill Format](/docs/understand/skill-format) for full details.
|
||||
|
||||
### What does "unknown target" warning mean?
|
||||
|
||||
@@ -282,7 +282,7 @@ description: Works everywhere
|
||||
1. **Ignore the warning** — the skill still installs, it just won't auto-filter to specific targets
|
||||
2. **Fork and fix** — Remove or correct the `targets` field in the skill's `SKILL.md`
|
||||
|
||||
See [Skill Format — `targets`](/docs/concepts/skill-format#targets) for the full specification.
|
||||
See [Skill Format — `targets`](/docs/understand/skill-format#targets) for the full specification.
|
||||
|
||||
### Can a skill have multiple files?
|
||||
|
||||
@@ -347,7 +347,7 @@ Skills are instructions for your AI agent — a malicious skill could tell the A
|
||||
- **CRITICAL findings block** — Prompt injection, data exfiltration, credential access are blocked by default
|
||||
- **Manual scan** — Run `skillshare audit` to scan all installed skills at any time
|
||||
|
||||
See [audit command](/docs/commands/audit) for the full list of detection patterns.
|
||||
See [audit command](/docs/reference/commands/audit) for the full list of detection patterns.
|
||||
|
||||
### What if audit blocks my install?
|
||||
|
||||
|
||||
@@ -86,4 +86,4 @@ If you can't resolve the issue:
|
||||
## Related
|
||||
|
||||
- [Troubleshooting Workflow](./troubleshooting-workflow.md) — Step-by-step debugging
|
||||
- [Commands: doctor](/docs/commands/doctor) — Doctor command details
|
||||
- [Commands: doctor](/docs/reference/commands/doctor) — Doctor command details
|
||||
|
||||
@@ -183,4 +183,4 @@ If you can't resolve the issue:
|
||||
- [Common Errors](/docs/troubleshooting/common-errors) — Error messages and solutions
|
||||
- [Windows Issues](/docs/troubleshooting/windows) — Windows-specific problems
|
||||
- [FAQ](/docs/troubleshooting/faq) — Frequently asked questions
|
||||
- [Commands: doctor](/docs/commands/doctor) — Doctor command
|
||||
- [Commands: doctor](/docs/reference/commands/doctor) — Doctor command
|
||||
|
||||
@@ -26,7 +26,7 @@ irm https://raw.githubusercontent.com/runkids/skillshare/main/install.ps1 | iex
|
||||
|
||||
### Does skillshare need admin privileges?
|
||||
|
||||
**No.** Skillshare uses NTFS junctions instead of symlinks, which don't require admin privileges.
|
||||
**No.** skillshare uses NTFS junctions instead of symlinks, which don't require admin privileges.
|
||||
|
||||
NTFS junctions work like symlinks for directories but are available to all users.
|
||||
|
||||
@@ -121,7 +121,7 @@ Then restart.
|
||||
|
||||
**Cause:** You're seeing symlinks instead of junctions.
|
||||
|
||||
**Note:** Skillshare uses NTFS junctions on Windows, not symlinks. If you see symlink errors, ensure you're using the Windows version of skillshare.
|
||||
**Note:** skillshare uses NTFS junctions on Windows, not symlinks. If you see symlink errors, ensure you're using the Windows version of skillshare.
|
||||
|
||||
---
|
||||
|
||||
@@ -139,7 +139,7 @@ function ssl { skillshare pull }
|
||||
|
||||
### Check PowerShell version
|
||||
|
||||
Skillshare works with PowerShell 5.1+ and PowerShell Core 7+:
|
||||
skillshare works with PowerShell 5.1+ and PowerShell Core 7+:
|
||||
```powershell
|
||||
$PSVersionTable.PSVersion
|
||||
```
|
||||
@@ -182,4 +182,4 @@ Include in bug reports:
|
||||
## Related
|
||||
|
||||
- [Common Errors](./common-errors.md) — General error solutions
|
||||
- [Configuration](/docs/targets/configuration) — Config file reference
|
||||
- [Configuration](/docs/reference/targets/configuration) — Config file reference
|
||||
|
||||
+2
-2
@@ -136,6 +136,6 @@ Contributors clone and run `skillshare install -p` to get project-specific AI co
|
||||
|
||||
## Related
|
||||
|
||||
- [Install command](../commands/install.md) — `skillshare install` with and without arguments
|
||||
- [Push/Pull](../commands/push.md) — backup and restore config via git
|
||||
- [Install command](/docs/reference/commands/install) — `skillshare install` with and without arguments
|
||||
- [Push/Pull](/docs/reference/commands/push) — backup and restore config via git
|
||||
- [Project Skills](./project-skills.md) — project-level manifests
|
||||
@@ -2,7 +2,7 @@
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Core Concepts
|
||||
# Understand
|
||||
|
||||
Understanding these concepts helps you get the most out of skillshare.
|
||||
|
||||
@@ -45,7 +45,7 @@ flowchart LR
|
||||
| **Tracked Repos** | Git repos installed with `--track` | [→ Tracked Repositories](./tracked-repositories.md) |
|
||||
| **Skill Format** | SKILL.md structure and metadata | [→ Skill Format](./skill-format.md) |
|
||||
| **Project Skills** | Project-level skills scoped to a repository | [→ Project Skills](./project-skills.md) |
|
||||
| **Organization Skills** | Organization-wide skills via tracked repositories | [→ Organization-Wide Skills](/docs/guides/organization-sharing) |
|
||||
| **Organization Skills** | Organization-wide skills via tracked repositories | [→ Organization-Wide Skills](/docs/how-to/sharing/organization-sharing) |
|
||||
|
||||
---
|
||||
|
||||
@@ -78,3 +78,17 @@ flowchart LR
|
||||
- Shared across all projects via tracked repositories (`--track`)
|
||||
- Install once, update with `skillshare update --all`
|
||||
- Complements project skills — organization for standards, project for repo context
|
||||
|
||||
---
|
||||
|
||||
## Design Philosophy
|
||||
|
||||
Deeper explanations of the design decisions behind skillshare.
|
||||
|
||||
| Topic | Summary |
|
||||
|-------|---------|
|
||||
| [Why Local-First](./philosophy/why-local-first) | Single binary, zero dependencies, offline by default |
|
||||
| [Security-First](./philosophy/security-first) | 15+ audit patterns, supply chain threat model |
|
||||
| [Sync Modes Deep Dive](./philosophy/sync-modes-explained) | Merge vs. symlink trade-offs in detail |
|
||||
| [Comparison](./philosophy/comparison) | How skillshare compares to other tools |
|
||||
| [Skill Design](./philosophy/skill-design) | Guidelines for writing effective skills |
|
||||
+4
-4
@@ -128,7 +128,7 @@ If you're already using another skill manager:
|
||||
curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh
|
||||
|
||||
# Homebrew
|
||||
brew install runkids/tap/skillshare
|
||||
brew install skillshare
|
||||
```
|
||||
|
||||
### Step 2: Initialize and collect existing skills
|
||||
@@ -144,7 +144,7 @@ skillshare collect --all # Imports existing skills from all detected targets
|
||||
skillshare sync # Symlinks source skills to all targets
|
||||
```
|
||||
|
||||
Your existing skills are now managed from one place. For a detailed walkthrough, see the [Migration Guide](./migration.md).
|
||||
Your existing skills are now managed from one place. For a detailed walkthrough, see the [Migration Guide](/docs/how-to/advanced/migration).
|
||||
|
||||
## Choosing the Right Tool
|
||||
|
||||
@@ -166,5 +166,5 @@ Your existing skills are now managed from one place. For a detailed walkthrough,
|
||||
|
||||
## See Also
|
||||
|
||||
- [Migration](./migration.md) — Migration guide
|
||||
- [Core Concepts](/docs/concepts) — How skillshare works
|
||||
- [Migration](/docs/how-to/advanced/migration) — Migration guide
|
||||
- [Core Concepts](/docs/understand) — How skillshare works
|
||||
@@ -0,0 +1,105 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# Security-First Design
|
||||
|
||||
> AI skills are executable instructions. skillshare treats them as untrusted input.
|
||||
|
||||
## The Threat Model
|
||||
|
||||
When you install a skill from GitHub, you're giving an AI tool instructions that will influence code generation, file modifications, and potentially command execution. A malicious skill could:
|
||||
|
||||
- **Inject prompts** that override the AI's safety guidelines
|
||||
- **Exfiltrate data** by instructing the AI to send file contents to external URLs
|
||||
- **Execute destructive commands** through the AI's shell access
|
||||
- **Steal credentials** by accessing environment variables or config files
|
||||
|
||||
This is not theoretical. Prompt injection is the #1 security concern in AI tooling.
|
||||
|
||||
## The Audit Engine
|
||||
|
||||
skillshare includes a built-in security scanner (`skillshare audit`) that checks every installed skill against 15+ detection patterns across 5 severity levels:
|
||||
|
||||
| Severity | Examples |
|
||||
|----------|----------|
|
||||
| CRITICAL | Prompt injection, system prompt override |
|
||||
| HIGH | Data exfiltration URLs, credential access patterns |
|
||||
| MEDIUM | Destructive commands (`rm -rf`, `DROP TABLE`), file system writes |
|
||||
| LOW | Network requests, external tool invocation |
|
||||
| INFO | Large file sizes, unusual formatting |
|
||||
|
||||
### How It Works
|
||||
|
||||
The audit engine scans SKILL.md content using pattern matching and heuristics:
|
||||
|
||||
```bash
|
||||
# Scan all installed skills
|
||||
skillshare audit
|
||||
|
||||
# JSON output for CI integration
|
||||
skillshare audit --json
|
||||
|
||||
# Scan project skills only
|
||||
skillshare audit -p
|
||||
```
|
||||
|
||||
### Automatic Blocking
|
||||
|
||||
During `skillshare install`, the audit runs automatically. If a CRITICAL finding is detected, installation is blocked:
|
||||
|
||||
```
|
||||
CRITICAL: Prompt injection detected in "malicious-skill"
|
||||
→ Pattern: "ignore previous instructions"
|
||||
→ Installation blocked. Use --force to override (not recommended).
|
||||
```
|
||||
|
||||
## Defense in Depth
|
||||
|
||||
The audit engine is one layer. skillshare's security model includes:
|
||||
|
||||
1. **Audit at install time** — catch threats before they reach your AI tools
|
||||
2. **Audit on demand** — re-scan existing skills as new patterns are added
|
||||
3. **Symlink isolation** — skills are symlinked, not copied, so the source remains the authority
|
||||
4. **Backup before changes** — `skillshare backup` snapshots your entire skill library
|
||||
5. **Trash with TTL** — deleted skills go to trash first, not permanent deletion
|
||||
6. **Operation logging** — every mutating operation is logged to `operations.log` (JSONL)
|
||||
|
||||
## Supply Chain Considerations
|
||||
|
||||
The AI skill ecosystem is young. There are no package registries with review processes, no code signing, no dependency resolution. Skills are Markdown files in git repositories.
|
||||
|
||||
skillshare's approach:
|
||||
- **Scan everything** — even skills from trusted sources
|
||||
- **Block by default** — CRITICAL findings prevent installation
|
||||
- **Log everything** — audit results are stored for forensic review
|
||||
- **Update patterns** — new detection patterns ship with each skillshare release
|
||||
|
||||
## Configuring Audit Behavior
|
||||
|
||||
Set the block threshold in `config.yaml` to control what severity blocks installation:
|
||||
|
||||
```yaml
|
||||
# config.yaml
|
||||
audit:
|
||||
block_threshold: HIGH # Block on HIGH and CRITICAL (default: CRITICAL)
|
||||
```
|
||||
|
||||
For per-rule customization, use a separate `audit-rules.yaml` file (initialized with `skillshare audit --init-rules`):
|
||||
|
||||
```yaml
|
||||
# audit-rules.yaml
|
||||
rules:
|
||||
- id: network-request-0
|
||||
enabled: false # Disable this specific rule
|
||||
- id: my-custom-check
|
||||
severity: MEDIUM
|
||||
pattern: "TODO|FIXME"
|
||||
description: Policy violation — unresolved TODOs
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
- [`audit` command reference](/docs/reference/commands/audit)
|
||||
- [Security guide](/docs/how-to/advanced/security)
|
||||
- [CI/CD validation recipe](/docs/how-to/recipes/ci-cd-skill-validation)
|
||||
+4
-4
@@ -417,7 +417,7 @@ Use `skillshare sync` to deploy changes, then test in your AI CLI. Watch for:
|
||||
|
||||
## See Also
|
||||
|
||||
- [Creating Skills](./creating-skills.md) — Step-by-step creation guide
|
||||
- [Best Practices](./best-practices.md) — Naming, organization, version control
|
||||
- [Skill Format](/docs/concepts/skill-format) — SKILL.md structure and metadata
|
||||
- [Securing Your Skills](./security.md) — Security scanning and audit
|
||||
- [Creating Skills](/docs/how-to/daily-tasks/creating-skills) — Step-by-step creation guide
|
||||
- [Best Practices](/docs/how-to/daily-tasks/best-practices) — Naming, organization, version control
|
||||
- [Skill Format](/docs/understand/skill-format) — SKILL.md structure and metadata
|
||||
- [Securing Your Skills](/docs/how-to/advanced/security) — Security scanning and audit
|
||||
@@ -0,0 +1,153 @@
|
||||
---
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
# Sync Modes Explained
|
||||
|
||||
> A deep dive into the three sync modes — merge, copy, and symlink — when to use each, and the trade-offs.
|
||||
|
||||
## The Three Modes
|
||||
|
||||
skillshare offers three sync modes that control how skills are delivered from your source directory to AI tool target directories.
|
||||
|
||||
### Merge Mode (Default)
|
||||
|
||||
```
|
||||
Source: ~/.config/skillshare/skills/
|
||||
├── code-review/SKILL.md
|
||||
├── testing/SKILL.md
|
||||
└── debugging/SKILL.md
|
||||
|
||||
Target: ~/.claude/skills/
|
||||
├── code-review → ~/.config/skillshare/skills/code-review (symlink)
|
||||
├── testing → ~/.config/skillshare/skills/testing (symlink)
|
||||
├── debugging → ~/.config/skillshare/skills/debugging (symlink)
|
||||
└── my-local-skill/SKILL.md (untouched)
|
||||
```
|
||||
|
||||
**How it works**: Creates one symlink per skill. Each skill directory in the target points back to the source.
|
||||
|
||||
**Key property**: **Non-destructive**. Local skills in the target directory (like `my-local-skill` above) are preserved. skillshare only manages symlinks it created.
|
||||
|
||||
### Copy Mode
|
||||
|
||||
```
|
||||
Source: ~/.config/skillshare/skills/
|
||||
├── code-review/SKILL.md
|
||||
├── testing/SKILL.md
|
||||
└── debugging/SKILL.md
|
||||
|
||||
Target: ~/.cursor/skills/
|
||||
├── code-review/SKILL.md (physical copy)
|
||||
├── testing/SKILL.md (physical copy)
|
||||
├── debugging/SKILL.md (physical copy)
|
||||
├── .skillshare-manifest.json (tracks managed files)
|
||||
└── my-local-skill/SKILL.md (untouched)
|
||||
```
|
||||
|
||||
**How it works**: Physically copies each skill into the target. A `.skillshare-manifest.json` file tracks which skills are managed and their SHA-256 checksums. On subsequent syncs, only changed skills are re-copied.
|
||||
|
||||
**Key property**: **Maximum compatibility**. Works everywhere — no symlink support required. Local skills are preserved just like merge mode.
|
||||
|
||||
### Symlink Mode
|
||||
|
||||
```
|
||||
Source: ~/.config/skillshare/skills/
|
||||
├── code-review/SKILL.md
|
||||
├── testing/SKILL.md
|
||||
└── debugging/SKILL.md
|
||||
|
||||
Target: ~/.claude/skills → ~/.config/skillshare/skills/ (single symlink)
|
||||
```
|
||||
|
||||
**How it works**: Replaces the entire target directory with a single symlink pointing to the source.
|
||||
|
||||
**Key property**: **Total control**. The target is exactly the source. No local skills can exist in the target.
|
||||
|
||||
## When to Use Each
|
||||
|
||||
| Factor | Merge | Copy | Symlink |
|
||||
|--------|-------|------|---------|
|
||||
| Preserves local skills | Yes | Yes | No |
|
||||
| Cross-platform support | May have issues | Works everywhere | May have issues |
|
||||
| Source changes reflected | Instantly | After `sync` | Instantly |
|
||||
| Handles nested paths | Flattens (`a/b/c` → `a__b__c`) | Flattens | Native structure |
|
||||
| Orphan cleanup | Automatic | Automatic | Not needed |
|
||||
| Disk usage | Minimal (symlinks) | Full copies | Minimal (one symlink) |
|
||||
| Recommended for | Most users | WSL, Docker, CI | Single-source setups |
|
||||
|
||||
### Choose Merge When
|
||||
|
||||
- You have local skills in your AI tool that you don't want managed by skillshare
|
||||
- You use multiple AI tools with different local customizations
|
||||
- You're adopting skillshare incrementally (some skills managed, some not)
|
||||
|
||||
### Choose Copy When
|
||||
|
||||
- Your platform has unreliable symlink support (WSL, some Docker setups)
|
||||
- The AI tool doesn't follow symlinks correctly
|
||||
- You're in a CI/CD pipeline or containerized environment
|
||||
- You want the target to work independently of the source directory
|
||||
|
||||
### Choose Symlink When
|
||||
|
||||
- skillshare is the only source of skills for a target
|
||||
- You want zero ambiguity about what's in the target
|
||||
- You're setting up a fresh environment
|
||||
|
||||
## Nested Path Handling
|
||||
|
||||
In merge and copy modes, nested source paths are flattened using double underscores:
|
||||
|
||||
```
|
||||
Source: skills/frontend/react-patterns/SKILL.md
|
||||
Target: ~/.claude/skills/frontend__react-patterns → skills/frontend/react-patterns
|
||||
```
|
||||
|
||||
This avoids directory creation in targets that expect a flat skill structure. In symlink mode, the directory structure is preserved as-is.
|
||||
|
||||
## Orphan Cleanup
|
||||
|
||||
Merge and copy modes automatically remove orphaned entries during `skillshare sync`. If you uninstall a skill from your source, the corresponding symlink (or copied directory) in the target is cleaned up on the next sync.
|
||||
|
||||
```bash
|
||||
skillshare uninstall old-skill
|
||||
skillshare sync
|
||||
# → Pruned orphan: old-skill
|
||||
```
|
||||
|
||||
## Per-Target Mode Override
|
||||
|
||||
You can set different modes per target. Global config uses map format:
|
||||
|
||||
```yaml
|
||||
targets:
|
||||
claude:
|
||||
path: ~/.claude/skills
|
||||
mode: merge
|
||||
cursor:
|
||||
path: ~/.cursor/skills
|
||||
mode: copy
|
||||
```
|
||||
|
||||
Project config uses list format:
|
||||
|
||||
```yaml
|
||||
targets:
|
||||
- name: claude
|
||||
mode: merge
|
||||
- name: cursor
|
||||
mode: copy
|
||||
```
|
||||
|
||||
Or change mode via CLI:
|
||||
|
||||
```bash
|
||||
skillshare target claude --mode copy
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
- [Sync modes concept page](/docs/understand/sync-modes)
|
||||
- [`sync` command reference](/docs/reference/commands/sync)
|
||||
- [Source and targets](/docs/understand/source-and-targets)
|
||||
@@ -0,0 +1,63 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Why Local-First
|
||||
|
||||
> skillshare is a single binary with no runtime dependencies. Here's why.
|
||||
|
||||
## The Decision
|
||||
|
||||
skillshare ships as a single Go binary. No Node.js, no Python, no package manager, no daemon. Install it, run it, done.
|
||||
|
||||
This wasn't the path of least resistance — it was a deliberate choice driven by three principles.
|
||||
|
||||
## Principle 1: Zero Dependency Chain
|
||||
|
||||
Every dependency is an attack surface and a maintenance burden.
|
||||
|
||||
If skillshare required Node.js, you'd need to manage Node versions, deal with `node_modules`, handle platform-specific native modules, and trust the entire npm supply chain. For a tool that manages AI skills — which are themselves untrusted content — adding an untrusted dependency chain is unacceptable.
|
||||
|
||||
Go compiles to a static binary. The dependency chain ends at compile time. What you download is what you run.
|
||||
|
||||
## Principle 2: Works Everywhere the Same Way
|
||||
|
||||
skillshare runs on:
|
||||
- macOS (Intel and Apple Silicon)
|
||||
- Linux (amd64 and arm64)
|
||||
- Windows (amd64)
|
||||
- Docker containers (no special setup)
|
||||
- CI/CD pipelines (no language runtime needed)
|
||||
- Dev containers and Codespaces
|
||||
|
||||
A single binary means identical behavior across all platforms. No "works on my machine" debugging. No CI environment drift.
|
||||
|
||||
## Principle 3: Offline by Default
|
||||
|
||||
skillshare's core operations — `sync`, `list`, `status`, `backup`, `restore` — work without network access. Only operations that explicitly need a remote (`install`, `search`, `check`, `update`, `push`, `pull`) require connectivity.
|
||||
|
||||
This matters for:
|
||||
- **Air-gapped environments**: Defense, healthcare, and financial institutions often restrict network access
|
||||
- **Unreliable connections**: Trains, planes, conference WiFi
|
||||
- **Speed**: Local operations complete in milliseconds, not seconds
|
||||
|
||||
## Why Not a Package Manager Plugin?
|
||||
|
||||
We considered shipping as an npm package, a Homebrew formula (which we now support as an additional channel), or a pip package. Each had the same problem: they add a runtime dependency that skillshare's users may not have or want.
|
||||
|
||||
A developer using Cursor on Windows shouldn't need to install Homebrew. A CI pipeline running Alpine Linux shouldn't need Node.js. The tool should adapt to the user's environment, not the other way around.
|
||||
|
||||
## The Trade-Off
|
||||
|
||||
The single-binary approach has costs:
|
||||
|
||||
- **Build complexity**: Cross-compilation for 6+ targets, CGO disabled
|
||||
- **Update mechanism**: No `npm update` — skillshare has its own `upgrade` command
|
||||
- **UI delivery**: The web dashboard can't bundle with the binary (too large), so it's downloaded at runtime and cached
|
||||
|
||||
We accept these trade-offs because they keep the user experience simple: download, run, done.
|
||||
|
||||
## Related
|
||||
|
||||
- [Security-First Design](/docs/understand/philosophy/security-first)
|
||||
- [Comparison with other tools](/docs/understand/philosophy/comparison)
|
||||
@@ -45,7 +45,7 @@ my-skill/ remote-skill/`"]
|
||||
|
||||
## Auto-Detection
|
||||
|
||||
Skillshare automatically enters project mode when `.skillshare/config.yaml` exists in the current directory:
|
||||
skillshare automatically enters project mode when `.skillshare/config.yaml` exists in the current directory:
|
||||
|
||||
```bash
|
||||
cd my-project/ # Has .skillshare/config.yaml
|
||||
@@ -183,6 +183,6 @@ Project mode has some intentional limitations:
|
||||
|
||||
## See Also
|
||||
|
||||
- [Project Setup](/docs/guides/project-setup) — Step-by-step setup guide
|
||||
- [Project Workflow](/docs/workflows/project-workflow) — Day-to-day project mode usage
|
||||
- [Organization-Wide Skills](/docs/guides/organization-sharing) — Team-wide sharing
|
||||
- [Project Setup](/docs/how-to/sharing/project-setup) — Step-by-step setup guide
|
||||
- [Project Workflow](/docs/how-to/daily-tasks/project-workflow) — Day-to-day project mode usage
|
||||
- [Organization-Wide Skills](/docs/how-to/sharing/organization-sharing) — Team-wide sharing
|
||||
@@ -72,7 +72,7 @@ name: my-skill
|
||||
```yaml
|
||||
name: code-review
|
||||
name: pdf-tools
|
||||
name: acme:frontend-ui # Namespaced for teams
|
||||
name: acme-frontend-ui # Namespaced for teams
|
||||
```
|
||||
|
||||
---
|
||||
@@ -115,9 +115,9 @@ targets: [claude, cursor]
|
||||
| `[claude]` | Syncs only to targets matching "claude" |
|
||||
| `[claude, cursor]` | Syncs to targets matching either name |
|
||||
|
||||
**Cross-mode matching:** A skill declaring `targets: [claude]` also matches the project target `claude`, because both refer to the same AI CLI. Matching uses the [target registry](/docs/targets/supported-targets).
|
||||
**Cross-mode matching:** A skill declaring `targets: [claude]` also matches the project target `claude`, because both refer to the same AI CLI. Matching uses the [target registry](/docs/reference/targets/supported-targets).
|
||||
|
||||
**Interaction with config filters:** Skill-level `targets` is applied **after** config-level `include`/`exclude`. Both must pass for a skill to be synced. See [Configuration](/docs/targets/configuration#skill-level-targets).
|
||||
**Interaction with config filters:** Skill-level `targets` is applied **after** config-level `include`/`exclude`. Both must pass for a skill to be synced. See [Configuration](/docs/reference/targets/configuration#skill-level-targets).
|
||||
|
||||
**Example — Claude-only skill:**
|
||||
|
||||
@@ -274,6 +274,6 @@ Checks for:
|
||||
|
||||
## See Also
|
||||
|
||||
- [new](/docs/commands/new) — Create a skill with the correct template
|
||||
- [Creating Skills](/docs/guides/creating-skills) — Full guide to writing skills
|
||||
- [Best Practices](/docs/guides/best-practices) — Naming and organization tips
|
||||
- [new](/docs/reference/commands/new) — Create a skill with the correct template
|
||||
- [Creating Skills](/docs/how-to/daily-tasks/creating-skills) — Full guide to writing skills
|
||||
- [Best Practices](/docs/how-to/daily-tasks/best-practices) — Naming and organization tips
|
||||
+5
-5
@@ -34,7 +34,7 @@ Without skillshare, you manage skills separately for each AI CLI:
|
||||
|
||||
## The Solution
|
||||
|
||||
Skillshare introduces a **source directory** that syncs to all **targets**:
|
||||
skillshare introduces a **source directory** that syncs to all **targets**:
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
@@ -126,7 +126,7 @@ Targets are AI CLI skill directories that skillshare syncs to.
|
||||
- `~/.cursor/skills/` — Cursor
|
||||
- `~/.codex/skills/` — OpenAI Codex CLI
|
||||
- `~/.gemini/skills/` — Gemini CLI
|
||||
- And [49+ more](/docs/targets/supported-targets)
|
||||
- And [49+ more](/docs/reference/targets/supported-targets)
|
||||
|
||||
**Auto-detection:** When you run `skillshare init`, it automatically detects installed AI CLIs and adds them as targets.
|
||||
|
||||
@@ -183,7 +183,7 @@ $EDITOR ~/.claude/skills/my-skill/SKILL.md
|
||||
|
||||
## See Also
|
||||
|
||||
- [sync](/docs/commands/sync) — Propagate changes from source to targets
|
||||
- [collect](/docs/commands/collect) — Pull skills from targets back to source
|
||||
- [sync](/docs/reference/commands/sync) — Propagate changes from source to targets
|
||||
- [collect](/docs/reference/commands/collect) — Pull skills from targets back to source
|
||||
- [Sync Modes](./sync-modes.md) — How files are linked (merge, copy, symlink)
|
||||
- [Configuration](/docs/targets/configuration) — Target config reference
|
||||
- [Configuration](/docs/reference/targets/configuration) — Target config reference
|
||||
@@ -76,7 +76,7 @@ Behavior when rules change:
|
||||
- Previously synced source-linked entries that become filtered out are removed on next `sync`
|
||||
- Existing local non-symlink folders in target are preserved
|
||||
|
||||
See [Target Configuration](/docs/targets/configuration#include--exclude-target-filters) for full examples.
|
||||
See [Target Configuration](/docs/reference/targets/configuration#include--exclude-target-filters) for full examples.
|
||||
|
||||
---
|
||||
|
||||
@@ -260,7 +260,7 @@ $ skillshare sync
|
||||
|
||||
## See Also
|
||||
|
||||
- [sync](/docs/commands/sync) — Run sync to apply mode changes
|
||||
- [target](/docs/commands/target) — Change a target's sync mode
|
||||
- [sync](/docs/reference/commands/sync) — Run sync to apply mode changes
|
||||
- [target](/docs/reference/commands/target) — Change a target's sync mode
|
||||
- [Source & Targets](./source-and-targets.md) — The core architecture
|
||||
- [Configuration](/docs/targets/configuration) — Per-target settings
|
||||
- [Configuration](/docs/reference/targets/configuration) — Per-target settings
|
||||
+9
-9
@@ -70,7 +70,7 @@ Tracked repos are prefixed with `_` to distinguish them from regular skills:
|
||||
|
||||
## Nested Skills & Auto-Flattening
|
||||
|
||||
Skill repos often organize skills in folders. Skillshare automatically flattens them for AI CLIs:
|
||||
Skill repos often organize skills in folders. skillshare automatically flattens them for AI CLIs:
|
||||
|
||||
```
|
||||
SOURCE TARGET
|
||||
@@ -96,12 +96,12 @@ _team-skills/
|
||||
| **AI CLI compatibility** | Most AI CLIs expect skills in a flat directory, not nested folders |
|
||||
| **Preserve organization** | Keep logical folder structure in source while meeting CLI requirements |
|
||||
| **Traceability** | Flattened name shows origin path (e.g., `_team__frontend__react` → came from `_team/frontend/react/`) |
|
||||
| **No manual work** | Skillshare handles the transformation automatically during sync |
|
||||
| **No manual work** | skillshare handles the transformation automatically during sync |
|
||||
|
||||
**You organize, skillshare adapts.** Write skills in any folder structure; they'll work everywhere.
|
||||
|
||||
:::tip
|
||||
Auto-flattening works for **all skills**, not just tracked repos. You can organize your personal skills in folders too. See [Organize with Folders](/docs/concepts/source-and-targets#organize-with-folders-auto-flattening).
|
||||
Auto-flattening works for **all skills**, not just tracked repos. You can organize your personal skills in folders too. See [Organize with Folders](/docs/understand/source-and-targets#organize-with-folders-auto-flattening).
|
||||
:::
|
||||
|
||||
---
|
||||
@@ -237,7 +237,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:
|
||||
@@ -258,13 +258,13 @@ 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.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [install](/docs/commands/install) — Install with `--track`
|
||||
- [update](/docs/commands/update) — Pull latest changes
|
||||
- [check](/docs/commands/check) — See available updates
|
||||
- [Organization-Wide Skills](/docs/guides/organization-sharing) — Team sharing guide
|
||||
- [install](/docs/reference/commands/install) — Install with `--track`
|
||||
- [update](/docs/reference/commands/update) — Pull latest changes
|
||||
- [check](/docs/reference/commands/check) — See available updates
|
||||
- [Organization-Wide Skills](/docs/how-to/sharing/organization-sharing) — Team sharing guide
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user