AI 스킬 문서를 한곳에서 관리하고 AI가 찾기 쉽게 쓰기

## 원본 파일만 고치고 나머지는 생성 도구로 다시 만들기 스킬의 정본 문서를 식별하고, 생성된 통합 결과물, 매니페스트, 플랫폼별 변환 결과를 파생 산출물로 취급한다. 정본과 그 참조를 편집한 다음 리포지토리의 생성기로 파생물을 다시 생성한다. CI가 관리하는 결과물을 절대 직접 편집하지 않는다. 메모리나 임시 영역에서 다시 생성하고, 커밋된 파생물이 정본과 달라지면 실패하는 검사 모드를 지속적 통합에 유지한다. 같은 스킬을 여러 플랫폼에 배포할 때는 별도 분기본을 유지하지 말고 콘텐츠를 공유한다. 콘텐츠, 메타데이터, 버전 값을 어느 파일이 관리하는지 기록하여 기여자가 서로 경쟁하는 정본을 만들지 않게 한다. 설치 방법과 최종 사용자용 사용법은 기여자 지침 밖에 둔다. 기여자 문서는 제품 가이드를 중복하지 않으면서 유지관리, 검증, 테스트, 릴리스 동작을 설명해야 한다. ## 선택에 필요한 내용은 입구 문서에, 자세한 절차는 참고 파일에 두기 주요 스킬 문서를 검색 진입점으로 사용하고, 상세 참조 자료는 필요할 때만 불러온다. 콘텐츠는 다음과 같이 배치한다. - 의사결정 프레임워크와 자주 사용하는 패턴은 진입 문서에 둔다. - 상세 가이드, 템플릿, 확장 예시는 참조 파일에 둔다. - 기준 시나리오와 판단 근거 기록은 테스트 문서에 둔다. - 설치 방법과 사용법은 사용자 대상 문서에 둔다. - 기여자 절차의 세부 내용은 기여 가이드에 둔다. 진입 문서와 인접한 참조 자료 사이에는 안정적인 상대 링크를 사용한다. 하위 섹션을 재구성하더라도 라우팅 표에서 사용하는 최상위 참조 앵커는 유지한다. 하나의 배치 기준을 적용한다. 어떤 경로를 선택할지 결정하는 항목은 진입점 가까이에 두고, 이미 선택한 경로를 깊이 있게 실행하는 방법을 설명하는 항목은 참조 자료로 옮긴다. ## 판단 표를 먼저 두고 짧고 직접적인 지시로 쓰기 가이드를 처음부터 끝까지 읽는 독자가 아니라 의도를 분류하고, 분기를 선택하고, 실행하는 에이전트에 맞춰 최적화한다. 여러 접근 방식이 모두 유효할 때는 실행 지침보다 앞에 간결한 의사결정 표를 둔다. 각 섹션은 다음 순서로 구성한다. 1. 의사결정 표 2. 기본 절차 3. 대안 4. 간결한 규칙과 주의점 명령형을 사용하고 글머리표 하나에는 하나의 사실만 쓴다. “고려해야 한다”, “참고한다”, “유념한다” 같은 조언용 서두를 직접적인 행동으로 바꾼다. 분명하지 않은 구분에는 짧은 긍정 규칙과 부정 규칙을 우선한다. 모든 표, 예시, 코드 블록은 아직 언급하지 않은 사실을 추가해야 한다. 절차만으로 지침이 이미 전달된다면 변경 전후 차이, 반복되는 근거, 교육용 여담, 완전성을 갖추기 위해서만 넣은 예시는 제외한다. 근거 설명은 도입부의 한 문장 이내로 제한한다. 하위 섹션마다 토큰 목표를 설정하고, 이를 초과하는 섹션은 의사결정 기준, 필수 조치, 제약, 예외를 빼지 않은 채 분할하거나 압축한다. ## 변경 후 문서 구조를 검사하고 AI의 동작 시험하기 산출물에 맞춰 검증한다. 문서 중심의 스킬은 컴파일이 필요하지 않을 수 있지만, 자동 구조 검사와 수동 동작 테스트는 여전히 필요하다. 필수 frontmatter 필드, 명명 규칙, 줄 수 또는 토큰 예산, 내부 링크, 생성 산출물의 동기화, 리포지토리별 lint 규칙을 자동 검사한다. 완화된 크기 목표는 경고로 처리하고 엄격한 무결성 제약은 실패로 처리한다. 콘텐츠를 변경할 때는 다음 순서로 진행한다. 1. 정본 스킬 또는 참조 자료를 편집한다. 2. 로컬 구조 검증을 실행한다. 3. 호스트 환경에서 스킬을 다시 불러온다. 4. 변경된 분기를 실행하는 현실적인 사용자 질의를 수행한다. 5. 동작을 기준 시나리오와 비교하여 회귀를 확인한다. 풀 리퀘스트에는 영향을 받는 시나리오의 변경 전후 근거를 요구한다. 정보 아키텍처를 실질적으로 변경할 때는 검색 구조, 압축, 누락된 의사결정 분기에 초점을 맞춘 독립 검토를 받는다. ## 풀 리퀘스트 검사를 필수로 하고 버전 번호는 자동 릴리스에 맡기기 메인 브랜치를 보호한다. 풀 리퀘스트, 검증 검사, 유효한 규약형 제목을 필수로 한다. 변경 사항을 스쿼시 병합하고 풀 리퀘스트 제목이 릴리스 커밋이 된다면, 그 제목이 버전 결정을 좌우하므로 제목도 검증한다. 규약형 변경 유형을 버전 증가에 대응시키고, 메이저 변경을 나타내는 명시적 신호도 포함한다. 릴리스 워크플로가 변경 로그, 정본 버전 메타데이터, 플랫폼 매니페스트, 생성 산출물을 한 번의 릴리스 변경으로 갱신하게 한다. 동기화된 버전 번호를 절대 직접 편집하지 않는다. 버전의 정본을 하나만 유지하고, 태그를 만들기 전에 릴리스 파이프라인이 각 위치에 반영하게 한다. 병합 전에 다음을 확인한다. - 생성 결과가 정본과 일치한다. - 분기형 실행 지침보다 앞에 의사결정 표가 있다. - 중복된 서두와 예시가 제외되어 있다. - 라우팅에 사용되는 앵커가 안정적으로 유지된다. - 변경된 기준 시나리오에 근거가 포함되어 있다. - 필수 검증과 제목 검사가 통과했다.