The docs said Windows always links with NTFS junctions and needs no admin rights, which is only true for folders. Explain that single files need Developer Mode for symlinks and otherwise sync as tracked copies, with the warning line users will see and the folder-icon symptom from the issue. Cover the per-target mode picker, the restore preview, changing a target's file location, the single-column file tab with edit/preview, universal's file list, and switching back to import. Also correct status and doctor output that no longer matched the code, and the doctor "Link not supported" advice, which pointed at Developer Mode although that check creates a folder junction. Refs #299
18 KiB
sidebar_position
| sidebar_position |
|---|
| 3 |
ファイル構造
skillshare のディレクトリレイアウトとファイルの場所です。
概要
~/.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/
設定ファイル
場所
~/.config/skillshare/config.yaml
XDG での上書き:
XDG_CONFIG_HOME=/custom/path → /custom/path/skillshare/config.yaml
Windows のデフォルト:
%AppData%\skillshare\config.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/**"
完全なリファレンスは Configuration を参照してください。
Metadata ファイル
場所
~/.config/skillshare/skills/.metadata.json
インストール済み・Tracked された Skill に関するメタデータを保存します。マルチマシン構成で git 経由の
Sync ができるよう、Source ディレクトリ内に置かれます。install、uninstall、update によって
自動管理されます — 手動で編集しないでください。
内容
{
"skills": [
{
"name": "pdf",
"source": "anthropics/skills/skills/pdf"
},
{
"name": "_team-skills",
"source": "github.com/team/skills",
"tracked": true
}
]
}
各エントリは Skill の名前とそのインストール Source を記録します。Tracked repos(_ プレフィックス
付き)は update と check の操作のためにリポジトリの完全な URL を含みます。
Source ディレクトリ
場所
~/.config/skillshare/skills/
Windows:
%AppData%\skillshare\skills\
構造
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 ファイル
SKILL.md(必須)
Skill の定義ファイルです。
---
name: skill-name
description: Brief description
---
# Skill Name
Instructions for the AI...
詳細は Skill フォーマット を参照してください。
.skillignore(任意)
Discovery から Skill を除外します。2つの場所に対応しています。
リポジトリレベル — Tracked された Skill リポジトリのルートに置きます。インストール時の
Discovery とインストール後のすべてのコマンド(doctor、status、list、sync など)に影響します。
# Hide vendored packages from discovery
.venv
node_modules
# Exclude internal tooling
validation-scripts
prompt-eval-*
Source ルート — Source ディレクトリのルート(~/.config/skillshare/skills/.skillignore)に
置きます。すべての Skill(Tracked と非 Tracked の両方)にグローバルに適用されます。
# Temporarily mute a skill
my-experimental-skill
# Exclude all drafts
draft-*
gitignore の構文 を使用します — 1行につき1パターンです。
*(1セグメント)、**(任意の深さ)、?、[abc](文字クラス)、!pattern(否定)、
/pattern(アンカー付き)、pattern/(ディレクトリのみ)、\#/\!(リテラルのエスケープ)に
対応しています。# で始まる行はコメントです。internal-tools のようなグループ名はそのディレクトリ
配下のすべての Skill を除外します。internal-tools/helper は特定の Skill のみを除外します。
両方のレイヤーが適用されます — どちらかが一致すれば、その Skill は除外されます。
:::tip
.skillignore は3つのフィルタリングレイヤーのうちの1つです。Target ごとのフィルターや SKILL.md の
targets を含むすべてのシナリオについては Skill のフィルタリング
を参照してください。
:::
.skillignore.local(任意)
.skillignore と併用するローカル専用のオーバーライドファイルです。.skillignore と同じ
ディレクトリ(Source ルートまたは Tracked repo のルート)に置きます。.skillignore.local の
パターンは .skillignore の後に追加されるため、否定パターン(!pattern)でベースファイルを
オーバーライドできます。
# The repo's .skillignore blocks private-*, but I need my own
!private-mine
このファイルはバージョン管理にコミットしないでください — .gitignore に追加します。これは、
リポジトリの利用者がリポジトリのメンテナーの .skillignore を変更することなくローカルで
オーバーライドできるようにするために存在します。
有効な場合、sync -v、status、doctor は .local active インジケーターを表示します。
Agent ファイル
Agent は Skill とは別のリソース種別です。隣接する Source ディレクトリに存在し、Agent 対応の Target(Claude、Cursor、Augment、OpenCode)に Sync されます。
Agent の Source ディレクトリ
~/.config/skillshare/agents/ # Global mode
.skillshare/agents/ # Project mode
Agent の Source は、skills/ と共に skillshare init によって自動的に作成されます。Global の場所は
agents_source config フィールドで上書きできます。Project mode は常に .skillshare/agents/ を
使います。
Agent ファイルのフォーマット
各 Agent はフロントマター付きの単一の Markdown ファイルです。
---
name: reviewer
description: Reviews pull requests for security and style issues.
---
# Reviewer
Instructions for the AI agent...
Agent のファイル名は a-z、0-9、_、-、. のみを使用する必要があります。Skill とは異なり、
Agent は単一ファイルです — サブディレクトリを含みません。
完全なファイルフォーマットと発見ルールについては Agents を参照してください。
.agentignore(任意)
Sync から Agent を除外します。Agent の Source ルートに置きます。
# Hide drafts
draft-*
# Disable a specific agent
experimental-reviewer
gitignore の構文 を使用します。.skillignore と同じ
パターンルール(*、**、!negation、# コメントなど)が適用されます。無効化された Agent は
Source ディレクトリに残りますが、Sync からは除外されます。
skillshare disable <agent> と skillshare enable <agent> はエントリを自動的に追加/削除します。
.agentignore.local(任意)
ローカル専用のオーバーライドファイルです(.skillignore.local と同じパターン)。.agentignore の
隣に置きます。パターンは .agentignore の後に追加されるため、!negation パターンでベースファイルが
無効化した Agent を再度有効化できます。バージョン管理にはコミットしないでください。
バックアップディレクトリ
場所
~/.local/share/skillshare/backups/
構造
backups/
└── <timestamp>/ # YYYY-MM-DD_HH-MM-SS
├── claude/ # Backup of target
│ ├── skill-a/
│ └── skill-b/
└── cursor/
└── ...
バックアップは以下のタイミングで作成されます。
syncとtarget removeの前に自動的にskillshare backupで手動に
Trash ディレクトリ
場所
~/.local/share/skillshare/trash/
Project mode:
<project>/.skillshare/trash/
構造
trash/
└── <skill-name>_<timestamp>/ # skill-name_YYYY-MM-DD_HH-MM-SS
├── SKILL.md
└── ... # All original files preserved
Trash に入れられた Skill は:
skillshare uninstallによって作成される- 7日間保持された後、自動的にクリーンアップされる
- 元の Skill 名とタイムスタンプで命名される
ログディレクトリ
場所
~/.local/state/skillshare/logs/
Project mode:
<project>/.skillshare/logs/
Target ディレクトリ
Target は AI CLI の Skill ディレクトリです。Sync 後、それらには Source へのシンボリックリンク (またはコピー)が含まれます。
Merge モード
各 Skill が個別にシンボリックリンクされます。マニフェストが孤立したリンクのクリーンアップのために 管理対象の Skill を追跡します。
~/.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 モード
各 Skill が実ファイルとしてコピーされます。マニフェストは差分 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 モード
ディレクトリ全体がシンボリックリンクされます。
~/.claude/skills -> ~/.config/skillshare/skills/
ファイルリンクの代わりのコピー(Windows)
Developer Mode がオフの Windows では、agent の Target と merge モードのディレクトリ Extras は、ファイルのリンクの代わりにコピーを受け取ります。その場合、Target ディレクトリには各コピーのチェックサムを記録する .skillshare-manifest.json が置かれ、後の Sync でコピーを更新・削除しつつ、自分のファイルはそのまま残せます。
~/.claude/agents/
├── reviewer.md # Copy of the source agent
├── local-agent.md # User-created, preserved
└── .skillshare-manifest.json # Tracks copied agents + checksums
単一ファイルの Extras(共有 AGENTS.md など)は、コピーを Target ディレクトリではなく skillshare の extras バックアップフォルダーに記録します。
Tracked Repositories
Tracked repos(--track でインストール)は git の履歴を保持します。
_team-skills/
├── .git/ # Git preserved
├── frontend/
│ └── ui/
│ └── SKILL.md
└── backend/
└── api/
└── SKILL.md
命名規則
_プレフィックス: Tracked repository- フラット化された名前の
__: パスセパレータ
Source では:
_team-skills/frontend/ui/SKILL.md
Target では(フラット化後):
_team-skills__frontend__ui/SKILL.md
プラットフォームの違い
:::tip XDG Base Directory
skillshare は XDG Base Directory Specification に従います。XDG_CONFIG_HOME、XDG_DATA_HOME、
XDG_STATE_HOME、XDG_CACHE_HOME でベースディレクトリを上書きできます。
詳細は 環境変数 を参照してください。 :::
macOS / Linux
| 項目 | パス |
|---|---|
| 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}/ |
| リンクの種類 | シンボリックリンク |
Windows
| 項目 | パス |
|---|---|
| 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}\ |
| リンクの種類 | フォルダーは NTFS Junctions、単一ファイルはシンボリックリンク(Developer Mode が必要、ない場合はコピー) |
XDG Base Directory のレイアウト
skillshare は Unix システム上で XDG Base Directory Specification に従います。
| XDG 変数 | デフォルトパス | skillshare の用途 |
|---|---|---|
XDG_CONFIG_HOME |
~/.config |
skillshare/config.yaml、skillshare/skills/(.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/(ダウンロードされた Web ダッシュボード) |
Windows のパス
| 用途 | パス |
|---|---|
| Config + Skills | %AppData%\skillshare\ |
| Data(バックアップ、trash) | %AppData%\skillshare\ |
| State(ログ) | %AppData%\skillshare\ |
| Cache(UI) | %AppData%\skillshare\ |
移行に関する注意
XDG 分割前のバージョンからアップグレードする場合、skillshare は初回実行時に古い場所
(~/.config/skillshare/)から正しい XDG ディレクトリへ自動的にデータを移行します。
関連項目
- Configuration — Config ファイルの詳細
- Skill フォーマット — SKILL.md フォーマット
- Agents — Agent ファイルフォーマットと発見
- Tracked Repositories — Tracked repos