올바르게 호출되고 검사를 통과하는 에이전트 스킬을 만들어 릴리스하기

## 스킬 설명에는 하는 일과 언제 쓰는지만 적기 설명은 압축된 절차가 아니라 라우팅 메타데이터로 취급한다. 에이전트는 전체 본문을 읽기 전에 설명을 보고 스킬을 선택할 수 있으므로, 설명에 포함된 프로세스 단계가 상세 워크플로를 덮어쓰거나 우회할 수 있다. 설명은 간단한 기능 진술 뒤에 발동 조건을 제시하는 형태로 작성한다. 즉, 스킬이 무엇을 하고 언제 사용해야 하는지를 밝힌다. 설명은 현재 스키마의 제한 안에 유지하고, 1,024자 상한이 적용될 때는 이 제한을 지킨다. 순서가 있는 단계, 구현 순서, 문제 해결 절차를 설명에 절대 넣지 말고, 모든 사용 방법은 스킬 본문에 둔다. 현실적인 프롬프트로 설명을 테스트하여 의도한 요청에서 발동하고, 관련 없는 작업에서는 발동하지 않으며, 에이전트를 전체 지침으로 안내하는지 확인한다. ## 프런트매터에는 사양에 있는 필드만 두고 관련 스킬 참조를 올바르게 유지하기 인접 저장소의 필드를 복사하지 말고 현재 적용되는 스킬 사양을 따른다. 최상위에는 `name`과 `description`을 비롯해 사양에서 정의한 필드만 유지하며, `license`와 `allowed-tools`는 저장소 계약에 따라서만 사용한다. `allowed-tools`가 있으면 공백으로 구분된 목록이어야 한다. 저장소별 필드는 `metadata` 아래에 둔다. 이름에는 영문자, 숫자, 하이픈만 허용한다. 설명의 길이와 발동 문구를 검증한다. 작성자, 시맨틱 버전, 도메인, 트리거, 역할, 범위, 출력 형식, 관련 스킬 등의 구조화된 메타데이터는 저장소에서 정의한 열거형 값과 형식을 따라야 한다. 모든 관련 스킬 항목은 기존 스킬 디렉터리로 해석되어야 한다. 저장소에서 승인한 라이선스 값을 일관되게 사용하고, 저장소가 라이선스를 MIT로 고정한 경우 `license: MIT`라고 정확히 쓴다. YAML 파서가 허용한다는 이유만으로 알 수 없는 열거형 값, 끊어진 참조, 사용자 정의 최상위 필드를 받아들여서는 안 된다. ## 메인 스킬 파일은 짧게 두고 자세한 내용은 참고 파일로 옮기기 기본 스킬 파일은 라우팅 및 운영 컨텍스트로 불러올 수 있을 만큼 간결하게 유지한다. 실용적인 첫 번째 계층은 대략 80~100줄로 구성하며, 역할, 발동 지침, 5단계 핵심 워크플로, 필수 및 금지 행동, 더 상세한 참조 자료로 연결하는 라우팅 표를 포함한다. 상세한 기술 자료는 각각 보통 100~600줄인 두 번째 계층의 주제별 참조 파일에 둔다. 각 참조 자료는 하나의 주제를 다루고, 관련 타입을 포함한 완전하게 작동하는 예제를 제공하며, 경계 사례와 안티패턴을 설명하고, 해당 지침을 사용해야 할 때와 사용하지 말아야 할 때를 명시해야 한다. 현재 작업에 필요한 참조 자료만 불러온다. 유용한 경우 관련 스킬을 상호 연결하되, 전체 내용을 중복하지 않는다. 컨텍스트 사용량 감소를 설계 성과로 간주한다. 라우팅이 잘 구성된 2계층 구조는 필요한 지침을 생략하지 않으면서 약 50% 감소를 목표로 삼을 수 있다. ## 예제에서는 각 프레임워크에 내장된 방식 쓰기 프레임워크별 지침은 해당 프레임워크에 정착된 메커니즘을 사용해야 한다. 프레임워크가 전역 오류 처리, 미들웨어, 의존성 주입, 수명 주기 훅 또는 다른 내장 추상화를 제공한다면 예제는 이를 수동으로 다시 만들지 말고 해당 메커니즘을 사용해야 한다. 저장소 전체의 시각적 일관성을 위해 서로 관련 없는 프레임워크에 하나의 일반 아키텍처를 강요하지 않는다. 오류 처리, 구성, 테스트, 통합에 관한 프레임워크 규약이 우선한다. 참조 예제는 완전하고 실행 가능하게 유지하며, 언어가 타입을 지원하면 타입도 포함한다. 적용 범위에 해당하는 프레임워크 버전을 기준으로 예제를 검토하고, 내장 동작을 중복 구현하거나 프레임워크별 제약을 감추는 패턴은 거부한다. ## 모든 스킬 파일 마지막에 문서 링크 하나 두기 모든 스킬 파일은 마지막 줄에 정규 문서 역링크를 정확히 하나만 두고 끝나야 한다. 엄격한 렌더러가 실제 하이퍼링크를 생성하도록, 일반 URL이 아니라 레이블이 `Documentation`이고 정규 URL을 가리키는 Markdown 링크 문법을 사용한다. `metadata.domain`이나 스킬 디렉터리 이름처럼 안정적인 메타데이터에서 정규 경로를 도출한다. 메타데이터가 없으면 문서에 규정된 대체 도메인을 적용한다. 스킬을 추가하거나 이름을 변경할 때는 디렉터리, 도메인, 역링크를 함께 갱신한다. 그렇지 않으면 게시된 링크가 존재하지 않는 페이지를 반환할 수 있다. 여러 게시 표면을 명시적으로 고려한다. 원시 파일 집계기는 검색을 위해 역링크가 필요할 수 있지만, 문서 빌드는 생성 페이지, 미러, 언어 모델 인덱스에서 같은 자기 참조 링크를 제외할 수 있다. 동기화 단계에서 두 동작을 모두 유지하고 렌더링된 대상을 테스트한다. ## 스킬을 만들거나 고칠 때 겹치는지 확인하고 관련 참조 고치기 새 스킬을 만들 때는 다음을 수행한다. 1. 기존 스킬 간에 책임이 겹치는지 확인한다. 2. 기능 및 발동 메타데이터를 포함한 기본 스킬을 작성하고, 프로세스 단계는 본문에 둔다. 3. 심층 콘텐츠를 위한 주제별 참조 자료를 추가한다. 4. 주제에서 참조 자료로 연결하는 라우팅 표를 추가한다. 5. 마지막 줄에 정규 문서 역링크 하나만 추가한다. 6. 발동해야 하는 프롬프트와 발동하지 않아야 하는 프롬프트를 테스트한다. 7. 분류 체계가 바뀌면 스킬 안내서와 도메인 인덱스를 갱신한다. 스킬을 수정하기 전에 현재 본문 전체와 변경의 영향을 받는 참조 자료를 읽는다. 기능과 발동 조건으로 구성된 설명 형태와 점진적 공개 아키텍처를 유지한다. 이름, 범위, 트리거 또는 의존성이 바뀔 때마다 라우팅 표, 관련 스킬 참조, 문서 인덱스, 발동 테스트를 갱신한다. ## 하나의 버전 파일을 기준으로 개수와 변경 기록 맞추기 하나의 버전 매니페스트를 릴리스 버전과 스킬, 워크플로, 참조 파일 등의 계산된 개수에 대한 단일 기준 정보로 사용한다. 저장소 갱신 도구를 실행하여 파일 시스템에서 개수를 다시 계산하고 생성 문서를 동기화한다. CI와 검토자가 쓰기 없이 불일치를 감지할 수 있도록 검사 모드와 시험 실행 모드를 지원한다. 안정적인 Added, Changed, Fixed 구조를 사용하여 변경 기록 맨 위에 새 릴리스를 추가하고 버전 비교 링크를 유지한다. 집계 문서를 다시 생성하기 전에 새 콘텐츠나 수정된 콘텐츠에 맞게 안내서, 의사 결정 트리, 명령 표, 상호 참조를 갱신한다. 개수가 포함된 소셜 미디어 자료는 포함된 개수가 바뀔 때만 다시 생성한다. 버전만 변경하는 패치에는 새 자료가 필요하지 않다. 자동화가 관련 없는 변경을 감추지 않도록 생성된 차이를 검토한다. ## 릴리스 전에 스킬과 Markdown 검사 도구 돌리기 릴리스 전에 스킬 무결성 검증기를 실행한다. 검증기는 YAML 파싱, 필수 필드, 이름 형식, 설명 길이와 필수 `Use when` 발동 구문, 참조 디렉터리의 존재 여부, 참조 구조, 개수 일관성을 검사해야 한다. 단일 스킬이나 단일 검증 계열로 범위를 제한한 검사와 CI용 기계 판독 가능 결과를 제공한다. Markdown 검증기는 별도로 실행한다. 표를 깨뜨리는 HTML 주석, 닫히지 않은 코드 펜스, 누락된 표 구분 행, 일관되지 않은 열 개수를 검사한다. 범위를 좁힌 조사 후에는 저장소 전체를 검증한다. 종료 코드 0은 성공으로, 종료 코드 1은 검증 실패로 처리하고, 경고는 명시적으로 검토한다. 범위가 더 좁은 검사를 통과했다는 이유만으로 해결되지 않은 검증 오류가 있는 릴리스를 절대 게시하지 않는다. ## 사용한 명령과 결과를 기록한 뒤 릴리스 준비 완료 알리기 동기화와 검증 후 의도적으로 남긴 변경 기록은 제외하고 오래된 버전 참조를 검색한다. 설명, 발동 테스트, 라우팅 표, 관련 스킬 참조, 정규 역링크, 생성된 개수, 조건부 자료가 릴리스와 일치하는지 수동으로 확인한다. 다른 작업에서 행동 패턴이나 프로세스 규율을 차용한 경우 제3자 귀속 표시, 라이선스 고지, 연구 참조를 유지한다. 정리 과정에서 출처를 잃어서는 안 된다. 정확한 갱신 및 검증 명령, 실행 결과, 검토한 경고, 의도적으로 건너뛴 조건부 단계를 기록한다. 필수 검증기가 모두 통과하고 최종 차이에 설명되지 않은 변경이 없을 때만 릴리스 준비가 완료되었다고 보고한다.