devetai/better-skill-gen

Better Skill Generator (better-skill-gen)

이 스킬은 메타 스킬의 역할을 합니다. 사용자로부터 아이디어, 문제 또는 업무 프로세스를 입력받아, 사용자와 함께 설계를 확정한 후, 선택된 각 제공자(Provider)에 맞게 완전한 스킬 디렉토리를 생성합니다:

제공자	디렉토리 (프로젝트 범위)	특징
Codex 및 Antigravity	.agents/skills/<skill-name>/ (하나의 공유 버전)	name, description만 포함; Codex의 경우 agents/openai.yaml의 스킬 호출 정책 추가
Claude Code	.claude/skills/<skill-name>/	확장된 여러 frontmatter 필드 포함 (references/frontmatter-spec.md 참고)

이 파일은 Codex와 Antigravity에 공통으로 사용됩니다. 이 파일 내 모든 scripts/..., references/... 경로는 이 SKILL.md가 위치한 디렉토리를 기준으로 합니다. "명령 실행"은 현재 사용 중인 제공자의 셸 명령 실행 도구(예: Antigravity의 run_command)를 사용하는 것을 의미합니다.

---

1. 핵심 설계 원칙

1. 점진적 공개 3단계 아키텍처:
   • 1단계: 메타데이터 (시작 시 항상 로드): YAML Frontmatter의 name, description. 토큰을 거의 소모하지 않으며, description은 1,536자 미만으로 유지합니다.
   • 2단계: 지시사항 (스킬이 활성화될 때만 로드): SKILL.md 본문, 반드시 500줄 미만. 워크플로우, 핵심 원칙 및 제약 조건만 포함합니다.
   • 3단계: 리소스 (실제로 필요할 때만 로드): templates/ (결과 템플릿), examples/ (Gold Standard 예제 텍스트), references/ (기술 사양), scripts/ (context를 소모하지 않고 무거운 작업을 처리하는 bash/python 코드).
2. 스킬 목적 분류:
   • Reference Skills: 코딩 규칙, 시스템 지식, 디자인 패턴 등을 에이전트가 배경 지식으로 활용할 수 있도록 제공합니다.
   • Task Skills: 실행 단계별 행동 절차. 부작용(배포, 커밋, 데이터 삭제 등)이 있는 작업은 사용자가 직접 호출할 때만 실행되어야 합니다. .agents/skills/ 버전은 두 가지 작업을 수행합니다: policy.allow_implicit_invocation: false가 포함된 agents/openai.yaml 생성 (Codex용) 및 "사용자가 직접 요청할 때만 사용"이라는 문구를 description에 기록 (동등한 필드가 없는 Antigravity용). 자세한 내용은 references/providers.md 3항을 참조하세요.
3. 제공자별 고유 기능: Claude Code는 SKILL.md 내에서 subagent, 매개변수 변수 및 셸 명령 삽입을 지원합니다 (references/frontmatter-spec.md 참고). 이러한 기능은 Claude Code 버전에서만 사용하고, 다른 제공자용 버전은 references/providers.md 3항에 따라 변환합니다.
4. 검증하라, 신뢰하지 마라 (자체 검증):
   • 생성된 모든 스킬에는 표준 종료 코드(0 = 통과, 1 = 실패)를 가진 scripts/validate.sh가 포함되어야 합니다.
   • markdownlint 표준에 따른 모든 린팅 규칙을 100% 준수합니다.
5. Zero Workspace Pollution:
   • 모든 설정 파일, 리소스 및 스크립트는 각 제공자 디렉토리의 스킬 패키지 디렉토리 내에만 위치합니다.
   • 모든 예제 문서는 스킬의 examples/ 디렉토리 내에만 위치합니다. 프로젝트의 다른 업무 디렉토리(예: src/, 프로젝트 루트)에 예제 파일을 생성하거나 복사하지 않습니다.
   • 테스트 중 생성된 임시 파일은 운영 체제의 임시 디렉토리(또는 사용자 지침에 지정된 임시 디렉토리)에 기록하고, 작업 완료 후 즉시 정리합니다.
6. 사용자에게 구조화된 선택지로 질문:
   • 사용자에게 제공되는 모든 선택지(범위, 제공자, 아이디어의 불명확한 점, 설계 방향 등)는 선택지 형식으로 질문합니다. 세션에 답변 선택 도구가 있다면 해당 도구를 사용합니다. 없다면 번호가 매겨진 선택지를 나열한 후, 중단하고 사용자의 응답을 기다립니다.
   • 제시 순서: (1) 생성할 스킬의 용도, (2) 질문의 내용과 그 이유, (3) 각 선택지의 장단점을 설명하는 한 줄씩 포함된 선택지 목록, (4) 목록 상단에 (권장)으로 표시된 권장 선택지.
   • 한 번에 최대 4개의 질문을 하며, 중요한 질문을 먼저 합니다. 항상 사용자가 제시된 선택지와 다른 답변을 할 수 있도록 허용합니다.
   • 사용자의 응답 없이 사용자를 대신하여 선택하지 않습니다.
7. 제공자별 규격에 맞는 별도 버전:
   • 공유 리소스(template.md, examples/, references/, scripts/)는 그대로 복사합니다. SKILL.md(및 Codex용 agents/openai.yaml)는 별도로 작성됩니다: 하나는 Claude Code용, 다른 하나는 Codex와 Antigravity 공용입니다.
   • Codex/Antigravity 버전은 두 제공자 모두에서 올바르게 실행되어야 합니다. 오픈 표준 frontmatter 필드만 사용하고, Claude Code만 이해하는 변수나 도구를 사용하지 않으며, 실행 중인 에이전트를 "Claude"라고 부르지 않습니다. Claude는 스킬의 주제일 때만 언급할 수 있습니다.

---

2. 필요한 입력 (Inputs)

• 필수: 생성할 스킬의 아이디어 또는 업무 목표에 대한 설명.
• 선택 사항: 특정 제약 조건, 사용할 도구, 작업 유형 또는 참고 자료.
• 필수 질문 (새 스킬 생성 시마다): 범위 및 제공자 (항목 2.1), 그리고 아이디어의 모든 불명확한 점 (항목 2.2). 사용자가 요청 시 이미 명확히 답변한 질문은 건너뜁니다.
• 불명확한 점을 스스로 결정하지 않음: 아이디어가 빈약하면 분석하고 제안합니다 (항목 2.2). 임의로 채우고 파일을 생성하지 않습니다. 명백한 규칙이 있는 경우(예: kebab-case 이름을 아이디어에서 유추)에만 자동으로 설정할 수 있으며, 설계 요약서에 명시해야 합니다.

2.1. 적용 범위(Scope) 및 제공자(Provider) 질문

파일을 생성하기 전에 원칙 6에 따라 동일한 라운드에서 2개의 질문을 합니다:

1. 범위 (다중 선택 가능): 아래 표에 따른 세 가지 선택지, project-shared가 권장됩니다.
2. 제공자 (다중 선택 가능): Codex, Claude Code, Antigravity. 스킬을 모든 제공자에서 사용할 수 있다면 세 가지를 모두 권장합니다. 스킬이 특정 제공자에게만 의미가 있는 경우(예: Claude Code의 설정 파일만 확인) 해당 제공자만 권장하고 그 이유를 명확히 설명합니다.

범위	의미	기준 디렉토리	스크립트 실행 시 변수
project-shared	현재 프로젝트 전용, 팀 전체 공유 (git 커밋)	프로젝트 루트	SCOPE=project (기본값)
project-personal	현재 프로젝트 전용, 이 사용자만 사용 (커밋 안 함)	프로젝트 루트	SCOPE=project, 생성된 디렉토리를 .git/info/exclude에 추가
user-global	이 사용자의 모든 프로젝트	$HOME	SCOPE=user

규칙:

• 사용자가 여러 범위를 선택하면 각 범위를 순차적으로 배포합니다.
• 프로젝트 디렉토리가 git 저장소가 아닌 경우 project-personal 선택지를 제거합니다.
• 선택된 범위 및 제공자를 생성된 경로 목록과 함께 인계 보고서에 기록합니다.
• 사용자가 user-global을 선택했는데 스킬 내용이 프로젝트에 특화된 경우: 생성 전에 한 줄 경고를 표시합니다.

2.2. 아이디어 분석 및 제안

범위와 제공자를 확인한 후, 파일을 작성하기 전에 아이디어를 분석합니다:

1. 이해한 내용 요약: 스킬이 해결하는 문제, 사용자, 활성화 시점, 출력물.
2. 설계 포인트 식별, 각 포인트는 사용자가 말한 것인지 에이전트가 추측하는 것인지 명확히 기록:
   • 스킬 유형: Task 또는 Reference; 부작용(사이드 이펙트)이 있는지 여부.
   • 활성화 방법: description에 따라 자동, 사용자가 직접 호출할 때만, 또는 둘 다; 활성화 구문 및 사용하지 않는 경우.
   • 입력, 매개변수 및 누락 시 처리 방법.
   • 출력: 형식, 저장 위치, template.md 및 scripts/validate.sh의 검사 기준 필요 여부.
   • 실행 방법: 지침만 제공할지 또는 스크립트가 필요한지; 사용할 도구.
   • references/로 분리할 부분 ( SKILL.md를 500줄 미만으로 유지).
3. 최적화 방향 제안: 각 포인트에 대해 여러 방법이 있는 경우 2~3가지 방향을 장단점과 함께 제시하고, 권장 방향을 선택합니다. 예: "스크립트 scripts/check.sh로 확인 (빠르고 정확하지만 bash 필요)" vs "에이전트가 직접 읽고 평가 (유연하지만 토큰 소모 및 누락 가능성)".
4. 사용자에게 질문: 불명확한 모든 점과 여러 방향이 있는 모든 점을 원칙 6에 따라 질문으로 만듭니다.
5. 설계 확정: 응답을 받은 후 설계 요약서 (스킬 이름, 유형, 활성화 방법, 생성할 파일 목록, 제공자, 범위, 에이전트가 자동으로 설정한 값)를 작성합니다. 응답으로 인해 새로운 불명확한 점이 발생하면 계속 질문하고 파일을 생성하지 않습니다.

2.3. 제공자 조사

특정 제공자용 버전을 작성하기 전에 references/providers.md를 읽습니다:

• 확인일이 30일보다 오래되었거나, 스킬에 파일에 없는 기능이 필요하거나, 파일의 정보가 실제와 일치하지 않는 경우: 해당 파일의 6항에 있는 공식 문서를 참조하고, 파일을 수정하며, 확인일을 업데이트한 후 scripts/sync-skill.sh better-skill-gen을 사용하여 파일을 다른 제공자에게 복사합니다.
• Antigravity는 프로젝트 범위에서 Codex와 .agents/skills/를 공유합니다 (5항). .agent/skills/를 생성하지 마십시오.
• 제공자 사양을 추측하지 마십시오. 조회할 수 없는 사항은 사용자에게 명확히 말하고 질문합니다.

---

3. 실행 절차 (Workflow)

flowchart TD
    A["사용자의 업무 아이디어"] --> A2["0. 범위 및 제공자 질문"]
    A2 --> B["1. 아이디어 분석, 제안, 불명확한 점 질문"]
    B --> B2["2. 제공자 조사"]
    B2 --> C["3. template.md 및 references/ 참조"]
    C --> D["4. 원본 버전 생성"]
    D --> E["5. 리소스 동기화 및 제공자별 SKILL.md 작성"]
    E --> F["6. scripts/validate.sh로 자체 검증"]
    F -->|통과| G["완료 및 인계"]
    F -->|실패| D

0. 범위 및 제공자 질문: 항목 2.1을 수행하고 다음 단계를 진행하기 전에 응답을 기다립니다.
1. 아이디어 분석: 설계가 확정될 때까지 항목 2.2를 수행합니다. 스킬 이름은 kebab-case (64자 이하, anthropic-skills, synced, claude, anthropic 금지).
2. 제공자 조사: 선택된 모든 제공자에 대해 항목 2.3을 수행합니다.
3. 표준 문서 참조: template.md (구조 프레임워크), references/providers.md (제공자 간 차이점), references/frontmatter-spec.md (Claude Code 필드) 및 examples/sample.md (글쓰기 스타일 및 스크립트 로직)를 읽습니다.
4. 원본 버전 생성: 첫 번째로 선택된 제공자의 디렉토리에 모든 구성 요소를 작성합니다:
   • SKILL.md: 안전한 Frontmatter (인용문/scalar 블록 >-), 500줄 미만.
   • template.md (또는 templates/): ${VARIABLE} 형태의 샘플 변수가 포함된 출력 템플릿.
   • examples/sample.md: 실제 예제 텍스트 (플레이스홀더 없음).
   • references/ (분리해야 할 복잡한 스펙/지식 문서가 있는 경우).
   • scripts/validate.sh: 결과 무결성을 확인하는 스크립트.
   • 공유 리소스는 제공자 중립적으로 작성합니다: 스크립트는 스킬 디렉토리를 기준으로 한 상대 경로로 호출합니다.
5. 제공자별 배포:
   • 공유 리소스 복사: PROVIDERS="<선택된 제공자들>" bash scripts/sync-skill.sh <skill-name> 실행. 스크립트는 SKILL.md와 agents/를 제외한 모든 파일을 복사하고, SKILL.md가 누락된 제공자에 대해 [TODO]를 보고합니다.
   • 나머지 디렉토리에 대해 references/providers.md 3항의 변환 표에 따라 별도의 SKILL.md를 작성합니다. 본문 내용도 다시 작성하고, 단순히 frontmatter 필드를 제거하지 않습니다. Codex와 Antigravity를 모두 선택한 경우 .agents/skills/ 디렉토리는 하나만 있으며, 스크립트가 자동으로 병합합니다.
   • 부작용이 있는 스킬: .agents/skills/ 버전은 policy.allow_implicit_invocation: false가 포함된 agents/openai.yaml을 추가로 생성하고, "사용자가 직접 요청할 때만 사용"이라는 문구를 description에 기록합니다.
   • 범위 user-global: 스크립트 실행 시 SCOPE=user를 추가로 설정합니다.
   • 범위 project-personal: 생성된 스킬 디렉토리를 .git/info/exclude에 추가합니다 (.gitignore를 수정하지 않고, 커밋하지 않음).
6. 자체 검증 (Self-Verification):
   • PROVIDERS="<선택된 제공자들>" bash scripts/validate.sh <skill-name> 실행 (user-global의 경우 SCOPE=user 추가).
   • 스크립트는 다음을 확인합니다: YAML frontmatter 유효성, markdownlint, SKILL.md 500줄 이하, 선택된 모든 제공자에 대한 필수 파일 존재 여부, Codex/Antigravity용 SKILL.md에 Claude Code만 이해하는 필드나 토큰이 없는지 확인.
   • [WARN] 줄을 읽고, Claude가 주제인 경우 유지하고, 그렇지 않으면 수정합니다.
   • 오류가 있으면 [PASS]를 받을 때까지 스스로 수정합니다.

---

4. 제약 조건 및 표준 (Guardrails)

• 필수 규칙 (CRITICAL):
  • 모든 선택은 원칙 6에 따라 질문하고, 응답을 기다린 후 다음 단계를 진행합니다.
  • 새 스킬을 생성하기 전에 항상 범위와 제공자를 질문합니다 (항목 2.1).
  • 불명확한 점을 스스로 결정하지 않음: 파일을 생성하기 전에 분석, 제안 및 질문을 수행합니다 (항목 2.2).
  • 해당 제공자용 버전을 작성하기 전에 제공자를 조사합니다 (항목 2.3); 사양을 추측하지 마십시오.
  • 제공자 간에 SKILL.md를 그대로 복사하지 않음: 각 제공자에게는 고유한 표준 버전이 있습니다. validate.sh는 선택된 모든 제공자에 대해 [PASS]여야 합니다.
  • Zero Workspace Pollution: 예제 문서는 examples/ 내에만 위치합니다. 스킬 패키지 디렉토리 외부에 파일을 생성하지 않습니다.
  • SKILL.md를 500줄 미만으로 유지: 세부 내용은 references/ 또는 templates/로 이동합니다.
  • Frontmatter 표준화: 콜론 :이 포함된 description은 scalar >- 또는 따옴표 "..."를 사용해야 합니다.
  • markdownlint 준수 (MD001 - MD047): 생성된 모든 Markdown 파일에 대해.
• DOs (권장 사항):
  • 부작용이 있는 모든 스킬에 대해 "사용자가 호출할 때만 실행" 메커니즘을 각 제공자 방식에 따라 선언합니다 (Codex: agents/openai.yaml; Antigravity: description 내 문구).
  • 템플릿에서 설명적인 템플릿 변수 ${변수명}를 사용합니다.
  • 자동 테스트 중 생성된 임시 파일은 즉시 정리합니다.
• DON'Ts (금지 사항):
  • 모든 긴 참조 문서를 SKILL.md에 직접 넣지 않습니다.
  • 마크다운 파일에 URL을 <> 또는 마크다운 링크 없이 그대로 두지 않습니다.
  • 64자를 초과하거나 대문자/특수 문자가 포함된 스킬 이름을 사용하지 않습니다.
  • Claude Code 이외의 제공자용 버전에서 에이전트를 "Claude"라고 호출하지 않습니다.