mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-19 02:17:09 +00:00
Keep machine-specific project changes out of shared configuration while preserving shared registrations and making their origin visible. Handle missing replicated roots and preserve startup maintenance for mutating commands.
531 lines
17 KiB
Markdown
531 lines
17 KiB
Markdown
---
|
|
sidebar_position: 3
|
|
---
|
|
|
|
# File Structure
|
|
|
|
Directory layout and file locations for skillshare.
|
|
|
|
## Overview
|
|
|
|
```
|
|
~/.config/skillshare/ # XDG_CONFIG_HOME
|
|
├── config.yaml # Configuration file
|
|
├── audit-rules.yaml # Custom audit rules (optional)
|
|
├── mcp.yaml # MCP servers, if sources.mcp points here (optional)
|
|
├── skills/ # Skills source (skills + metadata)
|
|
│ ├── .metadata.json # Installed skill metadata (auto-managed)
|
|
│ ├── .skillignore # Optional: exclude skills from sync
|
|
│ ├── my-skill/ # Regular skill
|
|
│ │ ├── SKILL.md # Skill definition (required)
|
|
│ ├── code-review/ # Another skill
|
|
│ │ └── SKILL.md
|
|
│ └── _team-skills/ # Tracked repository
|
|
│ ├── .git/ # Git history preserved
|
|
│ ├── frontend/
|
|
│ │ └── ui/
|
|
│ │ └── SKILL.md
|
|
│ └── backend/
|
|
│ └── api/
|
|
│ └── SKILL.md
|
|
├── agents/ # Agents source (single .md files)
|
|
│ ├── .agentignore # Optional: exclude agents from sync
|
|
│ ├── reviewer.md # Agent file
|
|
│ └── auditor.md # Another agent
|
|
├── rules/ # Extras source (if configured)
|
|
│ ├── coding.md
|
|
│ └── testing.md
|
|
└── commands/ # Extras source (if configured)
|
|
└── deploy.md
|
|
|
|
~/.local/share/skillshare/ # XDG_DATA_HOME
|
|
├── backups/ # Backup directory
|
|
│ ├── 2026-01-20_15-30-00/
|
|
│ │ ├── claude/ # Skills backup for claude
|
|
│ │ ├── claude-agents/ # Agents backup for claude
|
|
│ │ └── cursor/
|
|
│ └── 2026-01-19_10-00-00/
|
|
│ └── claude/
|
|
└── trash/ # Uninstalled skills/agents (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
|
|
├── projects/ # Machine-local project registrations and locks
|
|
│ ├── <config-identity>.yaml # Local project registry
|
|
│ └── <config-identity>.lock # Serializes project mutations
|
|
├── plugins/<config-path-hash>/
|
|
│ ├── state.json # Machine-local plugin receipts and migration hints
|
|
│ └── .operation.lock # Serializes plugin mutations for this config
|
|
├── logs/ # Operation logs (JSONL)
|
|
│ ├── operations.log # install, sync, update, etc.
|
|
│ └── audit.log # Security audit scans
|
|
├── mcp/ # MCP sync state (auto-managed)
|
|
│ ├── state.json # Which native entries Skillshare owns
|
|
│ ├── tool-pins.json # Tool definition hashes recorded by mcp check --live
|
|
│ └── backups/ # Agent files before each write (newest 20 per file)
|
|
└── plugins/ # Reviewed local copies of plugin sources
|
|
|
|
~/.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/
|
|
```
|
|
|
|
On Windows, project registrations and their locks default to `%LOCALAPPDATA%\skillshare\state\projects\`. An explicit `XDG_STATE_HOME` places them under `$XDG_STATE_HOME/skillshare/projects/` on every platform. Keep this directory local to the machine; see [shared and local registrations](../commands/project.md#local-registrations).
|
|
|
|
---
|
|
|
|
## 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
|
|
agents_source: ~/.config/skillshare/agents # Optional; defaults to <source parent>/agents
|
|
mode: merge
|
|
targets:
|
|
claude:
|
|
path: ~/.claude/skills
|
|
agents: # Optional; enables agent sync for this target
|
|
path: ~/.claude/agents
|
|
cursor:
|
|
path: ~/.cursor/skills
|
|
ignore:
|
|
- "**/.DS_Store"
|
|
- "**/.git/**"
|
|
```
|
|
|
|
See [Configuration](/docs/reference/targets/configuration) for full reference.
|
|
|
|
---
|
|
|
|
## Metadata File
|
|
|
|
### Location
|
|
|
|
```
|
|
~/.config/skillshare/skills/.metadata.json
|
|
```
|
|
|
|
Stores metadata about installed and tracked skills. Lives inside the source directory so it can be synced via git for multi-machine setups. **Auto-managed** by `install`, `uninstall`, and `update` — don't edit manually.
|
|
|
|
### Contents
|
|
|
|
```json
|
|
{
|
|
"skills": [
|
|
{
|
|
"name": "pdf",
|
|
"source": "anthropics/skills/skills/pdf"
|
|
},
|
|
{
|
|
"name": "_team-skills",
|
|
"source": "github.com/team/skills",
|
|
"tracked": true
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
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/
|
|
├── .metadata.json # Centralized skill metadata (auto-managed)
|
|
├── skill-name/ # Skill directory
|
|
│ ├── SKILL.md # Required: skill definition
|
|
│ ├── 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) {#skillignore-optional}
|
|
|
|
Excludes skills from discovery. Supports two locations:
|
|
|
|
**Repo-level** — at the root of a tracked skill repository. Affects install discovery and all post-install commands (`doctor`, `status`, `list`, `sync`, etc.):
|
|
|
|
```text title="_team-skills/.skillignore"
|
|
# Hide vendored packages from discovery
|
|
.venv
|
|
node_modules
|
|
|
|
# Exclude internal tooling
|
|
validation-scripts
|
|
prompt-eval-*
|
|
```
|
|
|
|
**Source-root** — at your source directory root (`~/.config/skillshare/skills/.skillignore`). Applies globally to all skills (tracked and non-tracked):
|
|
|
|
```text title="~/.config/skillshare/skills/.skillignore"
|
|
# Temporarily mute a skill
|
|
my-experimental-skill
|
|
|
|
# Exclude all drafts
|
|
draft-*
|
|
```
|
|
|
|
Uses [gitignore syntax](https://git-scm.com/docs/gitignore) — one pattern per line. Supports `*` (single segment), `**` (any depth), `?`, `[abc]` (character class), `!pattern` (negation), `/pattern` (anchored), `pattern/` (directory-only), and `\#`/`\!` (escaped literals). Lines starting with `#` are comments. A group name like `internal-tools` excludes all skills under that directory; `internal-tools/helper` excludes only a specific skill. Both layers apply — if either matches, the skill is excluded.
|
|
|
|
:::tip
|
|
`.skillignore` is one of three filtering layers. See [Filtering Skills](/docs/how-to/daily-tasks/filtering-skills) for all scenarios including per-target filters and SKILL.md `targets`.
|
|
:::
|
|
|
|
### .skillignore.local (Optional) {#skillignorelocal-optional}
|
|
|
|
A local-only override file that works alongside `.skillignore`. Place it in the same directory as a `.skillignore` (source root or tracked repo root). Patterns from `.skillignore.local` are appended after `.skillignore`, so negation patterns (`!pattern`) can override the base file:
|
|
|
|
```text title="_team-skills/.skillignore.local"
|
|
# The repo's .skillignore blocks private-*, but I need my own
|
|
!private-mine
|
|
```
|
|
|
|
This file should **not** be committed to version control — add it to `.gitignore`. It exists so that a repo consumer can locally override the repo maintainer's `.skillignore` without modifying it.
|
|
|
|
When active, `sync -v`, `status`, and `doctor` display a `.local active` indicator.
|
|
|
|
|
|
---
|
|
|
|
## Agent Files
|
|
|
|
Agents are a separate resource kind from skills. They live in a sibling source directory and are synced to agent-capable targets (Claude, Cursor, Augment, OpenCode).
|
|
|
|
### Agent source directory
|
|
|
|
```
|
|
~/.config/skillshare/agents/ # Global mode
|
|
.skillshare/agents/ # Project mode
|
|
```
|
|
|
|
The agents source is created automatically by `skillshare init` alongside `skills/`. You can override the global location with the `agents_source` config field; project mode always uses `.skillshare/agents/`.
|
|
|
|
### Agent file format
|
|
|
|
Each agent is a single Markdown file with frontmatter:
|
|
|
|
```markdown title="~/.config/skillshare/agents/reviewer.md"
|
|
---
|
|
name: reviewer
|
|
description: Reviews pull requests for security and style issues.
|
|
---
|
|
|
|
# Reviewer
|
|
|
|
Instructions for the AI agent...
|
|
```
|
|
|
|
Agent filenames must use only `a-z`, `0-9`, `_`, `-`, `.`. Unlike skills, agents are **single files** — they do not contain subdirectories.
|
|
|
|
See [Agents](/docs/understand/agents) for the full file format and discovery rules.
|
|
|
|
### .agentignore (Optional)
|
|
|
|
Excludes agents from sync. Lives at the agents source root:
|
|
|
|
```text title="~/.config/skillshare/agents/.agentignore"
|
|
# Hide drafts
|
|
draft-*
|
|
|
|
# Disable a specific agent
|
|
experimental-reviewer
|
|
```
|
|
|
|
Uses [gitignore syntax](https://git-scm.com/docs/gitignore). The same pattern rules as `.skillignore` apply (`*`, `**`, `!negation`, `#` comments, etc.). Disabled agents remain in the source directory but are excluded from sync.
|
|
|
|
`skillshare disable <agent>` and `skillshare enable <agent>` add/remove entries automatically.
|
|
|
|
### .agentignore.local (Optional)
|
|
|
|
A local-only override file (same pattern as `.skillignore.local`). Place it next to `.agentignore`. Patterns are appended after `.agentignore`, so `!negation` patterns can re-enable agents the base file disables. Should not be committed to version control.
|
|
|
|
---
|
|
|
|
## 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/
|
|
```
|
|
|
|
### Copies in place of file links (Windows)
|
|
|
|
On Windows without Developer Mode, agent targets and directory extras in `merge` mode get copies instead of file links. The target directory then has a `.skillshare-manifest.json` that records a checksum for each copy, so later syncs can update or prune them and leave your own files alone:
|
|
```
|
|
~/.claude/agents/
|
|
├── reviewer.md # Copy of the source agent
|
|
├── local-agent.md # User-created, preserved
|
|
└── .skillshare-manifest.json # Tracks copied agents + checksums
|
|
```
|
|
|
|
A single-file extra (such as a shared `AGENTS.md`) records its copy in skillshare's [extras backup folder](../commands/extras.md#single-file-extras) instead of the target directory.
|
|
|
|
---
|
|
|
|
## 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` |
|
|
| Metadata | `~/.config/skillshare/skills/.metadata.json` |
|
|
| Skills source | `~/.config/skillshare/skills/` |
|
|
| Agents source | `~/.config/skillshare/agents/` |
|
|
| Backups | `~/.local/share/skillshare/backups/` |
|
|
| Trash | `~/.local/share/skillshare/trash/` |
|
|
| Logs | `~/.local/state/skillshare/logs/` |
|
|
| Project registrations and locks | `~/.local/state/skillshare/projects/` |
|
|
| Version cache | `~/.cache/skillshare/version-check.json` |
|
|
| UI cache | `~/.cache/skillshare/ui/{version}/` |
|
|
| Link type | Symlinks |
|
|
|
|
### Windows
|
|
|
|
| Item | Path |
|
|
|------|------|
|
|
| Config | `%AppData%\skillshare\config.yaml` |
|
|
| Metadata | `%AppData%\skillshare\skills\.metadata.json` |
|
|
| Skills source | `%AppData%\skillshare\skills\` |
|
|
| Agents source | `%AppData%\skillshare\agents\` |
|
|
| Backups | `%AppData%\skillshare\backups\` |
|
|
| Trash | `%AppData%\skillshare\trash\` |
|
|
| Logs | `%AppData%\skillshare\logs\` |
|
|
| Project registrations and locks | `%LOCALAPPDATA%\skillshare\state\projects\` |
|
|
| Version cache | `%AppData%\skillshare\version-check.json` |
|
|
| UI cache | `%AppData%\skillshare\ui\{version}\` |
|
|
| Link type | NTFS Junctions for folders; symlinks for single files (need Developer Mode, otherwise copied) |
|
|
|
|
## 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/skills/` (includes `.metadata.json`), `skillshare/agents/` |
|
|
| `XDG_DATA_HOME` | `~/.local/share` | `skillshare/backups/`, `skillshare/trash/` |
|
|
| `XDG_STATE_HOME` | `~/.local/state` | `skillshare/logs/`, `skillshare/projects/` |
|
|
| `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\` |
|
|
| Project registrations and locks | `%LOCALAPPDATA%\skillshare\state\projects\` |
|
|
| 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
|
|
- [Agents](/docs/understand/agents) — Agent file format and discovery
|
|
- [Tracked Repositories](/docs/understand/tracked-repositories) — Tracked repos
|