plugin-forge

plugin-forge 스킬 개요

plugin-forge는 Claude Code 플러그인 작성자가 폴더 구조, manifest 파일, 마켓플레이스 등록을 워크플로를 새로 짜지 않고도 제대로 갖출 수 있게 도와주는 빌드·유지보수용 스킬입니다. 핵심 과제는 단순히 “JSON 몇 개 작성하기”가 아니라, “스캐폴딩이 올바르고, 버전 관리가 일관되며, 마켓플레이스 기반 워크플로에서 실제로 설치 가능한 플러그인을 출시하는 것”에 가깝습니다.

plugin-forge가 특히 잘 맞는 사용자

다음에 해당한다면 plugin-forge 스킬이 잘 맞습니다.

• Claude Code 플러그인을 처음부터 새로 만들고 있다
• commands/, agents/, skills/, hooks/ 같은 플러그인 구성 요소를 추가하려 한다
• .claude-plugin/plugin.json과 마켓플레이스 메타데이터를 함께 업데이트해야 한다
• 배포 전에 플러그인을 로컬에서 테스트하고 싶다
• 여러 플러그인을 담는 마켓플레이스형 플러그인 저장소를 운영하고 있다

특히 일회성 프롬프트 결과물이 아니라, 반복 가능한 구조를 원할 때 유용합니다.

일반 프롬프트와 다른 plugin-forge의 강점

일반 프롬프트로도 플러그인 뼈대 정도는 만들 수 있지만, plugin-forge는 실제 작업에 필요한 안전장치를 더해 줍니다.

• 정해진 플러그인 디렉터리 레이아웃
• manifest 위치와 필수 필드에 대한 명확한 기준
• 마켓플레이스 스키마 기준 참조
• 로컬 설치 및 테스트 워크플로
• 스캐폴딩과 버전 업데이트를 위한 자동화 스크립트

이 차이는 중요합니다. 실제로 플러그인이 실패하는 가장 흔한 이유는 코드 품질이 아니라, 구조가 들쭉날쭉하거나 메타데이터가 서로 맞지 않기 때문입니다.

plugin-forge가 실제로 다루는 범위

저장소 기준으로 보면 plugin-forge의 중심은 다음 파일들입니다.

• 새 플러그인 스캐폴딩용 scripts/create_plugin.py
• 버전을 동기화해 올리는 scripts/bump_version.py
• 폴더 구조와 manifest 배치를 설명하는 references/plugin-structure.md
• 마켓플레이스 엔트리 규칙을 설명하는 references/marketplace-schema.md
• 생성, 테스트, 배포 흐름을 정리한 references/workflows.md

즉, 이 스킬은 폭넓은 이론 문서라기보다 구현 가이드와 보조 도구 모음에 가깝습니다.

Code Generation에서 plugin-forge가 특히 강한 경우

Code Generation 용도로 plugin-forge가 가장 빛나는 순간은, 모델이 생성하는 파일이 반드시 올바른 플러그인 형태로 들어맞아야 할 때입니다. 예를 들면 다음과 같습니다.

• 유효한 메타데이터를 갖춘 새 플러그인 스켈레톤 생성
• 기존 플러그인에 새 command 또는 skill 추가
• plugin.json 수정과 그에 맞는 마켓플레이스 엔트리 변경
• semantic version bump가 포함된 릴리스 준비

반대로 이미 정상 동작하는 플러그인 내부의 비즈니스 로직만 필요하다면, plugin-forge보다 도메인 특화 코딩 스킬이 더 직접적일 수 있습니다.

plugin-forge 스킬 사용법

plugin-forge 설치 맥락

상위 SKILL.md에는 자체 설치 명령이 따로 적혀 있지 않으므로, 실제 설치 방식은 현재 환경에서 스킬을 어떻게 로드하느냐에 따라 달라집니다. 저장소의 스킬 번들을 쓰는 경우 흔한 패턴은 다음과 같습니다.

npx skills add softaworks/agent-toolkit --skill plugin-forge

설치 후에는 플러그인 생성, manifest 작성, 마켓플레이스 등록, 로컬 테스트, 버전 관리가 필요한 작업에서 plugin-forge를 사용하면 됩니다.

먼저 읽어야 할 파일

빠르게 익히려면 아래 순서로 보는 것이 좋습니다.

1. skills/plugin-forge/SKILL.md
2. skills/plugin-forge/references/plugin-structure.md
3. skills/plugin-forge/references/marketplace-schema.md
4. skills/plugin-forge/references/workflows.md
5. skills/plugin-forge/scripts/create_plugin.py
6. skills/plugin-forge/scripts/bump_version.py

이 순서대로 보면 먼저 “무엇을 하는 스킬인지”를 잡고, 그다음 기대되는 파일 구조, 마켓플레이스 규약, 마지막으로 바로 실행 가능한 보조 도구까지 연결해서 이해할 수 있습니다.

plugin-forge가 입력으로 필요로 하는 정보

plugin-forge는 “플러그인 하나 만들어줘” 같은 추상적 요청보다, 저장소 구조와 배포 맥락이 분명할 때 훨씬 잘 작동합니다. 최소한 아래 정보는 주는 편이 좋습니다.

• kebab-case 형식의 플러그인 이름
• 마켓플레이스 루트 경로
• 플러그인의 목적
• 작성자 이름과 이메일
• 초기 키워드
• 카테고리
• commands, agents, skills, hooks, MCP 설정 중 무엇이 필요한지
• 새 플러그인인지, 기존 플러그인 업데이트인지

이 정보가 없더라도 모델이 초안은 만들 수 있지만, 대체로 사람이 직접 손봐야 할 부분이 많이 남습니다.

대략적인 목표를 강한 plugin-forge 프롬프트로 바꾸는 법

약한 프롬프트:

Create a Claude Code plugin for my project.

더 강한 프롬프트:

Use plugin-forge to scaffold a new Claude Code plugin named schema-audit inside /repos/internal-marketplace. Author is Jane Doe <jane@example.com>. Description: “Validate JSON and OpenAPI schemas in CI.” Keywords: schema,openapi,json,validation. Category: developer-tools. Include commands/ and skills/, but no hooks yet. Generate the expected folder layout, plugins/schema-audit/.claude-plugin/plugin.json, the matching .claude-plugin/marketplace.json entry, and a short README. Follow the marketplace and plugin structure references.

두 번째 프롬프트처럼 써야 plugin-forge가 실제로 바로 쓸 수 있는 수준에 가까운 파일을 만들어낼 수 있습니다.

속도가 중요하면 스캐폴딩 스크립트를 써라

메타데이터를 이미 알고 있다면, 초기 트리를 손으로 만들기보다 보조 스크립트를 쓰는 편이 낫습니다.

python scripts/create_plugin.py plugin-name \
  --marketplace-root /path/to/marketplace \
  --author-name "Your Name" \
  --author-email "your.email@example.com" \
  --description "Plugin description" \
  --keywords "keyword1,keyword2" \
  --category "productivity"

맞춤형으로 하나하나 손수 짜는 것보다, 우선 올바른 초기 구성을 빨리 갖추는 게 중요할 때 가장 빠른 경로입니다.

manifest 불일치를 막으려면 버전 스크립트를 써라

plugin-forge에서 가장 실용적인 부분 중 하나는 버전 동기화입니다. 이 스킬에는 다음 두 파일을 함께 업데이트하는 scripts/bump_version.py가 포함되어 있습니다.

• plugins/<plugin-name>/.claude-plugin/plugin.json
• .claude-plugin/marketplace.json

예시:

python scripts/bump_version.py plugin-name patch \
  --marketplace-root /path/to/marketplace

이게 중요한 이유는, 실제 유지보수에서 가장 흔한 실수 중 하나가 이 두 파일 간 버전 불일치이기 때문입니다.

실제 plugin-forge 워크플로를 따르기

실무적으로는 다음 흐름이 가장 안정적입니다.

1. 플러그인을 스캐폴딩한다
2. 생성된 plugin.json을 검토한다
3. .claude-plugin/marketplace.json의 마켓플레이스 엔트리를 확인한다
4. command나 skill 같은 구성 요소를 추가한다
5. 마켓플레이스 설치 흐름으로 로컬 테스트한다
6. 반복 수정한다
7. 릴리스 전에 버전을 올린다

모든 걸 한 번에 거대한 프롬프트 하나로 처리하려 하기보다, 이 흐름대로 나누는 편이 훨씬 안정적입니다.

초반부터 염두에 둬야 할 로컬 테스트 흐름

참조 문서에는 로컬 테스트 경로도 구체적으로 나와 있습니다.

/plugin marketplace add /path/to/marketplace-root
/plugin install plugin-name@marketplace-name

즉, plugin-forge에 요청할 때도 설명용 파일만이 아니라 실제 설치 가능한 경로와 메타데이터가 나오도록 해야 합니다. 소스 경로나 플러그인 이름이 조금이라도 어긋나면 테스트는 바로 깨집니다.

plugin-forge가 자주 수정하는 핵심 파일

실제 사용 시 plugin-forge는 대체로 다음 파일과 경로를 만들거나 수정합니다.

• plugins/<plugin-name>/.claude-plugin/plugin.json
• .claude-plugin/marketplace.json
• plugins/<plugin-name>/README.md
• plugins/<plugin-name>/commands/
• plugins/<plugin-name>/agents/
• plugins/<plugin-name>/skills/
• plugins/<plugin-name>/hooks/hooks.json
• plugins/<plugin-name>/.mcp.json

검토 계획을 세울 때 이 범위를 알아두는 것이 좋습니다. plugin-forge는 흔히 여러 파일에 걸친 변경을 한꺼번에 만들어내기 때문입니다.

plugin-forge 결과 품질을 높이는 실전 팁

plugin-forge에 다음을 명시해서 요청하면 결과 품질이 좋아집니다.

• 기존 플러그인 이름과 경로를 정확히 유지할 것
• 모든 식별자를 kebab-case로 유지할 것
• 플러그인 manifest와 마켓플레이스 엔트리를 함께 보여줄 것
• 추론하지 못한 필수 필드는 따로 설명할 것
• “generated files”와 “manual follow-up”을 구분할 것
• manifest 간 버전과 이름이 일치하는지 검증할 것

이런 요청은 보기에는 그럴듯하지만 실제로는 설치되지 않는 결과물을 줄이는 데 효과적입니다.

plugin-forge 스킬 FAQ

프롬프트를 잘 써도 plugin-forge를 쓸 가치가 있나?

있습니다. 특히 위험 요소가 구조적 정확성에 있다면 그렇습니다. 일관된 manifest, 마켓플레이스 엔트리, 디렉터리 레이아웃이 필요한 상황에서는 일반 프롬프트보다 plugin-forge가 더 유용합니다. 반대로 이미 있는 플러그인 안에서 command 파일 하나만 작성하면 되는 정도라면 차이는 크지 않을 수 있습니다.

plugin-forge는 초보자도 쓰기 쉬운가?

대체로는 그렇습니다. plugin-forge는 플러그인 생성과 테스트까지 가는 구체적인 경로를 초보자에게 제시해 줍니다. 다만 초보자라도 마켓플레이스 루트가 어디인지, 네이밍 규칙을 어떻게 쓸지, 실제로 어떤 구성 요소가 필요한지는 알고 있어야 합니다. 구조를 잡아주는 데는 강하지만, 제품 설계 자체를 대신해 주는 도구는 아닙니다.

언제는 plugin-forge를 쓰지 않는 편이 좋은가?

다음 경우라면 plugin-forge를 건너뛰는 편이 낫습니다.

• Claude Code 플러그인을 만드는 작업이 아니다
• 마켓플레이스 방식의 배포를 사용하지 않는다
• 일반적인 Python 또는 JavaScript 코드 생성만 원한다
• 저장소가 문서화된 구조와 일부러 다르게 설계된 커스텀 플러그인 레이아웃을 사용한다

이런 경우 plugin-forge는 오히려 잘못된 형태로 결과를 유도할 수 있습니다.

plugin-forge가 배포까지 자동으로 처리하나?

완전히 그렇지는 않습니다. 스캐폴딩, manifest 작성, 마켓플레이스 등록, 로컬 테스트 가이드, 버전 업데이트 같은 준비 작업은 잘 커버합니다. 하지만 엔드투엔드 릴리스 플랫폼은 아닙니다. 최종적으로는 파일 검토, 로컬 테스트, 실제 배포 또는 배포 자동화 프로세스 실행을 직접 해야 합니다.

도입 시 가장 큰 걸림돌은 무엇인가?

대부분은 저장소 맥락 부족입니다. plugin-forge는 마켓플레이스 루트가 어디 있는지, 플러그인을 어떤 카테고리로 넣을지 사용자가 알고 있다고 가정합니다. 이 질문에 답하지 못하면 결과물은 초안 수준에 머물 가능성이 큽니다.

manifest를 손으로 수정하는 것과 비교하면 어떤가?

일회성 수정이라면 수작업도 가능합니다. 하지만 반복 가능성이 중요하거나 plugin.json과 marketplace.json 사이 드리프트를 피해야 한다면 plugin-forge가 더 낫습니다. 특히 함께 제공되는 스크립트들이 가장 분명한 실무상 이점입니다.

plugin-forge 스킬을 더 잘 활용하는 방법

저장소 맥락이 드러나는 입력을 plugin-forge에 주기

가장 큰 개선 포인트는 정확한 경로와 현재 파일 상태를 함께 주는 것입니다. 예를 들어 “버전 올려줘”라고만 하지 말고 이렇게 요청하세요.

Use plugin-forge to bump schema-audit in /repos/internal-marketplace from its current version using a minor change. Check both plugins/schema-audit/.claude-plugin/plugin.json and .claude-plugin/marketplace.json, then show the diff.

이렇게 해야 일반론이 아니라 실제 검증 가능한 변경 쪽으로 결과를 밀어줄 수 있습니다.

요약만 말고 파일별 산출물을 요청하기

plugin-forge는 결과물을 구체적으로 요청할수록 더 잘 작동합니다.

• 완전한 plugin.json
• 정확한 마켓플레이스 엔트리
• 제안하는 디렉터리 트리
• README 초안
• 로컬 테스트용 후속 명령어

특히 Code Generation 용도의 plugin-forge는 바로 적용 가능한 파일을 만들어낼 때 가치가 커지므로, 이 점이 중요합니다.

가장 흔한 실패 패턴을 미리 막기

plugin-forge 출력에서는 다음 문제를 특히 주의해 보세요.

• 파일마다 플러그인 이름이 다르다
• 마켓플레이스 source 경로가 실제 폴더 구조와 맞지 않는다
• 버전이 한 manifest에만 반영되고 다른 쪽에는 빠진다
• 메타데이터에는 선택 구성 요소가 언급되지만 실제 파일은 생성되지 않는다
• 생성 구조에 .claude-plugin/plugin.json이 빠져 있다

references/plugin-structure.md와 references/marketplace-schema.md 기준으로 빠르게 대조해 보면 대부분 잡아낼 수 있습니다.

더 나은 결과를 위한 2단계 workflow

실전에서 강한 plugin-forge 운영 방식은 다음과 같습니다.

1. 1차 패스: 구조와 manifest 생성
2. 2차 패스: 플러그인 구성 요소와 README 개선

스캐폴딩, 비즈니스 로직, 문서, 테스트 설정, 배포 노트까지 한 프롬프트에 모두 넣으면 품질이 떨어지는 경우가 많습니다. plugin-forge는 구조를 먼저 잡을 때 가장 강합니다.

첫 결과 후에는 모호한 지시 대신 정밀 수정 요청하기

“이거 고쳐줘”처럼 뭉뚱그려 말하지 말고, 정확한 수리 지시를 주는 편이 좋습니다. 예를 들면:

• “Regenerate marketplace.json entry so source points to ./plugins/schema-audit.”
• “Add skills/ to the tree and keep manifest fields unchanged.”
• “Update only version fields; do not rewrite descriptions or keywords.”
• “Align the plugin name to kebab-case everywhere.”

이처럼 범위를 제한한 반복 수정이 plugin-forge를 훨씬 더 믿을 만하게 만듭니다.

plugin-forge를 참조 문서와 함께 쓰고, 대체재로 쓰지 않기

plugin-forge 결과를 개선하는 가장 좋은 방법은 저장소의 참조 문서를 명시적으로 따르도록 만드는 것입니다. 프롬프트에 다음 문서를 직접 언급하세요.

• 디렉터리 기준은 references/plugin-structure.md
• 마켓플레이스 필드는 references/marketplace-schema.md
• 설치와 테스트 흐름은 references/workflows.md

이렇게 해야 스킬이 일반적인 플러그인 관행으로 흐르지 않고, 저장소가 실제로 요구하는 규약에 맞춰 결과를 내게 됩니다.