첫 스킬 수정
저장소 원본 SKILL.md를 찾아 작은 변경을 만들고 새 세션에서 비교하는 실습
목표: cocode-compass가 추천 이유를 표로 보여주도록 작은 변경을 해 봅니다.
완료하면 수정한 원본 파일, 전후 차이, 검증 결과가 남습니다.
1단계 — 원본 작업 공간 준비#
준비물: 저장소 읽기 권한, Git, GitHub CLI, 편집기, Python 3.10 이상.
동작 확인 예제는 --plugin-dir을 지원하는 Claude Code를 사용합니다.
Orca에서의 로컬 연결 방법도 아래에 있습니다.
터미널 · 작업 폴더를 만들 상위 폴더에서:
gh repo clone coco-de/skills skills-learning
cd skills-learning
git switch -c docs/my-first-skill-edit
git status --short
정상 결과: plugins/와 scripts/가 보이고 git status --short
출력은 비어 있습니다.
이미 체크아웃했다면 새로 clone하지 말고 해당 폴더에서 상태를 확인하세요.
기존 수정이 있으면 먼저 저장·커밋하고 실습을 시작합니다. 여기서 만든 브랜치는 개인 실습용입니다.
2단계 — 검증용 Python 준비#
터미널 · 저장소 루트에서:
python3 --version
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install pyyaml
정상 결과: Python이 3.10 이상이고 PyYAML 설치가 성공합니다.
가상환경은 프로젝트용 도구 상자입니다. 새 터미널에서는 source .venv/bin/activate로 다시 켭니다.
externally-managed-environment 오류가 나면 전역 설치를 강제하지 말고 가상환경 활성화 여부를 확인하세요.
.venv/는 커밋 대상이 아닙니다.
3단계 — 고칠 파일 찾기#
편집기에서 다음 원본을 엽니다.
plugins/cc-compass/skills/cocode-compass/SKILL.md| 위치 | 역할 | 편집 여부 |
|---|---|---|
plugins/.../SKILL.md | 버전 관리하는 원본 | 여기서 수정 |
~/.claude/skills/, ~/.config/opencode/ 등 |
설치본 또는 변환본 | 재설치 때 바뀔 수 있으므로 원본 실습 위치로 쓰지 않음 |
docs_site/content/plugins/ | 웹 문서 생성 결과 | 생성기를 다시 실행하면 덮어씀 |
파일의 처음은 아래처럼 생겼습니다. 위아래 --- 사이가 frontmatter라는 설정 영역입니다.
---
name: cocode-compass
description: "코코드 스킬 저장소 전체의 도구 선택 나침반 — 워크플로우/런타임 도구/규칙·가이드/레퍼런스 4계층으로 저장소의 전체 플러그인을 라우팅합니다. 어떤 플러그인·커맨드·스킬을 써야 할지 모르는 경우, 작업 유형에 맞는 진입점을 고르는 작업에서 사용합니다."
---name: 스킬 식별자. 이번 실습에서는 이름을 바꾸지 않습니다.description: 언제 이 스킬을 선택할지 설명합니다. “전문가입니다”만 쓰기보다 사용할 상황을 적습니다.- 아래 Markdown 본문: AI가 따라야 할 절차, 예시, 결과 형식입니다.
자동 생성마커 사이의 표는 그 옆에 적힌 원본/생성기로 갱신합니다.
4단계 — 결과 형식 한 가지 바꾸기#
먼저 아래 5단계의 요청으로 변경 전 응답을 저장합니다.
그다음 편집기에서 SKILL.md의 맨 끝에 다음 내용을 추가하고 저장하세요.
기존 결정 트리와 자동 생성 표는 유지합니다.
## 추천 결과 형식
도구를 추천할 때는 다음 열을 가진 표로 응답합니다.
| 추천 도구 | 선택 이유 | 시작 전 준비물 |
|---|---|---|
준비물을 확인하지 못했다면 추측하지 말고 "확인 필요"라고 적습니다.터미널 · 저장소 루트에서:
git diff -- plugins/cc-compass/skills/cocode-compass/SKILL.md
정상 결과: 방금 추가한 부분만 +로 보입니다. 파일 전체가 바뀌면 줄바꿈/인코딩 변경을 확인하세요.
추가한 내용이 없다면 편집기의 저장 여부와 열린 파일의 경로를 확인합니다.
5단계 — 수정본을 새 세션에 로드#
터미널 · 저장소 루트에서:
claude --plugin-dir "$PWD/plugins/cc-compass"열린 AI 채팅에 입력:
cocode-compass 스킬을 사용해 코드 리뷰에 맞는 도구를 추천해줘.
사용한 SKILL.md 경로를 보여주고, 실제 리뷰나 파일 수정은 시작하지 마.성공 기준:
-
실행 기록에서 내 체크아웃의
plugins/cc-compass/skills/cocode-compass/SKILL.md가 로드됩니다. - 결과에
추천 도구 / 선택 이유 / 시작 전 준비물열이 있습니다. - 추천 도구가 원본 라우팅 표에 존재하고 선택 이유가 요청과 맞습니다.
- 확인하지 않은 준비물을 이미 설치되어 있다고 단정하지 않습니다.
파일 경로를 답변에 적는 것만으로는 충분하지 않습니다. 로드/읽기 기록도 확인합니다.
변경 전에도 우연히 표를 썼을 수 있으므로, 수정 파일 로드 + 내용 준수를 함께 봅니다.
--plugin-dir은 그 세션에만 적용됩니다. 수정을 반복하면 세션을 종료하고 같은 명령으로 새로 여세요.
Orca 사용자는 설정 → 플러그인 → 개발 → 경로 추가에 이 저장소 루트를 등록한 뒤 새 세션에서 같은 요청을 합니다. OpenCode 변환 검사는 다음 검증 단계에서 실행하며, 실제 설치본 반영은 도구별 갱신 절차를 따릅니다.
6단계 — 저장하기 전에 검사#
터미널 · 저장소 루트, 가상환경 활성화 상태에서:
python3 validate_plugins.py
python3 scripts/check_skill_metadata.py
python3 scripts/check_skill_drift.py
git diff --check정상 결과: 각 명령이 종료 코드 0으로 끝납니다. 마지막 명령은 문제가 없으면 아무것도 출력하지 않습니다. 검사 통과는 문법/정해진 패턴의 통과이며 5단계 동작 확인을 대신하지 않습니다. 실패 종류와 추가 검사는 검증하기에 있습니다.
실습 내용을 되돌리려면#
아래 명령은 아직 커밋하지 않은 해당 파일 수정을 지웁니다. 남겨둘 변경이 있으면 편집기로 실습에서 추가한 부분만 지우세요. 파일 전체를 되돌리기로 결정했다면 먼저 diff를 확인합니다.
git diff -- plugins/cc-compass/skills/cocode-compass/SKILL.md
git restore -- plugins/cc-compass/skills/cocode-compass/SKILL.md
git status --short커밋하거나 공유한 변경을 복구하는 방법은 업그레이드와 복구에 있습니다.
완료 체크: 원본 경로 확인 → 한 가지 변경 → 새 세션 비교 → 자동 검사.
다음 단계: 검증하기 — 오류 읽기와 변경 유형별 검사 →