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

{
  "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:

---
name: skill-name
description: Brief description
---

# Skill Name

Instructions for the AI...

See Skill Format for details.

.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.):

_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):

~/.config/skillshare/skills/.skillignore

# Temporarily mute a skill
my-experimental-skill

# Exclude all drafts
draft-*

Uses gitignore syntax — 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 for all scenarios including per-target filters and SKILL.md targets.

.skillignore.local (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:

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

~/.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 for the full file format and discovery rules.

.agentignore (Optional)

Excludes agents from sync. Lives at the agents source root:

~/.config/skillshare/agents/.agentignore

# Hide drafts
draft-*

# Disable a specific agent
experimental-reviewer

Uses gitignore syntax. 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 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

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 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 for folders; symlinks for single files (need Developer Mode, otherwise copied)

XDG Base Directory Layout

skillshare follows the XDG Base Directory Specification 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 — Config file details
• Skill Format — SKILL.md format
• Agents — Agent file format and discovery
• Tracked Repositories — Tracked repos