Files
skillshare/website/docs/troubleshooting/faq.md
T
Willie 2c3003e04f feat(website): complete website revamp — Diátaxis IA, blog, recipes, quickstarts
Restructure the entire documentation site following the Diátaxis framework
(Learn / How-to / Understand / Reference) with new content across 110 files.

## Information Architecture (M1)
- Move all docs to Diátaxis directory structure (learn/, how-to/, understand/, reference/)
- Add client-redirects plugin for old URL compatibility
- Rewrite sidebar, navbar, and footer to match new IA
- Update all internal cross-references

## Homepage + Quickstarts (M2)
- Add scenario entry cards to homepage with hand-drawn design
- 5 quickstart pages: Claude Code, GitHub Copilot (with copy mode recommendation),
  Codex, Multiple Tools, Dev Containers, Playground

## Blog + Changelog (M3)
- Enable Docusaurus blog plugin with authors.yml
- 5 blog posts: 5-min tutorial, managing 50+ skills, skillshare vs vercel/skills
  comparison, team sharing patterns, write your first skill
- Static /changelog page from CHANGELOG.md

## Recipes + Philosophy (M4)
- 5 recipe pages: CI/CD validation, enterprise skills, project setup,
  cross-machine sync, team onboarding
- 3 philosophy pages: why-local-first, security-first, sync-modes-explained

## Content Polish
- Cross-validate all content against CLI source (19 inaccuracies fixed)
- Lowercase "skillshare" throughout (avoid brand conflict with Skillshare Inc.)
- Add registry.yaml to file structure and Key Paths docs
- Highlight multi-platform git support (GitHub, GitLab, Bitbucket, Gitea,
  Azure DevOps, AtomGit, Codeberg)
- Standardize brew install command
- Add AsciinemaPlayer component (cast recordings pending)
2026-02-26 04:52:29 +08:00

10 KiB

sidebar_position
sidebar_position
4

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 git@github.com: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?

backup trash
Protects target directories (sync snapshots) source skills (uninstall)
Location ~/.local/share/skillshare/backups/ ~/.local/share/skillshare/trash/
Triggered by sync, target remove uninstall
Restore with skillshare restore <target> skillshare trash restore <name>
Auto-cleanup manual (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

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?

Aspect Regular Skill Tracked Repo
Source Copied to source Cloned with .git
Update install --update update <name> (git pull)
Prefix None _ prefix
Nested skills Flattened Flattened 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

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