mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-20 20:34:19 +00:00
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)
354 lines
7.7 KiB
Markdown
354 lines
7.7 KiB
Markdown
---
|
|
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:**
|
|
```bash
|
|
skillshare init
|
|
```
|
|
|
|
Add `--source` if you want a custom path:
|
|
```bash
|
|
skillshare init --source ~/my-skills
|
|
```
|
|
|
|
---
|
|
|
|
## Target Errors
|
|
|
|
### `target add: path does not exist`
|
|
|
|
**Cause:** The skills directory doesn't exist yet.
|
|
|
|
**Solution:**
|
|
```bash
|
|
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:
|
|
```bash
|
|
skillshare target add myapp ~/.myapp/skills # Preferred
|
|
```
|
|
|
|
### `target directory already exists with files`
|
|
|
|
**Cause:** Target has existing files that might be overwritten.
|
|
|
|
**Solution:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
# 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:
|
|
```yaml
|
|
# ~/.config/skillshare/config.yaml
|
|
ignore:
|
|
- "**/.DS_Store"
|
|
- "**/.git/**"
|
|
- "**/node_modules/**"
|
|
```
|
|
|
|
---
|
|
|
|
## Git Errors
|
|
|
|
### `Could not read from remote repository`
|
|
|
|
**Cause:** SSH key not set up, or the remote URL is wrong.
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Check SSH access
|
|
ssh -T git@github.com
|
|
|
|
# If SSH isn't set up, use HTTPS instead
|
|
git -C ~/.config/skillshare/skills remote set-url origin https://github.com/you/my-skills.git
|
|
|
|
# Or set up SSH keys
|
|
ssh-keygen -t ed25519 -C "you@example.com"
|
|
# Then add the public key to GitHub → Settings → SSH keys
|
|
```
|
|
|
|
### `push: remote has changes`
|
|
|
|
**Cause:** Remote repository is ahead of local.
|
|
|
|
**Solution:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
cd ~/.config/skillshare/skills
|
|
git status # See conflicted files
|
|
# Edit files to resolve conflicts
|
|
git add .
|
|
git commit -m "Resolve conflicts"
|
|
skillshare sync
|
|
```
|
|
|
|
### `Git identity not configured`
|
|
|
|
**Cause:** No `user.name` / `user.email` in git config. skillshare uses a local fallback (`skillshare@local`) so init can complete, but you should set your own.
|
|
|
|
**Solution:**
|
|
```bash
|
|
git config --global user.name "Your Name"
|
|
git config --global user.email "you@example.com"
|
|
```
|
|
|
|
---
|
|
|
|
## Install Errors
|
|
|
|
### `skill already exists`
|
|
|
|
**Cause:** A skill with the same name is already installed.
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Update the existing skill
|
|
skillshare install <source> --update
|
|
|
|
# Or force overwrite
|
|
skillshare install <source> --force
|
|
```
|
|
|
|
### `Authentication failed` / `Access denied`
|
|
|
|
**Cause:** HTTPS credentials are missing, expired, or wrong token type.
|
|
|
|
**Solution — Option 1: Set a token env var:**
|
|
|
|
```bash
|
|
# GitHub
|
|
export GITHUB_TOKEN=ghp_xxxx
|
|
|
|
# GitLab (must be a Personal Access Token, prefix glpat-)
|
|
export GITLAB_TOKEN=glpat-xxxx
|
|
|
|
# Bitbucket
|
|
export BITBUCKET_TOKEN=your_app_password
|
|
```
|
|
|
|
**Windows (PowerShell):**
|
|
```powershell
|
|
$env:GITLAB_TOKEN = "glpat-xxxx"
|
|
|
|
# Permanent (survives restarts)
|
|
[Environment]::SetEnvironmentVariable("GITLAB_TOKEN", "glpat-xxxx", "User")
|
|
```
|
|
|
|
**Solution — Option 2: Use SSH URL:**
|
|
```bash
|
|
skillshare install git@github.com:team/private-skills.git
|
|
skillshare install git@gitlab.com:team/skills.git
|
|
skillshare install git@bitbucket.org:team/skills.git
|
|
```
|
|
|
|
**Solution — Option 3: Git credential helper:**
|
|
```bash
|
|
gh auth login # GitHub CLI
|
|
git credential approve # or platform-specific credential manager
|
|
```
|
|
|
|
**Required token permissions:**
|
|
|
|
| Platform | Token type | Scopes / Permissions |
|
|
|----------|-----------|---------------------|
|
|
| GitHub | Personal Access Token (`ghp_`) | `repo` (private repos), none (public) |
|
|
| GitLab | Personal Access Token (`glpat-`) | `read_repository` + `write_repository` |
|
|
| Bitbucket | Repository Access Token | Read + Write |
|
|
| Bitbucket | App Password + `BITBUCKET_USERNAME` | Repositories: Read + Write |
|
|
|
|
:::warning GitLab token types
|
|
Only **Personal Access Token** (`glpat-`) works for git operations. Feed Tokens (`glft-`) do **not** have git access.
|
|
:::
|
|
|
|
See [Environment Variables](/docs/reference/appendix/environment-variables#git-authentication) and [Private Repositories](/docs/reference/commands/install#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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 1. Sync
|
|
skillshare sync
|
|
|
|
# 2. Check format
|
|
skillshare doctor
|
|
|
|
# 3. Restart AI CLI
|
|
```
|
|
|
|
### `skill name 'X' is defined in multiple places`
|
|
|
|
**Cause:** Multiple skills have the same `name` field and land on the same target.
|
|
|
|
**Solution:** Rename one in SKILL.md or use `include`/`exclude` filters to route them to different targets:
|
|
```yaml
|
|
# Option 1: Namespace in SKILL.md
|
|
name: team-a-skill-name
|
|
|
|
# Option 2: Route with filters (global config)
|
|
targets:
|
|
codex:
|
|
path: ~/.codex/skills
|
|
include: [_team-a__*]
|
|
claude:
|
|
path: ~/.claude/skills
|
|
include: [_team-b__*]
|
|
|
|
# Option 2: Route with filters (project config)
|
|
targets:
|
|
- name: claude
|
|
exclude: [codex-*]
|
|
- name: codex
|
|
include: [codex-*]
|
|
```
|
|
|
|
:::tip
|
|
If filters already isolate the duplicates, sync shows an info message instead of a warning — no action needed.
|
|
See [Target Filters](/docs/reference/targets/configuration#include--exclude-target-filters) for full syntax.
|
|
:::
|
|
|
|
---
|
|
|
|
## Binary Errors
|
|
|
|
### `integration tests cannot find the binary`
|
|
|
|
**Cause:** Binary not built or wrong path.
|
|
|
|
**Solution:**
|
|
```bash
|
|
go build -o bin/skillshare ./cmd/skillshare
|
|
# Or set
|
|
export SKILLSHARE_TEST_BINARY=/path/to/skillshare
|
|
```
|
|
|
|
---
|
|
|
|
## Still Having Issues?
|
|
|
|
See [Troubleshooting Workflow](./troubleshooting-workflow.md) for a systematic debugging approach.
|