문제 해결
설치·스킬 수정·검증·업데이트·문서 빌드에서 막혔을 때 확인할 순서
처음 실패한 단계부터 확인하세요. 메시지를 숨기거나 모든 설정을 지우기보다, 경로·버전·실행 위치를 먼저 확인하면 문제 범위를 좁힐 수 있습니다.
증상별 빠른 확인#
| 증상 | 먼저 확인 | 다음 조치 |
|---|---|---|
command not found |
해당 도구의 --version |
도구 설치 및 새 터미널의 PATH 확인. Python 도구는 가상환경 활성화 |
Repository not found, HTTP 403 |
gh auth status, gh repo view coco-de/skills --json name |
로그인 계정과 저장소 접근 권한 확인. 공개 다운로드는 Git 인증 불필요 |
No module named yaml |
python3 -m pip show pyyaml |
가상환경에서 python3 -m pip install pyyaml |
externally-managed-environment |
현재 Python 환경 | 전역 설치 강제 옵션 대신 가상환경 생성·활성화 |
| 수정한 내용이 안 보임 | git diff와 AI가 실제 로드한 파일 경로 |
원본 저장 → 변환/재설치 또는 세션 전용 로드 → 새 세션 |
| 스킬이 자동 선택되지 않음 | 스킬 목록, description, 입력 요청 |
스킬 이름을 명시해 로드를 먼저 확인한 뒤 자연어 선택을 따로 검증 |
| 커맨드/에이전트가 없음 | 설치 방식이 npx skills인지 |
스킬만 설치한 것인지 확인. 필요한 플러그인/변환 설치 방식 선택 |
Not loaded·동일 이름 충돌 |
설치본·마켓플레이스·개발 경로 중복 | 사용할 원본/설치 경로 하나를 정하고 중복 등록 정리 |
| OpenCode 이름 충돌 | 오류에 나온 기존 파일과 설치 manifest | 개인 파일을 백업·이름 조정한 뒤 재설치. 사용자 폴더 전체 삭제 금지 |
| 업데이트가 “이미 최신”인데 파일이 없음 | 설치 스탬프와 실제 파일 | 백업 후 같은 선택 범위로 --update 없이 재설치 |
plugin.json 검증 실패 |
필드·버전·등록 목록 | 기여 규칙과 대조, 생성기 실행 후 재검사 |
| 검사가 통과했는데 결과가 틀림 | AI 실행 기록·입력별 결과 | 동작 시나리오로 재현하고 절차·예제 보완 |
Codex에서 등록이 사라질 때#
터미널 · 실제 사용하는 Codex 세션과 같은 환경에서:
codex plugin marketplace list --json
codex plugin list --json --marketplace cocode-skills --available
일반 터미널은 보통 ~/.codex, Orca는 계정별 CODEX_HOME을 사용합니다.
No plugin marketplaces in scope는 다른 설정 범위를 보고 있다는 신호일 수 있습니다.
Orca 계정/플러그인 설정과 설치 스크립트가 출력한 설정 범위를 대조하세요.
remove/add를 반복하거나 인증 토큰을 다시 발급하기 전에 확인할 항목입니다.
문서 사이트 빌드가 안 될 때#
| 증상 | 확인·해결 |
|---|---|
| Jaspr CLI와 라이브러리 버전 불일치 |
docs_site/pubspec.yaml
과
.github/workflows/deploy-docs.yml
의 핀 확인. 현재 CI CLI는 0.22.4
|
Unknown language 등 코드 블록 오류 |
루트에서 python3 generate_docs.py 실행. 지원되지 않는 언어의 블록을 HTML로 변환 |
| 생성 후 문서 파일 diff가 생김 | 지원되지 않는 코드 블록 변환인지 확인. 수동 문서에도 변환이 적용됨 |
Address already in use (5567/8080) |
아래 포트 확인. 내가 실행한 서버면 정상 종료 후 빌드, 다른 작업이면 별도 CI 환경에서 빌드 |
| 페이지가 404 | 경로에 해당하는 콘텐츠 존재 → 생성 → 빌드 결과 → 배포한 커밋 순으로 확인 |
| 배포가 성공했는데 옛 내용 | Deploy Docs 실행의 커밋과 원격 main/Auto Version 후속 배포를 대조하고 브라우저 새로고침 |
macOS 터미널 · 아무 폴더에서:
lsof -nP -iTCP:5567 -sTCP:LISTEN
lsof -nP -iTCP:8080 -sTCP:LISTEN
프로세스가 나오면 소유한 작업을 먼저 확인합니다. Jaspr CLI 0.22.4의 정적 생성 프록시는
5567을 사용하며 jaspr build --port 옵션은 제공하지 않습니다. 단순히 웹 미리보기 포트만 바꿔도
이 충돌이 해결된다고 가정하지 마세요. 빌드된 정적 파일을 보는 HTTP 서버는 별도의 빈 포트를 선택할 수 있습니다.
도움을 요청할 때 남길 것#
아래 양식에 값만 채워 GitHub 이슈에 남기거나 담당자에게 전달합니다.
설치 방식: (공개 스크립트 / Agent Skills / Codex / OpenCode / Orca / 기타)
운영체제와 AI 도구 버전:
실행 위치: (홈 / 저장소 루트 / docs_site 등)
실행 명령 또는 AI 입력:
처음 실패한 오류 메시지:
기대 결과 / 실제 결과:
변경한 파일과 Git 커밋:
지금까지 시도한 조치:설정 파일 전체보다 필요한 오류 부분만 공유하세요. 토큰·계정 정보·개인 경로는 가려도 됩니다.