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:
Willie
2026-02-26 04:52:29 +08:00
parent efa3a34599
commit 2c3003e04f
110 changed files with 24844 additions and 675 deletions
+7 -7
View File
@@ -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
+90
View File
@@ -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
-44
View File
@@ -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
-24
View File
@@ -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>
-29
View File
@@ -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:
![Docusaurus Plushie](./docusaurus-plushie-banner.jpeg)
The blog supports tags as well!
**And if you don't want a blog**: just delete this directory, and use `blog: false` in your Docusaurus config.
@@ -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)
+5 -25
View File
@@ -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
-19
View File
@@ -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
+13 -9
View File
@@ -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
+4 -4
View File
@@ -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
-51
View File
@@ -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 |
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
+54
View File
@@ -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)
+19
View File
@@ -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)
@@ -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
@@ -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
View File
@@ -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
+62
View File
@@ -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)
+60
View File
@@ -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)
+79
View File
@@ -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)
+63
View File
@@ -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)
+81
View File
@@ -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)
+114
View File
@@ -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)
@@ -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
@@ -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
+43
View File
@@ -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
@@ -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
+11 -30
View File
@@ -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
@@ -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
@@ -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
@@ -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.
:::
---
+6 -6
View File
@@ -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?
+1 -1
View File
@@ -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
+4 -4
View File
@@ -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
@@ -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 |
@@ -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)
@@ -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/ &nbsp; 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
@@ -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
@@ -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