mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-19 02:17:09 +00:00
These headings mix prose with technical terms (e.g. '.skillignore (Optional)', 'Git Authentication', 'Target include/exclude filters') and are referenced by anchor fragment from other pages. Translating the prose changes the auto-generated slug and breaks the link, so pin the current slug explicitly before the next translation batch.
507 lines
15 KiB
Markdown
507 lines
15 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
|
|
├── 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
|
|
│ └── 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/
|
|
```
|
|
|
|
---
|
|
|
|
## 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/
|
|
```
|
|
|
|
---
|
|
|
|
## 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/` |
|
|
| 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\` |
|
|
| 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/skills/` (includes `.metadata.json`), `skillshare/agents/` |
|
|
| `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
|
|
- [Agents](/docs/understand/agents) — Agent file format and discovery
|
|
- [Tracked Repositories](/docs/understand/tracked-repositories) — Tracked repos
|