Files
skillshare/website/docs/troubleshooting/common-errors.md
T
Willie 4d17ff5d57 feat: add security audit — scan engine, CLI, install hooks, web UI, and docs
Scan skills for prompt injection, data exfiltration, credential access,
destructive commands, obfuscation, and suspicious URLs. CRITICAL findings
block installation by default; HIGH/MEDIUM shown as warnings.

- Scan engine: internal/audit with regex-based pattern matching
- CLI: `skillshare audit [name]` with per-skill progress and summary
- Install hooks: auto-scan after copy, block on CRITICAL unless --force
- Web UI: AuditPage with run/rescan, InstallForm shows ConfirmDialog
  for audit blocks (force-retry) and warning details
- ConfirmDialog: add `wide` prop, hide cancel when cancelText is empty
- Reduced false positives: rm -rf only flags root/glob, skip localhost
  URLs, exclude `fetch` as English word, hidden-unicode downgraded to HIGH
- README: add audit section, update screenshots, unify image sizes,
  add audit to Why/Comparison/Daily Commands
- Docs: audit command page, install security scanning section, FAQ,
  common errors, daily workflow, sidebar, landing page, intro
- Blog specs: add audit sections to Dev.to and Medium drafts
2026-02-10 01:53:55 +08:00

5.3 KiB

sidebar_position
sidebar_position
2

Common Errors

Error messages and their solutions.

Config Errors

config not found: run 'skillshare init' first

Cause: No configuration file exists.

Solution:

skillshare init

Add --source if you want a custom path:

skillshare init --source ~/my-skills

Target Errors

target add: path does not exist

Cause: The skills directory doesn't exist yet.

Solution:

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

target path does not end with 'skills'

Cause: Warning that path doesn't follow convention.

Solution: This is a warning, not an error. Proceed if your path is intentional, or fix it:

skillshare target add myapp ~/.myapp/skills  # Preferred

target directory already exists with files

Cause: Target has existing files that might be overwritten.

Solution:

skillshare backup
skillshare sync

Sync Errors

deleting a symlinked target removed source files

Cause: You ran rm -rf on a target in symlink mode.

Solution:

# If git is initialized
cd ~/.config/skillshare/skills
git checkout -- .

# Or restore from backup
skillshare restore <target>

Prevention: Use skillshare target remove instead of manual deletion.

sync seems stuck or slow

Cause: Large files in skills directory.

Solution: Add ignore patterns:

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

Git Errors

push: remote has changes

Cause: Remote repository is ahead of local.

Solution:

skillshare pull   # Get remote changes first
skillshare push   # Now push works

pull: local has uncommitted changes

Cause: You have local changes that haven't been pushed.

Solution:

# Option 1: Push your changes first
skillshare push -m "Local changes"
skillshare pull

# Option 2: Discard local changes
cd ~/.config/skillshare/skills
git checkout -- .
skillshare pull

merge conflicts

Cause: Same file was edited on multiple machines.

Solution:

cd ~/.config/skillshare/skills
git status                    # See conflicted files
# Edit files to resolve conflicts
git add .
git commit -m "Resolve conflicts"
skillshare sync

Install Errors

skill already exists

Cause: A skill with the same name is already installed.

Solution:

# Update the existing skill
skillshare install <source> --update

# Or force overwrite
skillshare install <source> --force

authentication required — for private repos use SSH URL

Cause: You're trying to install from a private repo using an HTTPS URL. Skillshare disables interactive credential prompts to prevent hanging.

Solution:

# Use SSH URL instead of HTTPS
skillshare install git@github.com:team/private-skills.git
skillshare install git@bitbucket.org:team/skills.git
skillshare install git@gitlab.com:team/skills.git

# With --track for team repos
skillshare install git@bitbucket.org:team/skills.git --track

Make sure your SSH key is configured for the git host. See Private Repositories.

invalid skill: SKILL.md not found

Cause: The source doesn't have a valid SKILL.md file.

Solution: Check the source path is correct and points to a skill directory.


Audit Errors

security audit failed — critical threats detected

Cause: The skill contains patterns matching critical security threats (prompt injection, data exfiltration, credential access).

Solution:

# Review the findings
skillshare audit <skill-name>

# If you trust the source, force install
skillshare install <source> --force

audit HIGH: Hidden zero-width Unicode characters detected

Cause: The skill contains invisible Unicode characters, which may be a copy-paste artifact or intentional obfuscation.

Solution: Open the file in an editor that shows hidden characters and remove them, or force install if you trust the source.


Upgrade Errors

GitHub API rate limit exceeded

Cause: Too many unauthenticated API requests.

Solution:

# Option 1: Set a GitHub token (recommended)
export GITHUB_TOKEN=ghp_your_token_here
skillshare upgrade

# Option 2: Force upgrade
skillshare upgrade --cli --force

Create a token at: https://github.com/settings/tokens (no scopes needed for public repos)


Skill Errors

skill not appearing in AI CLI

Causes:

  1. Skill not synced
  2. Invalid SKILL.md format
  3. AI CLI caching

Solutions:

# 1. Sync
skillshare sync

# 2. Check format
skillshare doctor

# 3. Restart AI CLI

skill name collision detected

Cause: Multiple skills have the same name field.

Solution: Use namespaced names:

# In _team-a/skill/SKILL.md
name: team-a:skill-name

# In _team-b/skill/SKILL.md
name: team-b:skill-name

Binary Errors

integration tests cannot find the binary

Cause: Binary not built or wrong path.

Solution:

go build -o bin/skillshare ./cmd/skillshare
# Or set
export SKILLSHARE_TEST_BINARY=/path/to/skillshare

Still Having Issues?

See Troubleshooting Workflow for a systematic debugging approach.