devetai/better-plugin-gen

Better Plugin Generator (better-plugin-gen)

이 스킬은 사용자가 플러그인을 생성할 수 있도록 돕습니다. 플러그인이란 스킬, 에이전트, 훅, MCP 서버와 같은 여러 컴포넌트를 하나의 디렉토리에 패키징하여 단일 명령어로 코딩 에이전트에 설치할 수 있게 하는 것입니다. 이 스킬은 세 가지 호스트(에이전트 도구로서 플러그인을 로드하는 도구)인 Claude Code, Codex, Antigravity를 지원합니다. 각 호스트는 고유한 매니페스트를 가지며, 스킬은 공통 skills/ 디렉토리를 사용하고 선택된 각 호스트에 대해 매니페스트를 생성합니다.

아래의 모든 template.md, references/, examples/, scripts/ 경로는 이 SKILL.md 파일이 위치한 디렉토리를 기준으로 합니다.

---

1. 핵심 원칙

1. 먼저 묻고, 나중에 생성합니다. 세션이 있을 경우 구조화된 질문 도구를 사용하여 모든 선택 사항을 사용자에게 묻습니다. 세션이 없으면 번호가 매겨진 선택지를 나열하고, 권장 선택지를 명확히 표시한 후 답변을 기다리며 중단합니다. 각 질문 전에 생성하려는 플러그인이 무엇을 하는지, 질문의 내용과 그 이유를 간략히 작성합니다. 명확하지 않은 사항을 추측하여 파일을 생성하지 않습니다.
2. 호스트 사양을 추측하지 않습니다. 파일 위치, 매니페스트 형식 및 MCP에 대한 정보는 references/hosts.md를 따릅니다. "미확인"으로 표시된 사항은 반드시 사용자에게 알립니다.
3. 핵심 로직은 스킬에 둡니다. 스킬은 세 호스트 모두에서 실행되는 유일한 컴포넌트입니다. 에이전트, 명령어, 훅, LSP는 사용자가 필요로 하고 호스트가 지원하는 경우에만 추가합니다.
4. 최소한으로 실행 가능한 프레임워크를 만듭니다. 생성된 각 컴포넌트는 즉시 실행 가능해야 하지만 간결해야 합니다. 프로젝트에 better-skill-gen 또는 better-agent-gen 스킬이 있다면, 플러그인이 실행된 후 이를 사용하여 스킬이나 에이전트를 더 자세히 작성하도록 사용자에게 제안합니다.
5. 자체 검증합니다. 플러그인은 scripts/validate.sh가 종료 코드 0을 반환할 때만 인계됩니다.
6. 외부에 부수 효과를 만들지 않습니다. 이 스킬은 대상 플러그인 디렉토리(및 사용자가 선택한 경우 저장소 루트의 마켓플레이스 파일) 내에만 파일을 씁니다. git commit, git push를 실행하지 않고, 플러그인을 설치하지 않으며, 사용자의 호스트 구성을 수정하지 않습니다. 사용자가 직접 실행할 명령어만 출력합니다.

---

2. 입력

• 필수: 플러그인이 무엇을 하는지에 대한 설명(한 문장도 괜찮음) 또는 컴포넌트를 추가하려는 기존 플러그인의 경로. 사용자의 요청에서 가져옵니다.
• 아직 없는 경우 질문: 대상 호스트, 디렉토리 위치, 컴포넌트 목록, 마켓플레이스 여부, 플러그인 이름, 작성자, 라이선스.
• 정보 부족: 섹션 3의 2단계에 따라 질문합니다. 답변이 없으면 중단하고 기다립니다.

---

3. 절차

1단계: 모드 확인 및 현재 상태 읽기

• 새로 생성: 사용자가 플러그인을 설명하고 디렉토리가 없습니다.
• 컴포넌트 추가 / 호스트 추가: 사용자가 .claude-plugin/plugin.json, .codex-plugin/plugin.json 또는 plugin.json이 있는 경로를 제공합니다. 모든 매니페스트를 읽고, 현재 있는 컴포넌트를 나열한 후 셸 명령어 bash scripts/validate.sh <dir>를 실행하여 수정 전에 기존 오류를 파악합니다.
• 마켓플레이스 생성: 사용자가 이미 플러그인을 가지고 있으며 배포만 필요합니다. 위와 같이 플러그인을 읽고 6단계로 이동합니다.
• references/hosts.md를 읽습니다. 검증 날짜가 30일보다 오래되었거나 플러그인에 파일에 없는 기능이 필요한 경우: 해당 파일의 섹션 6에 있는 소스를 웹에서 조회하고, 파일과 검증 날짜를 업데이트한 후 변경된 부분을 사용자에게 알립니다.

2단계: 사용자에게 질문

이해한 내용(플러그인이 무엇을 하는지, 누가 사용하는지, 언제 실행되는지)을 요약한 후, 1차 질문을 합니다. 사용자가 명확히 답변한 질문은 건너뜁니다.

질문	유형	선택지 (권장 사항을 맨 앞에)
플러그인이 어떤 호스트에서 실행되나요?	다중 선택	Claude Code; Codex; Antigravity. 플러그인이 스킬과 MCP로만 구성된 경우 세 가지 모두 권장; 훅, LSP 또는 userConfig가 필요한 경우 Claude Code만 권장
플러그인을 어디에 둘까요?	단일 선택	별도 저장소, 루트에 플러그인 (./<이름>/); 마켓플레이스 저장소 내 (plugins/<이름>/); 테스트를 위해 현재 프로젝트 내
플러그인은 어떤 컴포넌트로 구성되나요?	다중 선택	스킬; 에이전트; 훅; MCP 서버; 명령어; LSP; userConfig
배포를 위해 마켓플레이스를 생성하시겠습니까?	단일 선택	예, 선택한 호스트용으로; 아니요, 로컬에서만 테스트

2차 질문(필요한 경우): 플러그인 이름(설명에서 추론한 kebab-case 이름 제안), 작성자 및 GitHub 저장소 소유자, 라이선스, 각 컴포넌트의 세부 사항(스킬이 무엇을 하는지, 에이전트가 어떤 도구를 사용하는지, 훅이 어떤 이벤트에서 실행되는지, 어떤 MCP 서버이며 토큰이 필요한지).

질문 규칙:

• 사용자가 Claude Code가 아닌 다른 호스트와 함께 훅을 선택하는 경우: references/hosts.md 섹션 4에서 충돌 가능성을 미리 알리고, 훅을 유지할지 질문합니다.
• 플러그인에 토큰 또는 비밀번호가 필요한 경우: 제공 방법을 질문합니다(Claude Code: userConfig에 sensitive: true; 다른 호스트: README에 기록된 환경 변수). 비밀 값을 파일에 절대 기록하지 않습니다.
• 이름이 Claude Code의 금지된 이름(references/hosts.md 섹션 2.1)과 충돌하는 경우: 다른 이름을 제안합니다.
• 대상 디렉토리에 이미 파일이 있는 경우: 덮어쓸 파일을 나열하고 쓰기 전에 질문합니다.

3단계: 설계 확정

채팅에 요약을 작성합니다: 이름, 호스트, 위치, 생성될 디렉토리 트리(각 파일의 호스트 표시), 각 호스트에서 실행되는 컴포넌트, 에이전트가 직접 설정하는 값, 미확인 사항. 답변로 인해 새로운 불명확한 점이 발생하면 추가로 질문하고, 파일을 생성하지 않습니다.

4단계: 파일 생성

1. template.md(각 파일의 프레임워크)와 references/components.md(각 컴포넌트의 형식)를 읽습니다. examples/sample.md를 읽어 원하는 세부 수준을 파악합니다.
2. 선택된 각 호스트에 대한 매니페스트를 작성합니다. name, version, description은 모든 매니페스트에서 동일합니다.
3. 컴포넌트는 플러그인 루트에 작성하고, .claude-plugin/ 또는 .codex-plugin/ 안에 두지 않습니다:
   • 스킬: skills/<이름>/SKILL.md, 프론트매터는 name, description만 포함하여 모든 호스트가 읽을 수 있도록 합니다.
   • MCP: Claude Code, Codex용 .mcp.json; Antigravity용 mcp_config.json(원격 서버는 serverUrl 사용). 두 파일은 동일한 서버 목록을 가집니다.
   • 훅: hooks/hooks.json을 "hooks" 키로 감싸고, 항상 matcher를 포함하며, "${CLAUDE_PLUGIN_ROOT}"(Claude Code 변수)를 사용하여 스크립트를 호출합니다. 스크립트는 scripts/에 shebang과 함께 둡니다.
   • 에이전트, 명령어, LSP, userConfig: references/components.md를 따릅니다.
4. File 8 프레임워크에서 README.md를 작성합니다. 최소 40단어 이상, 호스트별 컴포넌트 표와 각 호스트별 설치 명령어(references/publishing.md 섹션 5)를 포함합니다.
5. 컴포넌트 추가 모드: 새 파일만 추가하고 매니페스트에서 필요한 키만 수정합니다. 플러그인이 이미 배포된 경우 모든 매니페스트에서 version(패치 버전)을 증가시킵니다.

5단계: 자체 검증

1. 셸 명령어 HOSTS="<선택된 호스트 공백으로 구분>" bash scripts/validate.sh <플러그인-디렉토리-또는-저장소>를 실행합니다. 예: HOSTS="claude codex antigravity".
2. 스크립트는 check_plugin.py(매니페스트, 이름, 경로, MCP, 훅, 스킬, 에이전트, 마켓플레이스, 플레이스홀더, 비밀 유사 문자열 확인)를 실행한 다음, 시스템에 해당 명령어가 있으면 claude plugin validate 및 agy plugin validate를 실행합니다.
3. [FAIL]이 있거나 CLI에서 오류를 보고하면 파일을 수정하고 종료 코드 0이 나올 때까지 다시 실행합니다.
4. 각 [WARN]을 읽습니다: 수정 가능하면 수정합니다. 유지해야 하는 경우(예: 이미 사용자에게 알린 다중 호스트 훅 경고) 그 이유를 인계 보고서에 기록합니다.
5. 임시 파일이 필요한 경우 사용자 지침에 지정된 임시 디렉토리에 쓰고, 지정이 없으면 운영 체제의 임시 디렉토리를 사용합니다. 검증이 완료되면 즉시 삭제합니다.

6단계: 마켓플레이스 (선택한 경우)

• Claude Code: 저장소 루트의 .claude-plugin/marketplace.json (File 9 프레임워크).
• Codex: 저장소 루트의 .agents/plugins/marketplace.json (File 10 프레임워크).
• Antigravity: 파일 불필요; README에 GitHub 저장소 URL과 함께 agy plugin install 명령어를 기록합니다(예: https://github.com/phucbui/pr-review-kit).
• 마켓플레이스까지 확인하기 위해 저장소 루트 디렉토리로 5단계를 다시 실행합니다.

7단계: 인계

template.md 끝에 있는 "인계 보고서" 프레임워크에 따라 보고서를 출력합니다: 디렉토리, 호스트, 검사 결과, 파일 테이블, 미확인 사항, 로컬 테스트 명령어, 사용자가 직접 실행할 배포 명령어(references/publishing.md 섹션 3~6). 프로젝트에 better-skill-gen 또는 better-agent-gen이 있으면 컴포넌트를 더 자세히 작성하는 방법을 한 줄로 제안합니다.

---

4. 제약 사항

• 필수:
  • 파일을 생성하기 전에 호스트, 위치, 컴포넌트, 마켓플레이스를 반드시 질문합니다. 불명확한 사항을 스스로 결정하지 않습니다.
  • 대상 플러그인 디렉토리와 저장소 루트의 마켓플레이스 파일에만 씁니다. 다른 곳에 샘플 파일을 만들지 않습니다. 예제는 이 스킬의 examples/에만 있습니다.
  • git commit, git push, claude plugin install, agy plugin install, codex plugin marketplace add를 실행하지 않습니다. 명령어만 출력합니다.
  • 토큰, 비밀번호, API 키를 어떤 파일에도 기록하지 않습니다.
  • scripts/validate.sh가 종료 코드 0일 때만 인계합니다.
• 권장 사항:
  • 플러그인, 스킬, 에이전트 이름은 kebab-case를 사용합니다. 초기 버전은 0.1.0입니다.
  • 플러그인을 하나의 목적에 집중시킵니다. 사용자가 관련 없는 작업을 함께 묶으면 분리할 것을 제안합니다.
  • README에 각 컴포넌트가 어떤 호스트에서 실행되는지 명확히 기록합니다.
• 금지 사항:
  • Claude Code 고유 필드가 포함된 SKILL.md를 Codex 또는 Antigravity용 플러그인에 그대로 복사하지 않습니다.
  • 매니페스트, 훅, MCP에 절대 경로나 ..를 사용하지 않습니다.
  • 플러그인 루트에 CLAUDE.md를 두지 않습니다. 로드 지침이 필요하면 스킬에 포함시킵니다.