플러그인과 마켓플레이스

플러그인과 마켓플레이스 (Plugins and Marketplaces)

에이전트에 스킬 하나만 더해도 작업 효율이 크게 바뀔 수 있어요. Deep Agents Code는 재사용 가능한 스킬, MCP 서버, 훅, Python 확장을 **플러그인(plugin)**으로 묶어서 확장할 수 있게 해줘요. 그리고 **마켓플레이스(marketplace)**는 이런 플러그인을 프로젝트나 팀 전체에서 발견·설치하기 위한 카탈로그예요. 여기서 플러그인과 마켓플레이스를 어떻게 관리하고 만드는지 살펴볼게요.

출처: 공식문서

설치 보안 주의

플러그인과 마켓플레이스는 신뢰하는 소스에서만 설치하세요. 활성화된 플러그인은 지시사항을 추가하고, MCP 서버·훅 명령·Python 확장을 사용자 권한으로 실행할 수 있어요.

플러그인 대화형 관리

dcode 세션에서 마켓플레이스를 탐색하고 플러그인을 관리하려면:

  1. /plugins로 플러그인 매니저를 엽니다.
  2. Marketplaces 탭에서 마켓플레이스를 추가합니다. 지원되는 소스는:
    • owner/repo 형식의 GitHub 저장소(선택적으로 @branch-or-tag 뒤에 붙임)
    • HTTPS Git 저장소 URL(선택적으로 #branch-or-tag)
    • 마켓플레이스 JSON 파일을 제공하는 HTTPS URL
    • 로컬 마켓플레이스 디렉토리 또는 JSON 파일
  3. 마켓플레이스에서 플러그인을 설치합니다.
  4. /reload로 새로 설치한 플러그인 스킬·MCP 서버·훅을 세션을 재시작하지 않고 활성화합니다. Python 확장이 있는 플러그인은 에이전트 그래프를 다시 빌드해야 하므로 /restart가 필요합니다.

플러그인 매니저는 설치된 플러그인을 활성화·비활성화·제거할 수도 있어요. 플러그인을 비활성화하면 설치 상태는 유지하지만, /reload나 새 세션 후에는 그 스킬·MCP 서버·훅이 제외돼요. Python 확장은 /restart하거나 새 세션을 시작하기 전까지 현재 그래프에 로드된 상태로 남아요.

마켓플레이스를 제거하면 그 플러그인이 제거되고 관리 캐시 데이터가 삭제돼요. 마켓플레이스가 로컬 디렉토리에서 온 경우 Deep Agents Code는 원본 소스를 보존해요. 활성 세션에 적용하려면 /reload하거나 새 세션을 시작하세요.

플러그인 자동 업데이트

Deep Agents Code는 첫 프롬프트 후 백그라운드에서 설치된 플러그인을 업데이트할 수 있어요. 업데이트는 자신의 매니페스트로 옵트인한 활성화된 플러그인에만 적용돼요. 플러그인 작성자는 그 플러그인의 plugin.json에 다음 블록을 추가해 플러그인별로 옵트인해요:

{
  "extensions": {
    "com.langchain.deepagents.code": {
      "autoUpdate": true
    }
  }
}

실행 중인 세션은 /reload를 실행하기 전까지 현재 플러그인 버전을 계속 사용해요. 자동 플러그인 업데이트를 전역으로 끄려면 config.toml에 [plugins].auto_update = false를 설정하거나 환경에 DEEPAGENTS_CODE_PLUGIN_AUTO_UPDATE=false를 설정하세요.

명령줄에서 플러그인 관리

스크립트와 터미널 기반 관리를 위해 dcode plugin을 써요. 플러그인 ID는 plugin-name@marketplace-name 형식을 사용해요.

# Add and inspect a marketplace
dcode plugin marketplace add acme/plugins
dcode plugin marketplace list

# Browse and install plugins
dcode plugin list
dcode plugin install code-review@acme-tools

# Change plugin state
dcode plugin disable code-review@acme-tools
dcode plugin enable code-review@acme-tools

# Remove a plugin or marketplace
dcode plugin uninstall code-review@acme-tools
dcode plugin marketplace remove acme-tools

plugin list와 plugin marketplace list는 --json을 받아요. 플러그인 설치 후 활성 대화형 세션에서는 /reload를 실행하거나 새 세션을 시작하세요.

플러그인 스킬·MCP 서버·훅 사용

플러그인 스킬은 프로젝트·사용자·다른 플러그인 스킬과의 충돌을 막기 위해 네임스페이스로 구분돼요. 플러그인 ID와 스킬 경로로 스킬을 호출해요:

/skill:plugin-name@marketplace-name:skill-name optional arguments

대화형 모드에서 자동완성은 더 짧은 /plugin-name:skill-name 형식도 매치해서 정식 /skill: 명령으로 확장해요. 중첩 스킬 디렉토리는 각 디렉토리를 네임스페이스에 추가해요. 예를 들어 quality@acme-tools의 skills/review/security/SKILL.md는 /skill:quality@acme-tools:review:security가 돼요.

활성화된 플러그인은 MCP 서버도 제공할 수 있어요. Deep Agents Code는 플러그인이 로드될 때 이 서버들을 일반 MCP 설정과 병합해요. /mcp로 사용 가능한 서버와 도구를 확인하세요.

플러그인 훅은 사용자·프로젝트 훅과 같은 수명주기 이벤트와 핸들러 형식을 사용해요. 플러그인 매니저는 각 플러그인이 선언하는 이벤트를 나열해요. 플러그인을 활성화하는 것이 그 훅의 유일한 동의 게이트예요. 워크스페이스 신뢰는 프로젝트 훅에 적용되지, 플러그인 훅에는 적용되지 않아요.

플러그인 만들기

Deep Agents Code 플러그인은 지원되는 구성요소 중 어느 하나를 포함하는 디렉토리예요:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── review/
│       └── SKILL.md
├── hooks/
│   └── hooks.json
└── .mcp.json

Deep Agents Code는 .codex-plugin/plugin.json도 인식해요. 구성요소가 기본 위치를 쓰면 매니페스트는 선택이에요. 플러그인에 스킬이 하나뿐이면 skills/를 만들지 않고 SKILL.md를 플러그인 루트에 둘 수 있어요.

플러그인 매니페스트 정의

있을 때 .claude-plugin/plugin.json 또는 .codex-plugin/plugin.json은 name을 반드시 포함해야 해요. 버전과 커스텀 구성요소 경로도 선언할 수 있어요:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "skills": "./skills",
  "mcpServers": "./.mcp.json",
  "hooks": "./hooks/hooks.json"
}

skills, mcpServers, hooks 필드는 경로 문자열 또는 경로 배열을 받아요. mcpServers와 hooks는 인라인 구성 객체도 담을 수 있어요. 모든 구성요소 경로는 ./로 시작하고, 플러그인 루트 안에 있어야 하며, ..를 포함하면 안 돼요.

커스텀 경로가 없으면 Deep Agents Code는 다음을 발견해요:

  • skills/ 아래의 스킬, 또는 skills/ 디렉토리가 없을 때 루트 SKILL.md
  • 루트 .mcp.json 파일의 MCP 서버
  • hooks/hooks.json의 훅

스킬 추가

각 스킬을 SKILL.md를 담은 디렉토리로 구성해요:

skills/
└── review/
    ├── SKILL.md
    └── checklist.md

스탠드얼론 Deep Agents Code 스킬과 같은 스킬 형식을 사용해요. 설치된 플러그인 이름이 스킬 네임스페이스가 돼요. 자세한 내용은 Memory and skills 문서를 참고하세요.

MCP 서버 추가

표준 MCP 서버 정의를 .mcp.json에 두거나, 플러그인 매니페스트에서 mcpServers로 인라인 선언해요. MCP 서버와 훅 명령은 이런 경로 변수를 지원해요:

  • ${CLAUDE_PLUGIN_ROOT} 또는 ${PLUGIN_ROOT}: 설치된 플러그인 디렉토리
  • ${CLAUDE_PLUGIN_DATA} 또는 ${PLUGIN_DATA}: 플러그인의 쓰기 가능한 데이터 디렉토리
  • ${CLAUDE_PROJECT_DIR}: 활성 프로젝트 디렉토리

예를 들어:

{
  "mcpServers": {
    "review-tools": {
      "command": "python",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.py"],
      "env": {
        "CACHE_DIR": "${CLAUDE_PLUGIN_DATA}"
      }
    }
  }
}

지원되는 MCP 전송과 필드는 MCP tools 문서를 참고하세요.

훅 추가

훅 문서를 hooks/hooks.json에 두거나, 상대 hooks 경로를 선언하거나, 플러그인 매니페스트에 인라인으로 정의해요. 훅 명령은 위 경로 변수를 받아요. 구성과 이벤트 참조는 Hooks 문서를 참고하세요.

Python 확장 추가

Python 확장은 DEEPAGENTS_CODE_EXPERIMENTAL=1이 필요합니다.

플러그인 매니페스트의 Deep Agents Code 네임스페이스 아래에 Python 진입 파일 하나 또는 목록을 선언해요:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "extensions": {
    "com.langchain.deepagents.code": {
      "pythonExtensions": "./extension.py"
    }
  }
}

플러그인은 비어 있지 않은 version을 선언해야 해요. 각 항목은 ./로 시작하고 플러그인 루트 안에 있어야 해요. 설치된 플러그인 확장을 변경한 후에는 dcode를 재시작하세요. 설정 함수, 지원 등록, 신뢰 모델, 보안 동작은 Python extensions 문서를 참고하세요.

마켓플레이스 만들기

마켓플레이스는 이름과 plugins 배열을 가진 JSON 카탈로그예요. 마켓플레이스 루트의 다음 경로 중 하나에 저장해요:

  • .claude-plugin/marketplace.json
  • .agents/plugins/marketplace.json
  • .agents/plugins/api_marketplace.json

다음 마켓플레이스는 같은 저장소에 저장된 플러그인 하나를 담고 있어요:

{
  "name": "acme-tools",
  "plugins": [
    {
      "name": "code-review",
      "source": "./plugins/code-review",
      "description": "Review code for correctness and maintainability"
    }
  ]
}

각 플러그인 항목은 name과 source를 필요로 해요. description과 author도 포함할 수 있어요. 로컬 소스 경로는 ./로 시작하고 마켓플레이스 루트 안에 있어야 해요. 모든 로컬 플러그인이 다른 기본 디렉토리를 공유할 때 metadata.pluginRoot를 설정하세요.

마켓플레이스 항목은 외부 Git 소스도 쓸 수 있어요:

{
  "name": "acme-tools",
  "plugins": [
    {
      "name": "code-review",
      "source": {
        "source": "github",
        "repo": "acme/code-review-plugin",
        "ref": "v1.0.0"
      }
    },
    {
      "name": "release-tools",
      "source": {
        "source": "git-subdir",
        "url": "https://github.com/acme/developer-tools.git",
        "path": "./plugins/release-tools",
        "ref": "main"
      }
    }
  ]
}

지원되는 외부 플러그인 소스 유형은 github, url, git-subdir예요. 원격 URL은 HTTPS여야 해요. 직접 JSON URL로 추가된 마켓플레이스는 카탈로그 파일만 다운로드되므로 로컬 상대 플러그인 소스를 포함할 수 없어요. 카탈로그가 같은 소스 트리의 플러그인 디렉토리를 참조한다면 Git 저장소나 로컬 디렉토리를 사용하세요.

로컬 마켓플레이스는 디렉토리를 추가하고, 플러그인을 설치하고, 새 세션을 시작하거나 /reload를 실행해 테스트해요:

dcode plugin marketplace add ./my-marketplace
dcode plugin install code-review@acme-tools

더 알아보기 (Learn more)