플러그인 생성기
빠른 시작
- 스캐폴딩 스크립트 실행:
# 플러그인 이름은 소문자 하이픈-케이스로 정규화되며 최대 64자여야 합니다.
# 생성된 폴더와 plugin.json의 이름은 항상 동일합니다.
# 스킬 루트(이 `SKILL.md`가 있는 디렉터리)에서 실행하세요.
# 기본적으로 `~/plugins/<plugin-name>`에 생성됩니다.
python3 scripts/create_basic_plugin.py <plugin-name>
-
요청에 특정 메타데이터가 있는 경우
<plugin-path>/.codex-plugin/plugin.json을 편집하세요. 스캐폴드는 유효한 기본값으로 시작하며[TODO: ...]플레이스홀더를 포함해서는 안 됩니다. -
플러그인이 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에서는 사용자 프로필 아래의 동등한 경로를 사용하세요.
- 필요에 따라 선택적 동반 폴더를 생성/조정하세요:
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).
- 생성된 플러그인을 반환하기 전에 다음을 실행하세요:
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-pluginMy--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를 통해 명시적으로 설치해야 하는 것으로 간주하세요. - 마켓플레이스 이름이 필요한 경우
scripts/read_marketplace_name.py를 선호하세요. 인수 없이 실행하면 기본 개인 마켓플레이스를 읽고, 명시적 경로를 제공하면 저장소/팀 마켓플레이스에서도 작동합니다. - 두 위치 모두 생성된 소스 경로는
./plugins/<plugin-name>으로 유지됩니다. - 마켓플레이스 루트 메타데이터는 최상위
name과 선택적interface.displayName을 지원합니다. plugins[]의 플러그인 순서는 Codex의 렌더링 순서로 간주합니다. 사용자가 명시적으로 목록 재정렬을 요청하지 않는 한 새 항목을 추가하세요.displayName은 개별plugins[]항목이 아닌 마켓플레이스interface객체에 속합니다.- 생성된 각 마켓플레이스 항목은 다음을 모두 포함해야 합니다:
policy.installationpolicy.authenticationcategory
- 새 항목의 기본값:
policy.installation: "AVAILABLE"policy.authentication: "ON_INSTALL"
- 사용자가 다른 허용 값을 명시적으로 지정하는 경우에만 기본값을 재정의하세요.
- 허용되는
policy.installation값:NOT_AVAILABLEAVAILABLEINSTALLED_BY_DEFAULT
- 허용되는
policy.authentication값:ON_INSTALLON_USE
policy.products는 재정의로 처리하세요. 사용자가 명시적으로 제품 게이팅을 요청하지 않는 한 생략하세요.- 생성된 플러그인 항목 형태는 다음과 같습니다:
{
"name": "plugin-name",
"source": {
"source": "local",
"path": "./plugins/plugin-name"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Productivity"
}
-
동일한 플러그인 이름의 기존 마켓플레이스 항목을 의도적으로 교체하는 경우에만
--force를 사용하세요. -
대상 마켓플레이스 파일이 아직 존재하지 않는 경우, 최상위
"name","interface"객체("displayName"포함) 및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: ...]플레이스홀더를 남기지 마세요. - 동반 파일이 실제로 생성되지 않는 한
plugin.json에apps와mcpServers를 포함하지 마세요. - 유효성 검사에서 거부하는 지원되지 않는 플러그인 매니페스트 필드(
hooks포함)는 생략하세요. - 기존 플러그인 경로 내에 파일을 생성하는 경우, 덮어쓰기가 의도적인 경우에만
--force를 사용하세요. - 기존 마켓플레이스
interface.displayName을 유지하세요. - 마켓플레이스 항목을 생성할 때 값이 기본값이더라도 항상
policy.installation,policy.authentication,category를 작성하세요. - 사용자가 명시적으로 해당 재정의를 요청하는 경우에만
policy.products를 추가하세요. - 마켓플레이스
source.path를 선택한 마켓플레이스 루트 기준./plugins/<plugin-name>으로 유지하세요. --marketplace-name은personal이라는 이름이 이미 다른 곳에서 사용 중이거나 설치되어 있어 새 마켓플레이스 파일의 이름이personal이 아니어야 하는 경우에만 사용하세요.- 마켓플레이스 파일을 작성하는 데 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 링크로 작성하세요. - 보기 딥링크는
codex://plugins/<정규화된 플러그인 이름>?marketplacePath=<절대 marketplace.json 경로>를 사용합니다. 공유 딥링크는 동일한 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>