* 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
31 KiB
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
--updateor--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 (recommended)
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:
- GitHub: Managing your personal access tokens
- GitLab: Token overview
- Bitbucket: Access tokens
- Azure DevOps: Use Personal Access Tokens
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_thresholdblock installation (default:CRITICAL) - Lower findings are shown as warnings and include risk score context
audit.block_thresholdonly controls block level; it does not disable scanning- There is no config switch to always skip audit; use
--skip-auditper 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
--trackinstall scans the entire cloned repository (not just one skill folder) - Findings at/above threshold block install unless
--forceis 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
--forcewhen you still want visibility into findings. - Use
--skip-auditonly when you intentionally need to bypass scanning. - If both are set,
--skip-audittakes 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,.mdfiles inside are discovered as agent candidates - If the repo has both
skills/andagents/, both are installed - If the repo has only loose
.mdfiles at root (noSKILL.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!