常見錯誤

錯誤訊息與其解決方法。

設定錯誤

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

原因： 沒有設定檔存在。

解決方法：

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 linter 驗證檔案，或如果有備份，可暫時從 .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 這個 key）

同樣的檢查也適用於 sources.agents 與 Agent Target 路徑之間。

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`

原因： Skill 目錄中有大型檔案。

解決方法： 新增忽略樣式：

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

`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」而失敗，直到釋放出一點空間為止。先刪除一個大檔案，再進行清理。

如果是 Source 很大，代表這些產出物就在你的 Skill 裡面。備份不會複製它們（symlink 的 Skill 會被跳過），但每個以 copy 模式運作的 Target 都會複製。把 runtime 快取、模型權重、瀏覽器 profile 移到 Skill 樹狀結構之外，或用 ignore: 排除它們。

備份範圍與 .gitignore 及 ignore: 的差異，請參閱備份與磁碟空間。

Git 錯誤

`Could not read from remote repository`

原因： SSH 金鑰未設定，或 remote 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`

原因： Remote 儲存庫領先於本地。

解決方法：

skillshare pull   # 先取得 remote 的變更
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 設定中沒有 user.name / user.email。skillshare 會使用本地的備援值（skillshare@local）讓 init 能夠完成，但你應該設定自己的身分。

解決方法：

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

`Git root mismatch`

原因： config.yaml 中的 git_root 指向一個沒有 git 儲存庫的 scope 目錄，但另一個 scope 目錄卻有。這通常發生在你變更 git_root 卻沒有搬移儲存庫時 — 切換 scope 的意思是「開始為另一個目錄建立版本控制」，而不是「搬移既有的歷史紀錄」。詳見 git_root。

解決方法： 從錯誤訊息印出的三個選項中選一個：

# 在設定的 scope 上開始一個全新的儲存庫（沒有歷史紀錄）
skillshare init --git-root <scope>

# 搬移既有的儲存庫，保留歷史紀錄
mv <old-scope>/.git <new-scope>/.git

# 或繼續使用既有的儲存庫：把 git_root 改回 config.yaml 中的值
#   git_root: <scope-that-has-the-repo>

`tracked repository clone is missing`

原因： .metadata.json 中宣告了一個 Tracked repo，但本地的 clone 目錄（例如 skills/_team-skills/）不存在。這通常發生在你於新機器上 clone 你的 skillshare Source 儲存庫之後，因為 Tracked repo 目錄有意被列在受管理的 .gitignore 區塊中。

解決方法： 從中繼資料重新產生遺失的 Tracked repo clone：

skillshare install
skillshare sync

在 Project mode 下：

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 會把它當成一個空的 submodule 上傳，並默默丟棄其中的檔案，因此 commit/push 會中止，直到每個巢狀儲存庫都被停用為止。

解決方法：

# 停用每個被回報的巢狀儲存庫（可還原 — 改回原名即可重新啟用）
mv ~/.config/skillshare/<dir>/.git ~/.config/skillshare/<dir>/.git.disabled

或使用 Web UI 的 Git Sync 頁面上的一鍵停用功能。skillshare 也會自動讓 config.yaml 不進入 root-scope 儲存庫（因為它包含機器特有的路徑）。

`Invalid git_root`

原因： config.yaml 中的 git_root 被設為無法辨識的值（例如拼字錯誤）。

解決方法： 使用 skills、agents、extras 或 root 其中之一 — 或留空（預設為 skills）。

安裝錯誤

`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

如果使用了 token 但被拒絕：

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

解決方法： 請參閱下方的驗證選項。

`Authentication failed` / `Access denied`

原因： HTTPS 憑證遺失、過期，或 token 類型錯誤。

解決方法 — 選項 1：設定 token 環境變數：

# 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 # 或平台專屬的憑證管理工具

所需的 token 權限：

平台	Token 類型	範圍／權限
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 token types

只有 Personal Access Token（glpat-）能用於 git 操作。Feed Tokens（glft-）沒有 git 存取權限。

請參閱環境變數與私人儲存庫。

`SSL certificate problem` / `certificate verification failed`

原因： Git 伺服器使用自簽憑證，或你的系統不信任的內部 CA。常見於自架的 GitLab、Gitea 或 Gogs 實例。

解決方法 — 選項 1：自訂 CA bundle（建議）：

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 目錄。

更新錯誤

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

原因： Remote 分支與你本地 Tracked 的副本已經分歧。

解決方法：

# 強制更新（以 remote 取代本地）
skillshare update --force

# 或手動解決
cd ~/.config/skillshare/skills/_repo-name
git pull --rebase

提示

skillshare update 與 skillshare install 現在會針對 git 失敗（身分驗證、SSL、分歧分支）提供可行動的錯誤訊息，而非原始的結束碼。

稽核錯誤

`security audit failed — critical threats detected`

原因： 該 Skill 包含符合重大安全威脅的樣式（Prompt injection、資料外洩、憑證存取）。

解決方法：

# 檢視發現的問題
skillshare audit <skill-name>

# 如果你信任此 Source，強制安裝
skillshare install <source> --force

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

原因： 該 Skill 包含隱藏的 Unicode 字元，可能是複製貼上留下的痕跡，也可能是刻意的混淆手法。

解決方法： 用能顯示隱藏字元的編輯器開啟檔案並移除它們，或如果信任此 Source，強制安裝。

升級錯誤

`GitHub API rate limit exceeded`

原因： 未驗證身分的 API 請求過多。

解決方法：

# 選項 1：設定 GitHub token（建議）
export GITHUB_TOKEN=ghp_your_token_here
skillshare upgrade

# 選項 2：強制升級
skillshare upgrade --cli --force

在此建立 token：https://github.com/settings/tokens （公開儲存庫不需要任何 scope）

Skill 錯誤

`skill not appearing in AI CLI`

原因：

Skill 尚未同步
SKILL.md 格式無效
AI CLI 快取

解決方法：

# 1. 同步
skillshare sync

# 2. 檢查格式
skillshare doctor

# 3. 重新啟動 AI CLI

Antigravity 無法載入已同步的 Skill

原因： Antigravity app 的 Skill 掃描器只會偵測真實目錄 — 它會跳過 symlink。skillshare 預設的 merge 模式會為每個 Skill 建立一個 symlink（在 Windows 上是 NTFS junction），因此沒有任何一個會被偵測到。在 Windows 上，這會出現 Incorrect function 錯誤；在 macOS 與 Linux 上，Skill 則會靜默地消失不見。

這是 Antigravity 端的限制，而非 skillshare 的臭蟲。此限制只影響 antigravity target（app，~/.gemini/config/skills）；獨立的 agy CLI 是另一個 antigravity-cli target，讀取 ~/.gemini/antigravity-cli/skills。有兩種解決方法：

選項 1 — 將 Target 切換為 copy 模式

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

會寫入真實目錄取代 symlink。取捨：編輯 Source Skill 後需要重新執行 skillshare sync。

選項 2 — 讓 Antigravity 指向你的 Source 目錄

在 Antigravity 中：Settings → Customizations → Skill Custom Paths → 「+ Add」，然後輸入你的 skillshare Source 絕對路徑（例如 /Users/you/.config/skillshare/skills）。~ 這種簡寫不會被展開，因此需要完整路徑。

無論用哪種方法，都要重新啟動 Antigravity 以重新載入 Skill。

`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：透過篩選條件路由（Global 設定）
targets:
  codex:
    path: ~/.codex/skills
    include: [_team-a__*]
  claude:
    path: ~/.claude/skills
    include: [_team-b__*]

# 選項 2：透過篩選條件路由（Project 設定）
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 沒有定義 Agent 目錄。只有 Claude、Cursor、Augment 和 OpenCode 有內建的 Agent 路徑；其他 Target 會被靜默跳過。

解決方法：

如果這些 Target 不需要 Agent，可以忽略此警告。
在 config.yaml 中為該 Target 新增 agents: 子欄位，為它啟用 Agent 同步：

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>）。在 Project mode 下，只支援 Agent 備份 — Skill 備份僅限於 Global mode。

解決方法： 加上 agents 位置參數，或使用 --all：

skillshare backup -p agents          # Project Agent Targets
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（Global）或 .skillshare/agents/.agentignore（Project）。
你的樣式比對到了非預期的部分 — 此檔案使用 gitignore 語法。

解決方法： 用 skillshare doctor 確認檔案路徑，並重新檢查樣式。Agent 是以基本檔名（不含 .md）進行比對的，所以 draft-* 會比對到 draft-experiment.md。使用 skillshare disable <agent> --kind agent 讓 CLI 幫你寫入該項目。

二進位檔錯誤

`integration tests cannot find the binary`

原因： 二進位檔未建置，或路徑錯誤。

解決方法：

go build -o bin/skillshare ./cmd/skillshare
# 或設定
export SKILLSHARE_TEST_BINARY=/path/to/skillshare

還有問題嗎？

請參閱疑難排解流程，了解系統性的除錯方法。

設定錯誤
Target 錯誤
Sync 錯誤
Git 錯誤
安裝錯誤
更新錯誤
- git failed: Need to specify how to reconcile divergent branches
稽核錯誤
- security audit failed — critical threats detected
- audit HIGH: Hidden zero-width Unicode characters detected
升級錯誤
- GitHub API rate limit exceeded
Skill 錯誤
Agent 錯誤
二進位檔錯誤
- integration tests cannot find the binary
還有問題嗎？

設定錯誤​

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​

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​

安裝錯誤​

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​

更新錯誤​

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

稽核錯誤​

security audit failed — critical threats detected​

audit HIGH: Hidden zero-width Unicode characters detected​

升級錯誤​

GitHub API rate limit exceeded​

Skill 錯誤​

skill not appearing in AI CLI​

Antigravity 無法載入已同步的 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 樣式沒有生效​

二進位檔錯誤​

integration tests cannot find the binary​

還有問題嗎？​

設定錯誤

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

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

安裝錯誤

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

更新錯誤

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

稽核錯誤

`security audit failed — critical threats detected`

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

升級錯誤

`GitHub API rate limit exceeded`

Skill 錯誤

`skill not appearing in AI CLI`

Antigravity 無法載入已同步的 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` 樣式沒有生效

二進位檔錯誤

`integration tests cannot find the binary`

還有問題嗎？