Skip to main content

FAQ

Frequently asked questions about skillshare.

General​

Isn't this just ln -s?​

Yes, at its core. But skillshare handles:

  • Multi-target detection
  • Backup/restore
  • Merge mode (per-skill symlinks)
  • Cross-device sync
  • Broken symlink recovery

So you don't have to.

What happens if I modify a skill in the target directory?​

Since targets are symlinks, changes are made directly to the source. All targets see the change immediately.

How do I keep a CLI-specific skill?​

Use merge mode (default). Local skills in the target won't be overwritten or synced.

skillshare target claude --mode merge
skillshare sync

Then create skills directly in ~/.claude/skills/ — they won't be touched.

I use a dotfiles manager (stow/chezmoi/yadm) — will skillshare break my symlinks?​

No. Skillshare detects external symlinks on both source and target directories and preserves them. All commands — sync, update, uninstall, list, diff, install — resolve symlinks and operate on the underlying directories without removing the links themselves. See Dotfiles Manager Compatibility for details.

Installation​

Can I sync skills to a custom or uncommon tool?​

Yes. Use skillshare target add <name> <path> with the tool's skills directory.

mkdir -p ~/.myapp/skills
skillshare target add myapp ~/.myapp/skills
skillshare sync

Can I use skillshare with a private git repo?​

Yes. Use SSH URLs:

skillshare init --remote [email protected]:you/private-skills.git

Sync​

Why do I need to run sync after every install/update?​

Sync is intentionally a separate step. Operations like install, update, and uninstall only modify the source directory — sync propagates those changes to all targets.

This lets you:

  • Batch changes — Install 5 skills, then sync once instead of 5 times
  • Preview first — Run sync --dry-run before applying
  • Stay in control — You decide when targets update

Note: pull is the only command that auto-syncs, because its intent is "bring everything up to date."

See Why Sync is a Separate Step for the full design rationale.

How do I sync across multiple machines?​

Use git-based cross-machine sync:

# Machine A: push changes
skillshare push -m "Add new skill"

# Machine B: pull and sync
skillshare pull

See Cross-Machine Sync for full setup.

If you have git initialized (recommended), recover with:

cd ~/.config/skillshare/skills
git checkout -- deleted-skill/

Or restore from backup:

skillshare restore claude

What if I accidentally uninstall a skill?​

Uninstalled skills are moved to trash and kept for 7 days. Restore with:

skillshare trash list                  # See what's in trash
skillshare trash restore my-skill      # Restore to source
skillshare sync                        # Sync back to targets

If the skill was installed from a remote source, you can also reinstall:

skillshare install github.com/user/repo/my-skill
skillshare sync

For project mode, trash is at .skillshare/trash/ within the project directory. Use -p flag with trash commands.

Run skillshare doctor to see current trash status (item count, size, age).

What's the difference between backup and trash?​

backuptrash
Protectstarget directories (sync snapshots)source skills (uninstall)
Location~/.local/share/skillshare/backups/~/.local/share/skillshare/trash/
Triggered bysync, target removeuninstall
Restore withskillshare restore <target>skillshare trash restore <name>
Auto-cleanupmanual (backup --cleanup)7 days

They are complementary — backup protects targets from sync changes, trash protects source skills from accidental deletion.

Can I sync specific skills to specific CLIs?​

Yes. For example, skill A only to Claude, skill B to Gemini and Codex, skill C to all:

Option 1: targets field in SKILL.md (set by skill author)

# skills/skill-a/SKILL.md
---
name: skill-a
targets: [claude]
---
# skills/skill-b/SKILL.md
---
name: skill-b
targets: [gemini, codex]
---
# skills/skill-c/SKILL.md — no targets field = syncs to all
---
name: skill-c
---

Option 2: include/exclude filters in config (set by consumer)

# ~/.config/skillshare/config.yaml
targets:
  claude:
    path: ~/.claude/skills
    include: [skill-a, skill-c]
  codex:
    path: ~/.codex/skills
    include: [skill-b, skill-c]

Both approaches can be combined — config filters are applied first, then the skill-level targets field. See Skill Format — targets and Configuration — filters.

Targets​

Using universal alongside npx skills​

The universal target points to ~/.agents/skills, the same directory used by the npx skills CLI. Both tools can manage this directory simultaneously with some caveats:

What works:

  • In merge mode (default), skillshare creates symlinks in ~/.agents/skills/; npx skills creates real directories. They coexist as long as skill names don't collide.
  • skillshare's prune logic only removes entries it manages — it won't delete files installed by npx skills.
  • Agent CLIs (Claude Code, Cursor, etc.) read directories directly, so they see skills from both tools.

What to watch out for:

  • Name collision — If both tools install a skill with the same name, the last sync/install wins. Avoid installing the same skill through both tools.
  • Copy mode is more aggressive — In copy mode (skillshare target universal --mode copy), skillshare overwrites managed directories on every sync. If npx skills modifies a same-named skill between syncs, skillshare will replace it. Merge mode (default) only creates symlinks, which is safer for coexistence.
  • npx skills list won't show skillshare skills — The npx skills CLI tracks installs via a lock file (~/.agents/.skill-lock.json), not by scanning the directory. Skills synced by skillshare won't appear in npx skills list -g, but they are visible to agent CLIs.
  • Other agent-specific targets still useful — universal and claude point to different paths (~/.agents/skills vs ~/.claude/skills). Selecting both is safe and not redundant.

Recommended workflow:

# Use skillshare as your primary skill manager
skillshare install github.com/user/skills --track
skillshare sync

# Use npx skills only for one-off community installs you don't need to sync
npx skills add someone/skill -g
tip

Keep the universal target in merge mode (default) for the safest coexistence with npx skills. Avoid switching to copy mode unless you don't use npx skills at all.

I used claude-code (or gemini-cli, etc.) as a project target — is that still valid?​

Yes. Old project target names like claude-code, gemini-cli, github-copilot still resolve via aliases. However, the canonical name is now the same as the global name (e.g., claude, gemini, copilot). We recommend updating your .skillshare/config.yaml to use the short name:

# Before
targets:
  - claude-code

# After
targets:
  - claude

How does target remove work? Is it safe?​

Yes, it's safe:

  1. Backup — Creates backup of the target
  2. Detect mode — Checks if symlink or merge mode
  3. Unlink — Removes all skillshare-managed symlinks, copies source content back as real files. In merge mode, only symlinks pointing to the source directory are removed; local (non-symlink) skills are preserved.
  4. Update config — Removes target from config.yaml

This is why skillshare target remove is safe, while rm -rf ~/.claude/skills would delete your source files.

Why is rm -rf on a target dangerous?​

In symlink mode, the entire target directory is a symlink to source. Deleting it deletes source.

In merge mode, each skill is a symlink. Deleting a skill through the symlink deletes the source file.

Always use:

skillshare target remove <name>   # Safe
skillshare uninstall <skill>      # Safe

Tracked Repos​

How do tracked repos differ from regular skills?​

AspectRegular SkillTracked Repo
SourceCopied to sourceCloned with .git
Updateinstall --updateupdate <name> (git pull)
PrefixNone_ prefix
Nested skillsFlattenedFlattened with __

Why the underscore prefix?​

The _ prefix identifies tracked repositories:

  • Helps you distinguish from regular skills
  • Prevents name collisions
  • Shows in listings clearly

Skills​

What's the SKILL.md format?​

---
name: skill-name
description: Brief description
---

# Skill Name

Instructions for the AI...

See Skill Format for full details.

What does "unknown target" warning mean?​

When running skillshare check or skillshare doctor, you may see:

! Skill targets: my-skill: unknown target "*"

This means the skill's SKILL.md frontmatter has a targets field with an unrecognized name — often "*" (wildcard). skillshare expects exact target names (e.g., claude, cursor, codex), not glob patterns.

If you want a skill to sync to all targets, omit the targets field entirely:

---
name: my-skill
description: Works everywhere
# no targets field = syncs to all targets
---

If this warning is from a third-party skill, the skill author used an unsupported syntax. You can:

  1. Ignore the warning — the skill still installs, it just won't auto-filter to specific targets
  2. Fork and fix — Remove or correct the targets field in the skill's SKILL.md

See Skill Format — targets for the full specification.

Can a skill have multiple files?​

Yes. A skill directory can contain:

  • SKILL.md (required)
  • Any additional files (examples, templates, etc.)

Reference them in your SKILL.md instructions.

Performance​

Sync seems slow​

Check for large files in your skills directory. Add ignore patterns:

# ~/.config/skillshare/config.yaml
ignore:
  - "**/.DS_Store"
  - "**/.git/**"
  - "**/node_modules/**"
  - "**/*.log"

How many skills can I have?​

No hard limit. Performance depends on:

  • Number of skills
  • Size of skill files
  • Number of targets

Thousands of small skills work fine.

Backups​

Where are backups stored?​

~/.local/share/skillshare/backups/<timestamp>/

How long are backups kept?​

By default, indefinitely. Clean up with:

skillshare backup --cleanup

Agents​

What's the difference between agents and skills?​

Skills are directories containing a SKILL.md file (and optionally helpers, examples, templates). Agents are single .md files with frontmatter — no nested structure. Both support install, sync, audit, check, backup, and trash.

See Agents for the full comparison and the agent file format.

Which targets support agents?​

Out of the box: claude, cursor, augment, opencode (plus the universal alias). Other targets are silently skipped during agent sync with a target(s) skipped for agents (no agents path) warning. You can add an agent path manually by editing config.yaml:

targets:
  myapp:
    path: ~/myapp/skills
    agents:
      path: ~/myapp/agents

How do I disable a single agent without deleting it?​

Use the disable command (or edit .agentignore directly):

skillshare disable my-agent --kind agent     # Adds entry to .agentignore
skillshare enable my-agent --kind agent      # Removes the entry

.agentignore lives in the agents source root (~/.config/skillshare/agents/.agentignore globally, .skillshare/agents/.agentignore in project mode) and uses gitignore syntax. A .agentignore.local overlay is also supported for local-only overrides.

Can I backup agents in project mode?​

Yes — and only agents. backup is not allowed in project mode for skills, but the agents flow is the explicit exception:

skillshare backup -p agents     # Backs up project agent targets
skillshare backup -p --all      # Same as above; --all narrows to agents in project mode

If you forget the agents filter, you'll see backup is not supported in project mode (except for agents). Same rule applies to restore. Agent backups are stored under <target>-agents/ next to the regular skill backups.

Security​

Can I trust third-party skills?​

Skills are instructions for your AI agent — a malicious skill could tell the AI to exfiltrate secrets or run destructive commands. skillshare mitigates this with a built-in security scanner:

  • Auto-scan on install — Every skill is scanned during skillshare install
  • CRITICAL findings block — Prompt injection, data exfiltration, credential access are blocked by default
  • Manual scan — Run skillshare audit to scan all installed skills at any time

See audit command for the full list of detection patterns.

What if audit blocks my install?​

If a skill triggers a CRITICAL finding, installation is blocked. You have two options:

  1. Review the finding — Check if it's a false positive (e.g., a documentation example)
  2. Force install — Use --force to bypass the check if you trust the source
skillshare install suspicious-skill --force

Does audit catch everything?​

No scanner is perfect. skillshare audit catches common patterns like prompt injection, curl/wget with secrets, credential file access, and obfuscated payloads. Always review skills from untrusted sources manually.

Getting Help​

Where do I report bugs?​

GitHub Issues

Where do I ask questions?​

GitHub Discussions