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 @@

Website License: MIT - Go Version Release Platform Go Report Card @@ -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 | |---|---| -| CLI sync output | CLI install with security audit | - -### UI +| CLI sync output | CLI install with security audit | | Dashboard | Security Audit | |---|---| -| Web dashboard overview | Web UI security audit | +| Web dashboard overview | Web UI 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. -leeeezx -Vergil333 -romanr -xocasdashdash -philippe-granet -terranc -benrfairless -nerveband -EarthChen -gdm257 -skovtunenko -TyceHerrman -1am2syman -thealokkr +leeeezx +Vergil333 +romanr +xocasdashdash +philippe-granet +terranc +benrfairless +nerveband +EarthChen +gdm257 +skovtunenko +TyceHerrman +1am2syman +thealokkr --- 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', ], }, ],