mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-18 18:04:17 +00:00
tree/HEAD/ links now install from the default branch, but the install page did not say so. The built-in skill reference and the translated install and hub-index pages also lacked the pinned web URL behavior, so agents and non-English readers could not learn how to pin a skill or a hub entry to a tag or commit. Refs #293
834 lines
31 KiB
Markdown
834 lines
31 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
|
|
│
|
|
├─ Cloned (1.8s)
|
|
│
|
|
└─ Found 20 skill(s)
|
|
|
|
Select skills to install (0/20 selected)
|
|
|
|
▌ [ ] 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 (Complete terms in LICENSE.txt)
|
|
▌ [ ] doc-coauthoring
|
|
▌ [ ] docx (Proprietary. LICENSE.txt has complete terms)
|
|
…
|
|
|
|
20 skills
|
|
↑↓ navigate space toggle 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 selection prompt groups them by directory for easier browsing.
|
|
|
|
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
|
|
```
|
|
|
|
:::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.
|
|
:::
|
|
|
|
## 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.
|
|
|
|
### 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
|
|
│
|
|
├─ Name _team-skills
|
|
│
|
|
├─ Cloned (1.9s)
|
|
│
|
|
├─ Found 6 skill(s)
|
|
│
|
|
├─ Tracked _team-skills
|
|
│
|
|
├─ Skills accessibility, best-practices, core-web-vitals, performance, seo, web-quality-audit
|
|
│
|
|
└─ Location ~/.config/skillshare/skills/_team-skills
|
|
|
|
- Audit Findings
|
|
→ 63 finding(s): HIGH=1, MEDIUM=1, LOW=60, INFO=1 — findings detected, but none at/above block threshold (CRITICAL)
|
|
→ risk: CRITICAL (100/100)
|
|
|
|
- Next Steps
|
|
→ Run 'skillshare sync' to distribute skills to all targets
|
|
→ Run 'skillshare update _team-skills' to 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 skill(s): 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
|