Common Errors

错误信息与对应的解决方式。

Config Errors

`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 必须是 list
targets: {}

# 正确
targets: []

# 错误 — skills 必须是 list
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 的 skills 路径相同（或两者互相包含）。例如同时设置 sources.skills: .claude/skills 和一个 claude Target——两者都指向 .claude/skills/。如果没有这项检查，sync --force 会把 Source 误认为 Target 目录并删除其内容。

解决方式： 选择一个不会与任何 Target 重叠的 Source 路径。常见的安全选择：

# 与项目文件放在一起
sources:
  skills: ./docs/skills

# 保留在 .skillshare/ 下（默认值 — 直接移除 sources 键即可）

同样的检查也适用于 sources.agents 与 Agent Target 路径之间。

Target Errors

`target add: path does not exist`

原因： skills 目录尚不存在。

解决方式：

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 Errors

`deleting a symlinked target removed source files`

原因： 你在 symlink 模式下对某个 Target 执行了 rm -rf。

解决方式：

# 如果已初始化 git
cd ~/.config/skillshare/skills
git checkout -- .

# 或从 backup 还原
skillshare restore <target>

预防方式： 用 skillshare target remove 取代手动删除。

`sync seems stuck or slow`

原因： skills 目录中有大文件。

解决方式： 加上忽略规则：

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

`no space left on device` / `ENOSPC` during sync

原因： 有东西把卷占满了。先检查 backup 目录，再检查你的 Source。

解决方式：

df -h ~                                     # 确认卷已满
du -sh ~/.local/share/skillshare/backups    # backup 用量
du -sh ~/.config/skillshare/skills          # Source 用量

如果 backup 占用很大，就清理它——保留策略会在每次 sync 后自动运行，但如果目录在此之前就已经变大，也可以手动清理：

skillshare backup --cleanup --dry-run   # 预览
skillshare backup --cleanup

如果卷被钉在 100% 满，rm 可能会因为 "Permission denied" 而失败，直到腾出一点空间为止。先删掉一个大文件，再执行清理。

如果是 Source 太大，问题往往出在 skills 内部的产物文件。backup 不会复制这些内容（symlink 的 skills 会被跳过），但处于 copy 模式的每个 Target 都会复制。请把运行时缓存、模型权重、浏览器 profile 移到 skill 目录之外，或用 ignore: 排除它们。

关于 backup 范围与 .gitignore、ignore: 的差异，参见 Backups & Disk Space。

Git Errors

`Could not read from remote repository`

原因： SSH key 未设置，或远程仓库地址不正确。

解决方式：

# 检查 SSH 访问权限
ssh -T [email protected]

# 如果没有设置 SSH，改用 HTTPS
git -C ~/.config/skillshare/skills remote set-url origin https://github.com/you/my-skills.git

# 或设置 SSH key
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 配置里没有 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

# 或继续使用既有仓库：把 config.yaml 的 git_root 改回去
#   git_root: <scope-that-has-the-repo>

`tracked repository clone is missing`

原因： 某个 tracked repo 已记录在 .metadata.json 中，但对应的克隆目录（例如 skills/_team-skills/）在本地却不存在。这常发生在你把 skillshare 的 Source 仓库克隆到新机器之后，因为 tracked repo 的目录会被有意列入受管理的 .gitignore 区块中。

解决方式： 从 metadata 重新还原缺失的 tracked repo 克隆：

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/ 下被 track 的 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）。

Install Errors

`skill already exists`

原因： 已经安装了同名的 Skill。

解决方式：

# 更新已安装的 Skill
skillshare install <source> --update

# 或强制覆盖
skillshare install <source> --force

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

原因： 仓库地址不正确、仓库不存在，或缺少身份验证信息。

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 地址：

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

解决方式 — 选项 3：Git 凭证助手：

gh auth login          # GitHub CLI
git credential approve # 或平台专属的 credential manager

所需的 token 权限：

平台	Token 类型	权限范围
GitHub	Personal Access Token（`ghp_`）	`repo`（私有仓库），公开仓库无需权限
GitLab	Personal Access Token（`glpat-`）	`read_repository` + `write_repository`
Bitbucket	Repository Access Token	读 + 写
Bitbucket	App Password + `BITBUCKET_USERNAME`	Repositories: 读 + 写

GitLab token types

只有 Personal Access Token（glpat-）可用于 git 操作。Feed Token（glft-）没有 git 访问权限。

参见 Environment Variables 与 Private Repositories。

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

参见 Environment Variables — Git SSL / TLS。

`invalid skill: SKILL.md not found`

原因： 该 Source 没有有效的 SKILL.md 文件。

解决方式： 确认 Source 路径正确，且指向一个 Skill 目录。

Update Errors

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

`security audit failed — critical threats detected`

原因： 该 Skill 包含匹配严重安全威胁的模式（prompt injection、数据外泄、凭证访问）。

解决方式：

# 查看检测结果
skillshare audit <skill-name>

# 如果你信任该来源，强制安装
skillshare install <source> --force

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

原因： 该 Skill 中含有不可见的 Unicode 字符，可能是复制粘贴产生的残留，也可能是刻意混淆。

解决方式： 用能显示隐藏字符的编辑器打开文件并移除它们，或者如果信任该来源，可以强制安装。

Upgrade Errors

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

`skill not appearing in AI CLI`

原因：

Skill 未同步
SKILL.md 格式无效
AI CLI 有缓存

解决方式：

# 1. Sync
skillshare sync

# 2. 检查格式
skillshare doctor

# 3. 重新启动 AI CLI

Antigravity does not load synced skills

原因： Antigravity 应用的 Skill 扫描器只会发现真实目录——它会跳过 symlink。skillshare 默认的 merge 模式会为每个 Skill 创建一个 symlink（在 Windows 上是 NTFS junction），所以没有一个会被扫描到。在 Windows 上会表现为 Incorrect function 错误；在 macOS 与 Linux 上，Skill 则是悄悄地不出现。

这是 Antigravity 那一侧的限制，不是 skillshare 的 bug。它只影响 antigravity target（应用，~/.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 Filters。

Agent Errors

Warning: `target(s) skipped for agents (no agents path)`

原因： 你执行了 skillshare sync（或 skillshare sync agents），而某些配置的 Target 没有定义 agents 目录。只有 Claude、Cursor、Augment 和 OpenCode 内置了 agents 路径；其他 Target 在 agent 同步时会被自动跳过。

解决方式：

如果这些 Target 不需要 agents，可以忽略这个警告。
在 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)`

原因： 你执行了 skillshare backup -p（或 skillshare backup -p <target>），却没有加上 agents 过滤条件。在 Project mode 下，只支持 agent 的 backup——Skill 的 backup 仅限 Global mode。

解决方式： 加上 agents 位置参数，或使用 --all：

skillshare backup -p agents          # Project mode 下的 agent Target
skillshare backup -p agents claude   # 指定某个 Target
skillshare backup -p --all           # 效果相同（在 Project mode 下会收窄为 agents）

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` patterns not taking effect

原因：

文件放错了位置。它必须位于 agents source 的根目录：~/.config/skillshare/agents/.agentignore（Global mode）或 .skillshare/agents/.agentignore（Project mode）。
你的匹配规则命中了非预期的路径片段——该文件使用 gitignore 语法。

解决方式： 用 skillshare doctor 确认文件路径，并重新检查匹配规则。agent 是按 basename（不含 .md）匹配的，所以 draft-* 会匹配 draft-experiment.md。可以用 skillshare disable <agent> --kind agent 让 CLI 帮你写入该条目。

Binary Errors

`integration tests cannot find the binary`

原因： 二进制文件未构建，或路径不正确。

解决方式：

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

Still Having Issues?

参见 Troubleshooting Workflow，了解系统化的排查方式。

Config Errors
Target Errors
Sync Errors
Git Errors
Install Errors
Update Errors
- git failed: Need to specify how to reconcile divergent branches
Audit Errors
- security audit failed — critical threats detected
- audit HIGH: Hidden zero-width Unicode characters detected
Upgrade Errors
- GitHub API rate limit exceeded
Skill Errors
Agent Errors
Binary Errors
- integration tests cannot find the binary
Still Having Issues?

Config Errors​

config not found: run 'skillshare init' first​

failed to load project config: ...​

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

Target Errors​

target add: path does not exist​

target path does not end with 'skills'​

target directory already exists with files​

Sync Errors​

deleting a symlinked target removed source files​

sync seems stuck or slow​

no space left on device / ENOSPC during sync​

Git Errors​

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

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

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

Audit Errors​

security audit failed — critical threats detected​

audit HIGH: Hidden zero-width Unicode characters detected​

Upgrade Errors​

GitHub API rate limit exceeded​

Skill Errors​

skill not appearing in AI CLI​

Antigravity does not load synced skills​

skill name 'X' is defined in multiple places​

Agent Errors​

Warning: 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 patterns not taking effect​

Binary Errors​

integration tests cannot find the binary​

Still Having Issues?​

Config Errors

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

`failed to load project config: ...`

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

Target Errors

`target add: path does not exist`

`target path does not end with 'skills'`

`target directory already exists with files`

Sync Errors

`deleting a symlinked target removed source files`

`sync seems stuck or slow`

`no space left on device` / `ENOSPC` during sync

Git Errors

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

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

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

Audit Errors

`security audit failed — critical threats detected`

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

Upgrade Errors

`GitHub API rate limit exceeded`

Skill Errors

`skill not appearing in AI CLI`

Antigravity does not load synced skills

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

Agent Errors

Warning: `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` patterns not taking effect

Binary Errors

`integration tests cannot find the binary`

Still Having Issues?