plugin-creator

플러그인 생성기

빠른 시작

1. 스캐폴드 스크립트 실행:

# 플러그인 이름은 소문자 하이픈 케이스로 정규화되며 최대 64자입니다.
# 생성된 폴더와 plugin.json 이름은 항상 동일합니다.
# 스킬 루트(이 `SKILL.md`가 있는 디렉토리)에서 실행합니다.
# 기본적으로 `~/plugins/<plugin-name>`에 생성됩니다.
python3 scripts/create_basic_plugin.py <plugin-name>

2. 요청에 특정 메타데이터가 있는 경우 <plugin-path>/.codex-plugin/plugin.json을 편집합니다. 스캐폴드는 유효한 기본값으로 시작하며 [TODO: ...] 플레이스홀더를 포함해서는 안 됩니다.

3. 플러그인이 Codex UI 순서에 표시되어야 하는 경우 개인 마켓플레이스 항목을 생성하거나 업데이트합니다:

# 개인 마켓플레이스 항목은 기본적으로 `~/.agents/plugins/marketplace.json`입니다.
python3 scripts/create_basic_plugin.py my-plugin --with-marketplace

기본 personal 마켓플레이스 이름이 이미 사용 중이거나 설치되어 있어 다른 새 마켓플레이스 파일을 시드해야 하는 경우에만 --marketplace-name <name>을 지정합니다:

python3 scripts/create_basic_plugin.py my-plugin \
  --with-marketplace \
  --marketplace-name team-local

사용자가 특별히 해당 대상을 요청한 경우에만 리포지토리/팀 마켓플레이스를 사용합니다:

python3 scripts/create_basic_plugin.py my-plugin \
  --path <repo-root>/plugins \
  --marketplace-path <repo-root>/.agents/plugins/marketplace.json \
  --with-marketplace

사용자가 마켓플레이스 경로를 지정하는 경우, 사용자에게 해당 마켓플레이스에서 재설치하라고 알리기 전에 실제로 설치되어 있는지 확인하십시오. 기본 개인 마켓플레이스 파일(~/.agents/plugins/marketplace.json)은 암시적으로 검색되지만, 다른 마켓플레이스 경로는 그렇지 않습니다. Windows에서는 사용자 프로필 아래의 동등한 경로를 사용합니다.

4. 필요에 따라 선택적 보조 폴더를 생성/조정합니다:

python3 scripts/create_basic_plugin.py my-plugin \
  --path <parent-plugin-directory> \
  --marketplace-path <marketplace-json-path> \
  --with-skills --with-hooks --with-scripts --with-assets --with-mcp --with-apps --with-marketplace

<parent-plugin-directory>는 플러그인 폴더 <plugin-name>이 생성될 디렉토리입니다 (예: ~/plugins).

5. 생성된 플러그인을 반환하기 전에 실행:

python3 scripts/validate_plugin.py <plugin-path>

개발 중 기존 로컬 플러그인을 업데이트하는 경우, 스캐폴드 흐름은 그대로 유지하고 마켓플레이스 파일을 수동으로 편집하는 대신 다음 참조를 사용합니다:

python3 scripts/update_plugin_cachebuster.py <plugin-path>

사용자가 명시적으로 특정 재정의를 요청하지 않는 한 기본 캐시버스터 도우미를 선호합니다. 기존 로컬 플러그인을 반복 개발하는 동안 예상되는 캐시버스터 및 재설치 흐름은 references/installing-and-updating.md를 참조하십시오.

이 스킬이 생성하는 것

• 기본 마켓플레이스 지원 스캐폴드는 ~/.agents/plugins/marketplace.json에 있는 개인 마켓플레이스 파일을 사용하며, 플러그인은 일반적으로 ~/plugins/<plugin-name>/에 저장됩니다.
• 플러그인 루트를 /<parent-plugin-directory>/<plugin-name>/에 생성합니다.
• 항상 /<parent-plugin-directory>/<plugin-name>/.codex-plugin/plugin.json을 생성합니다.
• 매니페스트를 수집 경로가 허용하는 검증된 스키마 형태로 채웁니다.
• --with-marketplace가 설정된 경우 ~/.agents/plugins/marketplace.json을 생성하거나 업데이트합니다.
  • 마켓플레이스 파일이 아직 없으면 첫 번째 플러그인 항목을 추가하기 전에 개인 마켓플레이스 루트를 시드합니다.
• <plugin-name>은 스킬 생성기 명명 규칙을 사용하여 정규화됩니다:
  • My Plugin → my-plugin
  • My--Plugin → my-plugin
  • 밑줄, 공백 및 구두점은 -로 변환됩니다.
  • 결과는 연속된 하이픈이 축소된 소문자 하이픈 구분 형식입니다.
• 다음 선택적 생성을 지원합니다:
  • skills/
  • hooks/
  • scripts/
  • assets/
  • .mcp.json
  • .app.json

마켓플레이스 워크플로우

• 개인 마켓플레이스 생성은 기본적으로 ~/.agents/plugins/marketplace.json입니다. 여기서 "개인 마켓플레이스"는 해당 경로에 있는 파일의 마켓플레이스를 의미합니다.
• 리포지토리/팀 마켓플레이스 생성은 --path와 --marketplace-path를 모두 사용한 옵트인 방식이며, 사용자가 특별히 요청한 경우에만 사용합니다.
• --marketplace-name은 예외 경로입니다. 기본 personal 마켓플레이스 이름이 이미 사용 중이고 다른 새 마켓플레이스 파일을 시드해야 하는 경우에만 사용합니다.
• 기존 마켓플레이스 파일의 이름을 바꾸기 위해 --marketplace-name을 사용하지 마십시오. 파일이 이미 존재하는 경우 최상위 name이 이미 일치해야 합니다.
• 사용자가 다른 마켓플레이스 경로를 지정하는 경우, 해당 마켓플레이스가 codex plugin marketplace add를 통해 명시적으로 설치되어야 하는 것으로 처리합니다.
• marketplace.json 파일에서 마켓플레이스 이름이 필요한 경우 scripts/read_marketplace_name.py를 선호합니다. 인수 없이 실행하면 기본 개인 마켓플레이스를 읽고, 명시적 경로를 제공하면 리포지토리/팀 마켓플레이스에서도 작동합니다.
• 두 위치 모두에서 생성된 소스 경로는 ./plugins/<plugin-name>으로 유지됩니다.
• 마켓플레이스 루트 메타데이터는 최상위 name과 선택적 interface.displayName을 지원합니다.
• plugins[]의 플러그인 순서를 Codex의 렌더링 순서로 처리합니다. 사용자가 명시적으로 목록 재정렬을 요청하지 않는 한 새 항목을 추가합니다.
• displayName은 개별 plugins[] 항목이 아닌 마켓플레이스 interface 객체 내에 속합니다.
• 생성된 각 마켓플레이스 항목에는 다음이 모두 포함되어야 합니다:
  • policy.installation
  • policy.authentication
  • category
• 새 항목의 기본값:
  • policy.installation: "AVAILABLE"
  • policy.authentication: "ON_INSTALL"
• 사용자가 명시적으로 다른 허용 값을 지정하는 경우에만 기본값을 재정의합니다.
• 허용되는 policy.installation 값:
  • NOT_AVAILABLE
  • AVAILABLE
  • INSTALLED_BY_DEFAULT
• 허용되는 policy.authentication 값:
  • ON_INSTALL
  • ON_USE
• policy.products는 재정의로 처리합니다. 사용자가 명시적으로 제품 게이팅을 요청하지 않는 한 생략합니다.
• 생성된 플러그인 항목 형태:

{
  "name": "plugin-name",
  "source": {
    "source": "local",
    "path": "./plugins/plugin-name"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}

• 동일한 플러그인 이름에 대한 기존 마켓플레이스 항목을 의도적으로 교체하는 경우에만 --force를 사용합니다.

• 대상 마켓플레이스 파일이 아직 없으면 최상위 "name", "displayName"을 포함하는 "interface" 객체, 그리고 plugins 배열로 생성한 후 새 항목을 추가합니다.

• 완전히 새로운 마켓플레이스 파일의 경우 루트 객체는 다음과 같아야 합니다:

{
  "name": "personal",
  "interface": {
    "displayName": "Personal"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "source": {
        "source": "local",
        "path": "./plugins/plugin-name"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

필수 동작

• 외부 폴더 이름과 plugin.json의 "name"은 항상 동일한 정규화된 플러그인 이름입니다.
• 필수 구조를 제거하지 마십시오. .codex-plugin/plugin.json을 유지합니다.
• 플러그인 매니페스트에 [TODO: ...] 플레이스홀더를 남기지 마십시오.
• 실제로 해당 보조 파일이 생성되지 않는 한 apps와 mcpServers를 plugin.json에 포함하지 마십시오.
• hooks를 포함하여 유효성 검사에서 거부되는 지원되지 않는 플러그인 매니페스트 필드를 생략합니다.
• 기존 플러그인 경로 내에 파일을 생성하는 경우, 덮어쓰기가 의도적인 경우에만 --force를 사용합니다.
• 기존 마켓플레이스 interface.displayName을 유지합니다.
• 마켓플레이스 항목을 생성할 때 값이 기본값이더라도 항상 policy.installation, policy.authentication, category를 작성합니다.
• 사용자가 명시적으로 해당 재정의를 요청하는 경우에만 policy.products를 추가합니다.
• 마켓플레이스 source.path를 선택된 마켓플레이스 루트를 기준으로 ./plugins/<plugin-name>으로 유지합니다.
• personal이라는 이름이 이미 다른 곳에서 사용 중이거나 설치되어 있어서 이름이 personal이 되어서는 안 되는 새 마켓플레이스 파일을 생성하는 경우에만 --marketplace-name을 사용합니다.
• Codex가 마켓플레이스 파일을 쓰기 위해 승인이 필요한 경우, 진행하기 전에 해당 승인을 요청합니다. 사용자가 직접 쓰기를 선호하는 경우 정확한 스캐폴드 명령을 제공한 다음, 워크플로우를 모호하게 남기지 않고 유효성 검사 또는 후속 플러그인 편집을 계속합니다.
• 개발 중 기존 로컬 플러그인을 업데이트하는 경우 마켓플레이스 구성이나 marketplace.json을 수동으로 편집하지 마십시오. references/installing-and-updating.md 및 scripts/update_plugin_cachebuster.py에 문서화된 업데이트 흐름을 사용합니다.
• 기본 개인 마켓플레이스 흐름에 대해 사용자에게 codex plugin marketplace add를 실행하도록 지시하지 마십시오. 해당 명령은 명시적인 비기본 마켓플레이스 구성을 위한 것이며, 표준 ~/.agents/plugins/marketplace.json 경로를 위한 것이 아닙니다.
• 사용자가 기본이 아닌 --marketplace-path를 제공한 경우, 재설치 지침을 제공하기 전에 해당 마켓플레이스가 설치되어 있는지 확인합니다. 해당 명시적 마켓플레이스가 아직 구성되지 않은 경우 codex plugin marketplace add <path-to-marketplace-root>를 사용합니다.
• 워크플로우가 마켓플레이스 지원 플러그인을 생성하거나 업데이트한 경우, 마지막 사용자 대면 응답을 짧은 Codex 앱 핸드오프로 종료합니다. Codex 앱에서 보려면:이라고 말하고 View <정규화된 플러그인 이름> 및 Share <정규화된 플러그인 이름>을 원시 URL이나 코드 범위가 아닌 Markdown 링크로 작성합니다.
• View 딥링크는 codex://plugins/<정규화된 플러그인 이름>?marketplacePath=<절대 marketplace.json 경로>를 사용합니다. Share 딥링크는 동일한 URL에 &mode=share를 추가하여 사용합니다.
• 플레이스홀더를 스캐폴드된 플러그인의 실제 정규화된 플러그인 이름과 절대 marketplace.json 경로로 바꿉니다. 필요한 경우 경로 세그먼트와 쿼리 값을 URL 인코딩합니다.
• 이러한 딥링크에 pluginName 또는 hostId 쿼리 매개변수를 추가하지 마십시오. Codex는 사용자가 링크를 클릭한 후 둘 다 파생합니다.
• 마켓플레이스 항목이 생성되거나 업데이트되지 않은 경우 View <정규화된 플러그인 이름> 또는 Share <정규화된 플러그인 이름> 링크를 내보내지 마십시오.

정확한 사양 샘플 참조

플러그인 매니페스트 및 마켓플레이스 항목에 대한 정확한 표준 샘플 JSON은 다음을 사용하십시오:

• references/plugin-json-spec.md
• 기존 로컬 플러그인을 반복 개발하는 동안 업데이트/재설치 지침 및 재설치 후 새 스레드 피킹 동작은 references/installing-and-updating.md

유효성 검사

SKILL.md 편집 후 실행:

python3 ../skill-creator/scripts/quick_validate.py .

생성된 플러그인을 반환하기 전에 실행:

python3 scripts/validate_plugin.py <plugin-path>