Elites Skills Architect

대략적인 아이디어를 실제로 동작하는 스킬로 전환합니다: 발견, 명세, 검증, 테스트 실행, 사람 검토, 설명 튜닝 및 패키징. 스킬에 대한 모든 주장은 한 번 읽고 기분 좋다고 끝나는 것이 아니라, 스크립트나 등급 평가 실행을 통해 뒷받침됩니다.

시작 위치

8단계. 사용자가 어디에 있는지 찾아서 그곳에서 시작하세요:

발견(Discovery): 구체적인 문제와 명세를 작성하는 데 필요한 사실 수집
문제 플래깅(Flag problems): 너무 단순함, 너무 광범위함, 중복, 모순
분류(Categorise): 문서 생성, 워크플로 자동화 또는 MCP 향상
구축 및 검증(Build and validate): 프론트매터, 본문, 폴더, 평가, scripts/validate_spec.py
테스트 및 리뷰(Test and review): 평가 실행, 출력 표시, 등급 부여, 스킬이 시행하는 모든 규칙 압력 테스트
개선(Improve): 단일 사례가 아닌 피드백 이면의 패턴 수정
설명 튜닝(Description tuning): 트리거 테스트 및 scripts/optimize_description.py
패키징(Package): scripts/package_skill.py

사용자에 맞춰 속도를 조절하세요. "MCP 서버"와 "프론트매터"를 자발적으로 말하는 사람은 빠른 진행을 원합니다. "Claude가 제 인보이스를 처리했으면 좋겠어요"라고 말하는 사람은 한 번에 하나씩 질문으로 안내받기를 원합니다. 평범한 영어로, 사용자가 먼저 사용하지 않은 전문 용어는 사용하지 마세요.

모든 스크립트는 표준 라이브러리 Python 3.9 이상이며, 스킬 루트에서 실행됩니다:

cd <path-to-elites-skills-architect>
python3 scripts/validate_spec.py <skill-folder>

1단계: 발견

references/discovery-questions.md에서 질문 은행과 약한 답변에 대한 후속 질문을 읽으세요. 두세 개씩 묶어서 질문하고, 답변에 기반하여 진행하며, 목록을 한 번에 던지지 마세요.

배치 1, 문제: 스킬이 반드시 생성해야 하는 하나의 결과물; 사용자가 실제로 말할 5~10개의 구문; 스킬이 처리하지 말아야 할 것. 배치 2, 데이터: 입력과 그 형식; 사용자가 작업이 잘 되었을 때 가지고 있던 것; 입력에서 자주 발생하는 문제. 배치 3, 워크플로: 단계 순서; 종속성; if/then 경로; 3단계가 실패하면 1단계와 2단계에 어떤 일이 발생하는지. 배치 4, 통합: MCP 서버, API, Claude 내장 기능, 인증 및 속도 제한. 배치 5, 복원력: 가장 발생 가능성이 높은 세 가지 런타임 실패; 완전 실패 시 메시지.

다음 네 가지를 모두 추측 없이 할 수 있을 때 질문을 중단하세요: 실제 트리거 구문으로 설명을 작성하고, 모든 단계를 순서대로 나열하고, 세 가지 실패 모드와 그 처리를 명명하고, 다른 개발자가 구축할 수 있을 만큼 스킬을 설명하는 것.

사용자가 이미 지식을 문서화해 놓았다면(핸드북, API 문서, 스타일 가이드, 저장된 웹 페이지), 다시 입력하는 대신 가져오세요:

python3 scripts/import_sources.py <files-or-folders> --skill <skill-folder> --dry-run

Markdown, 텍스트 및 저장된 HTML을 참조 파일로 변환하고, 긴 파일은 제목에서 분할하며, 그 옆에 sources-index.md를 작성하고 본문에 사용할 "Y 때 X 읽기" 줄을 출력합니다. 절대 다운로드하지 않습니다. 먼저 페이지를 저장하세요.

2단계: 구축 전에 문제 플래깅

너무 단순함: Claude가 이미 수행합니다. 스킬은 도메인 로직이나 매번 적용해야 하는 형식이 있을 때 자리를 잡습니다. 그런 것이 있는지 물어보세요.
너무 광범위함: 여러 관련 없는 워크플로. 분할을 제안하세요. 작은 스킬이 더 안정적으로 트리거됩니다. 어떤 것이 먼저인지 물어보세요.
중복: docx, pptx, xlsx, pdf 또는 프론트엔드 디자인에 가까움. 그렇게 말하고 확장할 것인지 다른 것을 만들 것인지 물어보세요.
불가능하거나 안전하지 않음: 솔직하게 말하고 가장 가까운 실행 가능한 버전을 제시하세요.
모순: 처음에는 "완전 자동", 지금은 "먼저 물어봐". 한 줄도 쓰기 전에 해결하세요.

3단계: 분류

references/categories-and-patterns.md를 읽으세요. 하나를 선택하세요:

카테고리 1, 문서 및 에셋 생성: Claude 내장 기능으로 파일을 만듭니다. 발견 배치 1과 2면 충분합니다.
카테고리 2, 워크플로 자동화: 도구 간의 정렬된 단계, 검증 게이트, 부분 실패 또는 롤백. 모든 5개 배치.
카테고리 3, MCP 향상: 판단 및 기본값으로 기존 MCP 서버를 래핑합니다. 배치 1, 2, 4.

사용자에게 카테고리와 그 이유를 알려주세요. 혼합도 괜찮습니다. 설명과 폴더 레이아웃을 위해 주요 카테고리를 선택하세요.

4단계: 구축 및 검증

아무것도 생성하기 전에 references/worked-example.md를 한 번 읽어서 출력이 해당 수준의 세부 사항과 일치하도록 하세요. references/spec-output-template.md를 뼈대로 사용하세요.

4a: 프론트매터

references/yaml-rules.md를 읽으세요. 검증기가 확인하는 사항(표시되지 않으면 오류):

name: kebab-case, "claude" 또는 "anthropic" 없음; 폴더 이름과 일치 (경고, --portable 사용 시 오류)
description: 1~~1024자; 동작 동사, 무엇을 만드는지, 언제 사용하는지, 큰따옴표로 묶인 3~~8개의 트리거 구문, 부정 범위 (길이는 오류; 동사, 구문 및 부정 범위는 경고)
꺾쇠 괄호, 탭, 스마트 따옴표 또는 하이픈 외의 대시 없음
설명에 아포스트로피 없음 (경고; 일부 업로드 파서가 거부함)
태그는 하나의 문자열로, tags: "a, b, c", 절대 [a, b, c] 아님 (경고); 숫자처럼 보이는 메타데이터 값은 따옴표로 묶음, version: "1.0"

설명을 적극적으로 만드세요. 테스트에서 Claude는 스킬을 잘못 선택하는 것보다 사용하지 않는 경우가 더 많았으므로, 간접 요청에 대해 "또한 누군가 ...를 언급할 때 트리거됨"을 추가하세요.

4b: 본문

최대 500줄, 명령형이며, 무엇뿐만 아니라 이유도 설명합니다. 순서: 한 줄 목적; 사용 시기와 사용하지 않을 시기; 각각 확인이 있는 번호 매겨진 단계; 두세 가지 예시 (구문, 동작, 결과); 원인과 대응을 포함한 오류 처리; 간단한 모범 사례. 더 큰 내용은 references/로 옮기고 "Y 때 X 읽기"로 가리키세요.

4c: 폴더

skill-name/
  SKILL.md
  evals/evals.json        테스트 케이스, references/schemas.md 참조
  scripts/                모델이 다시 유도하지 말아야 할 결정적 로직
  references/             필요 시 로드되는 심층 자료
  assets/                 템플릿 및 샘플

스킬 폴더 안에 README.md 없음; 문서는 SKILL.md와 references/에 있습니다.

4d: 테스트 계획 및 평가

트리거되어야 하는 5개 이상의 쿼리와 트리거되지 말아야 하는 5개 이상의 쿼리를 작성하세요. 좋은 쿼리는 구체적이고 사람처럼 들립니다: "좋아, 체크아웃 리디자인 월요일에 시작, Linear에서 스프린트 설정, 2주, 프론트엔드 팀". 최고의 부정 쿼리는 긍정 쿼리와 단어를 공유하지만 다른 것을 원합니다: 실행 대신 조언, 생성 대신 보고.

2~3개의 평가를 evals/evals.json에 작성하세요 (형식은 references/schemas.md 참조). 각 기대치는 하나의 확인 가능한 문장입니다. 실행하기 전에 사용자에게 보여주세요.

4e: 검증

python3 scripts/validate_spec.py <skill-folder>
python3 scripts/validate_spec.py <skill-folder> --json     # 도구용
python3 scripts/validate_spec.py <skill-folder> --strict   # 경고도 실패 처리
python3 scripts/validate_spec.py <skill-folder> --portable # Claude 외 에이전트용

프론트매터 규칙, 본문 길이, 위의 섹션, 남아 있는 플레이스홀더, evals.json, pressure-evals.json (있는 경우), 그리고 본문에서 언급된 모든 scripts/... 또는 references/... 경로가 존재하는지 확인합니다. 모든 오류를 수정하세요. 실패하는 명세를 절대 보여주지 마세요. --portable은 다른 에이전트에서도 실행될 스킬에 대해 오픈 에이전트 스킬 명세 규칙(폴더 이름이 일치해야 함, 메타데이터 값은 텍스트여야 함)을 추가합니다.

5단계: 테스트 및 리뷰

하나의 시퀀스; 중간에 멈추지 마세요.

5a: 평가 실행

작업 공간 레이아웃 (references/schemas.md에 전체 트리):

<skill-name>-workspace/iteration-1/eval-<id>/<configuration>/run-<k>/outputs/

각 eval-<id>/ 폴더에 eval_metadata.json을 작성하세요. 그런 다음 각 평가를 실행하세요:

서브 에이전트 사용 (Claude Code, Cowork): 동일한 턴에서 모든 평가에 대해 스킬 있음과 스킬 없음 실행을 시작하세요. 각 실행자는 스킬을 읽고, 프롬프트를 수행하고, 파일을 outputs/에 저장하고, 확실하지 않은 내용에 대해 outputs/user_notes.md를 작성하고, outputs/metrics.json을 작성합니다. 작업 알림에서 즉시 timing.json을 저장하세요. 숫자는 다른 곳에 보관되지 않습니다.
서브 에이전트 없음 (claude.ai): SKILL.md를 읽고 각 프롬프트를 직접, 하나씩, 동일한 폴더에 수행하세요.

5b: 실행 중에 단언문 초안 작성

측정 가능한 기대치를 eval_metadata.json과 evals/evals.json에 추가하세요. 각각을 한 문장으로 사용자에게 설명하세요. 취향에 대한 단언문은 건너뛰세요. 사람이 판단합니다.

5c: 판단하기 전에 출력 먼저 보여주기

python3 eval-viewer/review.py <skill-name>-workspace/iteration-1 --skill-name <name>

페이지가 브라우저에서 열리고, 오프라인으로 작동하며, 사용자가 입력하는 대로 피드백을 작업 공간의 feedback.json에 저장합니다. Cowork에서 또는 서버를 사용할 수 없을 때는 --static review.html을 추가하세요. 피드백은 파일로 다운로드됩니다. 먼저 뷰어를 열고, 두 번째로 출력물을 직접 살펴보세요. 사용자가 반응하기 전에 스킬을 변경하지 마세요.

5d: 등급 부여 및 벤치마킹 (서브 에이전트)

agents/grader.md로 각 실행에 등급을 부여하세요. 가능하면 평가를 실행한 모델과 다른 모델을 사용하세요. 모델은 자신의 작업을 제대로 평가하지 못합니다.

집계:

python3 scripts/aggregate_benchmark.py <skill-name>-workspace/iteration-1 --skill-name <name>

벤치마크 탭을 위해 --benchmark <iteration>/benchmark.json으로 뷰어를 다시 여세요. 평균이 숨기는 패턴에 대해서는 agents/analyzer.md 작업 2를 실행하세요.

5e: 압력 테스트 (규칙을 시행하는 스킬)

스킬의 가치가 반드시 유지되어야 하는 규칙(형식, 확인, 승인 단계)일 때, references/pressure-tests.md를 읽고 3~5개의 시나리오를 evals/pressure-evals.json에 작성하세요: 구체적인 상황, 두 가지 이상의 압력(마감일, 상사, 클라이언트 요청, 이미 소요된 시간), 그리고 유혹적인 타협을 포함한 강제 선택.

python3 scripts/pressure_eval.py --skill-path <skill-folder> \
  --scenarios <skill-folder>/evals/pressure-evals.json --runs 3 --model <model-id> \
  --output <skill-name>-workspace/pressure-results.json \
  --report <skill-name>-workspace/pressure-report.md --dry-run

사용자가 호출 횟수를 승인한 후 --dry-run을 제거하세요. 각 시나리오는 스킬 없이와 스킬 있이 실행됩니다. "스킬이 유지되지 않음"은 보고서에 Claude가 제시한 변명이 포함되어 있음을 의미합니다. 스킬에서 각각을 반박하고(이름을 지정하고, 왜 잘못되었는지 설명하고, 무엇을 해야 하는지 말함) 다시 실행하세요. "통과했지만 기준선도 통과함"은 시나리오가 너무 쉬워서 아무것도 증명할 수 없음을 의미합니다.

6단계: 개선

피드백 이면의 패턴을 찾아서 수정하세요. 세 번의 테스트 프롬프트가 전부가 아닙니다. 출력물뿐만 아니라 대화록도 읽고, 모델이 단계를 낭비하게 만든 지침을 잘라내세요. ALWAYS 또는 NEVER를 대문자로 쓰고 있다면 멈추고 대신 이유를 설명하세요. 이유가 있는 모델이 규칙만 있는 모델보다 더 멀리 갑니다. 모든 실행이 동일한 도우미를 작성했다면 그것을 scripts/에 넣고 그렇게 말하세요. 세 가지 평가만 통과하고 그 외에는 아무것도 통과하지 못하는 스킬을 조심하세요.

그런 다음: 변경 사항을 적용하고, 모든 평가를 iteration-2/에 다시 실행하고, --previous-workspace iteration-1로 뷰어를 열어 사용자가 이전과 새 결과를 나란히 볼 수 있게 하고, 피드백을 읽고, 반복하세요. 사용자가 만족하거나, 피드백이 없거나, 진전이 정체될 때 중단하세요.

엄격한 이전 대 이후 비교를 위해서는 agents/comparator.md (스왑 확인이 있는 블라인드 A/B 평가자)를 사용한 다음 agents/analyzer.md 작업 1로 결과를 설명하세요. 선택 사항입니다. 일반적으로 리뷰 루프로 충분합니다.

7단계: 설명 튜닝

설명은 Claude가 스킬을 선택하게 만드는 요소입니다. 스킬 자체가 작동하면 튜닝하세요.

7a: 트리거 쿼리

20개의 쿼리를 evals/trigger-evals.json에 작성하세요: 약 절반은 트리거되어야 하고, 절반은 트리거되지 말아야 합니다. 일상적인 대화, 파일 이름, 개인적인 맥락을 포함하세요. 가치 있는 부정 쿼리는 근접 실패입니다. 목록을 사용자에게 보여주고 변경을 요청하는 대로 변경하세요. 나쁜 쿼리는 나쁜 설명을 만듭니다.

7b: 지출 전에 카운트

python3 scripts/trigger_eval.py --skill-path <skill-folder> --eval-set <skill-folder>/evals/trigger-evals.json --dry-run

모든 실행은 claude -p 호출입니다. 사용자에게 숫자를 알리고 승인을 받으세요.

7c: 측정

python3 scripts/trigger_eval.py --skill-path <skill-folder> \
  --eval-set <skill-folder>/evals/trigger-evals.json \
  --runs-per-query 3 --workers 4 --model <model-id> \
  --output <skill-name>-workspace/trigger-results.json --verbose

스크립트는 임시 프로젝트에 스킬을 설치하고 해당 프로젝트 설정으로만 Claude를 실행하므로 사용자의 실제 프로젝트에 영향을 주지 않으며 다른 스킬이 간섭할 수 없습니다. 요약을 읽으세요: 놓친 쿼리(거짓 음성)는 설명이 너무 좁다는 것을 의미합니다. 잘못 발생한 쿼리는 너무 넓다는 것을 의미합니다. 실행이 모두 오류가 발생한 쿼리는 알 수 없음으로 보고되며, 통과로 보고되지 않습니다.

7d: 최적화 (Claude Code 전용)

python3 scripts/optimize_description.py --skill-path <skill-folder> \
  --eval-set <skill-folder>/evals/trigger-evals.json --model <model-id> \
  --max-iterations 4 --results-dir <skill-name>-workspace/description-runs --verbose

쿼리를 학습 세트와 유보 세트로 한 번 분할하고, 평가하고, 학습 실패만 사용하여 더 나은 설명을 Claude에 요청하고, validate_spec.py와 동일한 규칙으로 후보를 검증하고, 반복합니다. 승자는 최고의 학습 점수를 가진 반복입니다. 동점은 더 짧은 텍스트가 승리합니다. 유보 점수는 보고되지만 선택에 사용되지 않으므로 정직한 확인으로 남습니다. 학습 점수보다 훨씬 낮으면 설명이 학습 쿼리에 맞춰 튜닝된 것입니다. results.json, report.md 및 best-description.txt를 작성하고, 승자가 모든 학습 쿼리를 통과할 때만 0으로 종료됩니다. claude.ai에서는 실패를 읽고 수동으로 다시 작성하세요.

7e: 적용

승자를 SKILL.md에 붙여넣고, 점수와 함께 이전과 이후를 사용자에게 보여주고, scripts/validate_spec.py를 다시 실행하세요.

8단계: 패키징

python3 scripts/package_skill.py <skill-folder> --output dist/
python3 scripts/package_skill.py --inspect dist/<skill-name>.skill

패키징은 먼저 검증하고 오류 시 거부합니다(--allow-warnings가 없으면 경고도). 아카이브는 재현 가능하며 SHA-256을 출력합니다. 사용자에게 경로 또는 파일을 제공하세요.

[truncated for translation]

elitesalgorithm/elites-skills-architect

elites-skills-architect란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

문서