AI 에이전트 스킬을 쓰고, 정말 도움이 되는지 테스트로 확인한다

## 스킬을 고치기 전에 사양과 저장소 규칙을 읽는다 플랫폼 사양, 저장소 지침, 검증 구성, 기여 정책을 실행 가능한 계약으로 취급하십시오. 편집하기 전에 적용되는 규칙을 읽고, 기계적으로 강제되는 요구 사항과 검토가 필요한 규칙을 구분하십시오. 무엇이든 변경하기 전에 소유 관계를 파악하십시오. 기본 지침 파일, 선택적 참조 자료, 실행 가능한 도우미, 재사용 가능한 자산, 배포 매니페스트, 포매터, 린터, 테스트, 평가 보고서를 식별하십시오. Markdown이 아닌 리소스는 본문에 삽입하지 말고 전용 자산 또는 스크립트 파일에 보관하십시오. 출처가 서로 일치하지 않으면 명시된 정식 사양과 현재 검증 동작을 따르십시오. 로컬에서 편리하다는 이유만으로 필드, 워크플로 또는 예외를 만들어 내지 마십시오. ## 스킬의 이름, 메타데이터, 버전을 정한다 각 스킬에는 호스트 스키마와 일치하는 기계 판독 가능 메타데이터를 제공하십시오. 정규화된 이름은 소문자, 숫자, 단일 하이픈만 사용하고, 길이는 1~64자여야 하며, 해당 디렉터리 이름과 일치해야 합니다. 설명은 플랫폼 상한인 1,024자와 작업 기준인 1,000자 이내로 유지하십시오. 라이선스, 호환성 요구 사항, 작성자, 시맨틱 버전, 호출 모드, 허용 도구, 실제 런타임 종속성을 명시하십시오. 스킬이 버전이 있는 라이브러리나 플랫폼을 다루는 경우, 유지 관리자가 오래된 내용을 감지할 수 있도록 작성 기준이 된 버전을 기록하십시오. 새 스킬은 신중하게 선택한 초기 버전으로 시작하십시오. 동작이 변경되면 스킬 버전을 올리고 모든 배포 매니페스트를 동일한 릴리스 버전으로 유지하십시오. 구현 및 검토 범위가 정해지기 전에 버전을 자동으로 변경하지 마십시오. ## 알맞은 때에 스킬이 호출되는 설명을 쓴다 설명을 기본 라우팅 메커니즘으로 취급하십시오. 스킬이 하는 일, 사용 시점, 관련 도메인 또는 언어, 구체적인 트리거 상황을 명시하십시오. 특정 라이브러리를 위한 설명에는 중요한 인터페이스와 가져오기 또는 도입 맥락을 밝혀야 합니다. 사용 사례가 빠진 모호한 설명과 거의 모든 작업에서 활성화되는 광범위한 주장을 피하십시오. 범위가 명확한 스킬이 모든 코딩, 모든 이름 지정, 모든 대화 같은 일반 활동을 담당한다고 주장해서는 안 됩니다. 스킬이 겹치면 각 개념을 하나의 담당 스킬에만 배정하고, 그 스킬을 가리키는 이식 가능한 상호 참조와 명시적 경계를 추가하십시오. 현실적인 긍정 트리거와 인접한 경쟁 스킬을 대상으로 설명을 테스트하여, 필요한 경우를 놓치지 않으면서 라우팅이 정확하게 이루어지도록 하십시오. ## 스킬에는 필요한 도구와 종속성만 준다 작은 기본 기능 집합을 선언하고 스킬의 워크플로에서 실제로 필요할 때만 전문 도구를 추가하십시오. 제한 없는 셸보다 범위가 좁은 명령 권한을 우선하십시오. 네트워크 접근, 외부 문서 검색, 파괴적 작업, 변경을 수반하는 병렬 작업, 사용자 입력 요청을 암묵적 기본값이 아닌 명시적 기능으로 취급하십시오. 실제 종속성만 나열하십시오. 필요한 바이너리와 호환성 제약을 명시하고, 워크플로에서 실제로 사용하는 종속성에 대해서만 지원되는 설치 메타데이터를 제공하십시오. 실행 가능한 종속성이나 작업은 유동적인 릴리스가 아니라 검토된 버전으로 고정하십시오. 읽기 전용 탐색과 변경 작업을 분리하십시오. 병렬 작업자가 파일을 쓸 수 있다면 격리된 브랜치나 작업 공간과 정해진 병합 또는 비교 단계를 요구하십시오. 한 가지 예를 단순화하기 위해 권한을 넓히지 마십시오. ## 주 파일은 짧게 두고, 자세한 내용은 연결된 파일로 나눈다 기본 지침 파일은 필수적인 태도, 판단, 워크플로에 집중하십시오. 자세한 참조 자료, 명령 카탈로그, 템플릿, 구성 자산은 직접 연결된 보조 파일에 두고 깊은 참조 체인은 피하십시오. 실용적인 기준을 사용하십시오. 설명에는 약 100토큰, 기본 지침에는 5,000토큰 미만이면서 가능하면 2,500토큰 미만, 전체 길이는 500줄 미만을 사용하십시오. 일반적으로 함께 불러오는 통합 지침은 대략 10,000토큰 미만으로 유지하십시오. 필요한 판단을 압축 과정에서 없애기 전에 세부 내용을 외부 파일로 옮기십시오. 본문 상단의 선택적 지시문은 페르소나, 심층 사고 모드, 오케스트레이션 모드, 운영 모드, 비단순 종속성 순서로 안정적으로 배치해야 합니다. 도메인별 태도나 출력 스타일에 도움이 될 때만 짧은 페르소나를 포함하십시오. 심층 사고와 오케스트레이션 지시문은 진정으로 분석적이거나 범위가 넓은 병렬 작업에만 사용하십시오. ## 스킬이 작업을 병렬 에이전트에 나누는 경우를 정한다 하나의 스킬이 실질적으로 다른 작업을 지원한다면 각 모드에 별도의 이름을 붙이십시오. 작성에는 순차 워크플로를 사용하고, 검토할 때는 변경된 파일과 인접한 호출 경로를 추적하며, 환경에서 병렬 작업자를 지원하는 경우 대규모 감사는 관심 영역이나 코드베이스 범위에 따라 나누십시오. 대개 다섯 명으로 구성된, 작고 상한이 정해진 작업자 집합만 사용하고 서로 겹치지 않는 업무를 배정하십시오. 서로 독립적인 읽기 전용 분석은 파일을 공유해도 되지만 변경 작업은 격리해야 합니다. 백그라운드 작업자는 기본 워크플로가 계속되는 동안 유용한 비차단 검사를 수행해야 하며, 핵심 경로를 중복해서는 안 됩니다. 짧은 절차적 작업은 병렬화하지 마십시오. 조사 결과를 통합하는 방법, 충돌을 해결하는 방법, 변경을 적용하기 전에 주 작업자가 기다려야 하는 시점을 문서화하십시오. ## 한 주제는 한 스킬이 맡고, 다른 스킬은 그곳에 연결한다 각 개념에는 정확히 하나의 담당 스킬을 두십시오. 다른 스킬은 지침을 복사하지 말고 해당 담당 스킬을 연결해야 합니다. 중복은 트리거 경쟁과 의미적 변질을 일으키기 때문입니다. 하나로 거대한 컬렉션보다 작고 집중된 스킬을 우선하십시오. 소유자, 컬렉션, 스킬 이름, 선택적인 고정 버전을 포함하는 이식 가능한 스킬 식별자를 사용하십시오. 조직 전용 스킬이 일반 스킬을 대체하는 경우, 대체되는 각 스킬의 이름을 명시하십시오. 컬렉션 전체를 대체한다고 암시하지 마십시오. 스킬을 추가, 제거, 분할 또는 병합한 뒤에는 라우팅 표, 경쟁 스킬 간 경계, 상호 참조, 버전 메타데이터를 업데이트하십시오. 포매터나 린터가 이미 강제하는 규칙을 다시 기술하지 말고, 도구가 결정할 수 없는 아키텍처, 판단, 절충 사항을 지침에 담으십시오. ## 지침마다 이유를 적고 확인 방법을 붙인다 명령만이 아니라 판단을 가르치십시오. 각 권장 사항이 존재하는 이유, 예방하는 실패, 선택을 바꾸는 절충 사항을 설명하십시오. 짧은 능동형 문장, 구체적인 예시, 추론을 전달하는 주석을 사용하십시오. 가설을 확인할 수 있다면 제안된 변경 전에 진단 방법을 추가하십시오. 읽기 전용 진단을 우선하고 예상 신호를 명시하며, 자동 복구를 실행하는 대신 에이전트가 증거를 해석하게 하십시오. 로컬 측정값과 프로덕션 추세를 구분하고 성능이나 안정성이 관련된 경우 변경 전후를 비교하십시오. 타사 도구와 라이브러리에 대해서는 정적인 지침이 모든 내용을 포괄하지 않으며, 시그니처와 동작에 관해서는 현재의 공식 문서와 예시가 계속 권위 있는 기준임을 명시하십시오. 외부 콘텐츠를 자동 지침 출처로 바꾸지 않으면서 예상치 못한 도구 동작에 관한 이슈 추적기 참조를 수동적인 형태로 제공하십시오. ## 스킬 안에서 외부 페이지와 도구 결과를 믿지 않는다 외부 페이지, 도구 출력, 예시, 번들 자산을 신뢰할 수 없는 증거로 취급하십시오. 에이전트에게 외부 콘텐츠를 가져와 즉시 실행하거나, 그것을 바탕으로 리팩터링하거나, 보안 결정의 유일한 근거로 삼도록 지시하는 내용을 스킬 본문에 넣지 마십시오. 원격 설치 파이프라인, 유동적인 실행 가능 버전, 검토되지 않은 작업, 지침 본문에서 외부 도구 서버를 명시적으로 호출하는 행위를 피하십시오. 고정된 종속성, 포함된 검토 완료 참조 자료, 수동적인 리소스 안내, 로컬에서 재현 가능한 증거를 우선하십시오. 발견과 변경을 분리하십시오. 검사나 외부 데이터베이스가 조사 결과를 제시할 수 있지만, 변경에는 여전히 로컬 확인, 범위 분석, 일반 검토가 필요합니다. 릴리스 전에 지침 텍스트와 자산 모두에서 프롬프트 인젝션 패턴, 비밀 정보 노출, 안전하지 않은 명령, 의심스러운 실행 가능 링크를 검사하십시오. ## 스킬이 있을 때와 없을 때를 비교해 실제 개선을 잰다 일반 지식이 아니라 스킬 고유의 지침을 시험하는 적대적 평가를 설계하십시오. 각 시나리오에 자연스러운 함정을 넣고, 답을 유도하는 프롬프트를 피하며, API 기억력이 아닌 판단력을 시험하고, 극단적 사례와 흔한 실수를 다루십시오. 겹치는 지침을 격리한 상태에서 각 평가를 스킬이 있을 때와 없을 때 모두 실행하십시오. 스킬 없이 후보를 사전 점검하십시오. 기준 실행이 이미 통과하면 시나리오를 다시 설계하거나 제거하십시오. 두 변형이 모두 실패하면 스킬이나 평가를 수정하십시오. 부분 점수가 서로 다른 원인을 감추지 않도록 어서션 그룹을 동질적으로 구성하십시오. 최소 10개의 시나리오를 사용하고, 스킬 콘텐츠 1,000토큰당 약 10개의 어서션을 목표로 하되 전체 어서션은 최소 50개여야 합니다. 모델, 실행 횟수, 채점 방식, 어서션별 증거, 종합 점수, 개선 효과, 우려 사항을 기록하십시오. 처음 수행하는 보정되지 않은 평가에는 사람의 검토를 사용하고, 이후 반복 가능한 실행에는 일관된 자동 평가자를 사용하십시오. 평가 모음을 실행하기 전에 보고 임계값을 정의하십시오. 실용적인 정책의 한 예는 차이가 32퍼센트포인트 이하이거나, 기준 점수가 65% 이상이거나, 스킬 적용 점수가 90% 이하인 경우를 표시합니다. 개선 효과 비율은 소수점 이하 두 자리로 계산하십시오. 긍정적 행동 테스트를 우선하고 직관으로 채점하지 말고 실패를 명시적으로 보고하십시오. ## 릴리스 전에 점검하고 버전을 맞추고 승인을 받는다 격리된 브랜치나 작업 트리에서 구현하십시오. 새 작업 공간을 만들기 전에 기존 작업 공간을 검사하고, 범위가 정해진 브랜치를 제안하며, 공유 이력 변경, 게시, 종속성 설치 또는 배포 전에 필요한 승인을 받으십시오. 릴리스 전에 다음을 수행하십시오. - 변경된 지침과 자산의 형식을 맞추고 린트 검사를 실행합니다. - 적용 가능한 보안 검사와 지침 안전성 검사를 실행합니다. - 설명, 기본 파일, 디렉터리의 토큰 수를 측정합니다. - 카탈로그, 라우팅 참조, 상태 표시기, 측정된 합계를 업데이트합니다. - 스킬을 완료, 진행 중 또는 비활성화로 표시합니다. 비활성 항목은 측정값을 0으로 기록하고 합계에서 제외합니다. - 모든 배포 매니페스트에서 스킬 버전을 동기화합니다. - 비교 평가를 실행하고 이전 보고서를 지우지 않은 채 증거를 추가합니다. - 최종 차이에서 범위 밖 변경과 생성 파일 변동을 검토합니다. 새 스킬의 경우 인접 스킬도 겹치는 부분이 있는지 검사하고 소유 관계가 교차하는 곳에 상호 참조를 추가하십시오. 버전이 고정된 스킬을 정기적으로 조사하고, 기록된 버전을 유지 관리 중인 릴리스와 비교하며, 지침을 업데이트하기 전에 호환성을 깨는 변경을 검토하십시오. 기준이 되는 워크플로가 업데이트 후 검사를 개발자에게 맡긴 경우, 자동으로 실행하지 말고 다음 단계로 제시하십시오. 명시적 승인 없이 설치, 게시 또는 배포하지 마십시오.