Agents
Skill と並んで管理される単一ファイルの .md リソース — 同じ sync、audit、ライフサイクルを持ちますが、形は異なります。
一部の AI CLI（Claude Code、Cursor、OpenCode、Augment、Copilot CLI、Droid）は skills（SKILL.md を含むディレクトリ）と agents（単一の .md ファイル）を区別しています。あなたの Target がこの agents をサポートしていれば、skillshare は単一の Source から両方を管理できます。
Skills と Agents
| Skill | Agent | |
|---|---|---|
| 形 | SKILL.md と任意のファイルを含むディレクトリ | 単一の .md ファイル |
| 名前解決 | SKILL.md frontmatter の name フィールド | ファイル名（例：tutor.md = "tutor"）、任意で frontmatter の name による上書き |
| Source ディレクトリ | ~/.config/skillshare/skills/ | ~/.config/skillshare/agents/（agents_source でカスタマイズ可能） |
| Project の Source | .skillshare/skills/ | .skillshare/agents/ |
| 無視ファイル | .skillignore | .agentignore |
| Sync 単位 | ディレクトリの symlink（merge）、ディレクトリ全体の symlink（symlink）、ディレクトリのコピー（copy） | ファイルの symlink（merge）、ディレクトリ全体の symlink（symlink）、ファイルのコピー（copy） |
| ネスト対応 | path/to/skill は path__to__skill にフラット化 | dir/file.md は dir__file.md にフラット化 |
| Tracking | 対応 | 対応 |
| Audit | 対応 | 対応 |
| Collect | 対応 | 対応 |
ディレクトリ構造
Global
~/.config/skillshare/
├── skills/ # Skill source (directories)
│ ├── my-skill/
│ │ └── SKILL.md
│ └── .skillignore
├── agents/ # Agent source (files)
│ ├── tutor.md
│ ├── reviewer.md
│ └── .agentignore
└── config.yaml
Project
.skillshare/
├── skills/
│ └── api-conventions/
│ └── SKILL.md
├── agents/
│ ├── onboarding.md
│ └── .agentignore
└── config.yaml
カスタム Source ディレクトリ
Global モードでは、agent の Source はデフォルトで ~/.config/skillshare/agents/ になります。カスタムの場所を使うには、config.yaml に agents_source を設定します。
agents_source: ~/my-agents
Project モードでは常に .skillshare/agents/ を使用し、agents_source はサポートされません。
詳細は Configuration — agents_source を参照してください。
Agent ファイルフォーマット
Agent は通常の .md ファイルです。Frontmatter は任意です。
---
name: math-tutor
description: Helps with math problems step by step
targets: [claude, cursor] # optional — only sync to these targets
---
# Math Tutor
You are a patient math tutor. Walk through problems step by step.
Agent ごとの targets： 任意の targets リストを指定すると、その agent は列挙された Target のみに同期されます（claude-code のようなエイリアスも claude にマッチします）。省略するとすべての場所に同期されます。それ以外の frontmatter フィールドはそのまま渡されます — skillshare はツール間で変換を行わないため、あるハーネス向けに書かれた agent が別のハーネスでは理解されないことがあります。同じ agent のハーネスごとのバリアントを並存させるには targets を使ってください（例：targets: [claude] を指定した reviewer.md と targets: [opencode] を指定した reviewer-opencode.md）。
命名ルール：
- ファイル名が agent 名を決定します：
tutor.md= "tutor" - YAML frontmatter の任意の
nameフィールドはファイル名を上書きします - ファイル名は文字または数字で始まる必要があり、使用できる文字は
a-z、A-Z、0-9、_、-、.のみです - 名前の最大長：128 文字
慣例的な除外対象 — 以下のファイル名は discovery 時に常にスキップされます。
README.md、CHANGELOG.md、LICENSE.md、HISTORY.md、SECURITY.md、SKILL.md
サポートされる Target
agents パス定義を持つ Target のみが agent の同期を受け取ります。現在は以下の通りです。
| Target | Global の agents パス | Project の agents パス |
|---|---|---|
claude | ~/.claude/agents | .claude/agents |
cursor | ~/.cursor/agents | .cursor/agents |
opencode | ~/.config/opencode/agents | .opencode/agents |
augment | ~/.augment/agents | .augment/agents |
copilot | ~/.copilot/agents | .github/agents |
droid | ~/.factory/droids | .factory/droids |
agents のエントリを持たない Target（大多数）は skill のみを受け取ります。
Sync の挙動
Agent の sync は、skill と同じく 3 つのモードすべてに対応しています。
| モード | 挙動 |
|---|---|
| merge（デフォルト） | ファイル単位の symlink。Target 内のローカルの agent ファイルは保持されます。 |
| symlink | agents ディレクトリ全体を symlink します。 |
| copy | Agent ファイルを実ファイルとしてコピーします。 |
# Sync everything (skills + agents)
skillshare sync
# Sync agents only
skillshare sync agents
孤立ファイルの掃除も同様に動作します — Source が存在しなくなった壊れた symlink やコピーされたファイルは自動的に削除されます。
Collect の挙動
Agent の collect は skill の collect と同じ CLI 契約を使いますが、.md の agent ファイルを対象に動作します。
# Global
skillshare collect agents claude
skillshare collect agents --all
skillshare collect agents claude --dry-run
skillshare collect agents claude --json
# Project
skillshare collect -p agents claude
skillshare collect -p agents --all
skillshare collect -p agents --json
ルール：
- 既存の Source agent はデフォルトでスキップされます
- 既存の Source agent を上書きするには
--forceを使用します --jsonは--forceを暗黙的に有効にし、確認プロンプトをスキップします- Web ダッシュボードの Collect ページは依然として skill のみに対応しています。agent には CLI を使用してください
.agentignore
.skillignore と全く同じように動作します — gitignore 形式のパターンで sync から agent を除外します。
| スコープ | パス |
|---|---|
| Global | ~/.config/skillshare/agents/.agentignore |
| Project | .skillshare/agents/.agentignore |
例：
# Disable draft agents
draft-*
# Disable a specific agent
experimental-reviewer
エントリを管理するには --kind agent 付きで enable/disable を使用します。
skillshare disable --kind agent draft-reviewer
skillshare enable --kind agent draft-reviewer
リポジトリからの Agent のインストール
リポジトリをインストールする際、skillshare は agent を自動検出します。
- リポジトリ内の
agents/という慣例ディレクトリを探します — その中の.mdファイル（慣例的な除外対象を除く）が agent の候補になります - リポジトリに
skills/とagents/の両方がある場合、両方がインストールされます - リポジトリに
agents/のみがある場合（SKILL.mdのマーカーがない場合）、agent がインストールされます - リポジトリに
skills/もagents/ディレクトリもなく、ルートに直接.mdファイルがある場合 — agent として扱われます（純粋な agent リポジトリ）
明示的なフラグ
# Install only agents from a repo
skillshare install github.com/user/repo --kind agent
# Install specific agents by name (-a shorthand)
skillshare install github.com/user/repo -a tutor,reviewer
# Install specific skills by name (unchanged)
skillshare install github.com/user/repo -s my-skill
CLI コマンド
ほとんどのコマンドは、agent に範囲を絞るための agents 位置引数または --kind agent フラグを受け付けます。
| コマンド | 例 | 動作内容 |
|---|---|---|
list agents | skillshare list agents | Source 内の agent を一覧表示 |
check agents | skillshare check agents | agent の整合性と更新状態をチェック |
audit agents | skillshare audit agents | agent のセキュリティスキャン |
sync agents | skillshare sync agents | agent のみを Target に同期 |
collect agents | skillshare collect agents claude | ローカルの Target agent を Source に回収 |
update agents | skillshare update agents --all | tracked な agent リポジトリとメタデータ管理下の agent を更新 |
enable --kind agent | skillshare enable --kind agent tutor | 無効化された agent を再度有効化 |
disable --kind agent | skillshare disable --kind agent tutor | .agentignore 経由で agent を無効化 |
install --kind agent | skillshare install repo --kind agent | リポジトリから agent のみをインストール |
install -a | skillshare install repo -a tutor | 名前で特定の agent をインストール |
kind フィルタを指定しない場合、コマンドは skill と agent の 両方 を対象に動作します。
データフロー
Project モード
Agent は skill と同じ方法で Project モードで動作します。
# Initialize project (creates .skillshare/agents/ alongside .skillshare/skills/)
skillshare init -p
# Install agents into project
skillshare install github.com/user/repo --kind agent -p
# Update project agents in place
skillshare update agents --all -p
# Sync project agents
skillshare sync -p
Project の agent Source：.skillshare/agents/
インストールされた agent（tracked）は .metadata.json に記録され、tracked な skill と同様に .gitignore のエントリが作成されます。