mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-20 20:34:19 +00:00
The CLI and dashboard update a tracked repo through update.TrackedRepo, which never looked for submodules. A pull that turned a skill directory into a submodule reported success and the skill vanished on the next sync. TrackedRepoResult now carries the skipped-submodule warnings and both callers show them. Refs #433
823 lines
32 KiB
Markdown
823 lines
32 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 |
|
||
| `--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-*`) |
|
||
| `--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, because a blocking audit finding would roll it back with `git reset --hard`. 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
|
||
|
||
**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 `..`.
|
||
|
||
```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`.
|
||
|
||
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`) are audited after `git pull`:
|
||
|
||
- 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
|
||
|
||
### `--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
|