Common Errors

오류 메시지와 그 해결 방법입니다.

Config Errors

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

Cause: Config 파일이 존재하지 않습니다.

Solution:

skillshare init

Custom 경로를 원한다면 --source를 추가하세요.

skillshare init --source ~/my-skills

`failed to load project config: ...`

Cause: .skillshare/config.yaml이 존재하지만 파싱할 수 없습니다 (잘못된 YAML, 잘못된 타입 등). 변경을 가하는 명령어(uninstall, new, enable/disable, check)는 이 상태에서 진행을 거부합니다. custom sources 설정이 있을 때 기본 .skillshare/skills/ 디렉터리를 실수로 건드리지 않기 위해서입니다.

Solution: YAML을 수정한 뒤 명령어를 다시 실행하세요. 흔한 문제:

# WRONG — targets는 리스트여야 함
targets: {}

# RIGHT
targets: []

# WRONG — skills는 리스트여야 함
skills: my-skill

# RIGHT
skills:
  - name: my-skill
    source: github.com/org/my-skill

아무 YAML linter로든 파일을 검증하거나, 백업이 있다면 .skillshare/backups/에서 임시로 복원하세요.

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

Cause: sources.skills가 어떤 Target의 skill 경로와 동일한 디렉터리로 해석되거나 (또는 한쪽이 다른 쪽을 포함) 합니다. 예를 들어, claude Target과 함께 sources.skills: .claude/skills를 설정하면 — 둘 다 .claude/skills/를 가리킵니다. 이 안전장치가 없다면, sync --force가 Source를 Target 디렉터리로 취급해 그 내용을 삭제하게 됩니다.

Solution: 어떤 Target과도 겹치지 않는 Source 경로를 선택하세요. 흔히 사용하는 안전한 선택지:

# 프로젝트 문서와 함께 배치
sources:
  skills: ./docs/skills

# .skillshare/ 아래 유지 (기본값 — sources 키를 완전히 제거)

같은 검사가 agent Target 경로에 대해 sources.agents에도 적용됩니다.

Target Errors

`target add: path does not exist`

Cause: skill 디렉터리가 아직 존재하지 않습니다.

Solution:

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

`target path does not end with 'skills'`

Cause: 경로가 관례를 따르지 않는다는 경고입니다.

Solution: 이것은 오류가 아니라 경고입니다. 경로가 의도한 것이라면 그대로 진행하거나, 수정하세요.

skillshare target add myapp ~/.myapp/skills  # 권장

`target directory already exists with files`

Cause: Target에 덮어써질 수 있는 기존 파일이 있습니다.

Solution:

skillshare backup
skillshare sync

Sync Errors

`deleting a symlinked target removed source files`

Cause: symlink 모드에서 Target에 rm -rf를 실행했습니다.

Solution:

# git이 초기화되어 있다면
cd ~/.config/skillshare/skills
git checkout -- .

# 또는 백업에서 복원
skillshare restore <target>

Prevention: 수동 삭제 대신 skillshare target remove를 사용하세요.

`sync seems stuck or slow`

Cause: skill 디렉터리에 큰 파일이 있습니다.

Solution: ignore 패턴을 추가하세요.

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

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

Cause: 무언가가 볼륨을 채우고 있습니다. 먼저 백업 디렉터리를, 그다음 Source를 확인하세요.

Solution:

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은 복사합니다. 런타임 캐시, 모델 가중치, 브라우저 프로필은 skill 트리 밖으로 옮기거나 ignore:로 제외하세요.

Backup 범위가 .gitignore 및 ignore:와 어떻게 다른지는 Backups & Disk Space를 참고하세요.

Git Errors

`Could not read from remote repository`

Cause: SSH 키가 설정되지 않았거나, remote URL이 잘못되었습니다.

Solution:

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

Cause: Remote repository가 로컬보다 앞서 있습니다.

Solution:

skillshare pull   # 먼저 remote 변경 사항 받기
skillshare push   # 이제 push가 동작함

`pull: local has uncommitted changes`

Cause: 아직 push되지 않은 로컬 변경 사항이 있습니다.

Solution:

# 옵션 1: 먼저 변경 사항 push
skillshare push -m "Local changes"
skillshare pull

# 옵션 2: 로컬 변경 사항 폐기
cd ~/.config/skillshare/skills
git checkout -- .
skillshare pull

`merge conflicts`

Cause: 동일한 파일이 여러 머신에서 수정되었습니다.

Solution:

cd ~/.config/skillshare/skills
git status                    # 충돌한 파일 확인
# 충돌을 해결하기 위해 파일 수정
git add .
git commit -m "Resolve conflicts"
skillshare sync

`Git identity not configured`

Cause: git config에 user.name / user.email이 없습니다. skillshare는 init이 완료될 수 있도록 로컬 폴백(skillshare@local)을 사용하지만, 본인의 것을 설정해야 합니다.

Solution:

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

`Git root mismatch`

Cause: config.yaml의 git_root가 git repo가 없는 scope 디렉터리를 가리키는데, 다른 scope 디렉터리에는 repo가 있습니다. 이는 repository를 옮기지 않고 git_root를 변경할 때 발생합니다 — scope 전환은 "다른 디렉터리를 버전 관리하기 시작한다"는 의미이지, "기존 히스토리를 옮긴다"는 의미가 아닙니다. git_root를 참고하세요.

Solution: 오류 메시지가 출력하는 세 가지 옵션 중 하나를 선택하세요.

# 설정된 scope에 새 repo 시작 (히스토리 없음)
skillshare init --git-root <scope>

# 히스토리를 유지하며 기존 repo 이동
mv <old-scope>/.git <new-scope>/.git

# 또는 기존 repo를 계속 사용: config.yaml에서 git_root를 되돌리기
#   git_root: <scope-that-has-the-repo>

`tracked repository clone is missing`

Cause: tracked repo가 .metadata.json에 선언되어 있지만, 클론 디렉터리(예: skills/_team-skills/)가 로컬에 없습니다. 이는 tracked repo 디렉터리가 관리형 .gitignore 블록에 의도적으로 포함되어 있기 때문에, 새 머신에서 skillshare source repo를 클론한 뒤 자주 발생합니다.

Solution: 메타데이터로부터 누락된 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`

Cause: git_root: root에서, 하위 디렉터리(예: skills/_org/ 아래의 tracked skill repo)가 자체 .git을 가지고 있습니다. Git은 이를 빈 submodule로 업로드해 조용히 파일을 누락시키므로, 각 중첩 repo가 비활성화될 때까지 commit/push가 중단됩니다.

Solution:

# 보고된 각 중첩 repo 비활성화 (되돌릴 수 있음 — 이름을 다시 바꾸면 재활성화됨)
mv ~/.config/skillshare/<dir>/.git ~/.config/skillshare/<dir>/.git.disabled

또는 웹 UI의 Git Sync 페이지에서 원클릭으로 비활성화하세요. skillshare는 또한 머신별 경로를 담고 있는 config.yaml을 root-scope repo에서 자동으로 제외합니다.

`Invalid git_root`

Cause: config.yaml의 git_root가 인식되지 않는 값(예: 오타)으로 설정되어 있습니다.

Solution: skills, agents, extras, root 중 하나를 사용하거나, 비워 두세요 (기본값은 skills).

Install Errors

`skill already exists`

Cause: 동일한 이름의 skill이 이미 설치되어 있습니다.

Solution:

# 기존 skill 업데이트
skillshare install <source> --update

# 또는 강제로 덮어쓰기
skillshare install <source> --force

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

Cause: repository URL이 잘못되었거나, repo가 존재하지 않거나, 인증이 누락되었습니다.

이제 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

Solution: 아래의 인증 옵션을 참고하세요.

`Authentication failed` / `Access denied`

Cause: HTTPS 자격 증명이 없거나, 만료되었거나, 잘못된 토큰 유형입니다.

Solution — Option 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")

Solution — Option 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

Solution — Option 3: Git credential helper:

gh auth login          # GitHub CLI
git credential approve # 또는 플랫폼별 credential manager

Required token permissions:

Platform	Token type	Scopes / Permissions
GitHub	Personal Access Token (`ghp_`)	`repo` (private repo), 없음 (public)
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 Token(glft-)은 git 접근 권한이 없습니다.

Environment Variables와 Private Repositories를 참고하세요.

`SSL certificate problem` / `certificate verification failed`

Cause: Git 서버가 자체 서명 인증서 또는 시스템이 신뢰하지 않는 내부 CA를 사용합니다. self-hosted GitLab, Gitea, Gogs 인스턴스에서 흔합니다.

Solution — Option 1: Custom CA bundle (권장):

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

Solution — Option 2: 대신 SSH 사용 (SSL을 완전히 회피):

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

Solution — Option 3: SSL 검증 비활성화 (권장하지 않음):

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

경고

SSL 검증 비활성화는 보안 위험입니다. Option 1 또는 2를 사용하세요.

Environment Variables — Git SSL / TLS를 참고하세요.

`invalid skill: SKILL.md not found`

Cause: Source에 유효한 SKILL.md 파일이 없습니다.

Solution: Source 경로가 올바르며 skill 디렉터리를 가리키는지 확인하세요.

Update Errors

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

Cause: remote 브랜치가 로컬 tracked 복사본과 갈라졌습니다.

Solution:

# 강제 업데이트 (로컬을 remote로 대체)
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`

Cause: skill이 중요 보안 위협(prompt injection, 데이터 유출, 자격 증명 접근)과 일치하는 패턴을 포함하고 있습니다.

Solution:

# 발견 항목 검토
skillshare audit <skill-name>

# Source를 신뢰한다면, 강제 설치
skillshare install <source> --force

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

Cause: skill에 보이지 않는 유니코드 문자가 포함되어 있으며, 이는 복사-붙여넣기 흔적이거나 의도적인 난독화일 수 있습니다.

Solution: 숨겨진 문자를 표시하는 에디터에서 파일을 열어 제거하거나, Source를 신뢰한다면 강제 설치하세요.

Upgrade Errors

`GitHub API rate limit exceeded`

Cause: 인증되지 않은 API 요청이 너무 많습니다.

Solution:

# 옵션 1: GitHub 토큰 설정 (권장)
export GITHUB_TOKEN=ghp_your_token_here
skillshare upgrade

# 옵션 2: 강제 업그레이드
skillshare upgrade --cli --force

다음에서 토큰을 생성하세요: https://github.com/settings/tokens (public repo에는 scope가 필요 없음)

Skill Errors

`skill not appearing in AI CLI`

Causes:

skill이 동기화되지 않음
잘못된 SKILL.md 형식
AI CLI 캐싱

Solutions:

# 1. 동기화
skillshare sync

# 2. 형식 확인
skillshare doctor

# 3. AI CLI 재시작

Antigravity does not load synced skills

Cause: Antigravity 앱의 skill scanner는 실제 디렉터리만 탐색합니다 — symlink는 건너뜁니다. skillshare의 기본 merge 모드는 skill마다 하나의 symlink를 생성하므로(Windows에서는 NTFS junction), 어느 것도 인식되지 않습니다. Windows에서는 Incorrect function 오류로 나타나며, macOS와 Linux에서는 skill이 조용히 사라진 것처럼 보입니다.

이는 skillshare의 버그가 아니라 Antigravity 측의 제약입니다. antigravity target(앱, ~/.gemini/config/skills)에만 해당하며, 독립 실행형 agy CLI는 ~/.gemini/antigravity-cli/skills를 읽는 별도의 antigravity-cli target입니다. 두 가지 우회 방법이 있습니다.

Option 1 — Target을 copy 모드로 전환

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

symlink 대신 실제 디렉터리가 작성됩니다. Trade-off: Source skill을 편집한 뒤 skillshare sync를 다시 실행해야 합니다.

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

Cause: 여러 skill이 동일한 name 필드를 가지고 있으며 같은 Target에 도달합니다.

Solution: SKILL.md에서 하나의 이름을 바꾸거나, include/exclude 필터로 서로 다른 Target으로 라우팅하세요.

# 옵션 1: SKILL.md에서 네임스페이스 지정
name: team-a-skill-name

# 옵션 2: 필터로 라우팅 (global config)
targets:
  codex:
    path: ~/.codex/skills
    include: [_team-a__*]
  claude:
    path: ~/.claude/skills
    include: [_team-b__*]

# 옵션 2: 필터로 라우팅 (project config)
targets:
  - name: claude
    exclude: [codex-*]
  - name: codex
    include: [codex-*]

팁

필터가 이미 중복 항목을 분리하고 있다면, sync는 경고 대신 정보 메시지를 표시합니다 — 별도 조치가 필요 없습니다. 전체 문법은 Target Filters를 참고하세요.

Agent Errors

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

Cause: skillshare sync (또는 skillshare sync agents)를 실행했는데, 설정된 Target 중 하나 이상이 agents 디렉터리를 정의하지 않았습니다. 내장 agent 경로를 가진 것은 Claude, Cursor, Augment, OpenCode뿐이며, 다른 Target은 조용히 건너뜁니다.

Solutions:

해당 Target에 agent가 필요 없다면 경고를 무시하세요.
config.yaml의 Target에 agents: 하위 키를 추가해 agent sync를 활성화하세요.

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

그런 다음 skillshare sync agents를 다시 실행하세요.

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

Cause: agents 필터 없이 skillshare backup -p (또는 skillshare backup -p <target>)를 실행했습니다. Project mode에서는 agent 백업만 지원됩니다 — skill 백업은 global 전용입니다.

Solution: agents 위치 인자를 추가하거나 --all을 사용하세요.

skillshare backup -p agents          # Project 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`

Cause: agent 파일 이름 또는 name: frontmatter 필드에 허용되지 않은 문자가 포함되어 있습니다.

Solution: Agent 이름은 a-z, 0-9, _, -, .만 사용해야 합니다. 파일 이름을 바꾸고(name: 필드도 함께 업데이트해) 동일한 정식 이름을 공유하도록 하세요.

`.agentignore` patterns not taking effect

Causes:

파일이 잘못된 위치에 있습니다. agents source root에 있어야 합니다: ~/.config/skillshare/agents/.agentignore (global) 또는 .skillshare/agents/.agentignore (project).
패턴이 예상과 다른 세그먼트와 일치합니다 — 이 파일은 gitignore 문법을 사용합니다.

Solution: skillshare doctor로 파일 경로를 확인하고 패턴을 다시 점검하세요. Agent는 (.md를 뺀) basename으로 매칭되므로, draft-*는 draft-experiment.md와 일치합니다. CLI가 항목을 대신 작성하게 하려면 skillshare disable <agent> --kind agent를 사용하세요.

Binary Errors

`integration tests cannot find the binary`

Cause: 바이너리가 빌드되지 않았거나 경로가 잘못되었습니다.

Solution:

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?