mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-20 20:34:19 +00:00
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)
This commit is contained in:
@@ -0,0 +1,280 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# Environment Variables
|
||||
|
||||
All environment variables recognized by skillshare.
|
||||
|
||||
## Configuration
|
||||
|
||||
### SKILLSHARE_CONFIG
|
||||
|
||||
Override the config file path.
|
||||
|
||||
```bash
|
||||
SKILLSHARE_CONFIG=~/custom-config.yaml skillshare status
|
||||
```
|
||||
|
||||
**Default:** `~/.config/skillshare/config.yaml`
|
||||
|
||||
---
|
||||
|
||||
### XDG_CONFIG_HOME
|
||||
|
||||
Override the base configuration directory per the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir/latest/).
|
||||
|
||||
```bash
|
||||
export XDG_CONFIG_HOME=~/my-config
|
||||
# skillshare will use ~/my-config/skillshare/
|
||||
```
|
||||
|
||||
**Default behavior:**
|
||||
|
||||
| Platform | Default |
|
||||
|----------|---------|
|
||||
| Linux | `~/.config/skillshare/` |
|
||||
| macOS | `~/.config/skillshare/` |
|
||||
| Windows | `%AppData%\skillshare\` |
|
||||
|
||||
**Priority:** `SKILLSHARE_CONFIG` > `XDG_CONFIG_HOME` > platform default.
|
||||
|
||||
:::note
|
||||
If you set `XDG_CONFIG_HOME` after initial setup, move your existing `~/.config/skillshare/` directory to the new location manually.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
### XDG_DATA_HOME
|
||||
|
||||
Override the data directory (backups, trash).
|
||||
|
||||
```bash
|
||||
export XDG_DATA_HOME=~/my-data
|
||||
# skillshare will use ~/my-data/skillshare/backups/ and ~/my-data/skillshare/trash/
|
||||
```
|
||||
|
||||
**Default:** `~/.local/share/skillshare/`
|
||||
|
||||
---
|
||||
|
||||
### XDG_STATE_HOME
|
||||
|
||||
Override the state directory (operation logs).
|
||||
|
||||
```bash
|
||||
export XDG_STATE_HOME=~/my-state
|
||||
# skillshare will use ~/my-state/skillshare/logs/
|
||||
```
|
||||
|
||||
**Default:** `~/.local/state/skillshare/`
|
||||
|
||||
---
|
||||
|
||||
### XDG_CACHE_HOME
|
||||
|
||||
Override the cache directory (version check cache, UI dist cache).
|
||||
|
||||
```bash
|
||||
export XDG_CACHE_HOME=~/my-cache
|
||||
# skillshare will use ~/my-cache/skillshare/
|
||||
```
|
||||
|
||||
**Default:** `~/.cache/skillshare/`
|
||||
|
||||
:::tip Automatic migration
|
||||
Starting from v0.13.0, skillshare follows the XDG Base Directory Specification for backups, trash, and logs. If you're upgrading from an older version, these directories are automatically migrated from `~/.config/skillshare/` to their proper XDG locations on first run.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## GitHub API
|
||||
|
||||
### GITHUB_TOKEN
|
||||
|
||||
GitHub personal access token.
|
||||
|
||||
**Used for:**
|
||||
- GitHub API requests (`skillshare search`, `skillshare upgrade`)
|
||||
- **Git clone authentication** — automatically injected when installing private repos via HTTPS
|
||||
|
||||
**Creating a token:**
|
||||
1. Go to https://github.com/settings/tokens
|
||||
2. Generate new token (classic)
|
||||
3. Scope: `repo` for private repos, none for public repos
|
||||
4. Copy the token
|
||||
|
||||
Official docs: [Managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
export GITHUB_TOKEN=ghp_your_token_here
|
||||
skillshare install https://github.com/org/private-skills.git --track
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
```powershell
|
||||
# Current session
|
||||
$env:GITHUB_TOKEN = "ghp_your_token"
|
||||
|
||||
# Permanent
|
||||
[Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "ghp_your_token", "User")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Git Authentication
|
||||
|
||||
These variables enable HTTPS authentication for private repositories. When set, skillshare automatically injects the token during `install` and `update` — no URL modification needed.
|
||||
|
||||
See [Private Repositories](/docs/reference/commands/install#private-repositories) for details and CI/CD examples.
|
||||
|
||||
|
||||
### GITLAB_TOKEN
|
||||
|
||||
GitLab personal access or CI job token. Used for HTTPS clone of GitLab-hosted private repos.
|
||||
|
||||
**Creating a token:**
|
||||
1. Go to https://gitlab.com/-/user_settings/personal_access_tokens
|
||||
2. Add new token
|
||||
3. Scopes: `read_repository` (pull only) or `read_repository` + `write_repository` (push & pull)
|
||||
4. Copy the token (prefix `glpat-`)
|
||||
|
||||
Official docs: [Token overview](https://docs.gitlab.com/security/tokens/)
|
||||
|
||||
:::warning Token types
|
||||
Only **Personal Access Token** (`glpat-`) and **Project/Group Access Token** work for git operations. Feed Tokens (`glft-`) do **not** have git access.
|
||||
:::
|
||||
|
||||
```bash
|
||||
export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
|
||||
skillshare install https://gitlab.com/org/skills.git --track
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
```powershell
|
||||
$env:GITLAB_TOKEN = "glpat-xxxxxxxxxxxxxxxxxxxx"
|
||||
```
|
||||
|
||||
### BITBUCKET_TOKEN
|
||||
|
||||
Bitbucket repository access token, or app password. Used for HTTPS clone of Bitbucket-hosted private repos.
|
||||
|
||||
**Creating a token (repository access token):**
|
||||
1. Go to Repository → Settings → Access tokens
|
||||
2. Create token with **Read** permission (pull only) or **Read + Write** (push & pull)
|
||||
3. Copy the token — uses `x-token-auth` automatically (no username needed)
|
||||
|
||||
**Creating a token (app password):**
|
||||
1. Go to https://bitbucket.org/account/settings/app-passwords/
|
||||
2. Create app password with **Repositories: Read** (pull only) or **Repositories: Read + Write** (push & pull)
|
||||
3. Also set `BITBUCKET_USERNAME` (or include it in the URL as `https://<username>@bitbucket.org/...`)
|
||||
|
||||
Official docs: [Access tokens](https://support.atlassian.com/bitbucket-cloud/docs/access-tokens/)
|
||||
|
||||
```bash
|
||||
export BITBUCKET_USERNAME=your_bitbucket_username
|
||||
export BITBUCKET_TOKEN=your_app_password
|
||||
skillshare install https://bitbucket.org/team/skills.git --track
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
```powershell
|
||||
$env:BITBUCKET_USERNAME = "your_bitbucket_username"
|
||||
$env:BITBUCKET_TOKEN = "your_app_password"
|
||||
```
|
||||
|
||||
### BITBUCKET_USERNAME
|
||||
|
||||
Bitbucket username used with `BITBUCKET_TOKEN` when that token is an app password.
|
||||
|
||||
```bash
|
||||
export BITBUCKET_USERNAME=your_bitbucket_username
|
||||
export BITBUCKET_TOKEN=your_app_password
|
||||
skillshare install https://bitbucket.org/team/skills.git --track
|
||||
```
|
||||
|
||||
### SKILLSHARE_GIT_TOKEN
|
||||
|
||||
Generic fallback token for any HTTPS git host. Used when no platform-specific token is set.
|
||||
|
||||
```bash
|
||||
export SKILLSHARE_GIT_TOKEN=your_token
|
||||
skillshare install https://git.example.com/org/skills.git --track
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
```powershell
|
||||
$env:SKILLSHARE_GIT_TOKEN = "your_token"
|
||||
```
|
||||
|
||||
**Token priority:** Platform-specific (`GITHUB_TOKEN`, `GITLAB_TOKEN`, `BITBUCKET_TOKEN`) > `SKILLSHARE_GIT_TOKEN`.
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
### SKILLSHARE_TEST_BINARY
|
||||
|
||||
Override the CLI binary path for integration tests.
|
||||
|
||||
```bash
|
||||
SKILLSHARE_TEST_BINARY=/path/to/skillshare go test ./tests/integration
|
||||
```
|
||||
|
||||
**Default:** `bin/skillshare` in project root
|
||||
|
||||
---
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Temporary override
|
||||
|
||||
```bash
|
||||
# Single command
|
||||
SKILLSHARE_CONFIG=/tmp/test-config.yaml skillshare status
|
||||
|
||||
# Multiple commands
|
||||
export SKILLSHARE_CONFIG=/tmp/test-config.yaml
|
||||
skillshare status
|
||||
skillshare list
|
||||
unset SKILLSHARE_CONFIG
|
||||
```
|
||||
|
||||
### Permanent setup (macOS/Linux)
|
||||
|
||||
Add to `~/.bashrc` or `~/.zshrc`:
|
||||
```bash
|
||||
export GITHUB_TOKEN="ghp_your_token_here"
|
||||
```
|
||||
|
||||
### Permanent setup (Windows)
|
||||
|
||||
```powershell
|
||||
[Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "ghp_your_token", "User")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
| Variable | Purpose | Default |
|
||||
|----------|---------|---------|
|
||||
| `SKILLSHARE_CONFIG` | Config file path | `~/.config/skillshare/config.yaml` |
|
||||
| `XDG_CONFIG_HOME` | Base config directory | `~/.config` (Linux/macOS), `%AppData%` (Windows) |
|
||||
| `XDG_DATA_HOME` | Data directory (backups, trash) | `~/.local/share` |
|
||||
| `XDG_STATE_HOME` | State directory (logs) | `~/.local/state` |
|
||||
| `XDG_CACHE_HOME` | Cache directory (version check, UI) | `~/.cache` |
|
||||
| `GITHUB_TOKEN` | GitHub API + git clone auth | None |
|
||||
| `GITLAB_TOKEN` | GitLab git clone auth | None |
|
||||
| `BITBUCKET_TOKEN` | Bitbucket git clone auth | None |
|
||||
| `BITBUCKET_USERNAME` | Bitbucket username for app password auth | None |
|
||||
| `SKILLSHARE_GIT_TOKEN` | Generic git clone auth (fallback) | None |
|
||||
| `SKILLSHARE_TEST_BINARY` | Test binary path | `bin/skillshare` |
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Configuration](/docs/reference/targets/configuration) — Config file reference
|
||||
- [Windows Issues](/docs/troubleshooting/windows) — Windows environment setup
|
||||
@@ -0,0 +1,411 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
---
|
||||
|
||||
# File Structure
|
||||
|
||||
Directory layout and file locations for skillshare.
|
||||
|
||||
## Overview
|
||||
|
||||
```
|
||||
~/.config/skillshare/ # XDG_CONFIG_HOME
|
||||
├── config.yaml # Configuration file
|
||||
├── registry.yaml # Installed skill registry (auto-managed)
|
||||
├── audit-rules.yaml # Custom audit rules (optional)
|
||||
└── skills/ # Source directory
|
||||
├── my-skill/ # Regular skill
|
||||
│ ├── SKILL.md # Skill definition (required)
|
||||
│ └── .skillshare-meta.json # Install metadata (auto-generated)
|
||||
├── code-review/ # Another skill
|
||||
│ └── SKILL.md
|
||||
└── _team-skills/ # Tracked repository
|
||||
├── .git/ # Git history preserved
|
||||
├── frontend/
|
||||
│ └── ui/
|
||||
│ └── SKILL.md
|
||||
└── backend/
|
||||
└── api/
|
||||
└── SKILL.md
|
||||
|
||||
~/.local/share/skillshare/ # XDG_DATA_HOME
|
||||
├── backups/ # Backup directory
|
||||
│ ├── 2026-01-20_15-30-00/
|
||||
│ │ ├── claude/
|
||||
│ │ └── cursor/
|
||||
│ └── 2026-01-19_10-00-00/
|
||||
│ └── claude/
|
||||
└── trash/ # Uninstalled skills (7-day retention)
|
||||
├── my-skill_2026-01-20_15-30-00/
|
||||
│ └── SKILL.md
|
||||
└── old-skill_2026-01-19_10-00-00/
|
||||
└── SKILL.md
|
||||
|
||||
~/.local/state/skillshare/ # XDG_STATE_HOME
|
||||
└── logs/ # Operation logs (JSONL)
|
||||
├── operations.log # install, sync, update, etc.
|
||||
└── audit.log # Security audit scans
|
||||
|
||||
~/.cache/skillshare/ # XDG_CACHE_HOME
|
||||
├── version-check.json # Version check cache (24h TTL)
|
||||
└── ui/ # Web UI dist cache
|
||||
└── 0.13.0/ # Per-version cached assets
|
||||
├── index.html
|
||||
└── assets/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration File
|
||||
|
||||
### Location
|
||||
|
||||
```
|
||||
~/.config/skillshare/config.yaml
|
||||
```
|
||||
|
||||
**Override with XDG:**
|
||||
```
|
||||
XDG_CONFIG_HOME=/custom/path → /custom/path/skillshare/config.yaml
|
||||
```
|
||||
|
||||
**Windows default:**
|
||||
```
|
||||
%AppData%\skillshare\config.yaml
|
||||
```
|
||||
|
||||
### Contents
|
||||
|
||||
```yaml
|
||||
# yaml-language-server: $schema=https://raw.githubusercontent.com/runkids/skillshare/main/schemas/config.schema.json
|
||||
source: ~/.config/skillshare/skills
|
||||
mode: merge
|
||||
targets:
|
||||
claude:
|
||||
path: ~/.claude/skills
|
||||
cursor:
|
||||
path: ~/.cursor/skills
|
||||
ignore:
|
||||
- "**/.DS_Store"
|
||||
- "**/.git/**"
|
||||
```
|
||||
|
||||
See [Configuration](/docs/reference/targets/configuration) for full reference.
|
||||
|
||||
---
|
||||
|
||||
## Registry File
|
||||
|
||||
### Location
|
||||
|
||||
```
|
||||
~/.config/skillshare/registry.yaml
|
||||
```
|
||||
|
||||
Stores metadata about installed and tracked skills. **Auto-managed** by `install`, `uninstall`, and `update` — don't edit manually.
|
||||
|
||||
### Contents
|
||||
|
||||
```yaml
|
||||
# yaml-language-server: $schema=https://raw.githubusercontent.com/runkids/skillshare/main/schemas/registry.schema.json
|
||||
skills:
|
||||
- name: pdf
|
||||
source: anthropics/skills/skills/pdf
|
||||
- name: _team-skills
|
||||
source: github.com/team/skills
|
||||
```
|
||||
|
||||
Each entry records the skill name and its install source. Tracked repos (prefixed with `_`) include the full repository URL for `update` and `check` operations.
|
||||
|
||||
---
|
||||
|
||||
## Source Directory
|
||||
|
||||
### Location
|
||||
|
||||
```
|
||||
~/.config/skillshare/skills/
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
```
|
||||
%AppData%\skillshare\skills\
|
||||
```
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
skills/
|
||||
├── skill-name/ # Skill directory
|
||||
│ ├── SKILL.md # Required: skill definition
|
||||
│ ├── .skillshare-meta.json # Optional: install metadata
|
||||
│ ├── examples/ # Optional: example files
|
||||
│ └── templates/ # Optional: code templates
|
||||
├── frontend/ # Category folder (via --into or manual)
|
||||
│ └── react-skill/ # Skill in subdirectory
|
||||
│ └── SKILL.md # Synced as frontend__react-skill
|
||||
└── _tracked-repo/ # Tracked repository
|
||||
├── .git/ # Git history
|
||||
└── ... # Skill subdirectories
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Skill Files
|
||||
|
||||
### SKILL.md (Required)
|
||||
|
||||
The skill definition file:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: skill-name
|
||||
description: Brief description
|
||||
---
|
||||
|
||||
# Skill Name
|
||||
|
||||
Instructions for the AI...
|
||||
```
|
||||
|
||||
See [Skill Format](/docs/understand/skill-format) for details.
|
||||
|
||||
### .skillignore (Optional, repo-level)
|
||||
|
||||
A file in the **root of a skill repository** that excludes skills from discovery during `skillshare install`:
|
||||
|
||||
```text
|
||||
# Hide internal tooling from discovery
|
||||
validation-scripts
|
||||
scaffold-template
|
||||
prompt-eval-*
|
||||
|
||||
# Exclude an entire group directory
|
||||
internal-tools
|
||||
```
|
||||
|
||||
One pattern per line. Patterns match against skill paths — a group name like `internal-tools` excludes all skills under that directory, while `internal-tools/helper` excludes only a specific skill. Also supports trailing wildcard (`prefix-*`). Lines starting with `#` are comments. Only applies to discovery — already-installed skills are not affected.
|
||||
|
||||
### .skillshare-meta.json (Auto-generated)
|
||||
|
||||
Metadata about where the skill was installed from:
|
||||
|
||||
```json
|
||||
{
|
||||
"source": "github.com/org/repo/path/to/skill",
|
||||
"type": "github",
|
||||
"installed_at": "2026-01-20T15:30:00Z",
|
||||
"repo_url": "https://github.com/org/repo.git",
|
||||
"subdir": "path/to/skill",
|
||||
"version": "abc1234"
|
||||
}
|
||||
```
|
||||
|
||||
**Don't edit this file manually.** It's used by `skillshare update` and `skillshare check`.
|
||||
|
||||
---
|
||||
|
||||
## Backup Directory
|
||||
|
||||
### Location
|
||||
|
||||
```
|
||||
~/.local/share/skillshare/backups/
|
||||
```
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
backups/
|
||||
└── <timestamp>/ # YYYY-MM-DD_HH-MM-SS
|
||||
├── claude/ # Backup of target
|
||||
│ ├── skill-a/
|
||||
│ └── skill-b/
|
||||
└── cursor/
|
||||
└── ...
|
||||
```
|
||||
|
||||
Backups are created:
|
||||
- Automatically before `sync` and `target remove`
|
||||
- Manually via `skillshare backup`
|
||||
|
||||
---
|
||||
|
||||
## Trash Directory
|
||||
|
||||
### Location
|
||||
|
||||
```
|
||||
~/.local/share/skillshare/trash/
|
||||
```
|
||||
|
||||
**Project mode:**
|
||||
```
|
||||
<project>/.skillshare/trash/
|
||||
```
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
trash/
|
||||
└── <skill-name>_<timestamp>/ # skill-name_YYYY-MM-DD_HH-MM-SS
|
||||
├── SKILL.md
|
||||
└── ... # All original files preserved
|
||||
```
|
||||
|
||||
Trashed skills are:
|
||||
- Created by `skillshare uninstall`
|
||||
- Retained for 7 days, then automatically cleaned up
|
||||
- Named with the original skill name and a timestamp
|
||||
|
||||
---
|
||||
|
||||
## Log Directory
|
||||
|
||||
### Location
|
||||
|
||||
```
|
||||
~/.local/state/skillshare/logs/
|
||||
```
|
||||
|
||||
**Project mode:**
|
||||
```
|
||||
<project>/.skillshare/logs/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Target Directories
|
||||
|
||||
Targets are AI CLI skill directories. After sync, they contain symlinks (or copies) to source.
|
||||
|
||||
### Merge mode
|
||||
|
||||
Each skill is symlinked individually. A manifest tracks managed skills for orphan cleanup:
|
||||
```
|
||||
~/.claude/skills/
|
||||
├── my-skill -> ~/.config/skillshare/skills/my-skill
|
||||
├── code-review -> ~/.config/skillshare/skills/code-review
|
||||
├── local-only/ # Not symlinked (user-created, preserved)
|
||||
└── .skillshare-manifest.json # Tracks managed skills
|
||||
```
|
||||
|
||||
### Copy mode
|
||||
|
||||
Each skill is copied as real files. The manifest tracks checksums for incremental sync:
|
||||
```
|
||||
~/.cursor/skills/
|
||||
├── my-skill/ # Real files (copied from source)
|
||||
├── code-review/ # Real files
|
||||
├── local-only/ # User-created, preserved
|
||||
└── .skillshare-manifest.json # Tracks managed skills + checksums
|
||||
```
|
||||
|
||||
### Symlink mode
|
||||
|
||||
Entire directory is symlinked:
|
||||
```
|
||||
~/.claude/skills -> ~/.config/skillshare/skills/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tracked Repositories
|
||||
|
||||
Tracked repos (installed with `--track`) preserve git history:
|
||||
|
||||
```
|
||||
_team-skills/
|
||||
├── .git/ # Git preserved
|
||||
├── frontend/
|
||||
│ └── ui/
|
||||
│ └── SKILL.md
|
||||
└── backend/
|
||||
└── api/
|
||||
└── SKILL.md
|
||||
```
|
||||
|
||||
### Naming conventions
|
||||
|
||||
- `_` prefix: tracked repository
|
||||
- `__` in flattened name: path separator
|
||||
|
||||
**In source:**
|
||||
```
|
||||
_team-skills/frontend/ui/SKILL.md
|
||||
```
|
||||
|
||||
**In target (flattened):**
|
||||
```
|
||||
_team-skills__frontend__ui/SKILL.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Platform Differences
|
||||
|
||||
:::tip XDG Base Directory
|
||||
skillshare respects the XDG Base Directory Specification. Override base directories with `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, and `XDG_CACHE_HOME`.
|
||||
|
||||
See [Environment Variables](./environment-variables.md#xdg_config_home) for details.
|
||||
:::
|
||||
|
||||
### macOS / Linux
|
||||
|
||||
| Item | Path |
|
||||
|------|------|
|
||||
| Config | `~/.config/skillshare/config.yaml` |
|
||||
| Registry | `~/.config/skillshare/registry.yaml` |
|
||||
| Source | `~/.config/skillshare/skills/` |
|
||||
| Backups | `~/.local/share/skillshare/backups/` |
|
||||
| Trash | `~/.local/share/skillshare/trash/` |
|
||||
| Logs | `~/.local/state/skillshare/logs/` |
|
||||
| Version cache | `~/.cache/skillshare/version-check.json` |
|
||||
| UI cache | `~/.cache/skillshare/ui/{version}/` |
|
||||
| Link type | Symlinks |
|
||||
|
||||
### Windows
|
||||
|
||||
| Item | Path |
|
||||
|------|------|
|
||||
| Config | `%AppData%\skillshare\config.yaml` |
|
||||
| Registry | `%AppData%\skillshare\registry.yaml` |
|
||||
| Source | `%AppData%\skillshare\skills\` |
|
||||
| Backups | `%AppData%\skillshare\backups\` |
|
||||
| Trash | `%AppData%\skillshare\trash\` |
|
||||
| Logs | `%AppData%\skillshare\logs\` |
|
||||
| Version cache | `%AppData%\skillshare\version-check.json` |
|
||||
| UI cache | `%AppData%\skillshare\ui\{version}\` |
|
||||
| Link type | NTFS Junctions |
|
||||
|
||||
## XDG Base Directory Layout
|
||||
|
||||
skillshare follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir/latest/) on Unix systems:
|
||||
|
||||
| XDG Variable | Default Path | skillshare Uses For |
|
||||
|-------------|-------------|---------------------|
|
||||
| `XDG_CONFIG_HOME` | `~/.config` | `skillshare/config.yaml`, `skillshare/registry.yaml`, `skillshare/skills/` |
|
||||
| `XDG_DATA_HOME` | `~/.local/share` | `skillshare/backups/`, `skillshare/trash/` |
|
||||
| `XDG_STATE_HOME` | `~/.local/state` | `skillshare/logs/` |
|
||||
| `XDG_CACHE_HOME` | `~/.cache` | `skillshare/ui/` (downloaded web dashboard) |
|
||||
|
||||
### Windows Paths
|
||||
|
||||
| Purpose | Path |
|
||||
|---------|------|
|
||||
| Config + Skills | `%AppData%\skillshare\` |
|
||||
| Data (backups, trash) | `%AppData%\skillshare\` |
|
||||
| State (logs) | `%AppData%\skillshare\` |
|
||||
| Cache (UI) | `%AppData%\skillshare\` |
|
||||
|
||||
### Migration Note
|
||||
|
||||
If upgrading from a version before the XDG split, skillshare automatically migrates data from the old location (`~/.config/skillshare/`) to the correct XDG directories on first run.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Configuration](/docs/reference/targets/configuration) — Config file details
|
||||
- [Skill Format](/docs/understand/skill-format) — SKILL.md format
|
||||
- [Tracked Repositories](/docs/understand/tracked-repositories) — Tracked repos
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Appendix
|
||||
|
||||
Technical reference appendix for skillshare.
|
||||
|
||||
## What are you looking for?
|
||||
|
||||
| Topic | Read |
|
||||
|-------|------|
|
||||
| Environment variables that affect skillshare | [Environment Variables](/docs/reference/appendix/environment-variables) |
|
||||
| Where skillshare stores config, skills, logs, cache | [File Structure](/docs/reference/appendix/file-structure) |
|
||||
| Supported git URL formats | [URL Formats](/docs/reference/appendix/url-formats) |
|
||||
| Config file format and options | [Configuration](/docs/reference/targets/configuration) |
|
||||
| All CLI commands | [Commands](/docs/reference/commands) |
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Key Paths (Unix)
|
||||
|
||||
| Path | Purpose |
|
||||
|------|---------|
|
||||
| `~/.config/skillshare/config.yaml` | Configuration file |
|
||||
| `~/.config/skillshare/registry.yaml` | Installed skill registry (auto-managed) |
|
||||
| `~/.config/skillshare/skills/` | Source directory (your skills) |
|
||||
| `~/.local/share/skillshare/backups/` | Backup directory |
|
||||
| `~/.local/share/skillshare/trash/` | Soft-deleted skills |
|
||||
| `~/.local/state/skillshare/logs/` | Operation and audit logs |
|
||||
| `~/.cache/skillshare/ui/` | Downloaded web dashboard |
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Purpose |
|
||||
|----------|---------|
|
||||
| `SKILLSHARE_CONFIG` | Override config path |
|
||||
| `GITHUB_TOKEN` | GitHub API authentication |
|
||||
|
||||
## See Also
|
||||
|
||||
- [Configuration](/docs/reference/targets/configuration) — Config file details
|
||||
- [Commands](/docs/reference/commands) — All commands
|
||||
@@ -0,0 +1,167 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
# URL Formats
|
||||
|
||||
All source URL patterns recognized by `skillshare install`.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Format | Example | Notes |
|
||||
|--------|---------|-------|
|
||||
| GitHub shorthand | `owner/repo` | Expands to `github.com/owner/repo` |
|
||||
| GitHub with subdir | `owner/repo/path/to/skill` | Installs specific skill from repo |
|
||||
| Full HTTPS | `https://github.com/owner/repo` | Any Git host |
|
||||
| Full HTTPS with subdir | `https://github.com/owner/repo/path` | Subdir after host/owner/repo |
|
||||
| SSH | `git@github.com:owner/repo.git` | Private repos via SSH key |
|
||||
| SSH with subdir | `git@github.com:owner/repo.git//path` | `//` separates repo from subdir |
|
||||
| GHE Cloud | `mycompany.github.com/org/repo` | Enterprise Cloud subdomain |
|
||||
| GHE Server | `github.mycompany.com/org/repo` | Enterprise Server |
|
||||
| Local path | `~/my-skill` or `/abs/path` | Copies directory to source |
|
||||
| Git file URL | `file:///path/to/repo` | Local git clone (for testing) |
|
||||
|
||||
## GitHub Shorthand
|
||||
|
||||
The simplest format — just `owner/repo`:
|
||||
|
||||
```bash
|
||||
skillshare install anthropics/skills
|
||||
skillshare install ComposioHQ/awesome-claude-skills
|
||||
```
|
||||
|
||||
This expands to `https://github.com/owner/repo` internally.
|
||||
|
||||
### With Subdirectory
|
||||
|
||||
Add a path after `owner/repo` to install a specific skill:
|
||||
|
||||
```bash
|
||||
skillshare install anthropics/skills/skills/pdf
|
||||
skillshare install anthropics/skills/skills/commit
|
||||
```
|
||||
|
||||
When the subdir doesn't match exactly, skillshare scans the repo for a skill with that basename:
|
||||
|
||||
```bash
|
||||
# "pdf" doesn't exist at root, but found at skills/pdf/ — resolves automatically
|
||||
skillshare install anthropics/skills/pdf
|
||||
```
|
||||
|
||||
## Full HTTPS URLs
|
||||
|
||||
Works with any Git host:
|
||||
|
||||
```bash
|
||||
# GitHub
|
||||
skillshare install https://github.com/owner/repo
|
||||
|
||||
# GitLab
|
||||
skillshare install https://gitlab.com/owner/repo
|
||||
|
||||
# Bitbucket
|
||||
skillshare install https://bitbucket.org/owner/repo
|
||||
|
||||
# Self-hosted Gitea
|
||||
skillshare install https://git.mycompany.com/team/skills
|
||||
```
|
||||
|
||||
## SSH URLs
|
||||
|
||||
Use SSH for private repositories:
|
||||
|
||||
```bash
|
||||
# Standard SSH
|
||||
skillshare install git@github.com:owner/repo.git
|
||||
|
||||
# With subdirectory (note the // separator)
|
||||
skillshare install git@github.com:owner/repo.git//path/to/skill
|
||||
|
||||
# GitLab SSH
|
||||
skillshare install git@gitlab.com:owner/repo.git
|
||||
```
|
||||
|
||||
:::info The `//` separator
|
||||
For SSH URLs, use `//` to separate the repo from the subdirectory path. This is because the `:` in SSH URLs already serves as a separator, so the standard `/` path convention would be ambiguous.
|
||||
:::
|
||||
|
||||
## GitHub Enterprise
|
||||
|
||||
Enterprise hostnames are recognized automatically:
|
||||
|
||||
```bash
|
||||
# Enterprise Cloud (subdomain pattern: *.github.com)
|
||||
skillshare install mycompany.github.com/org/repo
|
||||
|
||||
# Enterprise Server (hostname pattern: github.*.*)
|
||||
skillshare install github.mycompany.com/org/repo
|
||||
skillshare install github.internal.corp/team/skills
|
||||
```
|
||||
|
||||
Both patterns support subdirectory paths:
|
||||
|
||||
```bash
|
||||
skillshare install github.mycompany.com/org/repo/path/to/skill
|
||||
```
|
||||
|
||||
## Local Paths
|
||||
|
||||
Install from a directory on your filesystem:
|
||||
|
||||
```bash
|
||||
# Absolute path
|
||||
skillshare install /home/user/my-skill
|
||||
|
||||
# Home directory shorthand
|
||||
skillshare install ~/my-skill
|
||||
|
||||
# Relative path
|
||||
skillshare install ./local-skill
|
||||
```
|
||||
|
||||
Local installs **copy** files (not symlink) and are not updatable via `skillshare update`.
|
||||
|
||||
## Authentication
|
||||
|
||||
### SSH Keys (Recommended for Private Repos)
|
||||
|
||||
```bash
|
||||
# Ensure your SSH key is loaded
|
||||
ssh-add ~/.ssh/id_ed25519
|
||||
|
||||
# Install via SSH
|
||||
skillshare install git@github.com:company/private-skills.git
|
||||
```
|
||||
|
||||
### HTTPS with Tokens
|
||||
|
||||
For HTTPS URLs, git uses your configured credential helper:
|
||||
|
||||
```bash
|
||||
# Configure git credential helper (one-time)
|
||||
git config --global credential.helper store
|
||||
|
||||
# Or use GH CLI for GitHub
|
||||
gh auth login
|
||||
|
||||
# Then install normally
|
||||
skillshare install https://github.com/company/private-repo
|
||||
```
|
||||
|
||||
:::tip Private Repos
|
||||
If you get an authentication error with HTTPS, switch to SSH URLs. skillshare sets `GIT_TERMINAL_PROMPT=0` to prevent hanging credential prompts, so interactive HTTPS auth won't work.
|
||||
:::
|
||||
|
||||
## Platform Support
|
||||
|
||||
| Feature | GitHub | GitLab | Bitbucket | Gitea | GHE |
|
||||
|---------|--------|--------|-----------|-------|-----|
|
||||
| Shorthand (`owner/repo`) | Yes | No | No | No | Yes |
|
||||
| Full HTTPS URL | Yes | Yes | Yes | Yes | Yes |
|
||||
| SSH URL | Yes | Yes | Yes | Yes | Yes |
|
||||
| Subdirectory | Yes | Yes | Yes | Yes | Yes |
|
||||
| `skillshare search` | Yes | No | No | No | No |
|
||||
|
||||
## Related
|
||||
|
||||
- [Install command](../commands/install.md) — full install options and examples
|
||||
Reference in New Issue
Block a user