업그레이드와 복구

목표: 최신 스킬을 받아 적용하고, 내가 작성하는 스킬도 근거와 검증을 갖춰 개선합니다.

예를 들어 claude update는 Claude CLI를 갱신합니다. 이 저장소의 스킬을 최신으로 받는 명령이 아닙니다.

1. 시작하기에서 내가 쓴 설치 방식을 확인합니다.
2. 설치 목록, 사용 중인 파일 경로, 현재 버전/커밋을 기록합니다.
3. 직접 수정한 설치본이 있다면 원본 작업 브랜치에 옮기거나 별도 폴더에 백업합니다.

터미널 · 아무 폴더에서, 공개 설치기의 cc-compass를 백업하는 예:

backup="$HOME/cocode-skills-backups/$(date +%Y%m%d-%H%M%S)"
mkdir -p "$backup"
cp -R "$HOME/.claude/skills/cc-compass" "$backup/"

정상 결과: $backup/cc-compass/에 SKILL.md를 포함한 복사본이 있습니다. 원본 폴더가 없다는 오류면 설치 경로부터 다시 확인하세요. 다른 플러그인을 고쳤다면 그것도 백업합니다. backup 변수는 같은 터미널에서 복구할 때 사용하며, 새 터미널에서는 실제 백업 경로로 다시 지정합니다.

저장소를 수정 중이면 루트에서 git status --short와 git diff를 확인합니다. 미완성 변경 위에 무작정 git pull이나 재설치를 하지 않습니다.

터미널 · 아무 폴더에서: 이전과 같은 --plugin/--preset/--dir 범위를 지정합니다.

curl -fsSL https://skills.cocode.im/install.sh | bash -s -- --update --plugin cc-compass

정상 결과: 업데이트 완료와 변경 내역, 또는 같은 버전이라는 메시지가 나옵니다. /reload-plugins 또는 재시작 후 실제 로드 경로와 새 내용을 확인하세요.

curl -fsSL https://skills.cocode.im/install.sh | bash -s -- --plugin cc-compass

터미널 · 저장소 루트에서: 깨끗한 main을 기준으로 합니다.

git status --short
git switch main
git pull --ff-only origin main
bash install.sh

변경이 남아 있거나 fast-forward가 불가능하면 원인을 해결한 뒤 진행합니다. 이 설치는 현재 원본의 전체 플러그인을 동기화합니다. 한 스킬의 미완성 수정을 확인하려면 세션 전용 로드를 사용하세요.

Agent Skills#

터미널 · 설치할 프로젝트 폴더에서(전역 설치는 아무 폴더):

npx skills --version
npx skills --help
npx skills list --global
npx skills update cocode-compass --global
npx skills list --global

현재 CLI가 추적하는 해당 스킬을 갱신합니다. 프로젝트 설치는 update의 --global 대신 --project를 사용하고 목록에서는 --global을 뺍니다. CLI 버전별 명령은 먼저 도움말로 확인합니다. 로컬 경로나 추적되지 않는 설치가 갱신되지 않으면 원본을 최신화하고 처음의 skills add 명령을 다시 사용합니다. 업데이트된 목록과 새 AI 세션의 로드 기록을 함께 확인합니다.

Codex#

터미널 · 저장소 루트에서:

bash scripts/install-codex.sh
codex plugin marketplace list --json
codex plugin list --json --marketplace cocode-skills --available

스크립트는 기존 마켓플레이스를 갱신하고 전체 플러그인을 설치합니다. 새 Codex 세션에서 확인합니다. Orca 계정별 CODEX_HOME과 일반 터미널의 설치는 다를 수 있습니다. 등록이 되돌아가면 반복 설치보다 설정 범위 점검을 먼저 합니다.

OpenCode#

터미널 · 최신화한 저장소 루트, Python 가상환경 활성화 상태에서:

python3 scripts/convert_to_opencode.py --check
bash scripts/install-opencode.sh

정상 결과: 변환 검사와 설치 완료. OpenCode를 재시작하고 변경된 내용이 읽히는지 확인합니다. 설치 전에 opencode.json과 직접 편집한 파일을 백업하세요. 설정 파일은 인증 정보를 포함할 수 있으므로 로컬에 보관합니다. 현재 기본 설정은 유지하지만 MCP 항목은 병합되며, 도구별 추가 준비는 MCP_SETUP.md에 있습니다.

OpenClaude 터미널 · 등록했던 저장소 루트에서:

openclaude plugin marketplace update cocode-skills
openclaude plugin update cc-compass@cocode-skills --scope user
openclaude plugin list

설치 당시 다른 범위를 썼다면 그 범위로 맞춥니다. 옵션이 다르면 해당 명령의 --help로 확인합니다. Desktop의 예시는 curl -fsSL https://skills.cocode.im/install.sh | bash -s -- --desktop --plugin cc-compass입니다. ZIP 다운로드 성공과 앱 업로드 성공을 각각 확인하세요.

웹 문서만 바뀌어도 전체 릴리스 버전이 오를 수 있습니다. 개별 플러그인 버전이 전부 같아야 하는 것은 아닙니다. 숫자만 보지 말고 변경된 문장/파일이 실제 로드되는지 확인하세요.

첫 실습은 결과 형식 변경이었습니다. 이제 실패 사례를 근거로 규칙을 개선해 봅니다.

상황: “설치 여부를 모르겠다”고 했는데 추천 응답이 필요한 MCP가 이미 준비됐다고 가정합니다.

1. 실패한 입력과 응답, 사용한 파일/도구 버전을 기록합니다.
2. 관련 공식 문서·실제 스크립트에서 필요한 준비물을 확인하고 출처와 확인일을 기록합니다.
3. 원본의 추천 결과 형식 아래에 다음처럼 관찰 가능한 행동을 추가합니다.

준비물이 미확인인 경우, 이를 확인할 명령 또는 설정 위치를 한 가지 제시합니다.
확인 결과가 없으면 실행 준비 완료라고 말하지 않습니다.

4. 검증 시나리오의 명시적 사용·자연어·관련 없는 요청·미확인 준비물을 모두 다시 확인합니다.
5. 개선 전후의 결과를 PR에 적고 기여와 배포로 넘깁니다.

API 업그레이드도 같은 순서입니다. 구/신 버전의 실제 시그니처와 실행 예제를 대조하고, 참조 문서·템플릿·설치 전제를 함께 갱신합니다. “최신 API를 써라”라는 문장만 추가하면 검증할 수 없습니다.

문제가 생겼을 때 복구#

위에서 만든 backup 변수가 유지된 같은 터미널에서, Code 플러그인 하나 복원:

mv "$HOME/.claude/skills/cc-compass" "$backup/cc-compass.failed"
cp -R "$backup/cc-compass" "$HOME/.claude/skills/cc-compass"

복원 후 /reload-plugins 또는 재시작합니다. 설치 대상 전체의 버전 스탬프는 이 한 플러그인의 복구 상태를 표현하지 못하므로, 버전 숫자만으로 정상 여부를 판정하지 않습니다. 공개 설치기는 구버전 지정 옵션이 없습니다. 이전 버전은 백업 또는 검증된 Git ref의 원본으로 복구합니다.

제거가 필요한 경우#

• 공개 설치기의 --uninstall은 대상 폴더의 cc-* 전체를 제거합니다. --plugin 하나만 삭제하는 의미가 아닙니다.
• OpenCode의 bash scripts/install-opencode.sh --uninstall은 설치 manifest가 소유한 항목을 제거하고 opencode.json은 유지합니다. 남은 MCP 설정은 별도로 점검합니다.
• Desktop/Web 업로드는 앱에서 관리합니다. 스크립트 제거가 업로드를 취소하지 않습니다.

다음 단계: 기여와 배포 — 변경 사항을 팀에 전달하기 →