Files
skillshare/website/docs/reference/appendix/file-structure.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

412 lines
10 KiB
Markdown

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