프로젝트 문서로 에이전트 스킬을 만들고 최신 상태로 유지하기

## 편집하기 전에 스킬을 누가 관리하는지 확인하기 파일을 만들거나 업데이트하기 전에 각 스킬의 소유 방식을 판단하세요. 문서는 게시하지만 에이전트 스킬 패키지는 유지 관리하지 않는 프로젝트에는 생성형 스킬을, 자체 스킬을 이미 게시하는 프로젝트에는 동기화형 스킬을, 의도적으로 선별한 전문 지식에는 수동 작성 스킬을 사용하세요. 이러한 워크플로를 혼용하지 마세요. 생성형 스킬은 문서에서 종합하고, 동기화형 스킬은 해당 업스트림 스킬 소스에서 복사하며, 수동 작성 스킬은 작업에 명시적으로 포함되지 않는 한 그대로 유지하세요. ## 문서에서 에이전트의 작업에 도움이 되는 내용만 고르기 기능, 결정 지점, 실용적인 사용 패턴, 작동하는 예시, 에이전트가 어떤 상황에서 한 접근법을 다른 접근법보다 선택해야 하는지에 집중하세요. 작업 실행을 실질적으로 개선하는 지식을 우선하세요. 사용자 대상 소개, 설치 안내, 일반적인 시작 자료, 홍보 문구, 유능한 모델이 이미 안정적으로 처리하는 개념은 제외하세요. 문서를 그대로 복사하지 말고 소스 자료를 다시 작성하고 종합하세요. 스킬을 간결하게 유지하세요. 서로 다른 개념을 다루는 데 필요한 참조 파일만 만들고, 중복 파일을 피하며, 패턴의 작동 방식뿐 아니라 그 패턴을 사용해야 하는 이유와 시점도 설명하세요. ## 새 프로젝트를 등록부에 추가하고 스킬 생성하기 새로운 생성형 소스를 해당 소스 위치와 안정적인 프로젝트 식별자와 함께 저장소의 기준 프로젝트 등록부에 추가하세요. 추적되지 않는 로컬 복사본을 만들지 말고 저장소에서 지원하는 워크플로를 통해 소스를 초기화하거나 동기화하세요. 프로젝트의 기능과 규칙을 이해할 수 있을 만큼 프로젝트 문서와 프로젝트별 생성 지침을 충분히 읽으세요. 유용한 자료를 핵심 개념, 기능, 모범 사례, 고급 워크플로 등의 범주로 정리하세요. 이름이 등록된 생성형 소스 식별자와 일치하는 출력 디렉터리를 만드세요. 참조 파일을 작성하고, 스킬 색인을 구축하며, 정확한 소스 리비전을 포함하는 생성 메타데이터를 기록하세요. ## 문서가 바뀐 부분만 생성형 스킬에 반영하기 생성 메타데이터에 기록된 소스 리비전을 읽고 현재 소스와 비교하세요. 소스 차이는 생성형 스킬을 규정하는 문서 영역으로 한정하세요. 해당 차이의 영향을 받는 참조 파일만 업데이트한 다음, 필요한 경우 색인의 프로젝트 버전, 생성 날짜, 주제 표, 설명을 갱신하세요. 영향을 받지 않는 참조 파일은 보존하고, 소스 저장소의 리비전이 올라갔다는 이유만으로 관련 없는 콘텐츠를 다시 생성하지 마세요. 검토 후 기록된 리비전을 업데이트에 사용한 정확한 리비전으로 교체하여 다음 비교에서 신뢰할 수 있는 기준으로 삼으세요. ## 업스트림이 관리하는 스킬은 직접 고치지 않고 복사로 동기화하기 업스트림에서 유지 관리되는 스킬은 등록부를 사용하여 복사할 소스 스킬과 사용할 출력 이름을 판단하세요. 출력 이름은 의도적으로 업스트림 디렉터리와 다를 수 있으므로 소스 이름만으로 절대 추론하지 마세요. 처음 가져올 때는 설정된 스킬 트리를 복사하고 업스트림 리비전을 동기화 메타데이터에 기록하세요. 업데이트할 때는 기록된 리비전과 현재 업스트림 스킬 디렉터리를 비교하고, 설정에 포함된 변경 파일만 복사한 뒤 기록된 리비전을 갱신하세요. 동기화형 스킬의 콘텐츠를 수동으로 수정하지 마세요. 수정 사항은 업스트림 소유자에게 제공하고 동기화 워크플로를 통해 다시 가져와서 로컬 복사본에 편차가 생기지 않도록 하세요. ## 각 참조 파일로 연결되는 짧은 스킬 색인 만들기 스킬 색인에 케밥 표기법 이름, 간결한 기능 설명, 출처 메타데이터, 생성 또는 동기화 날짜, 관련 도구 또는 프로젝트 버전을 포함한 유효한 프런트매터를 설정하세요. 짧은 안내 문단을 추가한 다음 참조 파일을 명확한 범주로 묶으세요. 각 주제에 간단한 설명과 해당 참조 파일의 상대 링크를 제공하여 에이전트가 현재 작업에 필요한 자료만 불러올 수 있게 하세요. 색인은 간결하고 탐색에 집중하도록 유지하세요. 색인에 참조 파일의 전체 콘텐츠를 중복하거나 존재하지 않는 파일의 항목을 추가하지 마세요. ## 참조 파일 하나에 실용적인 주제 하나만 쓰기 각 참조 파일에 안정적인 이름과 초점을 맞춘 설명이 포함된 프런트매터를 설정하고, 그 뒤에 명확한 개념 제목을 두세요. 관련 없는 기능을 결합하지 말고 파일마다 일관된 기능 또는 워크플로 하나를 다루세요. 실용적인 사용 지침, 개념을 실행할 수 있는 경우 작동하는 코드 예시, 주요 제약, 권장 패턴의 근거를 포함하세요. 에이전트가 결정을 내리거나 실행하는 데 도움이 되지 않는 배경은 제외하세요. 콘텐츠를 종합하는 데 사용한 문서를 식별하는 소스 참조로 마무리하세요. 스킬을 소스 자료의 복사본으로 만들지 않으면서 해당 참조를 추적 가능하게 유지하세요. ## 각 스킬을 만들 때 쓴 소스 리비전과 날짜 기록하기 생성형 스킬은 소스 위치, 정확한 소스 리비전, 생성 날짜를 기록하세요. 동기화형 스킬은 업스트림 스킬 위치, 정확한 업스트림 리비전, 동기화 날짜를 기록하세요. 색인 버전을 실제 소스 상태와 일치시키고 저장소 정책에 따라 최근 생성 또는 동기화 날짜를 사용하세요. 콘텐츠가 파생된 것보다 최신인 프로젝트 버전이나 리비전을 표방하지 마세요. 등록부를 지원되는 프로젝트와 소스 위치의 기준 목록으로 취급하세요. 등록부가 이미 관리하는 변경 가능한 저장소 URL이나 소유권 대응 관계를 여러 스킬 파일에 중복하지 마세요. ## 마지막 diff에서 깨진 링크와 오래된 리비전 확인하기 완료 전에 소스 분류, 등록부 항목, 출력 이름 규칙, 색인 링크, 참조 파일의 프런트매터, 범주 구성, 리비전 메타데이터, 소스 인용이 모두 일치하는지 확인하세요. 생성된 콘텐츠가 복사가 아니라 종합된 것인지, 동기화된 콘텐츠에 수동 변경으로 인한 편차가 없는지, 수동 작성 스킬이 범위에 포함되지 않은 채 변경되지 않았는지, 각 참조 파일이 에이전트에게 서로 다른 가치를 제공하는지 검증하세요. 최종 차이에서 관련 없는 파일, 과도한 참조 파일, 오래된 버전, 누락된 예시, 끊어진 링크, 기록되지 않은 소스 변경을 검토하세요. 완전한 생성 또는 동기화를 막은 소스나 도구의 제약이 있다면 보고하세요.