검증하기
스킬 수정 뒤 실행할 검사, 오류 읽는 법, 실제 동작 확인과 PR 전 체크리스트
목표: “파일 형식이 맞다”와 “AI가 의도대로 동작한다”를 각각 확인합니다. 첫 스킬 수정을 끝내고, 저장소 루트에서 가상환경을 켠 상태로 시작하세요.
먼저 수정 범위 확인#
터미널 · 저장소 루트에서:
git status --short
git diff --stat
git diff --check
정상 결과: 내가 고친 파일만 표시되고 마지막 명령은 출력 없이 끝납니다.
.venv/나 빌드 폴더가 보이면 커밋하기 전에 제외 설정을 확인하세요.
첫 수정에 필요한 기본 검사#
아래 명령을 한 줄씩 실행하고 결과를 확인합니다.
python3 validate_plugins.py
python3 scripts/check_skill_metadata.py
python3 scripts/check_skill_drift.py
python3 scripts/convert_to_opencode.py --check| 검사 | 무엇을 보나요? | 정상 결과 |
|---|---|---|
validate_plugins.py |
플러그인 구조·등록·이름 중복·메타데이터 형식 | 요약의 오류 0, 모든 검증 통과 |
check_skill_metadata.py | 스킬 선택 조건, 커맨드 설명/호출명, 경로·언어 규약 | 신규 위반 0 |
check_skill_drift.py |
금지된 구 API·깨진 호출 등 알려진 낡은 패턴 | error 0; warn은 별도 검토 |
convert_to_opencode.py --check |
임시 변환 후 이름 충돌·변환된 참조 경로 | 변환 수 출력, 종료 코드 0 |
종료 코드는 명령이 성공했는지 셸에 돌려주는 숫자입니다. 0은 성공, 그 외는 실패입니다.
각 명령 바로 다음에 echo $?를 입력하면 확인할 수 있습니다. 다른 명령을 먼저 실행하면 그 명령의 코드로 바뀝니다.
--check 변환은 임시 폴더를 정리하며 실제 OpenCode 설정에는 설치하지 않습니다.
오류 메시지를 읽는 순서#
예를 들어 검사 결과에 plugins/.../SKILL.md, L3, 설명 위반이 나온다면:
- 파일 경로를 편집기에서 엽니다. 설치된 사본이 아니라 검사 대상 원본입니다.
L3는 3번째 줄입니다. 그 줄의description과 해당 규칙을 확인합니다.- 문제를 한 가지 수정합니다. 스킬 설명에는 “어떤 작업에서 사용하는가”를 구체적으로 적습니다.
- 실패한 검사를 다시 실행하고, 모두 통과하면 기본 검사 묶음을 다시 확인합니다.
| 실패 종류 | 수정할 것 |
|---|---|
| 이름 중복 | 기존 이름을 찾고 고유한 도메인 접두사 사용. 단순 복사로 새 스킬을 늘리지 않기 |
| plugin.json 형식 | name, version, description만 사용. 디렉토리 목록 필드를 넣지 않기 |
| 스킬 선택 조건 부족 | 무엇을 돕는지 + 언제 사용할지를 description에 명시 |
| 커맨드 설명 부족 | 동작 + 산출물/판정 + 선택 기준 명시 |
| 경로/호출명 불일치 | 실제 파일·현재 커맨드 이름과 대조하고 참조도 함께 변경 |
| 버전·카탈로그 불일치 | 원본 메타데이터와 생성물 확인 후 아래 해당 생성기 사용 |
| 새로 컴파일되지 않는 예제 |
예제를 현행 CoUI 로 고친다. 컴파일 대상이 아니면(조각 · 다른 패키지 코드) 블록 첫 줄에
// skill-example: no-compile — <사유>
. 일부러 틀린 예는
// ❌
주석 뒤에
|
기존 경고나 baseline은 “아무 문제가 없다”는 뜻이 아닙니다.
기존 부채와 새 오류를 구분해 기록하세요. 검사 통과를 위해 --write-baseline으로
새 오류를 허용 목록에 넣는 것은 해결이 아닙니다.
바꾼 내용에 따른 추가 작업#
명령·진입점·에이전트 스킬 참조를 바꿨다면 python3 scripts/plugin_catalog.py --check도 실행합니다.
정식명과 OpenCode 설치 이름이 다를 수 있으며 name을 별도 실행 alias로 추론하지 않습니다.
검사 명령은 상태를 확인합니다. 생성 명령은 파일을 바꾸므로 실행 뒤 git diff를 읽습니다.
| 변경 내용 | 생성/갱신 (필요할 때만) | 확인 |
|---|---|---|
| 스킬/커맨드/에이전트 추가·삭제·설명 변경 | python3 scripts/update_plugin_readmes.py --write |
같은 명령의 --check |
| 개수 또는 인덱스 정보 변경 |
python3 scripts/update_readme_stats.py --write
,
python3 scripts/generate_skill_index.py
|
각 명령의 --check |
| 분류·프리셋·네임스페이스 변경 | taxonomy.json 수정 → python3 scripts/sync_taxonomy.py --write |
python3 scripts/sync_taxonomy.py --check |
| 플러그인 메타데이터/버전 변경 | 원본 수정 → python3 scripts/sync_codex_plugins.py --write |
python3 scripts/sync_codex_plugins.py |
| 웹 안내·플러그인 문서 변경 | python3 generate_docs.py | 문서 생성 테스트와 사이트 빌드 |
| CoUI 를 쓰는 Dart 예제(cc-flutter · cc-coui · cc-blueprint) | 텍스트 역할 표는 python3 scripts/generate_coui_typography.py --coui <CoUI 체크아웃> |
PR CI 의 예제 컴파일. 로컬은
python3 scripts/compile_skill_examples.py --coui <CoUI 체크아웃>
— 체크아웃은
coui.version.json
의
coui_skills_basis
태그
|
generate_docs.py는 플러그인 웹 페이지를 다시 만들고, 수동 작성 페이지의 지원되지 않는
코드 블록도 HTML로 바꿀 수 있습니다. 실행 후 diff를 확인하세요.
모든 생성기를 매번 실행할 필요는 없지만, PR 전에 아래 최신성 검사는 통과해야 합니다.
python3 scripts/sync_codex_plugins.py
python3 scripts/sync_taxonomy.py --check
python3 scripts/update_readme_stats.py --check
python3 scripts/generate_skill_index.py --check
python3 scripts/update_plugin_readmes.py --check정상 결과: 모두 최신/일치, 종료 코드 0입니다. 생성 뒤에도 불일치하면 생성물 자체를 편집하기보다 어떤 원본을 읽는지 기여 가이드에서 확인하세요.
AI 동작은 별도로 확인#
정적 검사는 문장의 의미와 실제 업무 결과를 보장하지 않습니다. 같은 도구·모델·입력으로 변경 전후를 비교하고, 매번 새 세션에서 수정본 로드를 확인합니다.
| 시나리오 | 첫 수정 실습의 입력 예 | 관찰할 결과 |
|---|---|---|
| 명시적 사용 | “cocode-compass 스킬로 코드 리뷰 도구를 추천해줘” | 원본 로드, 추천 표, 유효한 진입점 |
| 자연어 선택 | “스킬이 많아서 코드 리뷰를 어디서 시작할지 모르겠어” | 도구가 스킬을 선택했는지 실행 기록 확인 |
| 관련 없는 요청 | “2 + 2는?” | 불필요한 도구 추천이나 작업 실행을 하지 않음 |
| 준비물 미확인 | “MCP 설치 여부는 모르는데 화면 검증 도구를 골라줘” | 확인 필요를 표시하고 설치됐다고 단정하지 않음 |
한 번의 그럴듯한 응답 대신 여러 입력에서 확인합니다. 자연어 선택 결과가 다르면 설명/트리거를 좁혀 고치고, 도구가 제공하는 실행 기록을 첨부하세요.
기록할 항목: 스킬 경로·Git 커밋·AI 도구/모델·입력·기대 결과·실제 결과·통과 여부. 토큰이나 개인정보가 들어간 로그는 공유 전에 제거합니다.
웹 문서도 바꿨다면#
터미널 · 저장소 루트에서:
python3 generate_docs.py
python3 -m unittest discover -s scripts -p 'test_*.py' -v
python3 scripts/check_docs.py
정상 결과: 문서 생성 완료와 테스트 OK. 이후
문서 사이트 빌드 안내를 따라
Jaspr 빌드와 브라우저 확인을 합니다. 빌드 성공만으로 링크나 코드 복사가 정상이라는 뜻은 아닙니다.
빌드와 패키징 뒤 루트에서 python3 scripts/check_docs.py --site-dir docs_site/build/jaspr를 실행하면
실제 HTML의 내부 링크·앵커·정적 자산까지 확인합니다. 정상 결과는 Documentation check passed입니다.
PR 전 완료 체크#
- 기본 검사와 변경 유형별 최신성 검사 통과
- 기대 동작·관련 없는 입력·실패 상황을 새 세션에서 확인
- 예제의 파일·명령·링크가 실제 존재함
- 자동 생성 결과를 확인하고 의도한 파일만 커밋
- 웹 변경이면 빌드·좁은 화면·코드 블록·페이지 이동 확인
다음 단계: 업그레이드와 복구 → · 오류별 문제 해결 →