웹사이트 품질을 점검하는 AI 에이전트 스킬 모음을 만든다

## 저장소를 웹 품질 주제별 스킬로 나눈다 저장소를 하나의 거대한 지침 파일이 아니라 자체 완결된 에이전트 기능의 모음으로 취급하세요. 성능, 접근성, 발견 가능성, 전반적인 품질, 사용자 경험 지표에 대한 광범위한 감사와 집중형 스킬을 분리하여 에이전트가 작업에 필요한 기능만 불러올 수 있도록 하세요. 저장소 수준의 문서, 기여 규칙, 라이선스, 에이전트 지침은 루트에 유지하세요. 각 스킬 디렉터리는 자체 기본 지침 파일, 자동화 스크립트, 상세 참조 자료를 관리합니다. 사용자용 지침, 실행 가능한 도우미 또는 소스 자료를 관련 없는 디렉터리에 숨기지 마세요. 스킬을 변경하기 전에 활성화 계약, 해당 스킬이 관리하는 파일, 종속 항목, 검증 경로, 다른 스킬과의 관계를 파악하세요. ## 스킬 폴더와 파일 이름을 정하고 SKILL.md 헤더를 채운다 모든 스킬에 다음 내용을 포함하는 유효한 YAML 프런트매터가 있는 `SKILL.md` 파일을 제공하세요. - kebab-case 형식의 `name`; - 스킬을 언제 사용해야 하는지 명시하고 현실적인 트리거 문구를 포함하는 한 문장의 `description`; - 필요한 경우 라이선스 메타데이터; - 저장소에서 이를 추적하는 경우 안정적인 작성자 및 버전 메타데이터. 정확한 명명 규칙을 일관되게 사용하세요. - 스킬 디렉터리는 kebab-case를 사용합니다. - 기본 지침 파일의 이름은 정확히 `SKILL.md`입니다. - 스크립트 파일명에는 kebab-case와 적절한 실행 파일 확장자를 사용합니다. - 참조 파일명에는 저장소에 문서화된 대문자 규칙을 사용합니다. 패키지를 자체 완결형으로 유지하고, 스킬에 언급된 모든 경로가 지원되는 저장소 구조 안에서 올바르게 해석되는지 확인하세요. ## SKILL.md는 500줄 미만으로 두고, 자세한 내용은 참조 파일로 옮긴다 기본 스킬은 500줄 미만으로 유지하세요. 활성화, 핵심 워크플로, 중요 제약 조건, 탐색 정보는 `SKILL.md`에 두고, 상세 설명, 큰 예시, 전문 자료는 참조 자료로 옮기세요. 구체적이고 실행 가능한 지침을 작성하세요. 각 지침에는 짧은 제목, 직접적인 명령, 적용에 필요한 값이나 임계값이 있어야 합니다. 무엇을 검사하고, 어떤 결정을 내리며, 어떤 증거로 완료를 입증할지 설명하는 지침을 우선하세요. 결정론적이거나 반복적인 작업의 출력이 추론 컨텍스트를 소모할 수 있다면 스크립트를 사용하세요. 기본 스킬과 여러 참조 자료에 동일한 절차를 중복해서 넣지 마세요. ## 수정 전후 코드와 좋음·나쁨 기준 표를 보여 준다 지침이 실행 동작을 규정할 때마다 문제와 수정된 패턴을 함께 보여 주세요. 예시는 독립적으로 이해할 수 있을 만큼 작게 유지하고 실제로 작동하는지 확인하세요. 예를 들어 이미지 안정성 지침은 정보가 충분하지 않은 이미지와 크기 및 유용한 로딩 메타데이터를 선언한 이미지를 대조해야 합니다. 문제: `src="hero.jpg"`만 있는 이미지 요소. 개선: 동일한 요소에 `width="1200"`, `height="600"`, `alt="Hero image"`, `loading="lazy"`를 추가합니다. 비교 가능한 품질 임계값은 양호, 중간, 불량 범위를 명시한 표로 제시하세요. 독자가 한계값 포함 여부를 추론하지 않도록 단위와 경계 연산자를 명시하세요. ## 오류가 나면 멈추고 결과를 JSON으로 내는 셸 스크립트를 쓴다 셸 도우미는 오류 발생 시 즉시 중단되고, 기계가 읽을 수 있으며, 안전하게 정리할 수 있어야 합니다. - 셔뱅으로 사용할 셸을 선언합니다. - `set -e`와 같은 오류 발생 시 즉시 중단하는 동작을 활성화합니다. - 진행 및 상태 메시지는 표준 오류로 보냅니다. - JSON과 같이 기계가 읽을 수 있는 결과는 표준 출력으로 보냅니다. - 임시 파일을 안전하게 만들고 정리 트랩을 등록합니다. - 자체 완결형으로 유지하거나 모든 외부 종속 항목과 사전 요구 사항을 문서화합니다. 사람이 읽는 진단 정보를 기계 판독용 스트림에 포함하지 마세요. 도우미를 재사용 가능한 자동화로 취급하기 전에 성공, 실패, 잘못된 형식의 입력, 정리 동작을 테스트하세요. ## 참조 파일은 한 주제로 좁히고 스킬에서 연결한다 각 참조 자료에 하나의 집중된 주제, 실용적인 예시, 권위 있는 자료로 연결되는 링크를 제공하세요. 에이전트가 관련 없는 컨텍스트를 함께 불러오지 않고 독립적으로 로드할 수 있도록 개별 참조 자료는 가능하면 200줄 미만으로 유지하세요. 모든 참조 자료를 기본 스킬이나 관리되는 색인에서 연결하세요. 오래된 링크와 중복 지침을 제거하고, 변경 가능한 사실은 가장 가까운 권위 있는 출처가 관리하도록 하세요. 참조 자료는 깊이 있는 정보를 제공하는 데 사용하고, 아무 자료나 모아 두는 곳으로 사용하지 마세요. 참조 자료는 에이전트가 별개의 결정을 내리거나 실행하는 데 도움을 주어야 합니다. ## 스킬을 공개하기 전에 헤더, 예시, 링크, 스크립트를 확인한다 스킬을 제출하거나 게시하기 전에 다음을 수행하세요. 1. YAML 프런트매터를 파싱하고 검증합니다. 2. 설명에 사용 가능한 활성화 트리거가 포함되어 있는지 확인합니다. 3. 실행 가능한 모든 예시를 실행하거나 다른 방식으로 검증합니다. 4. 참조된 모든 파일이 존재하고 모든 내부 링크가 올바르게 해석되는지 확인합니다. 5. 문서화된 인터페이스를 통해 스크립트를 테스트하고 출력 채널 동작을 검증합니다. 6. 적용되는 에이전트 스킬 명세에 따라 패키지를 검증합니다. 구문 검사 성공은 필요하지만 충분하지는 않습니다. 활성화 설명, 예시, 참조 자료, 스크립트는 스킬이 약속한 동작과 일치해야 합니다. ## 문제를 치명부터 낮음까지 순위를 매기고, 특정 프레임워크에 묶지 않는다 발견 사항의 순위를 일관되게 정하세요. 1. **심각:** 보안 취약점 또는 완전한 기능 장애. 2. **높음:** 심각한 성능 장애 또는 주요 접근성 장벽. 3. **중간:** 성능, 발견 가능성 또는 검색 품질을 유의미하게 개선할 기회. 4. **낮음:** 코드 스타일 및 사소한 최적화 기회. 웹 지침을 프레임워크 중립적으로 유지하세요. 표준 HTML, CSS, JavaScript를 먼저 제시하고, 프레임워크별 참고 사항은 별도의 섹션에 배치하며, 프레임워크 종속성이 작업에 필수적이지 않은 한 표준 플랫폼 API를 우선하세요. 스타일 개선에 노력을 들이기 전에 사용자 영향이 가장 큰 정확성 문제와 접근 장벽을 검토하세요. ## 스킬을 부르는 문구를 깨지 않고 스킬을 업데이트한다 스킬 설명을 업데이트할 때 하위 호환성을 유지하고 기존 트리거 문구가 계속 작동하도록 하세요. 구현과 함께 버전 메타데이터를 업데이트하고, 호환성을 깨뜨리는 변경 사항은 저장소에서 요구하는 변경 기록이나 커밋 설명에 문서화하세요. 구조가 변경되면 기본 스킬, 영향을 받는 참조 자료, 스크립트, 예시, 링크를 함께 업데이트하세요. 최종 diff를 검토하여 의도하지 않은 범위 확장, 오래된 생성 자료, 중복 지침이 없는지 확인하세요. 동작을 변경할 때마다 집중 검증 체크리스트를 다시 실행하세요. 활성화 경로, 예시 또는 참조된 자산이 검증되지 않은 상태에서 업데이트된 스킬이 준비되었다고 주장하지 마세요.