AI Skill Builder
목적
공유 SKILL.md 형식과 Anthropic의 방법론을 사용하여 Agent Skill을 구축합니다: 모든 명명된 대상에서 작동하는 가장 작은 휴대용 코어에 명시적인 런타임 어댑터를 더하는 것입니다. 휴대성은 포맷 스타일이 아니라 테스트된 호환성 주장입니다.
references/sources.md는 Claude Code, Codex, Qwen Code에 대한 호스트 문서를 인용합니다. 다른 모든 호스트는 여기서 테스트되지 않았으므로 대상으로 하는 호스트를 확인하세요(1단계).
이 방법론은 의도적으로 Markdown 본문 내에 일관된 의미론적 XML 영역을 요구합니다. 이는 복잡한 운영 지침의 모호성을 줄이기 위한 품질 정책이며, 현재 Anthropic 프롬프팅 지침에서 지원되고 4단계의 순방향 테스트에서 확인됩니다. 이는 휴대용 Agent Skill 사양의 파서 요구 사항, 권한 부여 경계, 또는 XML만으로 프롬프트 인젝션을 방지할 수 있다는 주장이 아닙니다.
주요 방법론 출처: "Claude용 스킬 구축 완벽 가이드" (Anthropic, 2026년 1월)
- PDF: https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf
- 추출된 텍스트:
references/ai-skill-builder-guide.md
휴대용 포맷 출처: https://agentskills.io/specification
빠른 시작
처음부터 스킬을 만들려면 아래의 4단계 프로세스를 따르세요.
기존 스킬을 개선하려면 references/refining-skills.md를 읽으세요.
구조를 검증하려면 scripts/audit-skill.sh를 실행하세요.
호출 방법: ai-skill-builder를 요청하세요. 호스트는 이를 /ai-skill-builder, $ai-skill-builder 또는 스킬 선택기를 통해 노출할 수 있습니다.
P0 요구 사항
이 방법론이 생성하는 모든 스킬은 13가지 요구 사항을 모두 충족합니다. 감사 및 검토에서 ID로 인용하세요.
- SKILL-REQ001-대상-런타임-파악. 작성 전에 정확한 제품, 버전, 호출 모드, 설치 루트, 신뢰 경계 및 파일 시스템 의미 체계를 식별합니다.
- SKILL-REQ002-표준과-확장-분리. Agent Skill 사양, 런타임 확장 및 프로젝트 규칙을 별도의 열에 유지합니다. Claude, Codex, Copilot, Gemini 또는 프레임워크별 필드를 범용으로 표시하지 마십시오.
- SKILL-REQ003-유효한-휴대용-코어-사용. 필수
SKILL.md를 이름과 일치하는 디렉토리에 배치하고, 스킬의 기능과 사용 시기를 설명하는 구체적인description을 포함합니다. 필요한 경우에만 표준 선택적 필드를 사용합니다. - SKILL-REQ004-의미론적-XML-영역-사용. 모든 주요 운영 영역을 Markdown 본문 내에서
<purpose>,<requirements>,<workflow>,<examples>,<output_contract>와 같은 일관되고 설명적인 XML 태그로 래핑합니다. 해당 영역 내부에는 Markdown을, 리터럴 소스는 펜스 코드 블록에 유지합니다. 이 필수 방법론 규칙은 최고 품질의 명령 분리를 목표로 합니다. Agent Skills 파서 요구 사항이나 보안 경계가 아닙니다.scripts/audit-skill.sh는 영역이 없거나, 태그가 불균형하거나 잘못 중첩되었거나, 모든 영역 외부에##제목이 있는 본문을 실패 처리합니다. - SKILL-REQ005-점진적-공개-설계. 활성화 설명을 정확하게 유지하고 주요 워크플로를 간결하게 유지합니다. 진정한 조건부 세부 정보는 집중되고 직접 연결된 참조로 이동합니다. 재사용 가능한 자동화는 스크립트에, 출력 자료는 자산에 유지합니다.
- SKILL-REQ006-운영-컨텍스트-유지. 모든 참조 또는 스크립트는 사용 시기, 허용하는 입력, 반환 또는 변경하는 내용, 실패 보고 방식을 명시해야 합니다. 깊은 참조 체인은 피합니다.
- SKILL-REQ007-호출-정확성-확보. 자동 활성화 및 명시적 호출을 테스트합니다. 런타임이 매개변수를 지원하는 경우 빈, 위치, 명명, 인용, 유니코드, 유효하지 않은 및 대규모 입력을 테스트합니다. 다른 런타임이 동일한 대체 구문을 구현한다고 가정하지 마십시오.
- SKILL-REQ008-도구-권한-최소화. 스킬 및 번들 스크립트를 실행 가능한 종속성으로 취급합니다. 필요한 최소 권한을 요청하고, 입력의 유효성을 검사하며, 실용적인 경우 승인 프롬프트를 유지하고, 프롬프트 구분 기호를 프롬프트 인젝션 방지 기능으로 설명하지 마십시오.
- SKILL-REQ009-모든-환경-검증. 지원되는 각 환경에서 검색, 로드, 참조, 스크립트, 인수, 심볼릭 링크, 중복 해결, 업데이트 및 제거를 검증합니다. 하나의 파서를 통과한다고 해서 크로스 런타임 호환성이 입증되는 것은 아닙니다.
- SKILL-REQ010-사용자-상태-보존. 설치 및 제거는 정확한 생성 경로를 소유하고, 수동 편집을 보존하며, 여러 구성된 스킬 루트를 지원하고, 설치 프로그램이 소유한 링크 또는 파일만 제거해야 합니다.
- SKILL-REQ011-컨텍스트-및-런타임-비용-측정. 검색 메타데이터 크기, 로드된 명령 크기, 조건부 참조 비용, 스크립트 시간/메모리/입출력 및 중복 로드를 기록합니다. 대상 런타임이 이를 규범적으로 만들지 않는 한 줄 및 토큰 목표를 휴리스틱으로 취급합니다.
- SKILL-REQ012-순방향-테스트-실제-작업. 현실적인 긍정, 부정, 모호 및 적대적 프롬프트를 사용합니다. 스킬이 목록에 나타났는지 여부가 아니라 작업 결과를 확인합니다.
- SKILL-REQ013-작성과-실행-분리. 작업이 스킬 변경, 스킬을 사용하여 아티팩트 또는 결과 생성, 또는 증거를 기반으로 스킬 평가 중 무엇인지 분류합니다. 명시적인 작성 결정이 이를 수용하고 일반화하지 않는 한, 런타임 입력, 생성된 출력, 예제 및 도그푸드 관찰은 스킬 명령이 되지 않습니다.
영역 이름은 보편적인 분류법이 아닌 작업을 따릅니다. 워크플로는 <workflow>, 참조 스킬은 <decision_guide>, 다중 모드 스킬은 <routing>, 엄격한 결과 계약은 <output_contract>, 인라인 참조 자료는 <reference>, 번들 파일 및 소스에 대한 포인터는 <resources>를 사용합니다. 태그는 일관되고, 설명적이며, 균형을 이루고, 작업이 요구하는 것보다 더 깊게 중첩되지 않아야 합니다. 표준-확장 매트릭스, 주장 감사 및 호스트별 검증 영수증은 references/portability-and-claim-audit.md에 있습니다.
작동 방식
Anthropic 가이드의 4단계 방법론입니다. 각 단계에는 완료 정의가 있습니다: 다음 단계를 시작하기 전에 충족되어야 하는 조건입니다.
| 단계 | 활동 | 완료 정의 |
|---|---|---|
| 1: 계획 및 설계 | 대상 호스트, 사용 사례, 카테고리, 성공 기준 정의 | 기준이 측정 가능하고 카테고리가 선택됨 |
| 2: 구현 | 폴더 생성, SKILL.md 작성, 리소스 추가 | audit-skill.sh가 실패를 보고하지 않음 |
| 3: 테스트 | 트리거링, 기능, 성능, 호환성, 순방향 테스트 | 모든 명명된 호스트가 검증 영수증과 함께 통과, 기준선 기록됨 |
| 4: 배포 | 패키징, 문서화, 게시 | 깨끗한 루트에서 설치 확인됨 |
1단계는 아래의 1-2단계를 다룹니다. 2-4단계는 3-5단계에 해당합니다.
각 단계에 걸리는 시간은 누가 또는 무엇이 실행하는지에 따라 다르므로, 이 스킬은 실제 시간 추정치를 명시하지 않으며, 여러분이 구축하는 스킬도 명시해서는 안 됩니다.
스킬 생성 워크플로
1단계: 요구 사항 파악
먼저 도메인을 조사하세요 — 지침을 작성하기 전에 호스트의 웹 도구를 사용하여 현재 모범 사례를 확인하세요. 오래된 지침은 없는 것보다 더 나쁩니다: 에이전트가 자신 있게 따릅니다.
모든 출처를 보관하세요: 확인한 내용에 대한 메모와 함께 참조한 모든 URL을 기록하세요. 출처가 없는 지침은 확인하거나 업데이트할 수 없습니다.
연구 전략, 출처 품질 기준 및 필수 출처 섹션 형식은 다음을 참조하세요: references/research.md
- 요청을 분류합니다: 작성(스킬 변경), 실행(스킬을 사용하여 결과 생성) 또는 평가(증거를 기반으로 스킬 판단). 작업 내용을 설계 입력으로 사용하기 전에 아티팩트와 변경 경계의 이름을 지정합니다(SKILL-REQ013).
- 문제와 대상 사용자를 식별합니다.
- 모든 대상 호스트와 버전, 검색 루트, 호출 형식 및 다시 로드 동작을 식별합니다. 알 수 없는 것은 추측하지 말고 알 수 없음으로 표시합니다. 병렬 패키지를 만들기 전에 기존 스킬 루트와 프로젝트 지침을 검사합니다.
- 2-3개의 구체적인 사용 사례를 정의합니다.
- 측정 가능한 성공 기준을 설정합니다(절약된 시간, 줄어든 오류, 향상된 품질).
- 스킬 카테고리를 선택합니다:
| 카테고리 | 입력 → 출력 | 예시 |
|---|---|---|
| 1: 문서 및 자산 생성 | 데이터/사양 → 문서, 코드, 보고서 | API 테스트 생성기, 회의록 요약기 |
| 2: 워크플로 자동화 | 작업 매개변수 → 완료된 다단계 프로세스 | 배포 파이프라인, 코드 리뷰 워크플로 |
| 3: MCP 개선 | MCP 도구 출력 → 더 스마트한 오케스트레이션 | 스마트 파일 검색, BigQuery 어시스턴트 |
심층적인 카테고리 지침: references/categories.md
대화형 파악 질문: references/discovery.md
2단계: 구조 설계
점진적 공개를 사용하여 설계 — 3가지 로딩 수준:
| 수준 | 로드 시점 | 대상 길이 | 내용 |
|---|---|---|---|
| 1: 메타데이터 | 항상 (~100 단어) | name + description | 트리거 조건 |
| 2: SKILL.md 본문 | 스킬 트리거 시 | 5,000단어 미만 (이상적으로는 2,000단어 미만) | 핵심 워크플로 + 포인터 |
| 3: references/ 파일 | 필요에 따라 | 무제한 | 심층 세부 정보, 스키마, 예시 |
점진적 공개 작성 팁 및 성공 메트릭: references/best-practices.md
3단계: 구현
중요 규칙:
- ✅ 파일 이름은
SKILL.md여야 합니다(README.md가 아님). - ✅ 폴더 이름은 케밥 케이스여야 합니다 — 공백이나 대문자 없음 (
my-skill이지My Skill이 아님). - ✅ YAML 머리말에는
name과description이 포함되어야 하며,metadata아래에 버전을 넣습니다. - ✅
description에는 특정 트리거 구문이 포함되어야 합니다 — 사용자가 스킬을 활성화하기 위해 말하는 내용입니다. - ✅ description은 1024자 미만이어야 합니다(하드 제한 — 더 긴 설명은 잘립니다).
- ✅ 머리말 필드에 XML 꺾쇠괄호(
<또는>)를 사용하지 마십시오 — Anthropic 스킬 가이드의 호스트 제한사항이며 YAML 규칙이 아닙니다. 본문은 영향을 받지 않습니다. - ✅ 본문: 모든 주요 섹션은 자체 줄에 균형 잡힌 설명적 XML 영역(
<purpose>,<requirements>,<workflow>,<examples>,<output_contract>) 안에 위치하며, 내부는 Markdown, 리터럴 소스는 펜스 코드 블록에 있습니다(SKILL-REQ004). H1 제목은 밖에 있을 수 있습니다. - ❌ 스킬 폴더 내에 README.md를 두지 마십시오 — 모든 문서는 SKILL.md 또는 references/에 넣습니다. (예외: GitHub 저장소 루트의 README.md는 스킬 폴더 외부에 있으므로 괜찮습니다.)
- ❌ 폴더 이름에 공백이나 밑줄을 사용하지 마십시오 (
my_skill→my-skill).
머리말: 필수 필드:
---
name: your-skill-name # 케밥 케이스만 가능, 공백, 대문자, 밑줄 없음
description: 무엇을 하는지 설명. 사용자가 "특정 구문", "다른 구문"을 요청할 때 사용.
# 반드시 포함: 하는 일 + 사용 시기(트리거 조건)
# 1024자 미만. XML 꺾쇠괄호 사용 금지.
# "claude" 또는 "anthropic"으로 시작하지 마십시오(예약된 네임스페이스).
---
모든 선택적 필드(license, compatibility, allowed-tools, metadata)와 호스트 휴대성 참고 사항: references/best-practices.md
포지셔닝 언어("테스트 생성 속도 87% 향상")는 저장소 README에 속하며 description에는 절대 넣지 마십시오. references/best-practices.md를 참조하세요.
폴더 구조(주석이 포함된 Claude Code 독립 실행형 예제: references/best-practices.md, 섹션 "폴더 구조 패턴"):
| 디렉토리 | 컨텍스트 로드? | 용도 |
|---|---|---|
references/ | 필요에 따라 예 | 스키마, API 문서, 정책, 워크플로 가이드 |
references/examples/ | 필요에 따라 | 사용자가 복사하여 수정하는 작동 코드 |
scripts/ | 아니요 (직접 실행) | 검증기, 스캐폴더, 유틸리티 |
assets/ | 아니요 (출력에 사용) | 스킬이 출력에 붙여넣는 이미지, 글꼴, HTML 템플릿 |
참고: 플러그인 스킬(plugin-name/skills/)은 examples/를 최상위 수준에 배치할 수 있습니다. 이는 플러그인 개발 규칙입니다. 독립 실행형 ~/.claude/skills/ 스킬의 경우 examples는 references/ 내부에 넣습니다.
새 스킬 스캐폴딩: bash scripts/scaffold-skill.sh my-skill-name
(다른 호스트의 루트를 대상으로 SKILLS_DIR 설정)
템플릿에서 시작하려면: references/examples/SKILL-template.md를 복사하세요.
4단계: 테스트
다섯 가지 테스트 접근 방식 (순서대로 실행):
- 트리거링 테스트 — 에이전트가 예상 구문에 활성화되고 관련 없는 요청에는 활성화되지 않는지 확인합니다.
- 기능 테스트 — 스킬의 핵심 워크플로가 알려진 입력에 대해 올바른 출력을 생성하는지 검증합니다.
- 성능 테스트 — 기준선 대비 개선 측정(절약된 시간, 오류 감소, 일관성).
- 호환성 테스트 — 모든 명명된 호스트 및 버전에서 검색, 명시적 호출, 참조 로딩, 스크립트 실행, 중복/이름 해결을 검증합니다. 각 호스트마다 새 세션을 시작하고, 호스트 자체 검증기가 있는 경우 실행하고(Codex는
skill-creator/scripts/quick_validate.py를 제공), 설치 프로그램 재실행, 여러 루트, 심볼릭 링크 대상, 수정된 사용자 파일 및 제거를 테스트하고, 호스트별 검증 영수증을 기록합니다(references/portability-and-claim-audit.md). - 순방향 테스트 — 현실적인 긍정, 부정, 모호 및 적대적 프롬프트; 스킬이 목록에 나타났는지 여부가 아니라 작업 결과를 판단하고, 근처 작업을 과도하게 트리거하지 않는지 확인합니다(SKILL-REQ012).
트리거 문제 디버깅:
에이전트에게 물어보세요: "[스킬 이름] 스킬을 언제 사용하시겠습니까?"
에이전트는 description을 그대로 인용해야 합니다. 누락되거나 너무 모호한 부분을 기반으로 조정하세요.
언더트리거링 수정: 더 구체적인 트리거 구문과 관련 기술 용어를 추가하세요.
오버트리거링 수정: description에 부정 트리거를 추가하세요:
description: PDF 법률 문서를 처리하여 계약 검토를 수행합니다. "이 계약 검토", "법률 문서 분석",
"계약 조항 추출"에 사용합니다. 일반 PDF 보기, 이미지 추출, 비법률 문서에는 사용하지 마십시오
(doc-converter 스킬을 대신 사용하세요).
네 가지 실패 모드를 모두 다루는 완전한 진단 및 수정 가이드: references/troubleshooting.md
구조 검증:
bash scripts/audit-skill.sh /path/to/YOUR-SKILL
5단계: 배포
참조: references/distribution.md
예시
사용 예시 1: 새 스킬 생성 (전체 워크플로)
사용자: "데이터베이스 스키마에서 REST API 문서를 생성하는 새로운 스킬을 만들어줘."
에이전트: 1단계를 시작하여 대상(Claude Code, Codex, Qwen Code)을 식별하고, 사용 사례를 정의하고(SQL 스키마 → API 문서), 카테고리(문서 및 자산 생성)를 선택합니다. 그런 다음 스캐폴딩을 진행합니다:
bash scripts/scaffold-skill.sh api-doc-generator
사용 예시 2: 기존 스킬 감사
사용자: "내 스킬을 감사해줘. references/portability-and-claim-audit.md를 확인하고 모든 요구 사항이 충족되는지 알려줘."
에이전트: references/portability-and-claim-audit.md를 읽고 13가지 P0 요구 사항 각각에 대해 SKILL.md를 검토한 후 결과를 표로 제공합니다.
사용 예시 3: 크로스 플랫폼 트리거 수정
사용자: "api-doc-generator 스킬이 Codex에서는 작동하지만 Claude Code에서는 트리거되지 않아."
에이전트: 두 환경의 트리거 구문과 파서 동작을 분석하고, description과 XML 영역을 조정하여 Cross-platform 호환성을 보장합니다.
<output_contract>
출력 계약
이 스킬은 다음 중 하나를 생성합니다:
- 유효한 SKILL.md 파일과 번들 리소스(새 스킬 생성 시)
- 기존 SKILL.md의 감사 보고서(감사 요청 시)
- 특정 요구 사항을 충족하도록 업데이트된 SKILL.md(개선 요청 시)
출력에는 항상 다음이 포함됩니다:
- P0 요구 사항 준수 상태 (SKILL-REQ001 ~ SKILL-REQ013)
- 테스트된 호스트 목록과 검증 상태
- 배포 지침 (해당하는 경우)
</output_contract>