Files
skillshare/website/docs/reference/commands/install.md
T
Willie 355b42ee57 feat(cli): one frame and keymap for every TUI, inline prompts, file viewer (#370)
* chore(devcontainer): add a TUI screenshot kit

Recreating the devcontainer wipes vhs and the browser it drives, so
every TUI review started with a manual reinstall. The start script now
installs the recording tools when they are missing and skips straight
through when they are present.

record-tui.sh screenshots each full-screen TUI in its own fresh ssenv,
filled by tui-fixture.sh through real commands, so the TUI redesign can
compare before and after on the same data.

Refs #200

* feat(cli): ask small choices inline instead of full screen

The restore source, new-skill wizard, install skill picker and the
other checklist prompts each took over the whole screen for a handful
of options, and the answer vanished once chosen. They now use the same
inline prompt as init: the question appears in place, collapses into a
"✓ label value" line, and stays in the scrollback.

Lists longer than the visible rows can be narrowed with /, and esc
inside the filter only leaves the filter. Every inline prompt shows
one key line in the wording the full-screen TUIs will share. The new
wizard drops its esc-goes-back steps: esc cancels, as in init.

Refs #200

* feat(cli): give the list TUI the shared frame and keymap

The full-screen TUIs each had their own header, footer and key letters,
so the same action used different keys per screen and the help line
listed everything at once. list is the first screen on a shared frame:
one title line with scope, counts and tabs, the list and details side
by side without dividers, and one key line with the common keys and
the position. Everything else moves under ?, and confirmations ask on
the key line so the list stays visible.

Keys follow one lowercase letter per action (u update, d uninstall,
t enable/disable, m manual only, ! audit). The All tab and the s
status cycle are gone: tab switches skills and agents, and status:
in the filter or --status covers enabled/disabled. Rows drop the
group prefix that the heading above them already shows.

Refs #200

* docs: drop key-by-key TUI instructions from command pages

The command pages carried key tables, screen mock-ups and one bullet
per key for every full-screen TUI, in five languages. The TUIs now show
their keys on screen, so these pages repeated what the screen says and
went stale with every key change (several already listed keys that no
longer exist). Each TUI section is now one paragraph on what the screen
shows and what it can do. What the screen does not explain stays: the
filter tag syntax, what manual only does to SKILL.md, the analyze color
thresholds, when audit opens its TUI, and that target changes are saved
to config immediately.

Refs #200

* feat(cli): move the trash TUI onto the shared frame

The trash TUI replaced the whole screen with a confirmation and a
spinner, so you lost sight of what you had selected, and r/d did
nothing until something was ticked. It now uses the shared frame:
checkbox rows with size and age, details beside them, and the
confirmation, the names it covers, the running operation and its
result on the bottom lines. With nothing selected, r and d act on the
row under the cursor.

Refs #200

* feat(cli): move the log TUI onto the shared frame

Log rows were two-line "[date] COMMAND — status" blocks, stats lived
behind s as a separate screen, and delete swapped the help bar for a
prompt you could miss. Rows are now one line with time, command and a
status mark; Entries and Stats are tabs on the title line next to the
count and success rate; and the delete confirmation takes over the key
line. With nothing selected, d deletes the entry under the cursor.

Row delegates no longer force a 40-column minimum, which wrapped every
row in lists narrower than that.

Refs #200

* feat(cli): move the audit TUI onto the shared frame

The audit TUI had its own tab bar, a divider column and a two-line
summary footer, and esc quit even with a filter typed. It now uses the
shared frame: scan counts and the Skills / Agents tabs on the title
line, the worst severity at the right of each row, the scan-wide
severity, threat and policy summary on the note line, and esc clears
the filter before quitting. Rows under a group no longer repeat the
group's name.

Colored title facts keep their color instead of being dimmed.

Refs #200

* feat(cli): move the audit rules TUI onto the shared frame

The rules browser used keys no other screen shared: s for severity,
space to toggle and R pressed twice to reset. It now follows the
shared keymap: t turns a rule or pattern on or off, e asks for the new
severity on the key line, and R asks yes/no before deleting
audit-rules.yaml. The severity tabs sit on the title line, rows show
the rule count or "off" at the right, and rule rows drop the pattern
prefix the group row already shows. Space still toggles.

When the title line is too narrow for every tab, it shows only the
active one instead of clipping them.

Refs #200

* feat(cli): move the analyze TUI onto the shared frame

Analyze put the target switcher, a stats line and the help text in a
three-line footer and sorted with s, which means sync everywhere else.
It now uses the shared frame: skill count and always-loaded and
on-demand tokens on the title line, one tab per target group, o to
sort with the current order on the key line, and esc clears the
filter before quitting. The details follow the list layout, and lint
warnings use the ! mark the CLI uses.

renderDetailSection and renderFactRow had no other callers and are
removed.

Refs #200

* feat(cli): move the diff TUI onto the shared frame

The diff browser drew ruled separators, "── Next Steps ──" banners and
an arrow before every suggested command, and esc quit with a filter
typed. It now uses the shared frame: target, extra and difference
counts on the title line, what differs at the right of each row, group
rows like the list's, plain headings in the details, and esc clears
the filter before quitting.

Refs #200

* feat(cli): move the restore TUI onto the shared frame

Restore replaced the whole screen for the confirmation, the running
operation and the result, rendered two-line rows, and esc quit even
with a filter typed. It now uses the shared frame: the target or the
chosen target and its backup count on the title line, one-line rows
with backup count and age or skill count and size at the right, and
the confirmation, what it covers, the spinner and the result on the
bottom lines. Esc clears the filter, then goes back, then quits.

Refs #200

* feat(cli): move the MCP manager onto the shared frame and keymap

The MCP manager used its own letters (a add, x remove, b backups, r
refresh), hid the details behind Enter, and printed two help bars.
It now uses the shared frame and the keys every other TUI uses: n
add, i import, e edit, d remove, s sync, r restore, with the details
of the selected server beside the list and ? for all keys. Refresh is
gone because the manager reloads after every action. Command docs drop
the key table, and the how-to page and built-in skill name the new
keys.

Refs #200

* feat(cli): move the search selector onto the shared frame

The search selector rendered two-line checkbox rows, put the details
under the list, used s for "search again" although s means sync
everywhere else, and Enter with nothing selected silently cancelled.
It now uses the shared frame with the keyword and counts on the title
line, one-line rows with stars or risk at the right, and the details
beside the list. Esc clears the filter, then goes back to the keyword
prompt; Enter with nothing selected installs the row under the cursor,
as r and d do in other TUIs. The command page drops its screen mock-up
and key list, and no longer claims the search restarts after an
install.

Refs #200

* feat(cli): move the target TUI onto the shared frame and keymap

The target TUI had five uppercase keys (M, N, I, E, R), a separate
skills-or-agents picker before three of them, and full-screen pickers
and remove confirmation. e now opens one menu of every setting the
target has (skills mode, naming, include, exclude; agents mode,
include, exclude, with agent filters marked as ignored in symlink
mode), and the pickers and pattern editor open beside the list. d asks
on the key line with the command it will run and what removal does.
Patterns are added with n, as everywhere else. Also drops the filter
style helper the MCP change left unused.

Refs #200

* feat(cli): move the extras TUI onto the shared frame and keymap

The extras TUI used six uppercase keys (N, X, S, C, M, F), each with
its own full-screen menu, and a full-screen confirmation. It now uses
the shared frame and keys: n new, d remove, s sync, c collect, and e
for one menu with the mode and flatten setting of every target. The
target menu and mode picker open beside the list, and confirmations
ask on the key line with what the action does. The picker row helper
moves to the shared frame, and the split and scroll-hint helpers no
TUI uses any more are removed.

Refs #200

* feat(cli): share one framed file viewer between list and extras

The list and extras file viewers were two copies of the same layout
with the old look: an indented title, a │ column between the tree and
the file, and a hard-coded yellow cursor. Both now draw through one
renderer in the shared frame: the skill or extra and the open file on
the title line, the tree beside the file without a divider, and the
scroll position at the end of the key line.

Refs #200

* feat(cli): ask for a large repo's folder inline

Installing from a repo with 50+ skills opened a full-screen folder
browser with its own filter bar and key line, then dropped back to an
inline skill checklist. The folder question is now an inline select
like every other install prompt: the first choice installs everything
below the current folder, esc goes up one level, and the chosen folder
collapses into a "✓ folder" line before the skill list appears.

The screenshot fixture gains a 60-skill repo so the picker can be
recorded, and the filter-bar and page-info helpers that only the old
picker used are removed.

Refs #200

* feat(cli): ask for MCP and plugin values inline

MCP and plugin values were typed into a separate textarea program that
submitted on ctrl+d, a key no other prompt uses. They now go through a
new ui.Text prompt drawn like the other inline questions: enter
submits, alt+enter starts a new line, and the box grows with the value.
The MCP name is a single line, so it uses ui.Input. Answers are not
echoed afterwards because a value can hold a secret.

Refs #200

* feat(cli): drop the full-screen MCP change preview

Every MCP add, edit, remove, restore and sync already prints its plan
inline and then asks whether to apply it. The full-screen preview in
between showed the same changes again and needed one more enter, so it
is removed along with the review step of the prompts interface. The
confirm question loses its "Review complete" prefix, and a blank line
now separates it from the plan.

Refs #200

* feat(cli): ask extras init questions inline

`extras init` without arguments ran its own full-screen wizard with a
hand-drawn cursor and a different key line on every step. It now asks
the same questions inline, like `init`: each answer collapses into a
"✓" line, the target line shows where the file lands, and esc cancels
with "Nothing was created".

A new ui.InputValid keeps a question open and shows the error under it
until the answer passes, which the name, file name and per-target file
name questions need.

Refs #200

* fix(cli): drop stale key hints from MCP prompts and help

`mcp --help` still listed the manager keys from before its redesign
(a add, x remove, b backups, r refresh), and several MCP and plugin
questions repeated "Esc cancels" or claimed `a` selects all, while the
key line under every prompt already shows the real keys (ctrl+a for
all). The help now just says where the keys are, and the questions keep
only what the key line cannot say. The MCP command page drops the same
key list in all five locales.

Refs #200

* feat(cli): open a skill's files at its audit findings

The audit TUI listed each finding's file, line and one-line snippet, but
judging whether a finding is real needs the lines around it, and that
meant leaving the TUI to open the file by hand. Enter now opens the
selected skill's files at its most severe finding, with the raw text
numbered and the flagged line marked; n/N steps through the findings in
the order the details number them, and the line above the keys says
which finding is shown.

The viewer state lives in a new fileBrowser so analyze and trash can
open skills the same way. Long lines wrap under their text instead of
being cut, since the evidence is often at the end of a line.

Refs #200

* feat(cli): open a skill's files from analyze

Analyze flags lint issues such as a description that is too short, but
the screen only showed the description text, so fixing a skill meant
finding its folder first. Enter now opens the selected skill's files,
including local ones that live only in a target, as raw numbered text
with the front matter, and the line above the keys repeats the first
lint issue so it can be checked against what is written.

Refs #200

* feat(cli): open a trashed item's files before restoring

The trash TUI showed only the first fifteen lines of SKILL.md, which is
not enough to tell two trashed versions apart or to see a skill's other
files. Enter now opens the item's files in the same viewer as list and
analyze, rendered as Markdown, and esc returns to the trash.

Refs #200

* fix(cli): leave front matter out of the agent viewer in list

Opening an agent in the list TUI rendered its whole file as Markdown,
so the front matter came out as a horizontal rule and a "## name: ..."
heading. Skills already drop it because the details panel shows the
name and description; agents now read their body the same way.

Refs #200

* test(cli): compare trash restore destinations home-relative

The trash TUI shows restore destinations through shortenPath, so with
HOME=/tmp, as in the offline Docker sandbox job, /tmp/skills prints as
~/skills and the tests that expected the absolute path failed. They now
expect whatever shortenPath gives for the same path.

Refs #200

* fix(cli): show control characters in viewed files as symbols

The file viewers in list, extras, audit, analyze and trash wrote a
file's bytes to the terminal as they were. Audit and analyze exist to
inspect skills that may not be trusted, and a SKILL.md with an ESC or
OSC sequence could rewrite the screen or the window title instead of
being shown. Control characters are now replaced with same-width
symbols such as ␛ before rendering, which keeps line numbers and the
marked finding line in place; newlines and tabs are kept and CRLF is
read as LF.

Refs #200

* fix(cli): open audit findings in files the tree leaves out

The file tree skips dotfiles and stops at three levels and 200 entries,
but the audit scan reads root dotfiles and goes deeper. A finding in
such a file, like a root .env, left the viewer on the previous file
with the new finding's note above unrelated text. Opening a finding now
adds its file to the top of the tree under its full relative path when
it is missing, so the marked line is always the one reported.

Refs #200

* fix(devcontainer): exit nonzero when a TUI screenshot fails to record

record-tui.sh printed FAIL for a screen whose vhs run failed but still
exited 0, so an unattended run looked like every screenshot was taken.
It now remembers a failure, keeps cleaning up and recording the other
screens, and exits 1 at the end.

Refs #200

* fix(cli): keep other files' front matter and fit text to the pane

Two problems in the shared file viewer:

- It dropped YAML front matter from every Markdown file, so a trashed
  skill's README or template lost its metadata, which nothing else in
  the trash view shows. Only SKILL.md and a single-file agent drop it
  now, since their name and description appear in the details.
- The open file was wrapped to at least 40 columns. In a narrow
  terminal that is wider than the right pane, so the layout wrapped
  each row a second time, breaking lines apart and moving the marked
  finding line. Text now wraps to the pane's real width.

Refs #200

* fix(cli): keep frame lines within the terminal width

joinEnds padded the title, confirm and filter lines but never cut them,
so a long search query, path or command made the line wrap. Every TUI
sizes its body for a fixed four lines of frame, so the wrap pushed the
bottom of the body off the screen. Long text is now cut from the left
side, keeping the status or tabs on the right. Lines are left alone
until the terminal has reported its width.

Refs #200

* fix(cli): show a nested skill's folder when no group heading names it

List rows dropped the first path segment for every skill on the grounds
that the group heading above shows it. With a single group, or a filter
that leaves one, there is no heading, so frontend/react showed as just
react and same-named skills from two folders looked alike. Rows now
drop it only under a heading; a tracked skill's repo dir is still
dropped as before.

Refs #200

* fix(ui): let esc leave a prompt's filter after enter found nothing

The inline prompt guessed the filter state from key presses and treated
enter as leaving the filter. huh's Select stays in the filter when enter
has no match, so the next esc, meant to leave the filter, cancelled the
question instead: one folder level back in the large-repo picker, or the
whole install at the top. The prompt now asks the field whether it is
filtering.

Refs #200

* fix(cli): show control characters in the trash preview as symbols

The trash details panel prints the first lines of a trashed SKILL.md,
and it wrote them to the terminal as they were. The file viewers already
pass text through printableText so an ESC or OSC sequence in a skill is
shown instead of acted on; the preview now does the same.

Refs #200

* fix(cli): scroll an agent's text with the wheel anywhere in list

An open agent has no file tree, but the wheel still treated the left
quarter of the screen as the tree, so scrolling there did nothing. The
whole screen now scrolls the agent's text.

Refs #200

* fix(ui): read prompt answers after the prompt has run

The prompt helpers returned "value, runPrompt(..., &value)". The Go spec
leaves the order between reading value and the call unspecified, so a
compiler may return the value from before the user answered. gc 1.25
runs the call first, so answers arrive today, but nothing guarantees it.
Each helper now runs the prompt into err and then returns the value.

Refs #200

* fix(cli): name hidden Unicode and skip oversized files in the viewer

Two gaps in the file viewer used to inspect untrusted skills:

- Zero-width and bidirectional characters passed through unchanged,
  although the audit reports them as HIGH (Trojan Source). Opening such
  a finding reordered or hid the text instead of showing the cause.
  They now appear as <U+202E> and the like.
- Moving onto a file read all of it, then copied it again while
  numbering and wrapping, with no size limit. The audit skips files
  over 1 MB; the viewer now does too and says the file is too large.

Refs #200

* fix(cli): show control characters in viewed file names as symbols

File contents in the viewer already pass through printableText, but the
tree and the title printed file and skill names as they were. A file
named with an ESC sequence, a newline or a bidirectional character in a
skill under review could still reach the terminal, or break the frame
across lines. Names now go through printableName, which also shows a
newline or tab as a symbol so the name stays on one line.

Refs #200
2026-10-04 04:14:47 +08:00

31 KiB
Raw Blame History

sidebar_position
sidebar_position
3

install

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

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

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

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

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

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

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

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