Universal Skill Creator
1. 핵심 재구성 및 절대 불가침 불변 조건
- 정신 모델: 세계적 수준의 스킬은 주문형 절차 운영 체제이지, 구조화되지 않은 프롬프트가 아닙니다. 독점 실무자 IP와 결정론적 코드 게이트(3영역 하이브리드 아키텍처)를 결합하며,
references/agentskills_spec.md를 엄격히 준수합니다. - 환경 알림: Python 3 및 표준 작업 공간 탐색 도구가 사전 설치되어 있습니다. 명시적인 import 실패가 발생하지 않는 한 패키지 러너를 설치하려고 시도하지 마십시오.
- 하드 불변 조건 1 (0-스멜 게이트):
python3 scripts/audit_skill.py <path>를 통과하지 못하는 스킬은 절대 제공하지 마십시오. 모든 구조적 레이아웃 스멜을 감사하고 해결해야 합니다. - 하드 불변 조건 2 (스크립트 스미스 의무): 후보 스킬이 유효성 검사, 스키마 검사 또는 AST 비교를 수행할 때마다
scripts/validate.py에 동반 실행 유틸리티를 반드시 작성해야 합니다(스크립트 코드에 0 컨텍스트 토큰). - 하드 불변 조건 3 (압축 생존): 불변 조건, 패키지 알림 및 작업 라우팅 테이블은 압축 전단을 방지하기 위해
SKILL.md의 상위 1,000개 토큰 내에 위치해야 합니다(references/compaction_resilience.md참조). - 하드 불변 조건 4 (생산 표준): 모든 스킬은 도메인 표준 용어, 반-합리화 테이블 및 검증 가능한 평가 테스트 케이스를 포함해야 합니다.
- 하드 불변 조건 5 (구조뿐만 아니라 행동 게이트): 감사와 보안을 통과했지만 스킬 없는 기준을 이기지 못하거나, 압력 테스트를 견디지 못하거나, 스텁 모드에서 올바르게 라우팅되지 않는 스킬은 출시되지 않습니다.
references/baseline_grading.md,references/pressure_scenarios.md,references/stub_router_mode.md및references/render_qa.md를 참조하십시오. - 하드 불변 조건 6 (예제 구조만): 제공되는 예제는 구조, 트리거, 워크플로우, 결정 테이블, 검증 스크립트, 평가만 보여줍니다. 예제의 도메인 규칙을 새 스킬에 복사하지 마십시오. 모든 새 스킬은 사용자의 SOP, 기록 및 도메인 연구를 기반으로 구축하십시오.
2. 작업 라우팅 결정 테이블
| 사용자 의도 / 입력 유형 | 권장 생성 워크플로우 | 지원 주문형 참조 |
|---|---|---|
| 상업용 B2B 스킬 (판매/클라이언트 전달용) | 전체 6단계 파이프라인 실행 (Phase 0–5) | references/competitor_teardown_protocol.md |
| 원시 노트 / SOP / 개발자 기록 | 전체 6단계 생성 파이프라인 실행 | references/domain_knowledge_ingestion.md |
| 외부 API 또는 MCP 서버가 필요한 스킬 | Phase 1 도구 탐색 + MCP 와이어링 실행 | references/mcp_tool_patterns.md |
| 기존 스킬 감사 또는 수정 | 0-토큰 26-스멜 감사 및 패치 실행 | references/smell_taxonomy_26.md |
| 다중 턴 대화형 마법사 생성 | OMSC 모호성 분류 프로토콜 적용 | references/question_triage_omsc.md |
| 버전에 민감한 스킬 (CLI, API, 변경 가이드) | 스텁/라우터 모드 사용, 40-60줄 포인터만 | references/stub_router_mode.md |
| 모든 스킬, 모든 결정 단계에서 | QA 체크포인트 실행, 체크포인트당 최대 2개 질문, 모든 체크포인트 기록 | references/qa_checkpoints.md |
| .docx, .pdf, .ppt 또는 유사 형식의 입력 | 먼저 하네스 네이티브 읽기 사용 (Claude Code/Claude); 추출기는 선택적 폴백이며, 텍스트 전용 렉시콘 스크립트 전에만 필요 | scripts/extract_text.py |
| 스킬이 실제로 도움이 된다는 증명 | 압력 + 기준선 채점 + 렌더 QA 실행 | references/pressure_scenarios.md, references/baseline_grading.md, references/render_qa.md |
3. Phase 0: 심층 시장 인텔리전스 및 경쟁사 분석
지침을 작성하기 전에 agents/niche_researcher.md를 사용하여 경쟁 정찰을 수행합니다.
- Step 0.1 (경쟁사 분석): 이 니치에서 기존 공개 스킬, 프롬프트 또는 사용자 지정 지침을 검색합니다.
- 26-스멜 분류법(
references/competitor_teardown_protocol.md)에 대해 경쟁사 제공 항목을 감사합니다. - 구조적 결함(예: 일반적인 AI 쓰레기, 옵션 뷔페, 누락된 검증 스크립트)을 식별합니다.
- 경쟁사의 구조적 결함을 수정하는 해결책을 정의합니다.
- 26-스멜 분류법(
- Step 0.2 (도메인 문헌 및 용어 통합):
- 관련 서적, 백서, 팟캐스트 기록 및 엔터프라이즈 SOP를 다음 형식 중 하나로 통합합니다: .txt, .md, .docx, .pdf, 노트 및 기록.
- 형식 규칙, 하네스 우선, 엄격한 규칙 아님: Claude Code와 Claude는 .md, .pdf, .docx, .ppt 및 유사 형식을 기본적으로 읽으므로, 먼저 하네스의 자체 읽기를 사용합니다. 하네스가 이미 파일을 읽은 경우 추출을 강제하지 마십시오.
- scripts/extract_text.py의 패키지 추출기는 평문이 필요한 하네스 또는 스크립트를 위한 선택적 폴백입니다. 유일한 필수 사용 사례는 텍스트만 읽는 렉시콘 스크립트이므로, .docx 또는 .pdf에 대해 렉시콘을 실행하는 경우 먼저 .txt로 추출합니다:
python3 scripts/extract_text.py path/to/source.docx --output evals/source.txt python3 scripts/extract_text.py path/to/source.pdf --output evals/source.txt - 스캔된 이미지 전용 PDF는 텍스트 레이어가 없습니다. 추출기가 경고하고 텍스트를 반환하지 않습니다. 텍스트를 임의로 생성하지 말고, 이 패키지 외부에서 OCR을 사용하고 해당 단계를 기록하거나, 가능하면 Claude가 파일을 기본적으로 읽도록 하십시오.
references/domain_knowledge_ingestion.md에 따라 다음을 추출합니다:- 권위 있는 업계 약어, 메트릭 및 표준 용어(예: MEDDPICC, CAC 회수 기간, 후크 체류 시간).
- 후보 렉시콘 용어:
python3 scripts/build_domain_lexicon.py <sources> --output evals/lexicon.json. - 알고리즘 임계값 및 측정 가능한 공식.
- 명백하지 않은 실패 모드('footguns')의 고밀도 목록.
4. Phase 1: 환경 및 도구 탐색 (Zone 1 게이트)
문서를 작성하기 전에 이 탐색 단계를 복사하여 실행합니다.
- Step 1.1 (환경 및 도구 탐색): 번들된 탐색 스크립트를 실행합니다:
Windows PowerShell에서는python3 scripts/discover_env.pypython3 scripts/discover_env.py를 사용합니다.- 감지된 OS, 사용 가능한 CLI 바이너리(
git,docker,python등) 및 활성 MCP 서버에 대한 출력을 검사합니다. - 후보 스킬이 외부 서비스(예: Figma, GitHub, Postgres)를 포함하는 경우 환경에 일치하는 MCP 도구 또는 CLI가 있는지 확인합니다.
- 감지된 OS, 사용 가능한 CLI 바이너리(
5. Phase 2: 자동 작업 공간 탐색 및 OMSC 분류
- Step 2.1 (자동 컨텍스트 읽기): 활성 저장소 구성 파일(
package.json,pyproject.toml,Cargo.toml,.env.example, git 히스토리)을 검사합니다.- 엄격한 규칙: 작업 공간에서 파일을 읽어서 알 수 있는 언어, 프레임워크 또는 도구에 대해 사용자에게 질문하지 마십시오.
- Step 2.2 (QA 체크포인트, 모든 단계에서 필수):
references/qa_checkpoints.md를 따르십시오. Phase 2 분류만으로는 충분하지 않습니다. 각 체크포인트에서 5줄 결정 요약을 제시하고, (권장) 기본값과 함께 최대 2개의 질문을 하고 기록합니다:python3 scripts/record_qa.py evals/qa-checkpoints.json --checkpoint teardown-domain --summary "niche, antidote, top footguns" --question "Is the niche boundary right? (Recommended: yes)" --confirmed- 체크포인트 1, Phase 0 이후: teardown-domain, niche, competitors, loopholes, strengths, antidote, top footguns.
- 체크포인트 2, 아키텍처 이후, 초안 작성 전: architecture, 6-tier structure, routing table, script list, reference list, what it will NOT do.
- 체크포인트 3, 초안 워크플로우 이후, 게이트 전: draft-workflow, steps in order, decision tables, anti-rationalization entries, example input/output.
- 체크포인트 4, 게이트 이후, 패키징 전: gates, audit grade, security, pressure excuses closed, baseline delta, render QA.
- 체크포인트 5, 출시 전, 트리거 및 번들 이후: ship, trigger results, bundle contents, gatekeeper status, stub/router status if applicable.
- 영향 범위가 크거나, 상업적이거나, 상호 배타적인 아키텍처: 해당 체크포인트에서 사용자의 응답을 기다린 후 진행합니다. 영향 범위가 작은 경우: 요약을 제시하고 권장 기본값으로 진행하는 것이 허용되지만, 요약과 가정된 답변은 여전히 기록되어야 합니다. 기록이 없는 체크포인트는 발생하지 않은 것입니다.
- Step 2.3 (OMSC 모호성 필터):
- 목표, 메트릭, 범위 또는 제약 조건에 차단하는 미지수가 포함되어 있는지 확인합니다(
references/decision_matrices_and_escalation.md). - 영향 범위가 작거나 표준 워크플로우: 도메인 기본값을 사용하여 즉시 진행합니다. 질문을 0개 합니다.
- 영향 범위가 크거나 상호 배타적인 UX 분기: 중단하고 최대 1~3개의 간결한 질문을 합니다:
- 가장 안전한 기본 선택에
(권장)을 첨부합니다. - 한 줄로 된 장단점과 함께 2~3개의 문자 옵션을 제공합니다.
- 가장 안전한 기본 선택에
- 목표, 메트릭, 범위 또는 제약 조건에 차단하는 미지수가 포함되어 있는지 확인합니다(
6. Phase 3: 하이브리드 3영역 합성
전체 스킬 폴더 구조를 작성합니다: <skill-name>/는 SKILL.md, scripts/, references/, assets/를 포함합니다.
- Step 3.1 (6계층 아키텍처로 SKILL.md 작성):
agents/architect.md 역할을 채택하여
assets/master_template.md를 사용하여 핵심 사양을 합성합니다:- Byte 0:
---로 즉시 시작합니다. 머리말에 꺾쇠 괄호가 전혀 없습니다. - 계층 1 (토큰 1-500): 도메인 정신 모델 및 절대 불가침 불변 조건.
- 계층 2 (토큰 500-1,000): 작업 라우팅 결정 테이블(TOB/MDT 스멜 제거).
- 계층 3 (토큰 1,000-1,500): 자동 탐색 및 OMSC 모호성 분류.
- 계층 4 (토큰 1,500-3,000): 복사 가능한
- [ ]체크리스트가 포함된 번호 매기기 단계. - 계층 5 (토큰 3,000-4,200): 고밀도 도메인 Footgun 및 반-합리화 테이블.
- 계층 6 (토큰 4,200-4,800): 이 스킬이 수행하지 않는 작업(NG 스멜 제거).
- 전체 본문 제한: 450줄 미만 유지(<5,000 토큰).
- Byte 0:
- Step 3.2 (동반 결정론적 스크립트 및 비밀 템플릿 합성):
agents/script_smith.md 역할을 채택합니다:
- 검증용:
assets/script_templates/validator_template.py를 사용하여scripts/validate.py를 작성합니다. - 배치/파괴적 변경용:
scripts/validate_plan.py를 작성합니다. SKILL.md에requires_secrets:가 선언된 경우: 대시보드 URL 및 자리 표시자 값으로 스킬 루트에.env.example을 작성합니다.- 스크립트가 stdout에 간결한 JSON을 출력하고 통과 시 exit 0, 실패 시 exit 1을 반환하도록 합니다.
- 검증용:
- Step 3.3 (심층 문서를 플랫 참조로 위임):
도메인 플레이북, 스키마 또는 보조 가이드가 50줄을 초과하는 경우
references/<topic>.md에 배치합니다.- 불변 조건: 참조는
SKILL.md에서 정확히 1홉 깊이의 플랫이어야 합니다.
- 불변 조건: 참조는
7. Phase 4: 제로-토큰 구조적 26-스멜 감사 및 평가
- Step 4.1 (자동화된 정적 린터 실행):
새로 생성된 스킬 디렉토리에 대해 구조적 린터를 실행합니다:
python3 scripts/audit_skill.py path/to/generated-skill - Step 4.2 (결정론적 보안 스캔 실행):
원격 코드 실행, 셸 인젝션 또는 자격 증명 누출이 없음을 확인하기 위해 AST 보안 스캐너를 실행합니다:
python3 scripts/security_scan.py path/to/generated-skill - Step 4.3 (모든 위반 및 스멜 패치):
감사에서 위반 사항을 보고하는 경우 agents/smell_auditor.md 역할을 채택합니다:
- 합리화 허점 (RL): 모델 변명을 반박하는 명시적인 반-합리화 테이블을 추가합니다.
- 옵션 뷔페 (TOB): 도구 목록을 시나리오당 단일 기본 도구로 교체합니다.
- 긴 본문 (LSB): 긴 코드 조각을
references/또는assets/로 이동합니다. - 등급이 A 또는 **A+**인 PASS 상태가 될 때까지
audit_skill.py를 다시 실행합니다.
- Step 4.4 (경험적 벤치마크 평가 실행):
검증 가능한 작업 통과율을 설정하기 위해 테스트 케이스를 실행합니다:
python3 scripts/run_evals.py path/to/generated-skill- 수정의 경우 agents/comparator.md 역할을 채택하여 기준과 이중 맹검 비교를 수행합니다.
- Step 4.5 (압력 시나리오, 필수):
결합된 압력 시나리오를 생성한 다음, 스킬 없이 AND 스킬을 사용하여 각각 실행하고 말 그대로의 변명을 기록합니다(
references/pressure_scenarios.md):python3 scripts/generate_pressure_scenarios.py path/to/generated-skill evals/pressure-scenarios.json- 생성된 스킬은 최소한 가장 일반적인 기준 변명 3개를 포함하는 생각 | 현실 테이블을 포함해야 합니다. 기준선과 스킬 사용 실행이 동일하다면 스킬이 아무것도 변경하지 않은 것입니다. 출시하지 마십시오.
- Step 4.6 (스킬 사용 vs 기준선 채점, 필수):
동일한 턴에서 스킬 사용 및 기준선 실행을 생성하고 agents/grader.md로 채점한 다음, 채점자 계약 및 출시 게이트의 유효성을 검사합니다(
references/baseline_grading.md):python3 scripts/grade_baseline.py --with evals/grading-with.json --baseline evals/grading-baseline.json- 스킬 사용 pass_rate >= 80%, 델타 > 0, 회귀가 없으며, 피드백.json에 이유와 함께 사람의 면제가 기록되지 않는 경우에만 출시합니다.
- Step 4.7 (렌더 QA, 출력에 필수):
스킬이 생성하는 모든 것에 대해 콘텐츠 및 파일 게이트를 실행하고, 출력이 시각적인 경우 사람이 육안 검사합니다(
references/render_qa.md):python3 scripts/render_qa.py path/to/generated-skill- 이 스크립트는 시각적 통과를 주장하지 않습니다. 시각적 통과는 사람이 수행하고 기록해야 합니다.
8. Phase 5: 트리거 확인 및 패키징
- Step 5.1 (트리거 정밀도 및 재현율 테스트):
대표적인 긍정 및 부정 프롬프트로 YAML 설명을 테스트합니다:
python3 scripts/test_skill_trigger.py path/to/generated-skill - Step 5.2 (설명 최적화, 학습/테스트 분할):
트리거 쿼리를 60% 학습 / 40% 테스트로 분할하고, 각 분할에 대해 트리거 테스트를 별도로 실행하고, 학습 점수가 아닌 테스트 점수로 최상의 설명을 선택합니다. 근접 실패 부정만; PDF 스킬에 대한 나쁜 부정은 "Write a fibonacci function"이고, 좋은 부정은 인접 작업에 대한 길고 지저분한 요청입니다:
python3 scripts/eval_description_split.py path/to/generated-skill - Step 5.3 (기술 메타데이터 완성):
최종
SKILL.md머리말과 번들 루트의tech.json에 다음을 포함합니다:requires_secrets:키, 키 이름 목록(예:FIGMA_ACCESS_TOKEN). 비밀이 필요하지 않은 경우requires_secrets: []를 사용합니다.platform:(CLAUDE_CODE, CURSOR, CODEX, OLLAMA, MCP, MULTI 중 하나).version:(생성 스크립트가 자동으로 실행된 경우"1.0.0").agent_hooks:(하네스별: CLAUDE_CODE의 경우.claude/settings.json에 추가).
- Step 5.4 (스킬 가져오기 및 게이트키퍼):
agents/gatekeeper.md를 실행합니다:
python3 scripts/gatekeeper.py path/to/generated-skill- 게이트키퍼는 감사, 보안, 벤치마크 평가, 압력 시나리오, 기준선 채점, 렌더 QA의 6가지 출시 게이트 상태를 모두 포함하는 JSON 레코드를 기록하고 평가합니다. 모든 게이트가 통과된 경우에만 출시합니다.
- Step 5.5 (번들 대상):
번들의 마지막 단계:
python3 scripts/bundle_skill.py path/to/generated-skill --output dist/- 심층 분석, 포스트모템 및 모든 기록:
evals/에 있어야 합니다. 번들은dist/<skill-name>.json또는<skill-name>.tar.gz를 생성합니다. - 기술 분류, 출시 게이트 현황, 이름, 필수 비밀, 플랫폼, 버전 및 소스 URL이 포함된 기술 JSON 파일.
- 게이트키퍼 출력.
- 5.1 및 5.2의 트리거 정밀도/재현율 결과.
- 학습-테스트 스플릿 점수.
- 압력 없는(기준선) 및 압력 있는(스킬) 텍스트 이력서 조각.
- 심층 분석, 포스트모템 및 모든 기록:
9. 스킬 예제(구조 전용)
agents/gatekeeper.md는 실용적인 예제를 제공합니다.
10. 참조
references/competitor_teardown_protocol.md— 경쟁 스킬 분석references/domain_knowledge_ingestion.md— 도메인 문헌 통합references/mcp_tool_patterns.md— MCP 서버 패턴references/smell_taxonomy_26.md— 26-스멜 분류법references/question_triage_omsc.md— OMSC 모호성 분류references/stub_router_mode.md— 버전에 민감한 스킬을 위한 스텁/라우터 모드references/qa_checkpoints.md— QA 체크포인트 가이드references/pressure_scenarios.md— 압력 시나리오 지침references/baseline_grading.md— 기준선 채점 지침references/render_qa.md— 렌더 품질 보증references/compaction_resilience.md— 압축 복원력references/decision_matrices_and_escalation.md— 결정 매트릭스 및 에스컬레이션