diff --git a/.skillshare/skills/update-docs/SKILL.md b/.skillshare/skills/update-docs/SKILL.md
index 5b8d31afc..c691b546d 100644
--- a/.skillshare/skills/update-docs/SKILL.md
+++ b/.skillshare/skills/update-docs/SKILL.md
@@ -61,9 +61,9 @@ If changes affect user-visible CLI behavior:
### Step 5: Check README
Review `README.md` for sections that may need updates:
-- Recent Updates section
-- Feature list
-- Usage examples
+- Recent Updates callout
+- Why skillshare bullet points (5 selling points)
+- Highlights section (core feature examples)
### Step 6: Build Verification
diff --git a/README.md b/README.md
index 408bf9bdd..df6ddc3f4 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,6 @@
-
@@ -31,12 +30,8 @@
Website •
Install •
Quick Start •
+ Highlights •
Screenshots •
- Commands •
- Web UI •
- Project Skills •
- Organization Skills •
- Hub •
Docs
@@ -48,45 +43,21 @@
## Why skillshare
-Stop managing skills tool-by-tool.
-`skillshare` gives you one shared skill source and pushes it everywhere your AI agents work.
+Every AI CLI has its own skills directory.
+You edit in one, forget to copy to another, and lose track of what's where.
-- **One command, everywhere**: Sync to Claude Code, Codex, Cursor, OpenCode, and more with `skillshare sync`.
-- **Safe by default**: Non-destructive merge mode keeps CLI-local skills intact while sharing team skills.
-- **Per-target mode control**: Keep a global default, then tune specific targets with `skillshare target --mode `.
-- **True bidirectional flow**: Pull skills back from targets with `collect` so improvements never get trapped in one tool.
-- **Cross-machine ready**: Git-native `push`/`pull` keeps all your devices aligned.
-- **Team + project friendly**: Use global skills for personal workflows and `.skillshare/` for repo-scoped collaboration.
-- **Folder-friendly**: Organize skills in folders (e.g. `frontend/react/`) — auto-flattened to flat names on sync.
-- **Any Git host**: Install, update, and check skills from GitHub, GitLab, Bitbucket, Azure DevOps, or any self-hosted Git — no platform-specific API required.
-- **Privacy-first**: No central registry, no telemetry, no install tracking. Your skill setup stays entirely local.
-- **Built-in security audit**: Scan skills for prompt injection, data exfiltration, and other threats before they reach your AI agent.
-- **Visual control panel**: Open `skillshare ui` for browsing, install, target management, and sync status in one place.
+skillshare fixes this:
-## Comparison
+- **One source, every agent** — sync to Claude, Cursor, Codex & 49+ more with `skillshare sync`
+- **Install from anywhere** — GitHub, GitLab, Bitbucket, Azure DevOps, or any self-hosted Git
+- **Built-in security** — audit skills for prompt injection and data exfiltration before use
+- **Team-ready** — project skills in `.skillshare/`, org-wide skills via tracked repos
+- **Local & lightweight** — single binary, no registry, no telemetry, fully offline-capable
-skillshare uses a **declarative** approach: define your targets once in `config.yaml`, then `sync` handles everything — no prompts, no repeated selections.
-
-| | Imperative (install-per-command) | Declarative (skillshare) |
-|---|---|---|
-| **Config** | No config; prompts every run | `config.yaml` — set once |
-| **Agent selection** | Interactive prompt each time | Defined in config |
-| **Install method** | Choose per operation | `sync_mode` in config |
-| **Source of truth** | Skills copied independently | Single source → symlinks (or copies) |
-| **Remove one agent's skill** | May break other agents' symlinks | Only that target's symlink removed |
-| **New machine setup** | Re-run every install manually | `git clone` config + `sync` |
-| **Project-scoped skills** | Global lock file only | `init -p` for per-repo skills |
-| **Cross-machine sync** | Manual | Built-in `push` / `pull` |
-| **Bidirectional** | Install only | `collect` pulls changes back |
-| **Security audit** | None | Built-in `audit` + auto-scan on install/update |
-| **Web dashboard** | None | `skillshare ui` |
-| **Git platform support** | GitHub only for update/check | Any Git remote (GitHub, GitLab, Bitbucket, etc.) |
-| **Runtime dependency** | Node.js + npm | None (single Go binary) |
-
-> [!TIP]
-> 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).
+> Coming from another tool? [Migration Guide](https://skillshare.runkids.cc/docs/how-to/advanced/migration) · [Comparison](https://skillshare.runkids.cc/docs/understand/philosophy/comparison)
## How It Works
+
- macOS / Linux: `~/.config/skillshare/skills/`
- Windows: `%AppData%\skillshare\skills\`
@@ -108,26 +79,25 @@ skillshare uses a **declarative** approach: define your targets once in `config.
| macOS/Linux | `~/.config/skillshare/skills/` | Symlinks |
| Windows | `%AppData%\skillshare\skills\` | NTFS Junctions (no admin required) |
-> Targets that can't follow symlinks? Use `skillshare target --mode copy` to sync as real files instead.
-> You can mix modes by target. See the [Sync Modes guide](https://skillshare.runkids.cc/docs/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/how-to/daily-tasks/organizing-skills) and [runkids/my-skills](https://github.com/runkids/my-skills) for a real-world example.
+| | Imperative (install-per-command) | Declarative (skillshare) |
+|---|---|---|
+| **Source of truth** | Skills copied independently | Single source → symlinks (or copies) |
+| **New machine setup** | Re-run every install manually | `git clone` config + `sync` |
+| **Security audit** | None | Built-in `audit` + auto-scan on install/update |
+| **Web dashboard** | None | `skillshare ui` |
+| **Runtime dependency** | Node.js + npm | None (single Go binary) |
+> [Full comparison →](https://skillshare.runkids.cc/docs/understand/philosophy/comparison)
## CLI and UI Preview
-### CLI
-
| Sync | Install + Audit |
|---|---|
-|
|
|
-
-### UI
+|
|
|
| Dashboard | Security Audit |
|---|---|
-|
|
|
+|
|
|
## Installation
@@ -149,9 +119,7 @@ irm https://raw.githubusercontent.com/runkids/skillshare/main/install.ps1 | iex
brew install skillshare
```
-> **Note:** All install methods include the web dashboard. `skillshare ui` automatically downloads UI assets on first launch — no extra setup needed.
-
-> **Tip:** To update to the latest version, run `skillshare upgrade`. It auto-detects your install method (Homebrew, manual, etc.) and handles the rest.
+> **Tip:** Run `skillshare upgrade` to update to the latest version. It auto-detects your install method and handles the rest.
### Shorthand (Optional)
@@ -161,316 +129,81 @@ Add an alias to your shell config (`~/.zshrc` or `~/.bashrc`):
alias ss='skillshare'
```
-### Uninstall
-
-```bash
-# macOS/Linux
-brew uninstall skillshare # Homebrew
-sudo rm /usr/local/bin/skillshare # Manual install
-rm -rf ~/.config/skillshare # Config & skills (optional)
-rm -rf ~/.local/share/skillshare # Backups & trash (optional)
-rm -rf ~/.local/state/skillshare # Logs (optional)
-rm -rf ~/.cache/skillshare # UI & version cache (optional)
-
-# Windows (PowerShell)
-Remove-Item "$env:LOCALAPPDATA\Programs\skillshare" -Recurse -Force
-Remove-Item "$env:APPDATA\skillshare" -Recurse -Force # optional
-```
-
----
-
## Quick Start
```bash
-skillshare init --dry-run # Preview setup
skillshare init # Create config, source, and detected targets
skillshare sync # Sync skills to all targets
```
-## Common Workflows
+## Highlights
-### Daily Commands
-
-| Command | What it does |
-|---------|---------------|
-| `skillshare list` | List skills in source |
-| `skillshare status` | Show sync status for all targets |
-| `skillshare sync` | Sync source skills to all targets |
-| `skillshare diff` | Preview differences before syncing |
-| `skillshare doctor` | Diagnose config/environment issues |
-| `skillshare new ` | Create a new skill template |
-| `skillshare install [source]` | Install skill from source, or all skills from config (no args) |
-| `skillshare collect [target]` | Import skills from target(s) back to source |
-| `skillshare update ` | Update one installed skill/repo |
-| `skillshare update --all` | Update all tracked repos |
-| `skillshare uninstall ... [-G ]` | Remove skill(s) or groups from source |
-| `skillshare audit [name]` | Scan skills for security threats |
-| `skillshare log` | View operations and audit logs for debugging and compliance |
-| `skillshare search ` | Search installable skills on GitHub |
-| `skillshare search --hub [url]` | Search a hub index (default: skillshare-hub) |
-| `skillshare hub index` | Generate a hub index from installed skills |
-
-`skillshare search` requires GitHub auth (`gh auth login`) or `GITHUB_TOKEN`. The `--hub` flag searches a JSON index instead — without a URL it defaults to the public [skillshare-hub](https://github.com/runkids/skillshare-hub).
-
-### Target Management
-
-```bash
-skillshare target list
-skillshare target add my-tool ~/.my-tool/skills
-skillshare target remove my-tool
-```
-
-### Backup and Restore
-
-```bash
-skillshare backup
-skillshare backup --list
-skillshare restore
-```
-
-### Cross-machine Git Sync
-
-```bash
-skillshare push
-skillshare pull
-```
-
-### Project Skills (Per Repo)
-
-```bash
-skillshare init -p
-skillshare new my-skill -p
-skillshare install anthropics/skills/skills/pdf -p
-skillshare install github.com/team/skills --track -p
-skillshare sync
-```
-
-Project mode keeps skills in `.skillshare/skills/` so they can be committed and shared with the repo. In both global and project mode, `config.yaml` acts as a **portable skill manifest** — run `skillshare install` with no arguments to install all listed skills:
-
-```bash
-# Global — new machine setup
-skillshare install # Installs all skills from ~/.config/skillshare/config.yaml
-skillshare sync
-
-# Project — new team member onboarding
-git clone github.com/your/project && cd project
-skillshare install -p # Installs all skills from .skillshare/config.yaml
-skillshare sync
-```
-
-### Organization Skills (Tracked Repo)
+**Install & update skills** —from GitHub, GitLab, or any Git host
```bash
skillshare install github.com/team/skills --track
-skillshare update _team-skills
+skillshare update --all
+skillshare target claude --mode copy # if symlinks don't work
+```
+
+**Symlink issues?** — switch to copy mode per target
+
+```bash
+skillshare target --mode copy
skillshare sync
```
-## Skill Hub
-
-Build a searchable skill catalog for your organization — no GitHub API required.
+**Security audit** —scan before skills reach your agent
```bash
-skillshare hub index # Generate index from installed skills
-skillshare search --hub # Browse the public skillshare-hub
-skillshare search react --hub # Search "react" in skillshare-hub
-skillshare search --hub ./skillshare-hub.json react # Search custom local index
-skillshare search --hub https://example.com/hub.json # Search custom remote index
+skillshare audit
```
-The generated `skillshare-hub.json` follows a versioned schema (`schemaVersion: 1`) with support for tags and multi-skill repos. Host it on any static server, internal CDN, or commit it alongside your skills repo.
-
-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/how-to/sharing/hub-index) for schema details and hosting options.
-
-## Web Dashboard
+**Project skills** —per-repo, committed with your code
```bash
-skillshare ui # Global mode
-skillshare ui -p # Project mode (manages .skillshare/)
+skillshare init -p && skillshare sync
```
-- Opens `http://127.0.0.1:19420`
-- Requires `skillshare init` (or `init -p` for project mode) first
-- Auto-detects project mode when `.skillshare/config.yaml` exists
-- UI assets are downloaded on first launch (~1 MB), then cached offline at `~/.cache/skillshare/ui/`
-
-For containers/remote hosts:
+**Web dashboard** —visual control panel
```bash
-skillshare ui --host 0.0.0.0 --no-open
+skillshare ui
```
-Then access: `http://localhost:19420`
-
-## Security Audit
-
-Scan installed skills for prompt injection, data exfiltration, credential theft, and other threats before they reach your AI agent.
-
-```bash
-skillshare audit # Scan all skills
-skillshare audit # Scan a specific skill
-skillshare audit -T h # Block on HIGH+ findings for this run
-skillshare update _team -T h # Override update gate to HIGH for this run
-```
-
-Skills are also scanned automatically during `skillshare install` and `skillshare update`.
-
-- `skillshare install` and `skillshare update` run an audit by default.
-- Block threshold is configurable with `audit.block_threshold` (`CRITICAL` default; also supports `HIGH`, `MEDIUM`, `LOW`, `INFO`).
-- Per-command threshold override is supported on install and update: `--audit-threshold`, `--threshold`, `-T` (supports shorthand: `c|h|m|l|i`, plus `crit`, `med`).
-- `audit.block_threshold` only controls blocking level; it does **not** disable scanning.
-- There is no config flag to permanently skip audit. To bypass a single run, use `--skip-audit`.
-- Use `--force` (where supported) to override blocked installs while still running audit (findings remain visible).
-- Use `--skip-audit` to bypass scanning for a single install/update command.
-- If both are set, `--skip-audit` takes precedence in practice (audit is not executed).
-- 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/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
-
-Use Docker for reproducible testing, interactive playgrounds, and production deployment.
-
-### Test pipeline
-
-```bash
-make test-docker # offline sandbox (build + unit + integration)
-```
-
-### Interactive playground
-
-```bash
-make playground # start + enter shell (one step)
-make playground-down # stop and remove
-
-# Advanced sandbox management:
-./scripts/sandbox.sh
-```
-
-Inside the playground:
-
-```bash
-skillshare status # global mode (pre-initialized)
-skillshare list # see flat + nested skills
-skillshare-ui # start global-mode dashboard (:19420)
-
-# Project mode (pre-configured demo project)
-cd ~/demo-project
-skillshare status # auto-detects project mode
-skillshare-ui-p # project mode dashboard (:19420)
-```
-
-### Dev profile
-
-```bash
-# With Go installed locally (single command):
-make ui-dev # Go API server + Vite HMR together
-
-# Without Go (API in Docker):
-make dev-docker # Go API server in Docker (:19420)
-cd ui && pnpm run dev # Vite dev server on host (:5173)
-make dev-docker-down # stop when done
-```
-
-### Production image
-
-```bash
-make docker-build # build production image
-make docker-build-multiarch # build for amd64 + arm64
-```
-
-Pre-built images are published to [GitHub Packages](https://github.com/runkids/skillshare/pkgs/container/skillshare) on each release.
-
-## Development
-
-**Recommended:** Open in [Dev Containers](https://containers.dev/) — Go toolchain, Node.js, pnpm, and demo content are pre-configured. All dev servers (API, Vite, Docusaurus) start automatically.
-
-```bash
-make build # build binary
-make test # unit + integration tests
-make lint # go vet
-make fmt # format Go files
-make check # fmt + lint + test
-make ui-dev # Go API server + Vite HMR together
-make build-all # frontend + Go binary
-```
-
-### AI-Assisted Development
-
-This repo ships project-mode skills (`.skillshare/skills/`) that AI coding agents can use directly:
-
-| Skill | Purpose |
-|-------|---------|
-| `cli-e2e-test` | Run E2E tests in devcontainer from `ai_docs/tests/` runbooks |
-| `codebase-audit` | Cross-validate CLI flags, docs, tests, and targets |
-| `implement-feature` | TDD workflow with spec → tests → implement → E2E runbook |
-| `update-docs` | Sync website docs with recent code changes |
-| `changelog` | Generate CHANGELOG entries from commits |
-
-```bash
-skillshare sync -p # Install project skills for your AI agent
-```
-
-### Isolated Testing with `ssenv` (Devcontainer)
-
-Inside the devcontainer, use `ssenv` to create isolated skillshare environments for parallel testing:
-
-```bash
-ssnew demo && ssuse demo # Create and switch to isolated environment
-ss init && ss sync # Run commands without affecting main config
-ssback # Return to original environment
-ssls # List environments
-ssrm demo # Delete environment
-```
-
-## Documentation
-
-- Docs home: https://skillshare.runkids.cc/docs/
-- 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
+[All commands & guides →](https://skillshare.runkids.cc/docs/reference/commands)
## Contributing
-Contributions are welcome! Here's the recommended workflow:
-
-1. **Open an issue first** — describe what you'd like to change and why. This helps align on scope and approach before writing code.
-2. **Submit a draft PR** — if you'd like to propose an implementation, open a [draft pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests) and link it to the issue. Draft PRs let us collaborate on the approach early, before investing time in polish.
-3. **Include tests** — PRs that include test coverage are much easier to review and merge. Run `make check` (format + lint + test) to verify before submitting.
+Contributions welcome! Open an issue first, then submit a draft PR with tests.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup details.
```bash
-git clone https://github.com/runkids/skillshare.git
-cd skillshare
-make check # format + lint + test (must pass)
+git clone https://github.com/runkids/skillshare.git && cd skillshare
+make check # format + lint + test
```
-Or open in [Dev Containers](https://containers.dev/) for a zero-setup environment.
-
> [!TIP]
-> Not sure where to start? Browse [open issues](https://github.com/runkids/skillshare/issues) or open a new one to discuss your idea.
+> Not sure where to start? Browse [open issues](https://github.com/runkids/skillshare/issues) or try the [Playground](https://skillshare.runkids.cc/docs/learn/with-playground) for a zero-setup dev environment.
## Contributors
-Thanks to everyone who helped shape skillshare through issues, PRs, and ideas.
+Thanks to everyone who helped shape skillshare.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
---
diff --git a/website/docs/learn/with-ai-coding-agents.md b/website/docs/learn/with-ai-coding-agents.md
new file mode 100644
index 000000000..a39ce9366
--- /dev/null
+++ b/website/docs/learn/with-ai-coding-agents.md
@@ -0,0 +1,46 @@
+---
+sidebar_position: 7
+---
+
+# AI-Assisted Development
+
+> Use AI coding agents to contribute to skillshare with pre-built project skills.
+
+## Prerequisites
+
+- An AI coding agent (Claude Code, Codex, etc.)
+- The skillshare repository cloned locally
+
+## Setup
+
+The repo ships project-mode skills in `.skillshare/skills/`. Sync them to your agent:
+
+```bash
+skillshare sync -p
+```
+
+Your AI agent now has access to specialized skills for working on this codebase.
+
+## Available Skills
+
+| Skill | What it does |
+|-------|-------------|
+| `implement-feature` | Implement a feature from a spec file or description using TDD workflow |
+| `update-docs` | Update website docs to match recent code changes, cross-validating every flag against source |
+| `codebase-audit` | Cross-validate CLI flags, docs, tests, and targets for consistency across the codebase |
+| `cli-e2e-test` | Run isolated E2E tests in devcontainer from runbooks |
+| `changelog` | Generate a CHANGELOG.md entry from recent commits in conventional format |
+
+## Typical Workflow
+
+1. **Start a feature** — ask your agent to use `implement-feature` with a spec
+2. **Update docs** — after code changes, invoke `update-docs` to sync website docs
+3. **Audit consistency** — run `codebase-audit` to catch flag/doc mismatches
+4. **Run E2E tests** — use `cli-e2e-test` to verify in a sandbox
+5. **Write changelog** — invoke `changelog` before release
+
+## What's Next?
+
+- [Dev Containers setup →](/docs/learn/with-devcontainer)
+- [Interactive Playground →](/docs/learn/with-playground)
+- [Contributing guide →](https://github.com/runkids/skillshare/blob/main/CONTRIBUTING.md)
diff --git a/website/docs/learn/with-devcontainer.md b/website/docs/learn/with-devcontainer.md
index 5930a10b3..d5eb483b9 100644
--- a/website/docs/learn/with-devcontainer.md
+++ b/website/docs/learn/with-devcontainer.md
@@ -56,6 +56,26 @@ Now every team member gets the same skills when they open the container.
The same `.devcontainer/` config works in Codespaces with no changes. Codespaces runs `postCreateCommand` the same way VS Code does.
+## Isolated Testing with ssenv
+
+Inside the devcontainer, `ssenv` lets you create isolated skillshare environments for parallel testing. Each environment gets its own `HOME` directory with separate config, skills, and targets.
+
+| Command | What it does |
+|---------|-------------|
+| `ssnew ` | Create a new isolated environment |
+| `ssuse ` | Switch to an environment |
+| `ssback` | Return to the original environment |
+| `ssls` | List all environments |
+| `ssrm ` | Delete an environment |
+
+```bash
+ssnew demo && ssuse demo # Create and switch
+ss init && ss sync # Commands run in isolation
+ssback # Return to original
+```
+
+This is useful for testing config changes or skill installations without affecting your main setup.
+
## What's Next?
- [Project skill setup →](/docs/how-to/sharing/project-setup)
diff --git a/website/sidebars.ts b/website/sidebars.ts
index 1b807fb07..7c654973c 100644
--- a/website/sidebars.ts
+++ b/website/sidebars.ts
@@ -22,6 +22,7 @@ const sidebars: SidebarsConfig = {
'learn/with-multiple-tools',
'learn/with-devcontainer',
'learn/with-playground',
+ 'learn/with-ai-coding-agents',
],
},
],