よくあるエラー

エラーメッセージとその解決方法です。

Config エラー

`config not found: run 'skillshare init' first`

原因: Config ファイルが存在しません。

解決策:

skillshare init

カスタムパスにしたい場合は --source を追加してください。

skillshare init --source ~/my-skills

`failed to load project config: ...`

原因: .skillshare/config.yaml は存在するがパースできません（不正な YAML、型の間違いなど）。変更を伴うコマンド（uninstall、new、enable/disable、check）は、カスタムの sources 設定がある場合にデフォルトの .skillshare/skills/ ディレクトリを誤って操作しないよう、この状態では処理を拒否します。

解決策: YAML を修正してコマンドを再実行してください。よくある問題:

# 誤り — targets はリストでなければならない
targets: {}

# 正しい
targets: []

# 誤り — skills はリストでなければならない
skills: my-skill

# 正しい
skills:
  - name: my-skill
    source: github.com/org/my-skill

任意の YAML リンターでファイルを検証するか、.skillshare/backups/ があれば一時的にそこから復元してください。

`target "<name>": skills target path X overlaps skills source Y`

原因: sources.skills が、ある Target の Skill パスと同じディレクトリに解決されている（または一方がもう一方を含んでいる）。例えば sources.skills: .claude/skills を claude Target と一緒に設定すると、両方が .claude/skills/ を指すことになります。このガードがなければ、sync --force は Source を Target ディレクトリとして扱い、その内容を削除してしまいます。

解決策: どの Target ともエイリアスにならない Source パスを選んでください。よくある安全な選択肢:

# プロジェクトのドキュメントと同じ場所に置く
sources:
  skills: ./docs/skills

# .skillshare/ 配下に維持する（デフォルト — sources キーを完全に削除する）

同じチェックが、Agent の Target パスに対する sources.agents にも適用されます。

Target エラー

`target add: path does not exist`

原因: Skill ディレクトリがまだ存在しません。

解決策:

mkdir -p ~/.myapp/skills
skillshare target add myapp ~/.myapp/skills

`target path does not end with 'skills'`

原因: パスが規約に従っていないという警告。

解決策: これはエラーではなく警告です。意図的なパスであればそのまま進めるか、修正してください。

skillshare target add myapp ~/.myapp/skills  # 推奨

`target directory already exists with files`

原因: Target に上書きされる可能性のある既存のファイルがある。

解決策:

skillshare backup
skillshare sync

Sync エラー

`deleting a symlinked target removed source files`

原因: symlink モードの Target に対して rm -rf を実行した。

解決策:

# git が初期化されている場合
cd ~/.config/skillshare/skills
git checkout -- .

# またはバックアップから復元する
skillshare restore <target>

予防策: 手動で削除する代わりに skillshare target remove を使用してください。

`sync seems stuck or slow`

原因: skills ディレクトリ内に大きなファイルがある。

解決策: ignore パターンを追加してください。

# ~/.config/skillshare/config.yaml
ignore:
  - "**/.DS_Store"
  - "**/.git/**"
  - "**/node_modules/**"

Sync 中の `no space left on device` / `ENOSPC`

原因: 何かがボリュームを圧迫している。まずバックアップディレクトリを確認し、次に Source を確認してください。

解決策:

df -h ~                                     # ボリュームが満杯であることを確認する
du -sh ~/.local/share/skillshare/backups    # バックアップの使用量
du -sh ~/.config/skillshare/skills          # Source の使用量

バックアップが大きい場合は整理してください — 保持ポリシーは各 sync の後に自動的に実行されますが、それ以前に肥大化したディレクトリはオンデマンドでクリアできます。

skillshare backup --cleanup --dry-run   # プレビュー
skillshare backup --cleanup

ボリュームが100%に張り付いている場合、少し空き容量ができるまで rm が「Permission denied」で失敗することがあります。まず大きなファイルを1つ解放してから、整理してください。

Source が大きい場合、そのアーティファクトは Skill の中にあります。バックアップはそれらをコピーしません（シンボリックリンクされた Skill はスキップされる）が、copy モードのすべての Target はコピーします。ランタイムキャッシュ、モデルの重み、ブラウザプロファイルは Skill ツリーの外に移動するか、ignore: で除外してください。

バックアップの範囲が .gitignore や ignore: とどう違うかについては Backups & Disk Space を参照してください。

Git エラー

`Could not read from remote repository`

原因: SSH キーが設定されていない、またはリモート URL が間違っている。

解決策:

# SSH アクセスを確認する
ssh -T [email protected]

# SSH が設定されていない場合は代わりに HTTPS を使う
git -C ~/.config/skillshare/skills remote set-url origin https://github.com/you/my-skills.git

# または SSH キーを設定する
ssh-keygen -t ed25519 -C "[email protected]"
# その後、公開鍵を GitHub → Settings → SSH keys に追加する

`push: remote has changes`

原因: リモートリポジトリがローカルより先行している。

解決策:

skillshare pull   # まずリモートの変更を取得する
skillshare push   # これで push できる

`pull: local has uncommitted changes`

原因: push されていないローカルの変更がある。

解決策:

# オプション1: 先に変更を push する
skillshare push -m "Local changes"
skillshare pull

# オプション2: ローカルの変更を破棄する
cd ~/.config/skillshare/skills
git checkout -- .
skillshare pull

`merge conflicts`

原因: 同じファイルが複数のマシンで編集された。

解決策:

cd ~/.config/skillshare/skills
git status                    # 競合しているファイルを確認する
# 競合を解決するためにファイルを編集する
git add .
git commit -m "Resolve conflicts"
skillshare sync

`Git identity not configured`

原因: git config に user.name / user.email が設定されていない。skillshare は init を完了させるためにローカルのフォールバック（skillshare@local）を使いますが、自分自身の情報を設定するべきです。

解決策:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

`Git root mismatch`

原因: config.yaml の git_root が git リポジトリのないスコープディレクトリを指しているが、別のスコープディレクトリにはリポジトリがある。これは、リポジトリを再配置せずに git_root を変更した場合に発生します — スコープの切り替えは「別のディレクトリのバージョン管理を開始する」ことであり、「既存の履歴を移動する」ことではありません。 git_root を参照してください。

解決策: エラーが表示する3つのオプションのいずれかを選んでください。

# 設定されているスコープに新しいリポジトリを開始する（履歴なし）
skillshare init --git-root <scope>

# 既存のリポジトリを移動し、履歴を維持する
mv <old-scope>/.git <new-scope>/.git

# または既存のリポジトリを使い続ける: config.yaml の git_root を戻す
#   git_root: <scope-that-has-the-repo>

`tracked repository clone is missing`

原因: Tracked リポジトリが .metadata.json に宣言されているが、clone されたディレクトリ（例: skills/_team-skills/）がローカルに存在しない。これは、Tracked リポジトリのディレクトリが意図的に管理された .gitignore ブロックに列挙されているため、新しいマシンで skillshare の Source リポジトリを clone した後によく発生します。

解決策: メタデータから欠けている Tracked リポジトリの clone を復元してください。

skillshare install
skillshare sync

プロジェクトモードの場合:

skillshare install -p
skillshare sync -p

status、check、update --all、doctor はこの状態を報告し、skillshare install を提案します。

`nested git repositories must be disabled first`

原因: git_root: root の場合、サブディレクトリ（例: skills/_org/ 配下の Tracked された Skill リポジトリ）が独自の .git を持っている。Git はこれを 空のサブモジュール としてアップロードし、そのファイルを黙って失ってしまうため、それぞれのネストされたリポジトリが無効化されるまで commit/push は中止されます。

解決策:

# 報告された各ネストされたリポジトリを無効化する（可逆的 — 名前を戻せば再度有効化できる）
mv ~/.config/skillshare/<dir>/.git ~/.config/skillshare/<dir>/.git.disabled

または Web UI の Git Sync ページでワンクリック無効化を使ってください。skillshare は、（マシン固有のパスを保持しているため）config.yaml を root スコープのリポジトリから自動的に除外します。

`Invalid git_root`

原因: config.yaml の git_root が認識できない値に設定されている（例: タイプミス）。

解決策: skills、agents、extras、root のいずれかを使うか、空のままにしてください（デフォルトは skills）。

Install エラー

`skill already exists`

原因: 同じ名前の Skill がすでにインストールされている。

解決策:

# 既存の Skill を更新する
skillshare install <source> --update

# または強制的に上書きする
skillshare install <source> --force

`git failed (exit 128): repository not found or authentication required`

原因: リポジトリの URL が間違っている、リポジトリが存在しない、または認証情報が不足している。

skillshare は現在、一般的な git の失敗に対して生の終了コードの代わりに実用的なエラーメッセージを提供します。エラーメッセージには提案が含まれます。

Error: git failed (exit 128): repository not found or authentication required

トークンが使用されたが拒否された場合:

Error: git failed (exit 128): authentication token was rejected — check permissions and expiry

解決策: 下記の認証オプションを参照してください。

`Authentication failed` / `Access denied`

原因: HTTPS の認証情報が不足している、期限切れである、またはトークンの種類が間違っている。

解決策 — オプション1: トークンの環境変数を設定する:

# GitHub
export GITHUB_TOKEN=ghp_xxxx

# GitLab（Personal Access Token でなければならない。プレフィックスは glpat-）
export GITLAB_TOKEN=glpat-xxxx

# Bitbucket
export BITBUCKET_TOKEN=your_app_password

Windows（PowerShell）:

$env:GITLAB_TOKEN = "glpat-xxxx"

# 永続化（再起動後も残る）
[Environment]::SetEnvironmentVariable("GITLAB_TOKEN", "glpat-xxxx", "User")

解決策 — オプション2: SSH URL を使う:

skillshare install [email protected]:team/private-skills.git
skillshare install [email protected]:team/skills.git
skillshare install [email protected]:team/skills.git

解決策 — オプション3: git credential helper を使う:

gh auth login          # GitHub CLI
git credential approve # またはプラットフォーム固有の credential manager

必要なトークンの権限:

プラットフォーム	トークンの種類	スコープ / 権限
GitHub	Personal Access Token（`ghp_`）	`repo`（プライベートリポジトリ）、なし（パブリック）
GitLab	Personal Access Token（`glpat-`）	`read_repository` + `write_repository`
Bitbucket	Repository Access Token	Read + Write
Bitbucket	App Password + `BITBUCKET_USERNAME`	Repositories: Read + Write

GitLab のトークンの種類

git 操作に使えるのは Personal Access Token（glpat-）のみです。Feed Token（glft-）には git アクセス権限が ありません。

環境変数とプライベートリポジトリを参照してください。

`SSL certificate problem` / `certificate verification failed`

原因: Git サーバーが自己署名証明書、またはシステムが信頼していない内部 CA を使用している。セルフホストの GitLab、Gitea、Gogs インスタンスでよく見られます。

解決策 — オプション1: カスタム CA バンドル（推奨）:

export GIT_SSL_CAINFO=/path/to/company-ca-bundle.crt
skillshare install https://gitlab.internal.company.com/team/skills.git --track

解決策 — オプション2: 代わりに SSH を使う（SSL を完全に回避する）:

skillshare install [email protected]:team/skills.git --track

解決策 — オプション3: SSL 検証を無効化する（非推奨）:

GIT_SSL_NO_VERIFY=true skillshare install https://gitlab.internal.company.com/team/skills.git --track

警告

SSL 検証を無効化するのはセキュリティリスクです。オプション1か2を優先してください。

環境変数 — Git SSL / TLS を参照してください。

`invalid skill: SKILL.md not found`

原因: Source に有効な SKILL.md ファイルがない。

解決策: Source のパスが正しく、Skill ディレクトリを指していることを確認してください。

Update エラー

`git failed: Need to specify how to reconcile divergent branches`

原因: リモートブランチがローカルの Tracked コピーから分岐している。

解決策:

# 強制的に更新する（ローカルをリモートで置き換える）
skillshare update --force

# または手動で解決する
cd ~/.config/skillshare/skills/_repo-name
git pull --rebase

ヒント

skillshare update と skillshare install は現在、git の失敗（認証、SSL、分岐したブランチ）に対して、生の終了コードの代わりに実用的なエラーメッセージを表示します。

Audit エラー

`security audit failed — critical threats detected`

原因: Skill に重大なセキュリティ脅威（プロンプトインジェクション、データ持ち出し、認証情報へのアクセス）にマッチするパターンが含まれている。

解決策:

# 検出結果を確認する
skillshare audit <skill-name>

# Source を信頼する場合は強制インストールする
skillshare install <source> --force

`audit HIGH: Hidden zero-width Unicode characters detected`

原因: Skill にコピー&ペーストの痕跡、または意図的な難読化である可能性のある不可視の Unicode 文字が含まれている。

解決策: 隠し文字を表示できるエディタでファイルを開いて削除するか、Source を信頼する場合は強制インストールしてください。

Upgrade エラー

`GitHub API rate limit exceeded`

原因: 未認証の API リクエストが多すぎる。

解決策:

# オプション1: GitHub トークンを設定する（推奨）
export GITHUB_TOKEN=ghp_your_token_here
skillshare upgrade

# オプション2: 強制的にアップグレードする
skillshare upgrade --cli --force

トークンの作成: https://github.com/settings/tokens （パブリックリポジトリにはスコープ不要）

Skill エラー

`skill not appearing in AI CLI`

原因:

Skill が Sync されていない
SKILL.md のフォーマットが無効
AI CLI がキャッシュしている

解決策:

# 1. Sync する
skillshare sync

# 2. フォーマットを確認する
skillshare doctor

# 3. AI CLI を再起動する

Antigravity が Sync された Skill を読み込まない

原因: Antigravity アプリの Skill スキャナーは 実際のディレクトリ のみを検出します — シンボリックリンクはスキップされます。skillshare のデフォルトの merge モードは Skill ごとに 1つのシンボリックリンク（Windows では NTFS ジャンクション）を作成するため、そのどれも検出されません。 Windows ではこれが Incorrect function エラーとして表面化し、macOS と Linux では Skill が黙って表示されません。

これは Antigravity 側の制限であり、skillshare のバグではありません。対象は antigravity ターゲット（アプリ、~/.gemini/config/skills）のみで、スタンドアロンの agy CLI は ~/.gemini/antigravity-cli/skills を読む別の antigravity-cli ターゲットです。回避策は2つあります。

オプション1 — Target を copy モードに切り替える

skillshare target antigravity --mode copy
skillshare sync --force

シンボリックリンクの代わりに実際のディレクトリが書き込まれます。トレードオフ: Source の Skill を編集した後は skillshare sync を再実行する必要があります。

オプション2 — Antigravity に Source ディレクトリを指定する

Antigravity で: Settings → Customizations → Skill Custom Paths → 「+ Add」 を開き、 skillshare の Source への絶対パス（例: /Users/you/.config/skillshare/skills）を入力してください。~ の省略形は展開されないため、完全なパスが必要です。

どちらの方法でも、Skill を再読み込みするために Antigravity を再起動してください。

`skill name 'X' is defined in multiple places`

原因: 複数の Skill が同じ name フィールドを持ち、同じ Target に配置されている。

解決策: SKILL.md で一方の名前を変更するか、include/exclude フィルターを使って異なる Target にルーティングしてください。

# オプション1: SKILL.md で名前空間を分ける
name: team-a-skill-name

# オプション2: フィルターでルーティングする（グローバル Config）
targets:
  codex:
    path: ~/.codex/skills
    include: [_team-a__*]
  claude:
    path: ~/.claude/skills
    include: [_team-b__*]

# オプション2: フィルターでルーティングする（プロジェクト Config）
targets:
  - name: claude
    exclude: [codex-*]
  - name: codex
    include: [codex-*]

ヒント

フィルターがすでに重複を分離している場合、sync は警告ではなく情報メッセージを表示します — 対応は不要です。完全な構文は Target フィルターを参照してください。

Agent エラー

警告: `target(s) skipped for agents (no agents path)`

原因: skillshare sync（または skillshare sync agents）を実行したが、設定済みの Target のうち1つ以上に Agent ディレクトリが定義されていない。組み込みの Agent パスを持つのは Claude、Cursor、Augment、OpenCode のみで、他の Target は黙ってスキップされます。

解決策:

それらの Target に Agent が不要であれば、警告は無視してください。
config.yaml の Target に agents: サブキーを追加して、その Target の Agent Sync を有効にしてください。

targets:
  myapp:
    path: ~/myapp/skills
    agents:
      path: ~/myapp/agents

その後 skillshare sync agents を再実行してください。

`backup is not supported in project mode (except for agents)`

原因: agents フィルターなしで skillshare backup -p（または skillshare backup -p <target>）を実行した。プロジェクトモードでは Agent のバックアップのみが対応しており、Skill のバックアップはグローバルモード限定です。

解決策: agents の位置引数を追加するか、--all を使用してください。

skillshare backup -p agents          # プロジェクトの Agent Target
skillshare backup -p agents claude   # 特定の Target
skillshare backup -p --all           # 上と同じ（Agent に絞り込まれる）

同じルールが restore にも適用されます: restore is not supported in project mode (except for agents)

`agent name 'X' has invalid characters`

原因: Agent のファイル名または name: frontmatter フィールドに、許可された文字セット外の文字が含まれている。

解決策: Agent 名には a-z、0-9、_、-、. のみを使用できます。ファイル名を変更し（name: フィールドも一致するよう更新して）、同じ正規名を共有するようにしてください。

`.agentignore` パターンが反映されない

原因:

ファイルが間違った場所にある。Agent Source のルート、つまり ~/.config/skillshare/agents/.agentignore（グローバル）または .skillshare/agents/.agentignore（プロジェクト）に置かなければなりません。
パターンが想定と異なるセグメントにマッチしている — このファイルは gitignore 構文を使用します。

解決策: skillshare doctor でファイルパスを確認し、パターンを再チェックしてください。 Agent はベース名（.md を除く）でマッチするため、draft-* は draft-experiment.md にマッチします。CLI にエントリを書き込ませるには skillshare disable <agent> --kind agent を使用してください。

Binary エラー

`integration tests cannot find the binary`

原因: バイナリがビルドされていない、またはパスが間違っている。

解決策:

go build -o bin/skillshare ./cmd/skillshare
# または設定する
export SKILLSHARE_TEST_BINARY=/path/to/skillshare

まだ問題がありますか？

体系的なデバッグ方法についてはトラブルシューティングワークフローを参照してください。

Config エラー
Target エラー
Sync エラー
Git エラー
Install エラー
Update エラー
- git failed: Need to specify how to reconcile divergent branches
Audit エラー
- security audit failed — critical threats detected
- audit HIGH: Hidden zero-width Unicode characters detected
Upgrade エラー
- GitHub API rate limit exceeded
Skill エラー
Agent エラー
Binary エラー
- integration tests cannot find the binary
まだ問題がありますか？

Config エラー​

config not found: run 'skillshare init' first​

failed to load project config: ...​

target "<name>": skills target path X overlaps skills source Y​

Target エラー​

target add: path does not exist​

target path does not end with 'skills'​

target directory already exists with files​

Sync エラー​

deleting a symlinked target removed source files​

sync seems stuck or slow​

Sync 中の no space left on device / ENOSPC​

Git エラー​

Could not read from remote repository​

push: remote has changes​

pull: local has uncommitted changes​

merge conflicts​

Git identity not configured​

Git root mismatch​

tracked repository clone is missing​

nested git repositories must be disabled first​

Invalid git_root​

Install エラー​

skill already exists​

git failed (exit 128): repository not found or authentication required​

Authentication failed / Access denied​

SSL certificate problem / certificate verification failed​

invalid skill: SKILL.md not found​

Update エラー​

git failed: Need to specify how to reconcile divergent branches​

Audit エラー​

security audit failed — critical threats detected​

audit HIGH: Hidden zero-width Unicode characters detected​

Upgrade エラー​

GitHub API rate limit exceeded​

Skill エラー​

skill not appearing in AI CLI​

Antigravity が Sync された Skill を読み込まない​

skill name 'X' is defined in multiple places​

Agent エラー​

警告: target(s) skipped for agents (no agents path)​

backup is not supported in project mode (except for agents)​

agent name 'X' has invalid characters​

.agentignore パターンが反映されない​

Binary エラー​

integration tests cannot find the binary​

まだ問題がありますか？​

Config エラー

`config not found: run 'skillshare init' first`

`failed to load project config: ...`

`target "<name>": skills target path X overlaps skills source Y`

Target エラー

`target add: path does not exist`

`target path does not end with 'skills'`

`target directory already exists with files`

Sync エラー

`deleting a symlinked target removed source files`

`sync seems stuck or slow`

Sync 中の `no space left on device` / `ENOSPC`

Git エラー

`Could not read from remote repository`

`push: remote has changes`

`pull: local has uncommitted changes`

`merge conflicts`

`Git identity not configured`

`Git root mismatch`

`tracked repository clone is missing`

`nested git repositories must be disabled first`

`Invalid git_root`

Install エラー

`skill already exists`

`git failed (exit 128): repository not found or authentication required`

`Authentication failed` / `Access denied`

`SSL certificate problem` / `certificate verification failed`

`invalid skill: SKILL.md not found`

Update エラー

`git failed: Need to specify how to reconcile divergent branches`

Audit エラー

`security audit failed — critical threats detected`

`audit HIGH: Hidden zero-width Unicode characters detected`

Upgrade エラー

`GitHub API rate limit exceeded`

Skill エラー

`skill not appearing in AI CLI`

Antigravity が Sync された Skill を読み込まない

`skill name 'X' is defined in multiple places`

Agent エラー

警告: `target(s) skipped for agents (no agents path)`

`backup is not supported in project mode (except for agents)`

`agent name 'X' has invalid characters`

`.agentignore` パターンが反映されない

Binary エラー

`integration tests cannot find the binary`

まだ問題がありますか？