* fix(install): omit the empty audit section in dry-run A dry-run skips the security audit, yet the single-skill path still printed the "Audit Findings" heading with nothing under it, which reads as if the audit ran and found an empty result. * feat(init): ask first, confirm a summary, then write The old init asked nine questions in three input styles and wrote files as it went, so cancelling midway left a half-built setup, and detection created tool folders even under --dry-run. Connecting a second machine to an existing repo was only offered at the very end, and the built-in skill defaulted to "no", which read as "not recommended" (#200). init now collects every answer into a plan, shows a summary with Yes / Change settings / Cancel, and writes nothing until confirmed. Esc cancels cleanly. A "Connect my existing skillshare repo" path checks the repo before writing, detects its layout, prefers the repo version of same-name skills and keeps local-only ones for the next push. The built-in skill is installed by default, and the first sync runs at the end so the tools work right away. Prompts use one inline huh-based component with theme colors. Without a terminal (CI, scripts, AI agents) init now applies the same defaults as pressing Enter and prints each decision with the flag that changes it, instead of silently doing less; init -p and --discover add the detected tools. Output that is not a terminal is plain text. BREAKING CHANGE: non-interactive `init` now enables git, installs the built-in skill and selects every detected tool; pass --no-git, --no-skill, --no-targets or --no-copy for the previous minimal setup. Piped or redirected output no longer contains ANSI colors; use --json where offered for machine-readable output. Refs #200 * docs(init): show the new init flow and the connect-a-repo path The getting-started page still described the old four-question wizard with a screenshot of it, the second-machine guide never mentioned the new "Connect my existing skillshare repo" choice, and the recipe told users to run pull and sync after init even though init now does both. Replace the screenshot with ones from the new flow, describe the questions, summary and cancel behavior, and explain what connecting a repo does before and after confirmation. The devcontainer example gains --no-git because init without a terminal now turns git on by default. Refs #200 * feat(devcontainer): seed fake tools and a repo with ssenv --seed Trying init by hand needed several manual steps to fake installed AI tools and a skills repo to connect. `ssenv create --seed` (and `ssnew --seed`) now creates claude/codex/cursor directories with a few skills and a local bare repo at ~/remote/skills.git, so both init paths can be tried at once. Refs #200 * fix(ui): skip the logo on 16-color terminals and hide the cursor while it plays `docker exec -it` sets only TERM=xterm, which reads as 16 colors: the logo was mapped onto the terminal's own palette and its fade-in collapsed into a few flickering cells. Below 256 colors the banner now prints only its text, and the devcontainer sets COLORTERM=truecolor. The visible cursor also jumped along the logo's left edge while frames redrew in place. It is hidden during the animation and restored on exit, including Ctrl+C. Refs #200 * style(ui): color the question mark in prompts The uncolored "?" before each question read like a stray character. It now uses the accent color of the "›" cursor. Refs #200 * fix(init): name the root git scope by what it versions "everything" suggested plugins, MCP servers and hooks were versioned too, but they live in config.yaml, which the root scope gitignores. The option and summary now say "skills, agents, extras" and note that those settings stay in each machine's config.yaml. Refs #200 * feat(init): show --discover in the new init style --discover still printed the old header, "agent(s)" counts and "+ name" lists next to the new prompt. Global and project discover now share init's answered rows (Tools, Config) and a Next line, and call the targets "AI tools" as init's banner does. Refs #200 * feat(init): replace the pixel logo with a SKILLSHARE wordmark The half-block logo looked stretched on terminals with tall line height and turned to mush when shrunk to fit. init now opens with a three-line pixel wordmark, SKILL in blue and SHARE in gold, that lights up from left to right, followed by the version and tagline on one dim line. The generated logo data and its generator script are gone. Without a terminal, without color, below 256 colors or on a narrow terminal, the banner still prints a plain "skillshare vX" line. Refs #200 * refactor(init): label the chosen tools "Targets" init called them "Tools" while the rest of the CLI, the config file and the `target` command call them targets. The answered rows and the summary now say "Targets", the same label the other commands will use. Sentences that describe what was detected ("Found 3 AI tools") stay as they are. The docs tables, the First Sync steps and both init screenshots are updated to match. Refs #200 * feat(cli): ask yes/no questions with the inline prompt uninstall, trash empty, extras remove, target add, collect, update, upgrade and audit each printed their own "[y/N]:" line and parsed the answer by hand, while init already used the inline Yes/No prompt. They now share it: esc answers no, and a declined question prints one dim "Cancelled. Nothing was …" line, as init's cancel now does too. Without a terminal the prompt reads one line from stdin instead, so piped answers such as `echo y | skillshare uninstall x` keep working. It reads byte by byte so a second question still gets its own answer. Refs #200 * feat(sync): report each target on one aligned row Sync printed a ruled header, a "Backing up" block and a "name: merged (43 linked, 0 local, 0 updated, 0 pruned)" line per target, so the counts that changed were hard to find among zeros. It now follows the init style: one row per target with only the non-zero counts, a single Backup row, and a closing line with the duration. `sync --all` names its Skills, Agents and Extras blocks and no longer explains how to set up extras when none are configured. The non-TTY text changes with it; `--json` stays the stable interface for scripts. Tests match rows through the new AssertRowContains helper. Refs #200 * feat(status): show targets as one table Status printed each target as a header with indented skills and agents lines full of bracketed modes and zero counts, and the audit policy as four lines of uppercase labels. Comparing targets meant reading every block. Each target is now one row with a skills and an agents column, a single line names the modes in use, and audit and version take one line each. Global and project mode share the renderer, so project paths read relative to the project root. Refs #200 * feat(install): report each step on one aligned row Install printed a logo, a box-drawn tree, "Next Steps" bullets and a separate "Audit Findings" block, so the result was hard to find. It now uses the same rows as sync and status: Source, Audit and Install with the destination folded to ~, then a closing line and a Next block. Spinners write through a gate that Stop closes before clearing the line. pterm's render goroutine checks IsActive and then writes, so a fast step such as install --dry-run left "Copying files..." stuck in front of the next line. Refs #200 * feat(uninstall): confirm against one line and point at undo Uninstall opened with a boxed header and Name/Path lines, and closed with the trash folder path and a "Next Steps" bullet. Now one line names the target, its folder and what it holds; the result is a single "Uninstall x → trash, kept 7 days" row; and Next offers sync, the trash restore command that undoes it, and the reinstall command when the skill came from a remote source. A batch run with --force or --dry-run no longer lists the targets twice, since there is no question for the list to support. Mixed batches are counted as items, not targets, which already names the AI tools. Refs #200 * feat(update): report each skill or repo on one Update row Update opened with an "Updating" header, the full source path and a "0 tracked repo(s), 1 skill(s)" line, then printed a Changes box and two success lines before "Next Steps". A single update is now an Update row (source or commit count, time), the commits it pulled in dim text, the Audit row, and Next. A batch ends with the audit result and one closing line that leaves out zero counts. Progress bars now clear themselves when they stop, like spinners, so a finished batch no longer leaves "[3/3] ... 100% Done" behind. Refs #200 * feat(check): list what needs attention and close with one line Check opened with a header, the full source path and an item count, counted skills with updates without naming them, and ended with two "Run ..." hints. It now prints one row per repo, skill or agent that needs attention (behind, update available, stale, failed), a closing line that leaves out zero counts, and the update command under Next. A single-name check is one row, like update. Refs #200 * feat(push,pull): report commit, push and pull as aligned rows Push and pull opened with a header and closed with "Push complete" or "Pull complete", so they never said what they committed, where they pushed, or what a pull brought in. Push now prints a Commit row (file count and message) and a Push row naming the upstream branch, never the remote URL since it can carry credentials. Pull prints a Pull row with the commit and file counts and the commits themselves, as update does for a tracked repository, before the sync output. Dry runs list the changed files as ~ + - instead of raw porcelain codes, and error hints are dim notes instead of info lines. Refs #200 * feat(upgrade): report the CLI and the skill on one row each Upgrade opened with the logo and printed a tree of steps per part (current version, latest version, status) ending in "Already up to date ✓". Each part is now one row, such as "✓ CLI v0.22.0 → v0.23.0 · 3.1s" or "✓ Skill v0.23.0, already up to date", with spinners that clear. Sync is offered under Next only when the skill changed, and the star request is a dim line at the end. Refs #200 * feat(new): report the created skill on one row New printed a "New Skill Created" header, the full path, and numbered "Next steps" that told the user to edit the file and run sync. It now prints "✓ Created ~/…/SKILL.md", the folders a pattern added, and sync under Next. A dry run shows the same row, a Preview section with the template, and the dry-run line. Refs #200 * feat(trash): list items and restores as aligned rows The plain trash list printed each item as an info line with its size and age in parentheses under a "Trash" header, and restore printed two success/info lines plus a "Next Steps" label. The list is now rows of name, size and age with one closing count, and restore is one row naming where the item went back, with sync under Next. An item trashed under a minute ago reads "just now" instead of "just now ago". Refs #200 * feat(collect): list local items and results as aligned rows Collect opened with a header, listed local items as "[target] path" list items under a second header, then printed a third header before the per-item results and a metric summary line. It now lists each local item as a row (name, target, path), asks the inline confirm, prints one row per result and closes with "Collected N skills" plus sync and, when the source is a git repository, commit under Next. Refs #200 * feat(hooks): show hooks and their changes as aligned rows Hooks printed "Hooks source: <path>" as an info line, statuses through the fixed-width Status helper, and results as sentences ending in "Run 'skillshare hooks sync' when ready." Hooks and Agent file changes are now rows, with conflicts marked as failures and inactive outputs as warnings, saves and applies close with one line, and the next command sits under Next. The list's "Pending sync" section no longer shows entries that are already in place. Refs #200 * feat(mcp): show servers, changes and checks as aligned rows MCP printed "MCP source: <path>" as an info line, plan changes through the fixed-width Status helper, results as sentences that named the next command inline, and check summaries as "2 server(s) checked: 1 error(s)". Changes and parked servers are now rows with conflicts marked as failures, saves and applies close with one line and Next, and check marks each server with its findings beneath and closes with "Checked 2 servers: 1 error". The Status helper had no callers left and is removed. Refs #200 * feat(plugin): show packages, plans and results as aligned rows Plugin text output was raw "name · target · id · state" lines with "Warning:", "Includes:" and "Revision:" prefixes, and the list walked a map so packages came out in a different order each run. Packages, discovered candidates, planned changes and results are now rows sorted by name, marked by state (registered, not installed, pending, blocked, failed), with details as dim notes and the dry-run line after a preview. JSON output is unchanged. Refs #200 * feat(audit): replace header and summary boxes with rows Audit framed its context in a header box (mode, path, block rule, policy), numbered batch results "[1/2]", printed per-skill verdicts as "→ Aggregate risk / Block decision" lines, and closed with a Summary box that listed every count including zeros. The context is now one title line with a dim note, flagged skills are aligned rows with their highest severity, the summary leaves out zero counts, and the run closes with one line saying whether anything was blocked and by which severity, followed by the command to see the first blocked skill's findings. The progress bar no longer writes its final frame when stdout is not a terminal; that frame had no newline and ran into the next line. Refs #200 * feat(audit): show audit rules as aligned rows The rules list was a fixed-width table framed by 90-character dividers with a "(N rules: N enabled, N disabled)" footer, and rule changes were sentences like "Set severity for X → HIGH". Rules are now rows keyed by ID with a colored severity and the pattern dimmed, disabled rules dim as a whole, the list closes with a count that names disabled rules only when there are some, and each change is one row. Refs #200 * feat(search): drop the logo and tree, show results as rows Search opened with the ASCII logo, drew its progress as a ├─/└─ tree, listed results under a column header with dividers, and ended installs with "Run 'skillshare sync' to distribute to all targets". Results are now aligned rows with the source, stars or risk, and the description and tags beneath; a single install reports the same Install row as `skillshare install`; batch installs list only failures before one Done line; and sync and audit sit under Next. Login and rate-limit problems name the command that fixes them. Non-terminal output no longer prints a "name: installing..." line per skill. Refs #200 * feat(backup): show backups and restores as rows with one closing line Backup and restore opened with headers, announced dry runs with a warning before doing anything, summarized with an operation box, and followed a backup with a "Recent backups" list. Targets now back up in name order as rows with folded paths, runs close with one Done line (and Next restore), listings are rows keyed by timestamp or path with a total, and dry runs end with the shared dry-run line. Cleanup reports how many backups remain instead of a separate "Current" line. Refs #200 * feat(help): one line per command, subcommands in each command's help The top-level help opened with the ASCII logo and listed about 70 lines across ten uppercase sections plus 15 examples, so it did not fit a screen, yet it left out analyze and the common options. It now lists each command once in six groups with the common options, and points to `<command> --help` for subcommands. The mcp, plugin, hooks and extras pages use the same layout and keep all their content. A mistyped command prints one error with the closest command instead of the whole help, a lone option such as --no-tui shows the help, and `skillshare version` prints one line. Refs #200 * feat(extras): show extras and their changes as rows with Next Extras printed a header, "→ name" lines with ad-hoc colored marks (including ✗ for targets that were only waiting for a sync), and ended each change with a sentence naming the next command. The list now shows each extra as a bold name over aligned target rows (! for drift or not synced) and closes with a count and, when something is pending, Next sync extras. Init, collect, add/remove target, mode and source changes close with one Done line, details become notes, and dry-run collect ends with the shared dry-run line. Refs #200 * feat(target): show targets as sections and rows with Next Target info and the plain list printed "Key:" lines at two indent levels, with "(none)" for every unset filter, and remove printed "Backing up" / "Unlinking" headers with one line per step. Info now shows the name over Skills and Agents sections with aligned rows, the list gives each target one row per resource with details dimmed, and empty filters are left out. Remove reports one row per target (plus its backups) and closes with a Done count; dry runs say what would happen per target and end with the shared dry-run line. Skills on/off, add and mode/naming/filter changes close with Done and Next. Refs #200 * feat(doctor): report checks as aligned rows and end with Next Doctor opened with the ASCII logo, split its report under divider headers, mixed ✓/→/! lines with full paths and "(s)" counts, listed targets in random map order, and ended with a bare warning count that left the fix to scattered "Run:" hints. Checks now print as aligned rows under bold sections (Environment, Targets, Extras, MCP/hooks/ plugins, Storage, Version), paths fold to ~, targets are sorted with one row per resource, and the report closes with a Done line plus up to three Next commands collected from the checks (sync, sync agents, sync hooks, upgrade, ...). The --json output is unchanged. Refs #200 * feat(hub): drop the logo and report hub changes with Done hub index opened with the ASCII logo and a tree of spinner steps, then repeated the result as "→ Mode / Skills / Output" lines with the full path. It now shows one spinner that clears itself and a Done line naming the folded output path, skill count and duration, with the index contents as a note. hub list shows aligned rows with the default and built-in hubs marked in dim text instead of a "*" column, and the add, remove and default commands close with a Done line. Refs #200 * test(install): match the shared dry-run line in online tests The online-tagged install tests still looked for the old "dry-run" banner, which install no longer prints since the restyle. They are skipped by default, so the mismatch only showed under -tags online. Refs #200 * fix(target): align remove rows on target names only The label column was sized for "<name>-agents" so an agents backup could fit, which left a wide gap on every row when no agents were backed up. The agents backup row now uses the target name too and says "agents backed up", so the column fits the names. Refs #200 * fix(update): list each item in a batch dry run A batch dry run only said "Would update N skills". Off a terminal the names leaked out through the progress bar's title lines, but on a terminal those lines clear, so the dry run never said which skills or repos it would touch. It now prints one Update row per item, as the single-item dry run does. Refs #200 * fix(ui): keep the progress bar silent off a terminal Off a terminal the bar printed "Title (0/N)", every title change and every phase header as permanent lines, which a terminal shows only as a frame that clears itself. Audit left a stale "Scanning skills (0/7)" line, and scripts saw different content than a terminal. The bar now prints nothing off a terminal, like the spinner. Refs #200 * fix(audit): avoid a double blank line before Summary The audit header ends with a blank line and Summary added its own, so a clean scan with no result rows showed two blank lines in a row. The Summary title no longer adds one; the result rows add it when present. Refs #200 * fix(mcp): drop the blank line above "Saved the MCP source" A save with no backup or migration notes printed a blank line with nothing above it, so mcp add and mcp edit opened on an empty line. Refs #200 * fix(doctor): stop repeating the extra's name in its findings Extras findings printed "rules rules → /home/me/.claude/rules: 1 file(s) out of sync": the row label already names the extra, the path was not folded to ~, and the count used "file(s)". The rows now start at the arrow, fold the path and pluralize the count. JSON details keep the extra's name so each line still stands alone. Refs #200 * fix(doctor): show integrity issues as rows under Integrity Tampered skills and missing hashes printed as free "! Skill integrity: N skill(s) ..." lines after the verified row, breaking the aligned Environment rows. They now sit under a single Integrity row, which turns to ! when any skill has an issue. Refs #200 * fix(doctor): pluralize the Skillignore and Trash rows The rows read "1 patterns, 1 skills ignored" and "1 item(s) (50 B), oldest <1 day". They now read "1 pattern, 1 skill ignored" and "1 item, 50 B · oldest under a day". The JSON messages keep their wording, since scripts may match on them. Refs #200 * docs: show the restyled output of batch 3 commands The reference pages still showed the old output of upgrade, new, trash, collect, audit, search, backup, restore, extras, hub, target and doctor: divider headers, arrow-prefixed lines and "(s)" plurals. The examples now match what the commands print, in all five locales, and the doctor check table uses the new row labels. Refs #200 * feat(trash): let trash empty skip its confirmation with --force Scripts had no way to empty the trash: off a terminal the confirmation reads stdin and cancels on EOF. --force (-f) skips it, as it does for uninstall and extras remove. Refs #200 * fix(doctor): show source, link and target problems as rows Missing sources, unsupported links, folders without SKILL.md, unknown skill targets, bad include/exclude patterns and broken symlinks printed as free "✗ Source not found: …" lines between the aligned rows. They now use the row of the check they belong to, and broken symlinks or a missing source add a Next suggestion. Refs #200 * fix(ui): leave out durations that would read 0.0s Fast commands ended with "· 0.0s", which says nothing. Every result line now formats its time through ui.Took, which init already used for its steps: durations under 0.05s are left out. Refs #200 * fix(ui): print dev builds without a v prefix Version labels were built as "v" + version everywhere, so a dev build printed "vdev". VersionLabel adds the prefix only when the version starts with a digit, and the logo, help header, version command and upgrade output share it. Refs #200 * fix: pluralize category and drop "just now ago" The checklist status bar appended "s" to its item name and printed "categorys". The trash TUI formatted ages with its own helper that added "ago" after "just now". plural now handles consonant + y, and the trash TUI uses the shared timeAgo, which makes formatAge unused. Refs #200 * fix(target): drop the parenthesized counts in the plain list The plain target list printed "merged (43 shared, 0 local)" while target info and doctor print "merged · 43 shared" with zero counts left out. The sync summary now returns both forms from one scan, so the TUI and --json keep their existing text and the plain list matches the other commands. Refs #200 * test(backup): make the agents backup test back something up The test only synced agents, which become symlinks into the source and are skipped by backup, so it passed without any backup being written. It now adds a target-local agent and checks that the file lands in the backup. Refs #200 * refactor(cli): render every command's --help with printHelp About forty help pages were hand-aligned raw strings with "Usage:", "Options:" and "Examples:" headings, while hooks, mcp, plugin, extras and the top-level help already used printHelp. They now share it, so headings, option order (short flag first) and alignment match across commands. Examples align on their own column so long commands no longer push option descriptions to the right, and "--help, -h" rows are dropped as on the converted pages. Refs #200 * feat(enable): print enable and disable results as rows enable/disable still used the old "Disabled: x (added to .skillignore)" line plus a "Run skillshare sync" sentence. They now print one row per pattern, a Next hint after a change, and the dry-run closing line, like the other restyled commands. Refs #200 * fix(sync): pluralize the leftover cleanup note Project sync printed "Cleaned 1 leftover skill(s)". The note now uses the singular or plural noun, and the sync docs show it as the dim note it is instead of an arrow line. Refs #200 * fix(cli): drop the arrow info lines left in install, update and sync These commands were restyled, but about fifty messages still went through ui.Info, which prints a leading arrow, and several said "skill(s)" or "item(s)". Hints now print as dim notes, empty results ("No agents found") as closing lines, follow-up commands as Next, and counts use the singular or plural noun. Refs #200 * fix(cli): tidy small leftovers found in the recorded output doctor printed "0 minutes ago" for a fresh backup and an ASCII arrow in the Update row, unlike trash and upgrade, which say "just now" and "v1.2.0 → v1.3.0". The "bring the Targets up to date" hint capitalized a word mid-sentence, and search --list showed hub sources under the home directory as a cut-off absolute path instead of folding it to ~. JSON messages keep their wording. Refs #200 * fix(search): fit a home-folded source path in the list Folding the home directory to ~ was not enough: a typical local hub path such as ~/.config/skillshare/skills/frontend/react is 42 characters, so the 40-character cap still cut it. Fifty characters next to the 24-character name column stays within 80 columns. Refs #200 * feat(list): print the plain list with rows and a closing count The --no-tui list still used the old header with a divider and an arrow on every skill, so it looked unlike every other restyled command. Skills now line up in one column under their group, tracked repos use the ✓ / ! marks, and the list closes with a count split by tracked, remote and local (zero counts left out). Project mode keeps its scope as a dim "· project" after the title. Global and project had copied the same plain-output code; both now call printSkillList. The loading spinner clears itself instead of leaving a "Loaded N skills" line. Refs #200 * fix(cli): show help for subcommand --help instead of running it target add/remove/list, trash list/empty and hub list/remove passed --help through as an argument, so they ran the command, failed on a target or hub named "--help", or rejected the flag. tui on --help even switched the TUI on. Each now prints its command's help page. The tui status and toggle lines also move to the row and Done style. Refs #200 * feat(diff): print differences as rows and close with next steps The plain diff still printed a Summary line, divider headers, arrow hints and per-target "scanning" lines when output was not a terminal. Each group of targets now lists one row per kind of change ("New a, b"), targets in sync share a single ✓ row, extras use the same rows, and diff closes with a count and up to three commands. The suggested sync command follows what differs: sync, sync agents, sync extras or sync --all. Agents no longer show as "New 1 skill", because rows name the change rather than counting skills. "skillshare diff all", listed in the help, failed with "target 'all' not found"; it now diffs everything, the same as no argument. Refs #200 * test: sync the install warning summary and gofmt two status tests The "6 findings" wording changed in an earlier commit, but the unit test under cmd/ still expected "6 finding(s)": scripts/test.sh and make check only run ./internal and ./tests, so the cmd tests never ran. Two status tests also had comment alignment gofmt rejects, which fails make check's fmt-check. Refs #200 * test: run the cmd unit tests in scripts/test.sh CI runs go test ./cmd/skillshare/... ./internal/..., but the local runner behind make test and make check only ran ./internal/..., so a stale assertion in cmd/skillshare passed locally and would only fail in CI. Refs #200 * feat(cli): restyle commit and analyze output commit and analyze were the last git and inspection commands still printing the old header and table layouts. They now use the same rows, Done line, and Next hints as push and pull, so a commit reads like the commit row of push, and analyze shows each target group as a bold name with aligned token rows instead of a boxed table. Refs #200 * feat(log): show entries as rows and fold the log path The plain log view still opened each section with a boxed header that printed the absolute log path, then a TIME | CMD | STATUS table. Entries now read like every other command: a status mark, the command, when it ran and how long it took, with details indented beneath. The log path is folded to ~ and moves to a dim footnote. log --stats drops its divider and ends with one summary line. It and the TUI stats panel said "just now ago" for a fresh entry; both now use timeAgo, which already handles that case. Refs #200 * feat(cli): restyle completion, ui and leftover arrow lines completion --install, ui start/stop and a few notices still printed arrow info lines with absolute paths. They now end with a Done line, fold paths to ~, and give config-file lines their own bold heading so the lines to paste read apart from the hints. The empty extras TUI now says the same thing as extras list. Refs #200 * feat(init): report git changes on an existing setup as rows init --remote and init --git-root on an existing setup still printed arrow lines with absolute paths and spinner results in a different voice. They now print aligned Git, Remote, Pull and Git root rows like a fresh init, end a dry run with the shared Dry run line, and give the choices after a remote check as Next commands. A source repo the user created before init had no fallback identity, so on a machine without git config the follow-up commit failed and dumped git's whole "Please tell me who you are" message. The existing repo now gets the same local fallback a new one does. Refs #200 * feat(doctor): warn when a newer built-in skill is published status already compared the skillshare skill with the published one, but doctor only printed the local version, so a run meant to find problems called an old skill healthy. doctor now fetches the published version alongside the CLI update check and suggests upgrade --skill. Both commands share a semver comparison. status compared with !=, so a skill ahead of main (a dev build) was reported as having an update. Refs #200 * fix(cli): count batch audit warnings in words and clear progress spinners The batch install and update audit summary still printed "2 skill(s)" and "warning(s)" after the rest of the output switched to "1 skill" / "2 skills". uninstall and agent update also left "Found N skills" and "Check complete" behind, progress messages the restyle clears. Refs #200 * fix(cli): say so when diff or analyze has no targets With no targets configured, diff reported "No differences" and analyze printed only its "Add -v" hint, both reading like a healthy result. They now say no targets are configured and suggest target add, as target list does. Refs #200 * fix(diff): align values across target sections Each target section sized its labels on its own, so a section with "Local only" started its values two columns later than one with only "New", and the list read ragged. All sections now share one width. Refs #200 * fix(doctor): count built-in skill warnings in the summary The skill rows (not found, missing version, newer version available) were marked as warnings and counted by --json, but never reached the text summary, so doctor could print "! Skill not found" and close with "All checks passed". The all-good integration test only passed because of this; it now installs the built-in skill it needs. Refs #200 * fix(init): stop writing a git identity into existing repos On a repo the user created, init stored skillshare@local in the repo config so its one commit would work. That setting outranks --global, so the advice we printed never took effect and later pushes went out as skillshare@local. The commit now gets the fallback through env vars only. The note for repos init creates names the repo-level command that actually overrides it. Dry runs also wrote .gitignore into existing repos while closing with "nothing was written", and warned about --no-git when it was not passed; both now only describe what would happen. Refs #200 * fix(cli): tell "no targets" apart from "nothing reaches them" diff and analyze said "No targets configured" and suggested adding one whenever there was nothing to show, including when targets exist but have skills turned off or no skill is meant for them. Refs #200 * fix(log): drop the trailing separator on instant entries Entries with no recorded duration ended in a dangling " · ". Also removes the formatRelativeTime alias the stats restyle left unused; its test now covers formatDurationShort directly. Refs #200 * docs: match tui, project list and log examples to the real output The tui and project list examples used label widths the CLI does not print, and the plain log example claimed to show non-TTY output, which joins each entry's details on one line. Refs #200 * perf(version): cache the published skill version for a day doctor and status asked GitHub for the latest skill version on every run, adding up to 3 s when offline. They now reuse the answer for 24 hours, the same interval the CLI update check caches for. upgrade --skill still fetches fresh and records what it got. Refs #200 * perf(server): reuse the cached skill version on the dashboard The version endpoint fetched the published skill version on every call, like doctor and status did, so it now shares their 24-hour cache. It also treated any difference as an update, offering a "newer" skill to anyone running a local build ahead of main. Refs #200 * test(redteam): match the restyled update --diff heading update --diff now titles its file list "Files changed" in sentence case, like every other section, so the check for the list looked for the old "Files Changed" box title and failed although the list was there. Refs #200 * test(cli): keep /tmp fixtures unfolded where HOME is /tmp scripts/test.sh now runs the cmd unit tests, so the docker sandbox runs them too, with HOME=/tmp. shortenPath then folds the /tmp fixtures in four tests to ~ and their exact-path checks fail. The tests now point the cached home elsewhere while they run. Refs #200 * fix(init): find skills/ in a repo that holds nothing else The check for a skills/ folder ran only when the repo root had no skill folders, but it counted skills/ itself as one, so it never ran. A repo with only skills/ became the source as a whole, one level too high. Refs #200 * fix(init): keep the skills git scope for a custom source With a remote that has no skills yet, init defaulted to versioning the whole skillshare folder. For a --source outside that folder it holds none of the user's skills, so the commit and every later push carried nothing while init reported the remote as linked. Refs #200 * test(sync): check only the Agents section for updated agents The restyle turned the old "0 updated" check on the agent summary into "no 'updated' anywhere", which also covered the Skills section. On macOS the first project sync reports the skill as updated there, so the test failed on something it was never meant to check. Refs #200
38 KiB
sidebar_position
| sidebar_position |
|---|
| 4 |
Configuration
Configuration file reference for skillshare.
Overview
~/.config/skillshare/
├── config.yaml ← Configuration file
├── skills/ ← Source directory (your skills)
│ ├── .metadata.json ← Skill metadata (auto-managed)
│ ├── my-skill/
│ ├── another/
│ └── _team-repo/ ← Tracked repository
├── extras/ ← Extras source root
│ └── rules/ ← Extra resource (e.g., rules)
~/.local/share/skillshare/
└── backups/ ← Automatic backups
└── 2026-01-20.../
IDE Support (JSON Schema)
Config files include a YAML Language Server directive that enables autocompletion, validation, and hover documentation in supported editors.
New configs created by skillshare init include this automatically:
# yaml-language-server: $schema=https://raw.githubusercontent.com/runkids/skillshare/main/schemas/config.schema.json
source: ~/.config/skillshare/skills
targets:
claude:
path: ~/.claude/skills
Adding to an existing config
If your config was created before this feature, add the comment as the first line:
Global config (~/.config/skillshare/config.yaml):
# yaml-language-server: $schema=https://raw.githubusercontent.com/runkids/skillshare/main/schemas/config.schema.json
Project config (.skillshare/config.yaml):
# yaml-language-server: $schema=https://raw.githubusercontent.com/runkids/skillshare/main/schemas/project-config.schema.json
Or simply re-run skillshare init --force (global) or skillshare init -p --force (project) to regenerate the config with the schema comment.
Supported editors
| Editor | Extension required |
|---|---|
| VS Code | YAML by Red Hat |
| JetBrains IDEs | Built-in YAML support |
| Neovim | yaml-language-server via LSP |
Config File
Location: ~/.config/skillshare/config.yaml
Full Example
# yaml-language-server: $schema=https://raw.githubusercontent.com/runkids/skillshare/main/schemas/config.schema.json
# Source directory (where you edit skills)
source: ~/.config/skillshare/skills
# Default sync mode for new targets
mode: merge
# Default target naming (flat or standard)
# target_naming: flat
# Targets (AI CLI skill directories)
targets:
claude:
path: ~/.claude/skills
# mode: merge (inherits from default)
codex:
path: ~/.codex/skills
mode: symlink # Override default mode
include: [codex-*] # merge/copy mode only
cursor:
path: ~/.cursor/skills
mode: copy # real files for Cursor
exclude: [experimental-*] # merge/copy mode only
# Custom target
myapp:
path: ~/apps/myapp/skills
# Remote skills — auto-managed by install/uninstall
skills:
- name: pdf
source: anthropics/skills/skills/pdf
- name: _team-skills
source: github.com/team/skills
tracked: true
# Fold $HOME → ~ on save (dotfiles-friendly)
# preserve_tilde_on_save: true
# Directory for commit/push/pull (skills default, agents, extras, root)
# git_root: skills
# Custom agents source (optional, overrides default location)
agents_source: ~/my-agents
# Custom extras source (optional, overrides default location)
extras_source: ~/my-extras
# Non-skill resources to sync
extras:
- name: rules
source: ~/company-shared/rules # optional per-extra override
targets:
- path: ~/.claude/rules
- path: ~/.cursor/rules
mode: copy
# Files to ignore during sync
ignore:
- "**/.DS_Store"
- "**/.git/**"
- "**/node_modules/**"
- "**/*.log"
Fields
source
Path to your skills directory (single source of truth).
source: ~/.config/skillshare/skills
Default: ~/.config/skillshare/skills
mode
Default sync mode for all targets.
mode: merge
| Value | Behavior |
|---|---|
merge |
Each skill symlinked individually. Local skills preserved. (default) |
copy |
Each skill copied as real files. For AI CLIs that can't follow symlinks. |
symlink |
Entire target directory is one symlink. |
target_naming
Default target naming strategy for merge/copy sync.
target_naming: flat
| Value | Behavior |
|---|---|
flat |
Nested skills flattened with __ separators (e.g. frontend__dev). (default) |
standard |
Uses the SKILL.md name field directly (e.g. dev). Follows the Agent Skills spec. |
include / exclude keep matching the flat name (frontend__dev) in both modes, so under standard the filter differs from the folder sync creates — see include / exclude.
targets
AI CLI skill directories to sync to.
targets:
<name>:
path: <path>
mode: <mode> # optional, overrides default
include: [<glob>, ...] # optional, merge/copy mode only
exclude: [<glob>, ...] # optional, merge/copy mode only
Example:
targets:
claude:
path: ~/.claude/skills
codex:
path: ~/.codex/skills
mode: symlink
custom:
path: ~/my-app/skills
Another account of an Agent
A target can be a second config directory of a built-in Agent: Claude Code started with CLAUDE_CONFIG_DIR, Codex with CODEX_HOME, or Pi with PI_CODING_AGENT_DIR. Name the Agent and the directory; the skills and agents paths follow it.
targets:
claude-work:
agent: claude
config_dir: ~/.claude-work # skills go to ~/.claude-work/skills, agents to ~/.claude-work/agents
codex-work:
agent: codex
config_dir: ~/.codex-work # skills go to ~/.codex-work/skills
Codex reads the shared ~/.agents/skills as well, but an account owns only its own directory, so its skills go to <config_dir>/skills. Pi works the same way. Only Claude has an agents directory.
| Field | Description |
|---|---|
agent |
The built-in Agent: claude (CLAUDE_CONFIG_DIR), codex (CODEX_HOME) or pi (PI_CODING_AGENT_DIR) |
config_dir |
That account's config directory. Absolute or starting with ~, not the Agent's default one, and used by one target only |
cli |
Optional. Runs the account's plugin commands with a compatible CLI instead of the Agent's own, such as omo for Pi. A name found on PATH, or an absolute path that may start with ~. One executable without arguments; shell aliases are not seen |
A compatible CLI that keeps the Agent's commands can run the account's plugins. For example, omo is built on Pi:
targets:
omo:
agent: pi
config_dir: ~/.omo/agent
cli: omo
cli changes only which program installs and removes plugins. Skills, agents and MCP servers are written to config_dir as before.
mode, include, exclude and the other target settings work as on any target. A skills.path or agents.path you write yourself wins over the derived one. The target name can also be used as an MCP target, as a plugin target and as a hooks target.
Instruction file
skillshare knows the instruction file (CLAUDE.md, AGENTS.md, GEMINI.md, ...) of
many built-in targets. For any other tool, instructions tells it which file the
tool reads, so the dashboard can show and edit it and attach
shared AGENTS.md files. A value
set here takes the place of the built-in file.
targets:
myagent:
path: ~/.myagent/skills
instructions:
path: ~/.myagent/AGENTS.md
import: true # the tool follows @path lines
| Field | Description |
|---|---|
instructions.path |
The file the tool reads. In the global config, an absolute path or one that starts with ~/. In a project config, a path relative to the project root, such as .myagent/AGENTS.md. It must name a file, not a directory |
instructions.import |
true when the tool follows @path lines. It can then use several shared files at once, each added as one import line. Default false: the tool uses one shared file, linked in place of its own |
The dashboard writes this field from the Custom target dialog when you add the target, or later from the target's instruction tab. It refuses to change or remove it while the target uses shared files. Removing it doesn't delete the file.
Other files
Besides its instruction file, a tool may read other plain files, such as Pi's
APPEND_SYSTEM.md. The dashboard shows each one as a tab on the target's page.
skillshare adds APPEND_SYSTEM.md for pi and omp; files lists the ones you add.
targets:
pi:
files:
- SYSTEM.md
- prompts/review.md
Each entry is relative to the tool's folder: ~/.pi/agent for pi in the global
config, .pi in a project. Entries may name a subfolder, but can't leave that folder:
absolute paths, .., and folders that link outside it are refused. The folder is the
tool's own config folder, such as ~/.codex for codex or an account's
config_dir; when skillshare knows none, it is the folder above
the skills folder. A target whose folder would be your home directory or the project
root has no + button.
The dashboard writes this field when you add or remove a tab. Removing a tab doesn't delete the file.
Skills off
skills.enabled: false stops syncing skills to a target while skillshare keeps managing its agents, MCP servers and instructions. Use it for a tool that already reads another target's skills folder, so it does not find each skill twice.
targets:
pi:
skills:
path: ~/.pi/agent/skills
enabled: false
The path, mode and filters stay in the config for when you turn skills back on. Set it with skillshare target <name> --skills=false, which also removes the folder's links into the source, or add the target with --no-skills. See Skills on or off.
include / exclude (target filters)
Use per-target filters to control which skills are synced in merge and copy modes.
targets:
codex:
path: ~/.codex/skills
include: [codex-*]
claude:
path: ~/.claude/skills
exclude: [codex-*]
Rules:
- Matching is against target flat names (for example
team__frontend__ui) - An
includepattern that matches no skill is reported, because such a target syncs nothing and drops what a previous pattern linked. Filters keep using flat names even whentarget_naming: standardshows the bareSKILL.mdname in the target includeis applied firstexcludeis applied after include- Pattern syntax uses Go
filepath.Match(*,?,[...]) - In
symlinkmode, include/exclude is ignored - If a previously synced source link becomes excluded,
syncremoves that target entry - Local non-symlink folders that already existed in target are preserved
Pattern cheat sheet
| Pattern | Matches | Typical use |
|---|---|---|
codex-* |
codex-agent, codex-rag |
Prefix-based grouping |
team__* |
team__frontend__ui |
Repo/group namespace |
*-experimental |
rag-experimental |
Suffix-based cleanup |
core-? |
core-a, core-1 |
Single-character variant |
[ab]-tool |
a-tool, b-tool |
Small explicit set |
Scenario A: include only
Use include when a target should receive only a focused subset.
targets:
codex:
path: ~/.codex/skills
include: [codex-*, shared-*]
Use case:
- Keep Codex focused on coding workflows only
- Avoid sending writing/research-only skills to this target
Scenario B: exclude only
Use exclude when a target should receive almost everything except a known subset.
targets:
claude:
path: ~/.claude/skills
exclude: [*-experimental, codex-*]
Use case:
- Keep one main target broad
- Hide unstable or target-specific skills
Scenario C: include + exclude
Use both when you want a broad include, then carve out exceptions.
targets:
cursor:
path: ~/.cursor/skills
include: [core-*, team__*]
exclude: [*-deprecated, team__legacy__*]
Evaluation order:
- Keep only names matching
include - Remove matches from
exclude
Given source skills:
core-authcore-deprecatedteam__frontend__uiteam__legacy__docsmisc-tool
Result for cursor:
- Synced:
core-auth,team__frontend__ui - Not synced:
core-deprecated,team__legacy__docs,misc-tool
Managing filters via CLI
Instead of editing YAML manually, use the target command:
# Skills
skillshare target claude --add-include "team-*"
skillshare target claude --add-exclude "_legacy*"
skillshare target claude --remove-include "team-*"
# Agents (only for targets with an agents path)
skillshare target claude --add-agent-include "team-*"
skillshare target claude --add-agent-exclude "draft-*"
skillshare target claude --remove-agent-include "team-*"
skillshare sync # Apply changes
Duplicate patterns are silently ignored. Invalid glob patterns return an error. Agent filters use the same glob syntax as skill filters, but only work in merge and copy modes. In symlink mode, agent filters are ignored because the entire agents directory is linked as one unit.
See target command for full reference.
Skill-level targets
Skills can declare which targets they're compatible with using metadata.targets in SKILL.md. A top-level targets field is still supported as a fallback for older skills, but metadata.targets takes precedence when both are present:
---
name: claude-prompts
metadata:
targets: [claude]
---
This is a second layer of filtering that works alongside config-level include/exclude:
Source Skills
│
├─ Config include/exclude ← per-target, set by consumer
│
└─ Skill targets field ← per-skill, set by author
│
▼
Skills synced to target
Evaluation order:
include— keep only matching namesexclude— remove matching namestargetsfield — remove skills whose targets list doesn't include this target
Both layers must pass (AND relationship). Config filters always take priority — even if a skill declares targets: [claude], a config exclude: [claude-*] will still exclude it.
Cross-mode matching: targets: [claude] matches both the global target claude and the project target claude, because they refer to the same AI CLI. See supported targets.
:::tip
Use config filters (include/exclude) when the consumer wants to control what goes where. Use skill-level targets when the author knows the skill only works with specific AI CLIs.
:::
Existing target entries when filters change
When you add or change filters, then run skillshare sync:
| Existing item in target | What happens |
|---|---|
| Link skillshare created for a source skill that is now filtered out | Removed (unlinked) |
| Managed copy (copy mode) that is now filtered out | Removed |
| Live symlink/junction into the source that skillshare never tracked | Preserved (counted as local) |
| Local non-symlink directory created in target | Preserved |
| Unrelated local content | Preserved |
skills
Tracks remotely-installed skills. Auto-managed by skillshare install and skillshare uninstall.
skills:
- name: pdf
source: anthropics/skills/skills/pdf
- name: _team-skills
source: github.com/team/skills
tracked: true
| Field | Required | Description |
|---|---|---|
name |
Yes | Skill directory name |
source |
Yes | GitHub URL or local path |
tracked |
No | true if installed with --track (default: false) |
When you run skillshare install with no arguments, all listed skills that aren't already present are installed. This makes config.yaml a portable skill manifest — copy it to another machine and run skillshare install && skillshare sync.
The skills: list is automatically updated after each install and uninstall operation. You don't need to edit it manually.
:::note Migrated to .metadata.json
Starting from v0.16.2, installed skill entries moved from config.yaml to a separate file. In the current version, all installation metadata is stored in a centralized .metadata.json inside the skills/ directory. Migration from older formats (registry.yaml, per-skill .skillshare-meta.json) is automatic on first run.
:::
agents_source
Custom source directory for agents. Overrides the default ~/.config/skillshare/agents/.
agents_source: ~/my-agents
When set, all agents are read from this directory instead of the default. Supports ~ expansion.
Default: ~/.config/skillshare/agents/ (auto-detected, no need to set explicitly unless you want a custom location).
:::note Global mode only
Project mode always uses .skillshare/agents/ and does not support agents_source.
:::
See Agents for details on agent file format, sync behavior, and supported targets.
projects
Project folders that get skills and agents from this global config. The folders need no .skillshare/ of their own, and one skillshare sync from anywhere writes them all.
Use it when projects should get different skills. Global targets already reach every project with the same set, and project mode keeps the setup in the project's repo for teammates. Many Projects, One Config compares the three.
projects:
<folder>: # absolute, or starting with ~
name: <name> # optional, defaults to the folder name
targets: [<target>, ...] # the tools used in this project
skills: # present = sync skills; empty = all of them
mode: <mode>
target_naming: <flat|standard>
include: [<glob>, ...]
exclude: [<glob>, ...]
agents: # present = sync agents; empty = all of them
mode: <mode>
include: [<glob>, ...]
exclude: [<glob>, ...]
Example:
projects:
~/work/shop-web:
targets: [claude, cursor, codex]
skills:
mode: copy
include: ["frontend-*"]
agents: {}
~/work/api-server:
targets: [claude]
skills: {}
Each entry in targets is a supported target name. Skillshare writes to that tool's project paths inside the folder, for example .claude/skills and .claude/agents for claude. There is no path to set.
- Shared folders are written once. Several tools read the same project folder (
cursorandcodexboth read.agents/skills). They become one sync target. - Names in output.
sync,status,diff,doctorandbackupshow a project's targets as<name>@<target>, for exampleshop-web@claude.namecannot contain@,/or\, and two projects cannot share one. - Agents are written only for tools that have a project agents folder. A project with
agentsand noskillssyncs agents alone. - A missing folder is skipped.
syncprintsproject <folder>: folder not found, skippedand never recreates a project you moved or deleted. targetandcollectleave projects alone.skillshare targetlists and edits thetargetssection only, andcollectdoes not pull a project's own skills into the source. Editprojectsinconfig.yaml, or on the dashboard's Projects page.- Skills with a
targetsfrontmatter field are matched against the tool, sotargets: [claude]reachesshop-web@claude.
MCP servers for the same folders are listed under mcp.projects, keyed by the same folder. For a step-by-step setup see Many Projects, One Config.
extras
Non-skill resources (rules, commands, prompts, etc.) to sync to arbitrary directories.
extras_source: ~/my-extras # optional global default source
extras:
- name: rules
source: ~/company-shared/rules # optional per-extra override
targets:
- path: ~/.claude/rules
- path: ~/.cursor/rules
mode: copy
- name: agents
targets:
- path: ~/.claude/agents
flatten: true # sync subdirectory files flat
- name: commands
targets:
- path: ~/.claude/commands
| Field | Required | Description |
|---|---|---|
name |
Yes | Extra identifier |
source |
No | Custom source directory for this extra (overrides extras_source and default) |
file |
No | Sync only this file from the source directory: a plain file name such as system.md or AGENTS.md. See single-file extras |
targets |
Yes | List of target paths |
targets[].path |
Yes | Destination directory |
targets[].mode |
No | merge (default), copy, or symlink; import for single-file extras only |
targets[].as |
No | File name in the target for a single-file extra (default: the file name) |
targets[].flatten |
No | When true, sync subdirectory files directly into target root (cannot use with symlink or file) |
extras_source is auto-populated to the default path (~/.config/skillshare/extras/) on skillshare init or first extras init. Override it to use a custom location for all extras.
Source resolution (three-level priority):
- Per-extra
source→ exact path (e.g.,~/company-shared/rules) extras_source→<extras_source>/<name>/(e.g.,~/my-extras/rules/)- Default →
~/.config/skillshare/extras/<name>/
Sync modes:
merge(default) — per-file symlinkscopy— per-file copysymlink— entire directory symlink
Run skillshare sync extras to sync, or skillshare sync --all to sync skills + extras together.
:::info Both modes supported
Extras work in both global and project mode. In project mode, source is .skillshare/extras/<name>/.
:::
See sync extras for usage details.
ignore
Glob patterns for files to skip during sync.
ignore:
- "**/.DS_Store"
- "**/.git/**"
- "**/node_modules/**"
Default patterns:
**/.DS_Store**/.git/**
gitlab_hosts
Hostnames of self-managed GitLab instances that use nested subgroups. Hosts containing gitlab or jihulab in the name are detected automatically — this field is only needed for other custom domains.
gitlab_hosts:
- git.company.com
- code.internal.io
When a hostname is listed here, skillshare install treats the full URL path as the repository (supporting nested subgroups up to 20 levels), instead of assuming the standard owner/repo two-segment split.
Without gitlab_hosts:
# git.company.com/team/frontend/ui → clones "team/frontend", subdir "ui"
skillshare install git.company.com/team/frontend/ui
With gitlab_hosts: [git.company.com]:
# git.company.com/team/frontend/ui → clones "team/frontend/ui" (full path)
skillshare install git.company.com/team/frontend/ui
Workaround without config: append .git to mark the end of the repo path:
skillshare install git.company.com/team/frontend/ui.git
Entries must be bare hostnames (no scheme, path, or port). They are normalized to lowercase.
Environment variable
For CI/CD pipelines that don't have a config file, use SKILLSHARE_GITLAB_HOSTS (comma-separated):
SKILLSHARE_GITLAB_HOSTS=git.company.com,code.internal.io skillshare install git.company.com/team/frontend/ui
When both the config file and env var are set, their values are merged (deduplicated). Invalid entries in the env var are silently skipped.
azure_hosts
Hostnames of self-hosted Azure DevOps Server instances. The built-in patterns for dev.azure.com and *.visualstudio.com are always active — this field is only needed for on-premises Azure DevOps Server with custom domains.
azure_hosts:
- azuredevops.mycompany.com
When a hostname is listed here, URLs containing /_git/ are routed through Azure DevOps parsing logic, which correctly extracts the org, project, and repo without appending .git to the clone URL.
Without azure_hosts:
# Falls through to generic HTTPS parsing — clone URL becomes
# https://azuredevops.mycompany.com/Org/Project.git (WRONG)
skillshare install https://azuredevops.mycompany.com/Org/Project/_git/Repo
With azure_hosts: [azuredevops.mycompany.com]:
# Correctly parsed — clone URL is
# https://azuredevops.mycompany.com/Org/Project/_git/Repo
skillshare install https://azuredevops.mycompany.com/Org/Project/_git/Repo
Entries must be bare hostnames (no scheme, path, or port). They are normalized to lowercase.
Environment variable
For CI/CD pipelines, use SKILLSHARE_AZURE_HOSTS (comma-separated):
SKILLSHARE_AZURE_HOSTS=azuredevops.mycompany.com skillshare install \
https://azuredevops.mycompany.com/Org/Project/_git/Repo
gitea_hosts
Hostnames of self-hosted Gitea instances. Hosts containing gitea in the name, such as gitea.com or gitea.company.com, are detected automatically. This field is only needed for other custom domains.
gitea_hosts:
- git.company.com
When a hostname is listed here:
installandupdateuseGITEA_TOKENfor HTTPS authentication on that hostinstalldownloads a subdirectory through the Gitea Contents API when a sparse checkout is unavailable or fails, instead of cloning the whole repository. If the API call fails too, it falls back to a full clone.
Entries must be bare hostnames (no scheme, path, or port). They are normalized to lowercase.
Environment variable
For CI/CD pipelines, use SKILLSHARE_GITEA_HOSTS (comma-separated):
SKILLSHARE_GITEA_HOSTS=git.company.com skillshare install https://git.company.com/team/skills/review
When both the config file and env var are set, their values are merged (deduplicated).
cnb_hosts
Hostnames of self-hosted CNB instances. cnb.cool is detected automatically. This field is only needed for a private deployment on another domain.
cnb_hosts:
- cnb.company.com
A listed host uses CNB_TOKEN for HTTPS authentication, and subdirectory installs can go through the CNB contents API with the same fallback to a full clone.
Entries must be bare hostnames (no scheme, path, or port). They are normalized to lowercase.
Environment variable
SKILLSHARE_CNB_HOSTS=cnb.company.com skillshare install https://cnb.company.com/team/skills/review
audit
Security audit configuration.
audit:
block_threshold: CRITICAL
profile: default
dedupe_mode: global
enabled_analyzers: [static, dataflow, tier, integrity]
| Field | Values | Default | Description |
|---|---|---|---|
block_threshold |
CRITICAL, HIGH, MEDIUM, LOW, INFO |
CRITICAL |
Minimum severity to block skillshare install |
profile |
default, strict, permissive |
default |
Audit profile preset (sets defaults for threshold and dedupe) |
dedupe_mode |
legacy, global |
global |
Finding deduplication mode |
enabled_analyzers |
Array of analyzer IDs | (all) | Allowlist of analyzers to run (omit for all) |
Profiles set sensible defaults that can be overridden by explicit field values:
| Profile | Threshold | Dedupe | Description |
|---|---|---|---|
default |
CRITICAL |
global |
Same as current behavior |
strict |
HIGH |
global |
Stricter blocking for security-conscious teams |
permissive |
CRITICAL |
legacy |
Advisory-only, minimal blocking |
Analyzer IDs: static, dataflow, tier, integrity, structure, cross-skill
Precedence: CLI flags → project config → global config → profile defaults.
block_thresholdonly controls when install is blocked — scanning always runs- Use
--skip-auditto bypass scanning for a single install - Use
--forceto override a block (findings are still shown)
context_budget
Token budget warning thresholds. Warnings appear after sync and analyze when token count exceeds budget.
context_budget:
warn_always_loaded_tokens: 10000
warn_on_demand_tokens: 100000
| Field | Type | Default | Description |
|---|---|---|---|
warn_always_loaded_tokens |
integer | 10000 |
Warn when always-loaded tokens exceed this value. 0 disables |
warn_on_demand_tokens |
integer | 100000 |
Warn when on-demand tokens exceed this value. 0 disables |
When omitted, defaults apply (10K / 100K). Use skillshare sync --quiet to suppress warnings. See sync — Context Cost for output format.
preserve_tilde_on_save
When true, folds $HOME prefixes back to ~ before writing config.yaml. Keeps the on-disk config portable across machines — useful when the config is shared via dotfiles (stow, chezmoi, yadm, bare git repo).
preserve_tilde_on_save: true
Default: false (existing behavior unchanged — paths are saved as absolute).
Without this flag, every save rewrites ~/... paths as /home/alice/... (the expanded form). When the config is version-controlled and shared across machines, this creates noisy diffs and breaks portability.
With the flag enabled, the serialized YAML uses ~ for any path under $HOME:
# Before (default): absolute, machine-specific
source: /home/alice/.config/skillshare/skills
targets:
claude:
skills:
path: /home/alice/.claude/skills
# After (preserve_tilde_on_save: true): portable
source: ~/.config/skillshare/skills
targets:
claude:
skills:
path: ~/.claude/skills
The in-memory config is unaffected — Load() still expands ~ as usual. Non-home absolute paths (e.g. /opt/shared/skills) are passed through unchanged.
:::note Global mode only
This option applies to the global config.yaml only. Project configs (.skillshare/config.yaml) typically use relative paths and don't need tilde folding.
:::
git_root
Selects which directory skillshare commit, push, and pull operate on.
git_root: skills
| Value | Directory versioned |
|---|---|
skills (default) |
Skills source (~/.config/skillshare/skills/) |
agents |
Agents source (~/.config/skillshare/agents/) |
extras |
Extras source (~/.config/skillshare/extras/) |
root |
Config root (~/.config/skillshare/) — skills + agents + extras in one repo; config.yaml is auto-ignored |
Default: skills
Set during init with skillshare init --git-root <scope>, or with Change settings in the init summary.
Changing the scope after init
Switch the scope headlessly on an already-initialized setup:
skillshare init --git-root <scope> # global mode; add -g if your cwd is a project
This initializes a git repo at the new scope directory (reusing one already there), persists git_root to config, and does not prompt or require --remote. It does not move an existing repo, though — switching scope means "start versioning a different directory", not "relocate history":
- Fresh history —
skillshare init --git-root <scope>initializes an empty repo at the new scope. - Keep history — first
mv <old-scope>/.git <new-scope>/.git, thenskillshare init --git-root <scope>to record the scope.
You can also edit git_root in config.yaml directly. If git_root points to a directory without a repo while another scope directory has one, commit/push/pull print a "Git root mismatch" error that includes the exact skillshare init / mv commands to resolve it.
:::note Global mode only
git_root applies to global mode only. Project mode uses the .skillshare/ directory and does not support this field.
:::
Project Config
Location: .skillshare/config.yaml (in project root)
Project config uses a different format from global config.
# yaml-language-server: $schema=https://raw.githubusercontent.com/runkids/skillshare/main/schemas/project-config.schema.json
# Targets — string or object form
targets:
- claude # String: known target with defaults
- cursor
- name: custom-ide # Object: custom path and mode
path: ./tools/ide/skills
mode: symlink
- name: codex # Object with filters
include: [codex-*]
exclude: [codex-experimental-*]
# Remote skills — auto-managed by install/uninstall
skills:
- name: pdf
source: anthropic/skills/pdf
- name: _team-skills
source: github.com/team/skills
tracked: true # Cloned with git history
# Audit — same fields as global
audit:
block_threshold: HIGH
profile: strict
targets (project)
Supports two YAML forms:
| Form | Example | When to use |
|---|---|---|
| String | - claude |
Known target, default path and merge mode |
| Object | - name: x, path: ..., mode: ..., include: [...], exclude: [...] |
Custom path, mode override, or per-target filters |
An object entry can also set instructions, with a path
relative to the project root.
skills (project)
Same schema as the global skills field. Auto-managed by skillshare install -p and skillshare uninstall -p.
:::tip Portable Manifest
config.yaml is a portable skill manifest — in both global and project mode. Run skillshare install && skillshare sync on a new machine (or skillshare install -p in a project) to reproduce the same setup.
:::
Managing Config
View current config
skillshare status
# Shows source, targets, modes
Edit config directly
# Open in editor
$EDITOR ~/.config/skillshare/config.yaml
# Then sync to apply changes
skillshare sync
Reset config
rm ~/.config/skillshare/config.yaml
skillshare init
Custom Audit Rules
Location:
| Mode | Path |
|---|---|
| Global | ~/.config/skillshare/audit-rules.yaml |
| Project | .skillshare/audit-rules.yaml |
Rules are merged in order: built-in → global → project. You can add new rules, disable built-in rules, or override severity.
rules:
# Add a custom rule
- id: flag-todo
severity: MEDIUM
pattern: todo-comment
message: "TODO comment found"
regex: '(?i)\bTODO\b'
# Disable a built-in rule
- id: insecure-http-0
enabled: false
| Field | Required | Description |
|---|---|---|
id |
Yes | Unique rule identifier |
severity |
Yes | CRITICAL, HIGH, MEDIUM, LOW, INFO |
pattern |
Yes | Pattern category name |
message |
Yes | Human-readable finding description |
regex |
Yes | Regular expression to match |
exclude |
No | Suppress match when line also matches this regex |
enabled |
No | Set false to disable a built-in rule |
To scaffold a starter file:
skillshare audit --init-rules # Global
skillshare audit --init-rules -p # Project
See audit command for full details.
Environment Variables
| Variable | Description |
|---|---|
SKILLSHARE_CONFIG |
Override config file path |
GITHUB_TOKEN |
For API rate limit issues |
Example:
SKILLSHARE_CONFIG=~/custom-config.yaml skillshare status
Skill Metadata
When you install a skill, skillshare records its metadata in the centralized .metadata.json file:
{
"skills": [
{
"name": "pdf",
"source": "anthropics/skills/skills/pdf",
"type": "github",
"installed_at": "2026-01-20T15:30:00Z",
"repo_url": "https://github.com/anthropics/skills.git",
"subdir": "skills/pdf",
"version": "abc1234"
}
]
}
Each skill entry includes:
| Field | Description |
|---|---|
name |
Skill directory name |
source |
Original install source input |
type |
Source type (github, local, etc.) |
installed_at |
Installation timestamp |
repo_url |
Git clone URL (git sources only) |
subdir |
Subdirectory path (monorepo sources only) |
version |
Git commit hash at install time |
This is used by skillshare update and skillshare check to know where to fetch updates from.
Don't edit this file manually.
Platform Differences
macOS / Linux
source: ~/.config/skillshare/skills
targets:
claude:
path: ~/.claude/skills
Uses symlinks.
Windows
source: %AppData%\skillshare\skills
targets:
claude:
path: %USERPROFILE%\.claude\skills
Folders are linked with NTFS junctions (no admin required). Single files — agents and directory extras in merge mode, and single-file extras — need file symlinks, which require Developer Mode; without it they are copied instead. See Windows troubleshooting.
Related
- Source & Targets — Core concepts
- Sync Modes — Merge vs copy vs symlink
- Environment Variables — All variables