Files
skillshare/website/docs/reference/commands/install.md
T
Rusty ShacklefordandWillie 85bcf589a7 feat(sync): recognize and route agent-specific skill variants (#649)
* docs(proposals): propose agent-specific skill variants

Tracked repositories can ship different files for the same skill across
agents. Counting and syncing each copy independently sends incompatible
instructions to every target unless users maintain routing filters.

Propose repository-scoped logical identity and exact variant routing while
preserving source files, explicit controls, and existing naming behavior.
Leave activation and compatibility decisions for maintainer review.

Refs #648

* docs(proposals): clarify variant routing compatibility

Explain how recognition affects universal-only targets and how existing
per-variant overrides preserve the desired routing. Fix the precedence
between variant identity and generic host-style path inference.

Include analyze, move, and catalog consumers while preserving physical
identifiers and actual context-cost accounting.

Refs #648

* docs(proposals): clarify activation assumptions and scope

Make acceptance cases conditional on maintainer-approved recognition being
enabled for the tracked source. Separate the provisional implementation
estimate from this proposal-only PR so its size is clear.

Refs #648

* docs(proposals): qualify naming and opt-in assumptions

State that the reproduced routing behavior uses default flat target
naming. Leave any opt-in surface with the maintainer's activation decision
without ruling out future CLI or config fields.

Refs #648

* feat: recognize and route tracked agent skill variants

Count tracked variants as logical skills in source and repository summaries,
while preserving physical paths, sync operations, and context costs. Select
matching canonical agent variants, including account targets, through shared
discovery and selection with existing explicit routing precedence.

Refs #648

* fix: count logical skills in sync inventory summaries

Use shared logical and physical inventory counts in global and project sync
closing lines while preserving each target's operation totals.

Refs #648

* fix: preserve variant routing diagnostics across previews

Resolve target selections once so CLI and server previews keep ambiguity
reasons and physical skip counts. Explain managed variants removed by
automatic agent routing, and report logical inventory in doctor.

Keep warning rows read-only, document upgrade recovery in translated
filtering references, and remove the optional README-only addition.

Refs #648

* fix: align sync matrix previews with shared variant selection

Classify the full source selection once per target so matrix previews honor
canonical aliases, account identity, exact-agent routing, and ambiguous
variant skips. Preserve each rejected physical path's existing diagnostic
and draft filter disambiguation; skipped preview rows remain read-only.

Refs #648

* test: expect singular skill wording in doctor source checks

Keep the undiscovered-link count assertion aligned with logical source
inventory formatting for one skill in global and project mode.

Refs #648

* fix: retain selection diagnostics in catalog and diff verdicts

Report warning-only diff targets as requiring attention while preserving
local-only folder semantics. Reuse shared per-path selection diagnostics
in target-scoped catalogs without applying target naming to served paths.

Compute source counts once in summary callers and require variant counts
in the source status formatter.

Refs #648

* test: tighten tracked variant preview fixtures

Use a real committed tracked repository for status counts, verify sync
preview banners retain server warnings, and use emitted ambiguity reason
text in target preview fixtures.

Refs #648

* fix(sync): keep agent variants in shared target folders

Compatible targets sharing a skills folder need a combined selection so
Codex and universal do not prune one another in merge or copy mode.
Carry every shared reader through selection, pruning and previews,
including project targets, account identities and path aliases.

Require a matching skill suffix under two distinct agents before
inferring variants, keeping ordinary agent-named categories unrestricted.
Separate naming warnings from ambiguous selection in diff and explain
ambiguous removals. Add global/project regression coverage for repeated
sync, target-only sync, status JSON, diff and API consumers.

* fix(variants): align consumer counts, hints and diagnostics

Use logical source counts in list, tracked install and init summaries while matching audit caches against physical variants. Restore localized dashboard skip hints and explain symlink routing limits in status and doctor, including project and JSON output.

Document paired-agent detection and compatible shared-folder selection in the proposal, built-in skill and English plus translated command pages. Add focused regressions for the affected consumers.

* fix(sync): cover initial sync and ignored variant diagnostics

Init syncs a fresh in-memory config, so resolve shared target identities
before its first sync as well as when loading saved configuration.

A whole-directory symlink exposes ignored skills too. Diagnose agent
variants using physical inventory when active discovery has none, while
keeping logical counts and merge/copy selection restricted to enabled
skills. Cover global/project JSON status and doctor with regressions.

Reuse sourcewalk directory and canonical-path helpers so traversal guards
remain enforced and path resolution has a single existing owner.

* fix(variants): address conversion, counts and selection diagnostics

Ignore runtime agent identities when comparing convertible project targets and count logical skills during init. Keep selection warnings separate from naming warnings and preserve agent-named parent skills as ordinary skills.

Cover account sync/prune, project ambiguity and overrides in merge/copy modes, and init/status agreement. Focused verification ran in an isolated Linux Codex container, not the devcontainer, as authorized.

* refactor(variants): remove obsolete selection helpers

Remove the unused FilterSkillsByTarget wrapper and prune agent parameter, cache canonical target aliases once, and restore catalog skip ordering to avoid an unrelated behavior change. Completes the optional cleanup from PR 649 review.

* fix(ui): expose localized variant selection diagnostics

Show target warnings with source paths, localize ambiguity across preview and detail consumers, and let skipped preview rows add a physical exclude pattern. Show tracked repository variant counts alongside logical skills.

Drop display-only rendered cases while retaining mutation protection and plain TypeScript logic coverage. Inspect target states in Clean/Playful light/dark and Traditional Chinese.

* docs(variants): explain diagnostics and add sync runbook

Document doctor variant_routing and logical/physical counts, diff selection skips, and the nested parent-skill boundary. Keep all four command translations aligned and add isolated account/project E2E scenarios.

Both runbook steps passed in the authorized Linux Codex container with separate HOME/XDG/TMPDIR fixtures. Website typecheck and all five locale builds passed.

* test(config): use native paths in project conversion fixture

The shared-agent regression fixture appended slash-separated suffixes to Windows temporary paths, so project path matching returned no candidates. Build each path with filepath.Join and preserve all conversion assertions.

Focused project configuration tests passed in the authorized isolated Linux Codex container, not the devcontainer. Windows CI verifies the platform-specific fixture correction.

* fix(ui): recompute shared skill routing for filter previews

Evaluate edited include/exclude settings in the complete target map before
classifying the draft, so a formerly shared folder no longer keeps its old
union when the filters differ. Preserve the saved target configuration.

* fix(mcp): keep parent skills when peer variants route elsewhere

Do not treat an otherwise eligible variant for another agent as an unserved
nested skill. Continue blocking parent publication for explicitly filtered,
disabled, ambiguous, or invalid children so filters still hide their files.

* fix(ui): distinguish agent selection from naming skips

Expose separate naming and selection skip counts on target summaries.
Show each applicable remedy in target details and sync previews so ambiguity
keeps its filter/override guidance alongside naming and collision hints.

* fix(list): include disabled rows in tracked repository counts

Count the complete inventory that list displays, including ignored skills
and physical variants, without changing the enabled counts used by status,
install, or sync. Clone rows before counting to preserve disabled state.

* docs: align variant counts and routing recovery guidance

Show logical skill and physical variant counts in list/install documentation
and keep the four translations aligned with the filtering examples. Explain
that agent-named skill parents keep ordinary nested skills and retain the
devcontainer-only runbook environment. Removal warnings now recommend a
source-local override, since include filters cannot undo agent routing.

* fix(mcp): preserve explicit target restrictions on nested variants

Limit the differently routed child exemption to automatic layout inference.
Frontmatter targets and dashboard source-local overrides must still prevent
a parent from publishing files explicitly restricted to another target.

* fix(ui): fill target name in naming warning guidance

Pass the current target name when rendering localized warning hints so the
same naming guidance shown beside the controls does not expose a placeholder
in the warning banner. Verified in the populated target preview.

---------

Co-authored-by: Willie <egg358358@gmail.com>
2026-10-29 16:47:38 +08:00

33 KiB
Raw Blame History

sidebar_position
sidebar_position
3

install

Add skills from GitHub repos, git URLs, or local paths.

Tracked repositories report Found N skills, M variants when agent-specific copies represent fewer logical skills. All physical variants remain installed in the source; merge and copy sync select the matching agent's instructions.

Overview

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

# 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:

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:

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:

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

# 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:

skillshare install anthropics/skills
$ 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 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:

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:

# 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:

# 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 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)

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:

# 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:

# 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 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:

# 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:

skillshare install ./my-skill -p

This guard applies to both the CLI and the Web UI (skillshare ui). :::

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:

skillshare install github.com/team/skills --track -p
skillshare sync

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

skillshare install anthropics/skills --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:

skillshare install anthropics/skills --json --into frontend
{
  "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:

skillshare install github.com/user/agents --kind agent --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:

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

# 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:

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:

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.

# ✅ 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:

skillshare install ~/my-skill --force

Update existing skill:

# By skill name (uses stored source)
skillshare install pdf --update

# By source URL
skillshare install anthropics/skills/skills/pdf --update

Install into a subdirectory:

# 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 for folder strategies.

Install from a specific branch:

# 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):

# 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.

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):

skillshare install addyosmani/web-quality-skills --track --name team-skills
$ 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

SSH is the simplest method — if your SSH key is configured, it just works:

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:

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:

For Bitbucket app passwords, also set your username:

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:

- name: Install shared skills
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: skillshare install https://github.com/org/skills.git --track

GitLab CI:

install-skills:
  script:
    - skillshare install https://gitlab.com/org/skills.git --track
  variables:
    GITLAB_TOKEN: $CI_JOB_TOKEN

Bitbucket Pipelines:

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

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

audit:
  block_threshold: HIGH
# 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 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

--exclude flag

Skip specific skills when installing from a multi-skill repo. Supports both exact names and glob patterns:

# 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

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.

# 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 uses .skillignore to exclude non-skill directories and internal tooling:

skillshare
feature-radar

Combined with --exclude, users can further narrow the selection:

skillshare install runkids/my-skills --exclude seo

Format — uses gitignore syntax:

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

# 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 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
# 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:

skillshare install anthropics/skills/skills/pdf
skillshare sync  # ← Don't forget!

See Also