mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-20 20:34:19 +00:00
* fix(update): audit tracked candidates before publication Prevent rejected tracked-update bytes from becoming readable through published target links by staging and auditing a private candidate before updating the active checkout. Publish the exact approved revision without a second upstream pull. Preserve sparse state, audit metadata, followed checkouts, and compatible edits. Recover staged and unstaged changes after failed forced publication, including deletions, renames, and sparse exclusions. Cover the boundary deterministically and align error messages and localized documentation. * fix(update): preserve local bytes across Git line-ending conversion Overlay dirty worktree bytes after staging candidate patches so core.autocrlf does not silently rewrite local edits. Cover staged, unstaged, and cancelled worktree changes while retaining their index state. Make permission-failure coverage explicitly POSIX-only and compare private checkout contents to their original bytes. Align red-team assertions with candidate rejection and register private temporary cleanup with the raw-write guard. * test(install): normalize checkout after configuring line endings Windows fixtures initially inherit core.autocrlf=true. Reset the isolated checkout after selecting the subtest setting so changing it to false does not turn untouched upstream files into local edits.
828 lines
33 KiB
Markdown
828 lines
33 KiB
Markdown
---
|
||
sidebar_position: 3
|
||
---
|
||
|
||
# install
|
||
|
||
Add skills from GitHub repos, git URLs, or local paths.
|
||
|
||
## Overview
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
INSTALL["install"] --> SOURCE["source"]
|
||
SOURCE --> SYNC1["sync"] --> TARGETS["targets"]
|
||
SOURCE --> UPDATE["update"]
|
||
SOURCE --> UNINSTALL["uninstall"] --> SYNC2["sync"] --> REMOVED["removed from targets"]
|
||
```
|
||
|
||
## When to Use
|
||
|
||
- Add a new skill from GitHub, GitLab, Bitbucket, Azure DevOps, or a local path
|
||
- Install an organization's shared skill repository (with `--track`)
|
||
- Re-install or update an existing skill (with `--update` or `--force`)
|
||
|
||
---
|
||
|
||
## Quick Examples
|
||
|
||
```bash
|
||
# From GitHub (shorthand)
|
||
skillshare install anthropics/skills/skills/pdf
|
||
|
||
# Browse available skills in a repo
|
||
skillshare install anthropics/skills
|
||
|
||
# From local path
|
||
skillshare install ~/Downloads/my-skill
|
||
|
||
# As tracked repo (for team sharing)
|
||
skillshare install github.com/team/skills --track
|
||
|
||
# Install into a subdirectory (organize by category)
|
||
skillshare install ~/my-skill --into frontend
|
||
|
||
# Install all skills from config (no arguments)
|
||
skillshare install
|
||
```
|
||
|
||
## Source Formats
|
||
|
||
### GitHub Shorthand
|
||
|
||
Use `owner/repo` format — automatically expands to `github.com/owner/repo`:
|
||
|
||
```bash
|
||
skillshare install anthropics/skills # Browse mode
|
||
skillshare install anthropics/skills/skills/pdf # Direct install
|
||
skillshare install ComposioHQ/awesome-claude-skills # Another repo
|
||
```
|
||
|
||
### GitLab / Bitbucket / Other Hosts
|
||
|
||
Use `domain/owner/repo` format for non-GitHub hosts:
|
||
|
||
```bash
|
||
skillshare install gitlab.com/user/repo # GitLab
|
||
skillshare install bitbucket.org/team/skills # Bitbucket
|
||
skillshare install git.company.com/team/skills # Self-hosted
|
||
```
|
||
|
||
Full URLs and SSH also work:
|
||
|
||
```bash
|
||
skillshare install https://gitlab.com/user/repo.git
|
||
skillshare install git@gitlab.com:user/repo.git
|
||
```
|
||
|
||
:::tip Self-managed GitLab on custom domains
|
||
Hosts containing `gitlab` or `jihulab` in the name are automatically detected with nested subgroup support. For other self-managed GitLab instances on custom domains (e.g., `git.company.com`), add the hostname to [`gitlab_hosts`](/docs/reference/targets/configuration#gitlab_hosts) in your config so skillshare treats the full URL path as the repository. Without config, you can append `.git` as a workaround: `git.company.com/team/frontend/ui.git`.
|
||
:::
|
||
|
||
### Azure DevOps
|
||
|
||
Use the `ado:` shorthand or full Azure DevOps URLs:
|
||
|
||
```bash
|
||
# Shorthand (ado:org/project/repo)
|
||
skillshare install ado:myorg/myproject/myrepo
|
||
skillshare install ado:myorg/myproject/myrepo/skills/react # With subdir
|
||
|
||
# Full HTTPS URL
|
||
skillshare install https://dev.azure.com/myorg/myproject/_git/myrepo
|
||
|
||
# Legacy format (auto-normalized)
|
||
skillshare install https://myorg.visualstudio.com/myproject/_git/myrepo
|
||
|
||
# SSH
|
||
skillshare install git@ssh.dev.azure.com:v3/myorg/myproject/myrepo
|
||
```
|
||
|
||
## Discovery Mode (Browse Skills)
|
||
|
||
When you don't specify a path, skillshare clones the repo, scans for skills, and presents an interactive picker:
|
||
|
||
```bash
|
||
skillshare install anthropics/skills
|
||
```
|
||
|
||
```text
|
||
$ skillshare install anthropics/skills
|
||
✓ Source github.com/anthropics/skills
|
||
Found 20 skills
|
||
|
||
? Install which skills?
|
||
› ○ academy-guide Complete terms in LICENSE.txt
|
||
○ algorithmic-art Complete terms in LICENSE.txt
|
||
○ brand-guidelines Complete terms in LICENSE.txt
|
||
○ canvas-design Complete terms in LICENSE.txt
|
||
○ claude-api Complete terms in LICENSE.txt
|
||
○ discernment-nudge
|
||
○ doc-coauthoring
|
||
○ docx Proprietary. LICENSE.txt has complete terms
|
||
…
|
||
|
||
↑↓ move · space toggle · ctrl+a all · enter confirm · / filter · esc cancel
|
||
```
|
||
|
||
Discovery scans all directories for `SKILL.md` files, skipping only `.git`. This means skills inside hidden directories like `.curated/` or `.system/` are discovered automatically. When multiple skills are found, the prompt lists skills from the same folder together and shows each one's description and folder; press `/` to narrow a long list.
|
||
|
||
If the repository contains a `.skillignore` file at its root, matching skills are automatically excluded from discovery. See [.skillignore](#skillignore) below.
|
||
|
||
If a skill's `SKILL.md` includes a `license:` frontmatter field, the license is shown in the selection prompt (e.g., `my-skill (MIT)`) and in the confirmation screen for single-skill installs.
|
||
|
||
**Tip**: Use `--dry-run` to preview without installing:
|
||
```bash
|
||
skillshare install anthropics/skills --dry-run
|
||
```
|
||
|
||
## Selective Install (Non-Interactive)
|
||
|
||
Pick specific skills from a multi-skill repo without prompts. The `--skill` flag supports **fuzzy matching** and **glob patterns** — if an exact name isn't found, it tries glob matching (`*`, `?`, `[...]`), then falls back to the closest substring match:
|
||
|
||
```bash
|
||
# Install specific skills by name (exact or fuzzy)
|
||
skillshare install anthropics/skills -s pdf,commit
|
||
|
||
# Install skills matching a glob pattern
|
||
skillshare install anthropics/skills -s "core-*"
|
||
|
||
# Install all discovered skills
|
||
skillshare install anthropics/skills --all
|
||
|
||
# Auto-accept (same as --all for multi-skill repos)
|
||
skillshare install anthropics/skills -y
|
||
|
||
# Combine with other flags
|
||
skillshare install anthropics/skills -s pdf --dry-run
|
||
skillshare install anthropics/skills --all -p
|
||
```
|
||
|
||
Glob matching is case-insensitive: `"Core-*"` matches `core-auth`, `CORE-DB`, etc.
|
||
|
||
:::tip Shell glob protection
|
||
Always quote glob patterns (`"core-*"`) to prevent your shell from expanding `*` into file names in the current directory.
|
||
:::
|
||
|
||
Useful for CI/CD pipelines and scripted workflows.
|
||
|
||
## Direct Install (Specific Path)
|
||
|
||
Provide the full path to install immediately:
|
||
|
||
```bash
|
||
# GitHub with subdirectory
|
||
skillshare install anthropics/skills/skills/pdf
|
||
skillshare install google-gemini/gemini-cli/packages/core/src/skills/builtin/skill-creator
|
||
|
||
# Fuzzy subdirectory — if exact path doesn't exist, matches by skill name
|
||
skillshare install runkids/my-skills/vue-best-practices
|
||
|
||
# Full URL
|
||
skillshare install github.com/user/repo/path/to/skill
|
||
|
||
# SSH URL
|
||
skillshare install git@github.com:user/repo.git
|
||
|
||
# SSH URL with subdirectory (use // separator)
|
||
skillshare install git@github.com:user/repo.git//path/to/skill
|
||
|
||
# Local path
|
||
skillshare install ~/Downloads/my-skill
|
||
skillshare install /absolute/path/to/skill
|
||
```
|
||
|
||
A local path is copied into the source directory. In global mode, a relative path such as `./my-skill` is recorded as an absolute path, so `update` and [`check`](./check.md#local-path-installs) find it from any directory. In project mode it is recorded as written, because `.skillshare/config.yaml` is shared across machines.
|
||
|
||
:::tip Fuzzy subdirectory resolution
|
||
When specifying a subdirectory path like `owner/repo/skill-name`, if the exact path doesn't exist in the repo, skillshare scans all `SKILL.md` files and matches by directory basename. If multiple skills share the same name, an ambiguity error is shown with full paths so you can specify the exact one.
|
||
:::
|
||
|
||
:::note Git submodules are not fetched
|
||
skillshare does not fetch git submodules. Installing a path that is a submodule, or lies inside one, fails with an error that names the submodule, its pinned commit, and its upstream URL; install from that upstream repository instead, or copy the files into the hub. When you browse a whole repository, `install`, `--track` and `update` warn about each submodule they skip.
|
||
:::
|
||
|
||
## Install from Config (No Arguments) {#install-from-config-no-arguments}
|
||
|
||
When run without a source argument, `skillshare install` reads the recorded remote skill metadata (global mode) or the project `skills:` manifest (project mode) and installs all remote skills that don't already exist locally:
|
||
|
||
```bash
|
||
# Global — reads ~/.config/skillshare/config.yaml
|
||
skillshare install
|
||
|
||
# Project — reads .skillshare/config.yaml
|
||
skillshare install -p
|
||
```
|
||
|
||
This makes the recorded metadata/manifest a **portable skill setup** — share it to reproduce the same skills on any machine:
|
||
|
||
```bash
|
||
# New machine setup
|
||
skillshare install # Rehydrates remote skills and tracked repos from metadata
|
||
skillshare sync # Sync to targets
|
||
|
||
# New team member onboarding
|
||
git clone github.com/team/project && cd project
|
||
skillshare install -p # Install all remote skills from project config
|
||
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. This is the recovery command to run after a fresh clone when tracked repo directories were gitignored and are missing locally.
|
||
|
||
:::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/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.
|
||
|
||
## Project Mode
|
||
|
||
Install skills into a project's `.skillshare/skills/` directory:
|
||
|
||
```bash
|
||
# Install a skill into the project
|
||
skillshare install anthropics/skills/skills/pdf -p
|
||
|
||
# Install into a subdirectory within the project
|
||
skillshare install anthropics/skills -s pdf --into tools -p
|
||
# → .skillshare/skills/tools/pdf/
|
||
|
||
# Install all remote skills from config (for new team members)
|
||
skillshare install -p
|
||
```
|
||
|
||
:::caution Don't install the project root into itself
|
||
In project mode, installing a local path that resolves to the project root (e.g. `skillshare install ./ -p`) is rejected — copying the root into its own `.skillshare/skills/` subtree would recurse into the destination. Point at a specific skill subdirectory instead:
|
||
|
||
```bash
|
||
skillshare install ./my-skill -p
|
||
```
|
||
|
||
This guard applies to both the CLI and the Web UI ([`skillshare ui`](./ui.md)).
|
||
:::
|
||
|
||
### How It Differs
|
||
|
||
| | Global | Project (`-p`) |
|
||
|---|---|---|
|
||
| Destination | `~/.config/skillshare/skills/` | `.skillshare/skills/` |
|
||
| `--track` | Supported | Supported |
|
||
| Config update | Auto-reconciles `config.yaml` `skills:` | Auto-reconciles `.skillshare/config.yaml` `skills:` |
|
||
| No-arg install | Installs all skills listed in config | Installs all skills listed in config |
|
||
|
||
**Tracked repos in project mode** work the same as global — the repo is cloned with `.git` preserved and added to `.skillshare/.gitignore` (which also ignores `.skillshare/logs/` and `.skillshare/trash/` by default). The `tracked: true` flag is auto-recorded in `.skillshare/config.yaml`:
|
||
|
||
```bash
|
||
skillshare install github.com/team/skills --track -p
|
||
skillshare sync
|
||
```
|
||
|
||
See [Project Setup](/docs/how-to/sharing/project-setup) for the full guide.
|
||
|
||
## Options
|
||
|
||
| Flag | Short | Description |
|
||
|------|-------|-------------|
|
||
| `--name <name>` | | Override installed name when exactly one skill is installed |
|
||
| `--into <dir>` | | Install into subdirectory (e.g. `--into frontend` or `--into frontend/react`) |
|
||
| `--force` | `-f` | Overwrite existing skill; override audit blocking and cross-path duplicate check |
|
||
| `--update` | `-u` | Update if exists (git pull or reinstall) |
|
||
| `--branch <ref>` | `-b` | Git branch, tag, or commit SHA to install from (default: remote default branch) |
|
||
| `--track` | `-t` | Keep `.git` for tracked repos. Cannot combine with `--all`, `--yes`, `--skill`, or `--agent`. |
|
||
| `--kind <skill\|agent>` | | Limit install to one resource kind |
|
||
| `--agent <names>` | `-a` | Select specific agents from a repo (comma-separated) |
|
||
| `--skill` | `-s` | Select specific skills from multi-skill repo (comma-separated; supports glob patterns like `core-*`). Rejects `--all` and `--yes`. |
|
||
| `--exclude` | | Skip specific skills during install (comma-separated; supports glob patterns like `test-*`) |
|
||
| `--all` | | Install all discovered skills without prompting |
|
||
| `--yes` | `-y` | Auto-accept all prompts (CI/CD friendly) |
|
||
| `--skip-audit` | | Skip security audit for this install |
|
||
| `--audit-threshold <t>`, `--threshold <t>` | `-T` | Override audit block threshold for this command (`critical|high|medium|low|info`; shorthand: `c|h|m|l|i`, plus `crit`, `med`) |
|
||
| `--audit-verbose` | | Show full audit findings per skill (default: compact summary) |
|
||
| `--project` | `-p` | Install into project `.skillshare/skills/` |
|
||
| `--global` | `-g` | Install into global `~/.config/skillshare/skills/` |
|
||
| `--dry-run` | `-n` | Preview only |
|
||
| `--json` | | Output as JSON (implies `--force`; also implies non-interactive selection when no `--skill`/`--agent` filter is given) |
|
||
|
||
## JSON Output
|
||
|
||
```bash
|
||
skillshare install anthropics/skills --json
|
||
```
|
||
|
||
```json
|
||
{
|
||
"source": "anthropics/skills",
|
||
"tracked": false,
|
||
"dry_run": false,
|
||
"skills": ["pdf", "commit", "review"],
|
||
"failed": [],
|
||
"duration": "2.345s"
|
||
}
|
||
```
|
||
|
||
When `--into` is used, the `into` field is included:
|
||
|
||
```bash
|
||
skillshare install anthropics/skills --json --into frontend
|
||
```
|
||
|
||
```json
|
||
{
|
||
"source": "anthropics/skills",
|
||
"tracked": false,
|
||
"dry_run": false,
|
||
"into": "frontend",
|
||
"skills": ["pdf", "commit"],
|
||
"failed": [],
|
||
"duration": "1.890s"
|
||
}
|
||
```
|
||
|
||
For agent-only installs, the JSON output still uses the `skills` array to report installed names:
|
||
|
||
```bash
|
||
skillshare install github.com/user/agents --kind agent --json
|
||
```
|
||
|
||
```json
|
||
{
|
||
"source": "github.com/user/agents",
|
||
"tracked": false,
|
||
"dry_run": false,
|
||
"skills": ["reviewer", "tutor"],
|
||
"failed": [],
|
||
"duration": "1.234s"
|
||
}
|
||
```
|
||
|
||
## Duplicate Detection
|
||
|
||
skillshare automatically detects when you're about to install something that already exists:
|
||
|
||
### Same-repo reinstall
|
||
|
||
If a skill already exists and was installed from the **same repo**, skillshare skips it with a warning instead of failing:
|
||
|
||
```bash
|
||
skillshare install anthropics/skills/skills/pdf
|
||
# ✓ Installed pdf
|
||
|
||
skillshare install anthropics/skills/skills/pdf
|
||
# ⊘ pdf — already installed from same repo
|
||
```
|
||
|
||
Use `--update` to refresh, or `--force` to overwrite.
|
||
|
||
`--update` on a tracked repo behind a [followed source link](../targets/configuration.md#follow_source_links) refuses to pull while that checkout has uncommitted changes. Commit or stash first.
|
||
|
||
### Cross-path duplicate
|
||
|
||
If a repo is already installed at one location and you try to install it at a **different** location, skillshare blocks the operation:
|
||
|
||
```bash
|
||
# First install (into a subdirectory)
|
||
skillshare install runkids/feature-radar --into feature-radar
|
||
|
||
# Later, forget about the first install
|
||
skillshare install runkids/feature-radar
|
||
# ✗ this repo is already installed at skills/feature-radar/scan (and 2 more)
|
||
# Use 'skillshare update' to refresh, or reinstall with --force to allow duplicates
|
||
```
|
||
|
||
This prevents accidental duplicates across different paths. Use `--force` to allow it intentionally.
|
||
|
||
### Conflict with different repo
|
||
|
||
If the destination directory exists but was installed from a **different** repo, the error message includes the original source:
|
||
|
||
```bash
|
||
skillshare install owner/repo-b --name my-skill
|
||
# ✗ my-skill already exists (installed from https://github.com/owner/repo-a.git).
|
||
# To overwrite: skillshare install owner/repo-b --name my-skill --force
|
||
```
|
||
|
||
The `--force` hint always includes the correct flags (including `--into` if applicable).
|
||
|
||
## Common Scenarios
|
||
|
||
**Default install names:** Skills keep their directory name. If that name is the generic `skill` or `skills`, a valid `SKILL.md` frontmatter `name` is used instead, lowercased with spaces normalized to hyphens (for example, `MinerU Document Extractor` → `mineru-document-extractor`). Missing, invalid, or conflicting frontmatter names fall back to the directory name. `--name` overrides this default. Updates preserve existing install names, and `--track` keeps its existing repository naming.
|
||
|
||
**Install with custom name:**
|
||
```bash
|
||
skillshare install google-gemini/gemini-cli/.../skill-creator --name my-creator
|
||
# Installed as: ~/.config/skillshare/skills/my-creator/
|
||
```
|
||
|
||
`--name` only works when install resolves to a single skill.
|
||
In `--track` mode, custom names are stored as tracked repo directories (auto-prefixed with `_`) and must not contain path separators or `..`.
|
||
`--track` accepts a local path when that path is the root of a git repository (it is cloned like `file:///path`); for any other local folder, install it without `--track`. With `--track --force`, the existing tracked repo is replaced only after the new clone succeeds, so a failed reinstall keeps the old one; a local source (path or `file://` URL) that is, or lies inside, that tracked repo is refused.
|
||
|
||
```bash
|
||
# ✅ Single skill (works)
|
||
skillshare install comeonzhj/Auto-Redbook-Skills --name haha
|
||
|
||
# ❌ Multiple discovered skills (errors)
|
||
skillshare install anthropics/skills --name my-skill
|
||
```
|
||
|
||
**Force overwrite existing:**
|
||
```bash
|
||
skillshare install ~/my-skill --force
|
||
```
|
||
|
||
**Update existing skill:**
|
||
```bash
|
||
# By skill name (uses stored source)
|
||
skillshare install pdf --update
|
||
|
||
# By source URL
|
||
skillshare install anthropics/skills/skills/pdf --update
|
||
```
|
||
|
||
**Install into a subdirectory:**
|
||
```bash
|
||
# Organize by category
|
||
skillshare install ~/my-skill --into frontend
|
||
# → ~/.config/skillshare/skills/frontend/my-skill/
|
||
|
||
# Multi-level nesting
|
||
skillshare install anthropics/skills -s pdf --into frontend/react
|
||
# → ~/.config/skillshare/skills/frontend/react/pdf/
|
||
|
||
# After sync, target shows flat name: frontend__my-skill, frontend__react__pdf
|
||
```
|
||
|
||
See [Organizing Skills](/docs/how-to/daily-tasks/organizing-skills) for folder strategies.
|
||
|
||
**Install from a specific branch:**
|
||
```bash
|
||
# Regular install from a branch
|
||
skillshare install github.com/team/skills --branch develop --all
|
||
|
||
# Track a specific branch
|
||
skillshare install github.com/team/skills --track --branch frontend
|
||
|
||
# Same repo, different branches (use --name to avoid collision)
|
||
skillshare install github.com/team/skills --track --branch frontend --name team-frontend
|
||
skillshare install github.com/team/skills --track --branch backend --name team-backend
|
||
```
|
||
|
||
**Pin to a tag or commit SHA (reproducible installs):**
|
||
```bash
|
||
# Pin to a release tag
|
||
skillshare install github.com/team/skills --branch v1.2.0 --all
|
||
|
||
# Pin to an exact commit (full or abbreviated SHA)
|
||
skillshare install github.com/team/skills --branch 8f14e45fceea167a5a36dedd4bea2543ce848564 --all
|
||
```
|
||
|
||
A web URL pins the same way: `skillshare install github.com/team/skills/tree/v1.2.0/skills/foo` installs from tag `v1.2.0`. GitLab (`-/tree/<ref>/`) and Bitbucket (`src/<ref>/`) URLs work too. Branch names containing `/`, such as `tree/feature/x/skills/foo`, are matched against the remote's branches and tags. A ref the remote no longer has, such as `tree/master/` after a rename to `main`, fails the install instead of falling back to the default branch. `tree/HEAD/` links, which GitHub uses for the default branch, install from the remote's default branch. An explicit `--branch` overrides the ref in the URL.
|
||
|
||
In a project you usually do not need this: `.skillshare/skills.lock.json` already pins every remote skill to the commit it was installed from, and `skillshare update` moves the pin. See [Lockfile](/docs/understand/project-skills#lockfile).
|
||
|
||
The pinned ref is stored in skill metadata, so `skillshare update` reinstalls the same revision and `skillshare check` reports a SHA pin as up to date without contacting the remote. `--track` requires a branch: a tag or commit SHA leaves the clone detached with nothing for `skillshare update` to pull, so the install is rejected.
|
||
|
||
**Install team repo (tracked):**
|
||
```bash
|
||
skillshare install addyosmani/web-quality-skills --track --name team-skills
|
||
```
|
||
|
||
```text
|
||
$ skillshare install addyosmani/web-quality-skills --track --name team-skills
|
||
✓ Source github.com/addyosmani/web-quality-skills
|
||
Found 6 skills
|
||
Skills accessibility, best-practices, core-web-vitals, performance, seo, web-quality-audit
|
||
! Audit 63 findings: HIGH=1, MEDIUM=1, LOW=60, INFO=1 — findings detected, but none at/above block threshold (CRITICAL) · risk CRITICAL (100/100)
|
||
✓ Install _team-skills → ~/.config/skillshare/skills/_team-skills · 1.9s
|
||
|
||
Next
|
||
skillshare sync link them into your targets
|
||
skillshare update _team-skills update this repo later
|
||
```
|
||
|
||
## Private Repositories {#private-repositories}
|
||
|
||
### SSH (recommended)
|
||
|
||
SSH is the simplest method — if your SSH key is configured, it just works:
|
||
|
||
```bash
|
||
skillshare install git@github.com:org/private-skills.git --track
|
||
skillshare install git@gitlab.com:org/skills.git --track
|
||
skillshare install git@bitbucket.org:team/skills.git --track
|
||
skillshare install git@ssh.dev.azure.com:v3/org/project/skills --track
|
||
|
||
# With subdirectory
|
||
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:
|
||
|
||
```bash
|
||
export GITHUB_TOKEN=ghp_your_token
|
||
skillshare install https://github.com/org/private-skills.git --track
|
||
```
|
||
|
||
| Platform | Env Var | Token Type |
|
||
|----------|---------|------------|
|
||
| GitHub | `GITHUB_TOKEN` | Personal access token (`repo` scope) |
|
||
| GitLab | `GITLAB_TOKEN` | Personal access or CI job token |
|
||
| Bitbucket | `BITBUCKET_TOKEN` | Repository token, or app password (with `BITBUCKET_USERNAME`) |
|
||
| Azure DevOps | `AZURE_DEVOPS_TOKEN` | Personal Access Token (Code: Read scope) |
|
||
| Gitea | `GITEA_TOKEN` | Access token (repository: Read) |
|
||
| CNB | `CNB_TOKEN` | Access token with repository read permission |
|
||
| Any host | `SKILLSHARE_GIT_TOKEN` | Generic fallback |
|
||
|
||
Platform-specific variables take priority over `SKILLSHARE_GIT_TOKEN`.
|
||
|
||
The token reaches git through a credential helper scoped to the host, so it never appears in process arguments such as `ps` output. While a token applies to a host, git does not ask your own credential helper or keychain for that host and stores nothing there.
|
||
|
||
Official token documentation:
|
||
- GitHub: [Managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
|
||
- GitLab: [Token overview](https://docs.gitlab.com/security/tokens/)
|
||
- Bitbucket: [Access tokens](https://support.atlassian.com/bitbucket-cloud/docs/access-tokens/)
|
||
- Azure DevOps: [Use Personal Access Tokens](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops)
|
||
|
||
For Bitbucket app passwords, also set your username:
|
||
|
||
```bash
|
||
export BITBUCKET_USERNAME=your_bitbucket_username
|
||
export BITBUCKET_TOKEN=your_app_password
|
||
skillshare install https://bitbucket.org/team/skills.git --track
|
||
```
|
||
|
||
### CI/CD Examples
|
||
|
||
**GitHub Actions:**
|
||
|
||
```yaml
|
||
- name: Install shared skills
|
||
env:
|
||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||
run: skillshare install https://github.com/org/skills.git --track
|
||
```
|
||
|
||
**GitLab CI:**
|
||
|
||
```yaml
|
||
install-skills:
|
||
script:
|
||
- skillshare install https://gitlab.com/org/skills.git --track
|
||
variables:
|
||
GITLAB_TOKEN: $CI_JOB_TOKEN
|
||
```
|
||
|
||
**Bitbucket Pipelines:**
|
||
|
||
```yaml
|
||
- step:
|
||
name: Install shared skills
|
||
script:
|
||
- skillshare install https://bitbucket.org/team/skills.git --track
|
||
env:
|
||
BITBUCKET_USERNAME: $BITBUCKET_USERNAME # for app passwords
|
||
BITBUCKET_TOKEN: $BITBUCKET_TOKEN
|
||
```
|
||
|
||
**Azure Pipelines:**
|
||
|
||
```yaml
|
||
- script: skillshare install https://dev.azure.com/org/project/_git/skills --track
|
||
env:
|
||
AZURE_DEVOPS_TOKEN: $(System.AccessToken)
|
||
```
|
||
|
||
## Security Scanning
|
||
|
||
Every skill is automatically scanned for security threats during installation:
|
||
|
||
- Findings at or above `audit.block_threshold` **block installation** (default: `CRITICAL`)
|
||
- Lower findings are shown as warnings and include risk score context
|
||
- `audit.block_threshold` only controls block level; it does **not** disable scanning
|
||
- There is no config switch to always skip audit; use `--skip-audit` per command when needed
|
||
- You can override threshold per command with `--audit-threshold`, `--threshold`, or `-T`
|
||
|
||
Threshold config example:
|
||
|
||
```yaml
|
||
audit:
|
||
block_threshold: HIGH
|
||
```
|
||
|
||
```bash
|
||
# Blocked — critical threat detected
|
||
skillshare install evil-skill
|
||
# → Installation blocked at active threshold. Use --force to override.
|
||
|
||
# Force install despite warnings
|
||
skillshare install suspicious-skill --force
|
||
|
||
# Skip scan entirely (use with caution)
|
||
skillshare install suspicious-skill --skip-audit
|
||
|
||
# Per-command threshold override (same meaning)
|
||
skillshare install suspicious-skill --audit-threshold high
|
||
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/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.
|
||
|
||
### Tracked Repo Audit Gate (`--track`)
|
||
|
||
Tracked repos use the same threshold model, but the scan scope and failure handling are stricter:
|
||
|
||
- Fresh `--track` install scans the **entire cloned repository** (not just one skill folder)
|
||
- Findings at/above threshold block install unless `--force` is used
|
||
- On blocked fresh install, skillshare automatically removes the cloned repo from source
|
||
- If automatic cleanup fails, install returns an explicit error and tells you to remove the path manually
|
||
|
||
Tracked repo updates through install (`skillshare install <repo> --track --update`) use the same isolated-candidate audit gate:
|
||
|
||
- Pull and audit happen in a temporary checkout, not the active source directory
|
||
- Rejection or a scan error leaves the active checkout and metadata unchanged
|
||
- Approval publishes the exact audited commit without another upstream pull
|
||
- `--force` can override findings, but cannot override a scan error
|
||
|
||
### `--force` vs `--skip-audit`
|
||
|
||
Both can unblock installation, but they do different things:
|
||
|
||
| Flag | Audit execution | What happens |
|
||
|------|------------------|--------------|
|
||
| `--force` | Audit still runs | Findings are still generated/logged; install continues even if threshold is hit |
|
||
| `--skip-audit` | Audit is skipped | No scan is performed for this install |
|
||
|
||
Recommended usage:
|
||
|
||
- Prefer `--force` when you still want visibility into findings.
|
||
- Use `--skip-audit` only when you intentionally need to bypass scanning.
|
||
- If both are set, `--skip-audit` takes precedence in practice (scan is skipped).
|
||
|
||
## Excluding Skills {#excluding-skills}
|
||
|
||
### `--exclude` flag
|
||
|
||
Skip specific skills when installing from a multi-skill repo. Supports both exact names and **glob patterns**:
|
||
|
||
```bash
|
||
# Install all except specific skills
|
||
skillshare install anthropics/skills --all --exclude cli-sentry,delayed-command
|
||
|
||
# Exclude by glob pattern
|
||
skillshare install anthropics/skills --all --exclude "test-*"
|
||
|
||
# Works with -y too
|
||
skillshare install org/skills -y --exclude internal-tool
|
||
|
||
# Combine with --skill for fine-grained control
|
||
skillshare install org/skills -s pdf,commit,docs --exclude docs
|
||
```
|
||
|
||
When skills are excluded, a message shows what was skipped: `Excluded 2 skills: cli-sentry, delayed-command`.
|
||
|
||
:::note Requires multi-skill discovery
|
||
`--exclude` only works when installing from a **git repo** that contains multiple skills. It works with `--all`, `--yes`, `--skill`, and interactive selection modes. For direct installs (local paths or single-skill git URLs), `--exclude` is not applicable — a warning is shown if specified.
|
||
:::
|
||
|
||
### .skillignore {#skillignore}
|
||
|
||
Repository maintainers can create a `.skillignore` file at the repo root to hide skills from discovery. Users installing from the repo will never see these skills in the selection prompt.
|
||
|
||
```text title=".skillignore"
|
||
# Internal tooling — not for public use
|
||
validation-scripts
|
||
scaffold-template
|
||
|
||
# Exclude all test/eval skills
|
||
prompt-eval-*
|
||
|
||
# Exclude an entire group directory
|
||
internal-tools
|
||
```
|
||
|
||
**Real-world example** — [`runkids/my-skills`](https://github.com/runkids/my-skills) uses `.skillignore` to exclude non-skill directories and internal tooling:
|
||
|
||
```text title=".skillignore"
|
||
skillshare
|
||
feature-radar
|
||
```
|
||
|
||
Combined with `--exclude`, users can further narrow the selection:
|
||
|
||
```bash
|
||
skillshare install runkids/my-skills --exclude seo
|
||
```
|
||
|
||
**Format** — uses [gitignore syntax](https://git-scm.com/docs/gitignore):
|
||
|
||
| Pattern | Example | Behavior |
|
||
|---------|---------|----------|
|
||
| Exact name | `validation-scripts` | Matches a skill at that path |
|
||
| Group match | `feature-radar` | Matches **all** skills under `feature-radar/` |
|
||
| Precise path | `feature-radar/feature-radar` | Only that specific skill |
|
||
| `*` wildcard | `prompt-eval-*` | Matches one segment (does not cross `/`) |
|
||
| `**` | `**/temp` | Matches at any directory depth |
|
||
| `?` | `?.md` | Matches a single character |
|
||
| `[abc]` | `[Tt]est` | Character class |
|
||
| `!pattern` | `!important` | Negation — un-ignore a previously matched skill |
|
||
| `/pattern` | `/root-only` | Anchored to the `.skillignore` location |
|
||
| `pattern/` | `build/` | Directory-only match |
|
||
| `\#`, `\!` | `\#file` | Escaped literal characters |
|
||
|
||
Lines starting with `#` are comments. Empty lines are ignored.
|
||
|
||
**Recommended scenarios:**
|
||
- Publishing a multi-skill repository while hiding internal tools or work-in-progress skills
|
||
- Using a monorepo with grouped skill directories and excluding an entire group (for example, `internal-tools`)
|
||
- Enforcing maintainer-level visibility rules so all installers never discover certain skills
|
||
|
||
**Not a fit:**
|
||
- Direct local-path installs (these skip discovery)
|
||
- Single-skill direct installs (similar to `--exclude`, which is ignored for direct install paths)
|
||
|
||
`.skillignore` is applied during git repo discovery, so it affects all discovery-based install paths: `--all`, `--skill`, `--yes`, and interactive selection. It does **not** apply to direct local-path installs (which skip discovery entirely).
|
||
|
||
:::tip .skillignore scope
|
||
**Repo-level** `.skillignore` (in a repository root) controls which skills are discoverable when users install from your repo. After installation, tracked repos retain their `.skillignore` — it is also respected by `doctor`, `status`, `list`, `sync`, `audit`, `diff`, and `check`.
|
||
|
||
**Source-root** `.skillignore` (`~/.config/skillshare/skills/.skillignore`) applies globally to all skills — tracked and non-tracked. Use it to temporarily mute skills or exclude patterns (e.g., `draft-*`) without uninstalling.
|
||
:::
|
||
|
||
### `.skillignore` vs `--exclude`
|
||
|
||
| | `.skillignore` | `--exclude` |
|
||
|---|---|---|
|
||
| **Who controls it** | Repo maintainer | Installing user |
|
||
| **Where it lives** | `.skillignore` in repo root | CLI flag |
|
||
| **When it applies** | During discovery (before selection) | After discovery (before prompt) |
|
||
| **Scope** | All users installing from this repo | This install only |
|
||
| **Requires** | Git repo with multiple skills | Git repo with multiple skills |
|
||
|
||
## Agent Support
|
||
|
||
When installing a repository, skillshare auto-detects agents (standalone `.md` files) alongside skills:
|
||
|
||
- If the repo contains an `agents/` directory, `.md` files inside are discovered as agent candidates
|
||
- If the repo has both `skills/` and `agents/`, both are installed
|
||
- If the repo has only loose `.md` files at root (no `SKILL.md`), they are treated as agents
|
||
|
||
### Explicit agent flags
|
||
|
||
```bash
|
||
# Install only agents from a repo
|
||
skillshare install github.com/user/repo --kind agent
|
||
|
||
# Install specific agents by name (-a shorthand)
|
||
skillshare install github.com/user/repo -a tutor,reviewer
|
||
|
||
# Combine with project mode
|
||
skillshare install github.com/user/repo --kind agent -p
|
||
```
|
||
|
||
The `-a <name>` flag is the agent equivalent of `-s <name>` for skills. Agents are installed into `~/.config/skillshare/agents/` (global) or `.skillshare/agents/` (project). See [Agents](/docs/understand/agents) for the full concepts.
|
||
|
||
### Scoping skills vs agents in a mixed repo
|
||
|
||
When a repo contains both skills and agents, the filters control exactly what is installed:
|
||
|
||
| Flags | What gets installed |
|
||
|-------|---------------------|
|
||
| _(none)_ | All skills and all agents |
|
||
| `--all` / `--yes` | All skills and all agents |
|
||
| `-s <names>` | Only the named skills — **no agents** |
|
||
| `-s <names> -a <names>` | The named skills and the named agents |
|
||
| `-a <names>` | Only the named agents |
|
||
|
||
```bash
|
||
# Install just one skill from a mixed repo — agents are NOT pulled in
|
||
skillshare install github.com/user/repo -s pdf
|
||
|
||
# Install one skill and one agent together
|
||
skillshare install github.com/user/repo -s pdf -a tutor
|
||
```
|
||
|
||
An unknown `-a` name fails the whole command up front — before any skill is installed — so automation never sees a half-completed install.
|
||
|
||
## After Installing
|
||
|
||
Always sync to distribute to targets:
|
||
|
||
```bash
|
||
skillshare install anthropics/skills/skills/pdf
|
||
skillshare sync # ← Don't forget!
|
||
```
|
||
|
||
## See Also
|
||
|
||
- [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
|