CoCo CLI plugins

CoCo CLI plugins (플러그인)

CoCo CLI 플러그인은 단일 매니페스트 아래 스킬, 하위 에이전트, 슬래시 명령, 훅, MCP 서버를 묶는 자족적인 패키지예요. 플러그인을 사용하면 큐레이션된 에이전트 확장 집합을 하나의 단위로 제공할 수 있어요 — Git 저장소에서 팀과 공유하거나, 공식 마켓플레이스에서 설치하거나, 프로젝트 안에서 로컬로 개발할 수 있어요.

출처: CoCo CLI plugins

본문

이 주제는 플러그인 매니페스트, CoCo가 플러그인을 찾는 위치, 설치·관리 방법, 플러그인이 다른 확장 표면과 어떻게 구성되는지 다뤄요.

플러그인이 기여하는 것

플러그인은 다음 중 어떤 조합이든 기여할 수 있어요.

구성 요소	설명	참조
Skills	세션에 도메인별 지침·지식을 주입하는 Markdown 스킬 파일.	Skills
Subagents	전문화된 자율 작업을 위한 사용자 지정 에이전트 정의.	Subagents
Slash commands	CoCo CLI 프롬프트에서 호출되는 프로젝트 스타일 명령.	CLI reference
Hooks	PreToolUse나 UserPromptSubmit 같은 이벤트에서 실행되는 수명 주기 훅.	Hooks
MCP servers	에이전트에 외부 도구를 노출하는 Model Context Protocol 서버.	Model Context Protocol (MCP)

비활성 플러그인은 실행 중인 세션에 구성 요소를 기여하지 않아요. 플러그인에 activation.md 파일이 있으면 CoCo는 사용자가 세션에서 플러그인을 발견하고 다시 켤 수 있게 하는 작은 스텁 스킬을 생성해요.

플러그인 레이아웃

플러그인은 잘 알려진 경로에 매니페스트 파일이 있는 디렉터리예요.

my-plugin/
├── .cortex-plugin/                # or .claude-plugin/
│   ├── plugin.json                # manifest (required)
│   └── activation.md              # optional; surfaces a re-enable skill when inactive
├── skills/                        # auto-discovered if present
│   └── my-skill/SKILL.md
├── commands/                      # auto-discovered if present
│   └── my-command.md
├── agents/                        # auto-discovered if present
│   └── my-agent.md
├── hooks/hooks.json               # optional; can also be inline in plugin.json
└── .mcp.json                      # optional; can also be inline in plugin.json

CoCo는 .cortex-plugin/plugin.json 또는 .claude-plugin/plugin.json 중 어느 매니페스트든 받아요. 둘 다 있으면 .cortex-plugin이 이겨요.

plugin.json의 commands, skills, agents, hooks, mcpServers 필드는 선택 사항이에요. 생략하면 CoCo는 표준 하위 디렉터리(./commands, ./skills, ./agents)와 표준 파일(./hooks/hooks.json, ./.mcp.json)이 존재할 때 자동으로 가져와요.

플러그인 매니페스트

매니페스트는 다음 필드를 가진 JSON 파일이에요.

필드	유형	설명
`name`	string	필수. 소문자 케밥-케이스 식별자(예: `data-engineering`).
`description`	string	플러그인이 무엇을 하는지에 대한 짧고 사람이 읽을 수 있는 요약.
`version`	string	선택적 시맨틱 버전(예: `1.2.0`).
`author`	object	선택. `{ "name": "...", "url": "..." }`.
`commands`	string 또는 문자열 배열	슬래시 명령 Markdown 파일을 포함한 하나 이상의 디렉터리. 기본 `./commands`.
`skills`	string 또는 문자열 배열	스킬 SKILL.md 파일을 포함한 하나 이상의 디렉터리. 기본 `./skills`.
`agents`	string 또는 문자열 배열	하위 에이전트 정의 파일을 포함한 하나 이상의 디렉터리. 기본 `./agents`.
`hooks`	object, string, 또는 문자열 배열	인라인 HooksConfig(settings.json에서 사용되는 것과 같은 스키마), 그 스키마의 JSON 파일 경로, 또는 그런 경로 목록.
`mcpServers`	object, string, 또는 문자열 배열	MCPServerConfig 항목의 인라인 맵, JSON 파일 경로, 또는 그런 경로 목록. 기본 `./.mcp.json`(파일이 존재하면).
`requiresSandbox`	boolean	true면 플러그인이 CoCo 샌드박스 안에서 실행되기를 기대함을 신호. Sandbox-aware plugins 참고.

mcpServers 블록은 사용자 MCP 구성과 같은 스키마를 사용해요. 전체 서버 스키마는 Model Context Protocol (MCP)를 참고해요.

샘플 매니페스트:

{
  "name": "data-engineering",
  "description": "Skills, hooks, and MCP servers for Snowflake data engineering",
  "version": "1.0.0",
  "author": { "name": "Data Platform Team" },
  "skills": ["./skills"],
  "agents": ["./agents"],
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "bash",
        "hooks": [
          { "type": "command", "command": "bash hooks/validate-bash.sh" }
        ]
      }
    ]
  },
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://internal.example.com/mcp"
    }
  }
}

CoCo가 플러그인을 찾는 위치

CoCo는 세션 시작 시 여러 소스에서 플러그인을 발견해요. 플러그인은 이름으로 중복 제거되며, 이 순서에서 플러그인을 제공하는 첫 소스가 이겨요.

CLI 인자. 실행 시 하나 이상의 --plugin-dir 인자로 전달된 디렉터리.
연결 프로필. 활성 Snowflake 연결 프로필이 선언한 플러그인.
사용자 설정. ~/.snowflake/cortex/settings.json의 plugins 배열에 나열된 디렉터리.
관리 레지스트리. ~/.snowflake/cortex/plugins/ 아래 설치되고 ~/.snowflake/cortex/plugins/registry.json에 추적되는 플러그인. cortex plugin install이 플러그인을 두는 곳.
프로젝트 플러그인. 현재 작업 디렉터리의 .cortex/plugins/와 .claude/plugins/.
번들 플러그인. CoCo 바이너리에 포함되며 기본 활성. 일부 번들 플러그인은 기능 플래그 뒤에 게이트되어 모든 빌드에 없을 수 있어요.
번들 외부 플러그인. CoCo 스킬 저장소에서 동기화된 플러그인, 기본 비활성. cortex plugin enable <name>으로 켜요.

명령줄에서 플러그인을 설치, 활성화, 비활성화하면 이미 실행 중인 CoCo 세션은 변경을 자동으로 반영하지 않아요. 세션에서 /plugin reload를 실행해 플러그인 기여를 재집계하거나 CoCo를 재시작해요.

발견된 플러그인의 출처는 cortex plugin list와 /plugin info <name>에서 보고돼요.

플러그인 관리

명령줄에서 cortex plugin으로, 또는 CoCo 세션에서 대화형으로 /plugin 슬래시 명령으로 플러그인을 관리할 수 있어요.

명령 참조

명령	설명
`cortex plugin install <source>`	마켓플레이스, GitHub 약칭(owner/repo), 또는 전체 Git URL에서 플러그인 설치. `--inactive`는 설치하되 비활성으로 둠. 별칭: add.
`cortex plugin uninstall <name>`	관리 플러그인을 레지스트리에서 제거. 별칭: remove, delete, rm.
`cortex plugin enable <name>`	관리 플러그인 활성화. 별칭: activate.
`cortex plugin disable <name>`	플러그인을 제거하지 않고 비활성화. 별칭: deactivate.
`cortex plugin list`	출처, 구성 요소, 활성 상태와 함께 모든 발견 플러그인 나열.
`cortex plugin validate [target]`	플러그인의 매니페스트와 구성 요소 검증. target은 플러그인 이름이나 디렉터리. 기본은 현재 작업 디렉터리.
`cortex plugin update [name]`	등록된 소스에서 관리 플러그인의 최신 버전 가져오기. name 생략 시 모든 관리 플러그인 업데이트.

대화형 관리

CoCo CLI 세션 안에서 /plugin(별칭 /plugins)을 실행해 세션을 떠나지 않고 플러그인을 관리해요. 사용 가능한 하위 명령:

하위 명령	설명
`/plugin list`	모든 발견 플러그인 나열.
`/plugin info <name>`	단일 플러그인의 상세 메타데이터 표시.
`/plugin install [--inactive] <source>`	마켓플레이스나 Git 소스에서 플러그인 설치.
`/plugin uninstall <name>`	관리 플러그인 제거.
`/plugin enable <name>`	플러그인 활성화.
`/plugin disable <name>`	플러그인 비활성화.
`/plugin update [name]`	하나 또는 모든 관리 플러그인 업데이트.
`/plugin validate`	현재 플러그인 디렉터리 검증.
`/plugin reload`	디스크에서 플러그인 런타임 다시 로드.

설치 소스

cortex plugin install은 세 가지 소스를 받아요.

소스 형태	예시	동작
마켓플레이스 이름	`cortex plugin install python-repl`	이름을 공식 CoCo 플러그인 마켓플레이스를 통해 해석.
GitHub 약칭	`cortex plugin install owner/repo` 또는 `cortex plugin install github:owner/repo@branch`	공개 GitHub 저장소로 해석.
Git URL	`cortex plugin install https://github.com/owner/repo.git`	저장소를 직접 복제. `git@`, `ssh://`, `file://` URL도 지원.

CoCo는 소스를 관리 플러그인 디렉터리에 복제하고, 매니페스트를 검증하고, 다음에 등록해요.

~/.snowflake/cortex/plugins/registry.json

각 레지스트리 항목은 플러그인의 소스, 설치 타임스탬프, 마지막 업데이트 타임스탬프, 현재 활성 여부를 기록해요. cortex plugin update는 등록된 소스에서 다시 가져와요.

플러그인이 런타임과 구성되는 방식

세션이 시작될 때(또는 /plugin reload를 실행할 때) CoCo는 모든 활성 플러그인의 기여를 라이브 런타임으로 집계해요.

각 플러그인의 스킬이 사용자, 프로젝트, 번들 스킬과 함께 스킬 레지스트리에 추가돼요. 플러그인 스킬은 출처로 태그되어 /skill list에서 볼 수 있어요.
하위 에이전트가 하위 에이전트 검색 경로에 추가돼요.
슬래시 명령이 명령 로더에 등록돼요.
훅은 고정 소스 우선순위(전역, 사용자, 프로젝트, 로컬 프로젝트, 플러그인, 연결 프로필(최고))로 전역 훅 목록에 병합돼요. 두 훅이 충돌하면 더 높은 우선순위 소스가 이겨요.
MCP 서버가 MCP 연결 매니저에 추가돼요. 플러그인 서버는 사용자·프로필 서버보다 우선순위가 낮고, 관리자가 사용자 MCP 서버를 비활성화하면 완전히 건너뛰어져요.

활성 플러그인 중 하나가 requiresSandbox: true를 설정하면, 샌드박스 기능을 사용할 수 있을 때 CoCo가 세션용 샌드박스 런타임을 시작해요. Sandbox-aware plugins 참고.

샌드박스 인지 플러그인

신뢰되지 않은 코드를 실행하거나 외부 서비스와 상호작용하는 플러그인은 매니페스트에 "requiresSandbox": true를 선언할 수 있어요. CoCo는 통합 중 이 플래그를 읽고, 샌드박스 기능이 켜져 있으면 세션용 샌드박스 런타임을 시작해요.

이 플래그는 샌드박스를 지원하지 않는 플랫폼이나 빌드에서 정보 제공용이에요 — 플러그인 로딩을 차단하지 않아요. 샌드박스 런타임에 대한 자세한 내용은 sandbox를 참고해요.

관리 플러그인 레지스트리

cortex plugin install로 설치된 플러그인은 다음에 쓰여져요.

~/.snowflake/cortex/plugins/

그 디렉터리의 레지스트리 파일 registry.json은 각 관리 플러그인을 추적해요.

{
  "data-engineering": {
    "source": "github:my-org/cortex-code-data-eng#main",
    "installedAt": "2026-04-24T10:15:00Z",
    "updatedAt": "2026-04-24T10:15:00Z",
    "active": true,
    "lastUpdateError": null
  }
}

레지스트리는 동시 수정을 방지하기 위해 쓰는 동안 잠겨요. lastUpdateError는 cortex plugin update의 가장 최근 실패를 기록해요.

플러그인 작성

로컬에서 플러그인을 만들려면:

플러그인용 디렉터리를 만들고 매니페스트를 초기화해요.

mkdir -p my-plugin/.cortex-plugin

최소한 name과 description으로 my-plugin/.cortex-plugin/plugin.json을 만들어요.

{
  "name": "my-plugin",
  "description": "What this plugin does",
  "version": "0.1.0"
}

매니페스트 옆에 구성 요소를 추가해요. 표준 레이아웃이 자동으로 발견돼요.

my-plugin/
├── .cortex-plugin/plugin.json
├── skills/my-skill/SKILL.md
├── agents/my-agent.md
├── commands/my-command.md
├── hooks/hooks.json
└── .mcp.json

플러그인을 검증해요.

cortex plugin validate ./my-plugin

검증기는 구성 요소별(매니페스트, 활성화, 스킬, 명령, 에이전트, 훅, MCP 서버)로 문제를 보고해요.

설치하지 않고 --plugin-dir을 실행 시 전달해 플러그인을 로컬에서 사용해요.

cortex --plugin-dir ./my-plugin

또는 프로젝트의 .cortex/plugins/에 디렉터리를 넣어 자동으로 로드하게 해요.

공유할 준비가 되면 플러그인을 Git 저장소에 푸시해요. 다른 개발자는 다음으로 설치할 수 있어요.

cortex plugin install your-org/your-plugin-repo

이름 충돌과 구성 요소 오버라이드

두 플러그인이 같은 이름의 구성 요소를 기여하면 발견 순서에서 첫 소스가 이겨요(CoCo가 플러그인을 찾는 위치 참고). 예를 들어 .cortex/plugins/의 프로젝트 플러그인은 cortex plugin install로 설치된 같은 이름의 관리 플러그인을 오버라이드해요. 어느 플러그인이 이기는지 보려면 cortex plugin list를 사용해요.

스킬에 관해서는 스킬 충돌을 참고해요 — 같은 스킬 이름이 여러 루트에서 오면 CoCo는 /skill list에 충돌 표시를 보여줘요.

관리자 제어

관리자는 Snowflake 연결 프로필의 일부로 플러그인을 제공할 수 있어서, 그 프로필의 모든 사용자가 일관된 스킬·에이전트·훅·MCP 서버 기준선을 얻게 돼요. 프로필 제공 플러그인은 cortex plugin list에 출처 profile로 나타나요.

사용자 MCP 강제도 플러그인 선언 MCP 서버에 영향을 줘요. managed settings에서 areUserMcpServersAllowed가 false면 플러그인 MCP 서버가 사용자 MCP 서버와 함께 건너뛰어져요. 전체 강제 스키마는 managed settings를 참고해요.

플러그인 문제 해결

플러그인이 cortex plugin list에 나타나지 않음

매니페스트가 .cortex-plugin/plugin.json 또는 .claude-plugin/plugin.json에 존재하는지 확인해요.
cortex plugin validate <path>를 실행해 매니페스트 오류를 표시해요.
Git으로 설치했다면 ~/.snowflake/cortex/plugins/registry.json에서 null이 아닌 lastUpdateError가 있는 항목을 확인해요.

플러그인의 스킬, 명령, 또는 에이전트가 로드되지 않음

플러그인이 활성인지 확인해요: cortex plugin list에서 active: true를 찾아요.
cortex plugin validate <name>을 실행해 구성 요소 수준 문제를 봐요.
세션에서 /plugin reload를 실행해 CoCo를 재시작하지 않고 플러그인 기여를 재집계해요.

플러그인의 MCP 서버가 없음

플러그인이 활성이고 mcpServers 블록이 유효한 JSON인지 확인해요.
관리자가 사용자 MCP 서버를 비활성화했는지 확인해요. 그 모드에서는 플러그인 MCP 서버가 건너뛰어져요.
/mcp를 사용해 서버가 알려진 서버로 나타나는지 확인해요.

플러그인 모범 사례

버전을 고정해요. 매니페스트에 version 필드를 포함해 사용자가 무엇을 실행 중인지 알게 해요.
배송 전 검증해요. 릴리스 프로세스의 일부로 cortex plugin validate를 실행해요.
MCP 자격 증명을 매니페스트에 넣지 마요. MCP 서버 항목에서 환경 변수 확장이나 OAuth를 사용해요. 토큰을 플러그인 소스에 절대 체크하지 마요.
규칙보다 규약을 선호해요. 기본 ./skills, ./agents, ./commands 디렉터리를 사용해 매니페스트를 최소로 유지해요.
activation.md를 제공해요. 플러그인이 비활성화되면 activation.md가 사용자가 정확한 이름을 알지 않아도 스텁 스킬을 통해 발견할 수 있게 해요.

더 알아보기

Plugins in CoCo Desktop — 데스크톱 플러그인
Model Context Protocol (MCP) — 플러그인 MCP 서버
Managed settings — 관리자 강제