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.

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​

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

Targets​

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 symlinks, copies source content back
  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.

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

~/.config/skillshare/backups/<timestamp>/

How long are backups kept?​

By default, indefinitely. Clean up with:

skillshare backup --cleanup

Getting Help​

Where do I report bugs?​

GitHub Issues

Where do I ask questions?​

GitHub Discussions