참조: 플러그인 생태계¶

agy-cli의 플러그인 시스템에 대한 심층 참조입니다. 필수 명령어는 모듈 1 — 섹션 1.7에서 다룹니다. 이 페이지는 커스텀 플러그인을 구축하고 유지 관리하는 팀을 위한 전체 라이프사이클 세부 정보를 제공합니다.

2.0 — 플러그인이 중요한 이유 5 min¶

agy-cli의 플러그인 시스템은 독특한 기능을 수행합니다. 재설치나 재구성 없이 Gemini CLI 또는 Claude Code에 이미 설치한 플러그인을 가져올 수 있습니다. 확장 프로그램에 대한 기존 투자가 그대로 이어집니다.

# See what plugins are currently active in agy
agy plugin list

출력은 JSON 형식이며 각 플러그인의 이름, 소스, 가져오기 날짜 및 구성 요소(스킬, 명령어, mcpServers, 에이전트)를 보여줍니다.

# More readable
agy plugin list | python3 -m json.tool

📖 공식 문서: 플러그인 · MCP · 스킬

2.1 — Gemini CLI에서 가져오기 10분¶

패턴: Cross-Tool Plugin Bridge — 전체 Gemini CLI 플러그인 설정을 agy로 가져옵니다.

모든 Gemini CLI 플러그인 가져오기¶

agy plugin import gemini

agy는 로컬 Gemini CLI 설치를 스캔하여 설치된 모든 플러그인을 검색하고, 해당 구성 요소(스킬, 명령어, MCP 서버, 에이전트)를 ~/.gemini/antigravity/에 있는 agy의 설정으로 스테이징합니다.

출력은 다음과 같습니다:

  [ok]    code-review
          ✔ skills      : 3 processed
          ✔ commands    : 2 processed
          - mcpServers  : skipped (not found)
  [ok]    gemini-deep-research
          ✔ commands    : 1 processed
          ✔ mcpServers  : 1 processed
  [skip]  superpowers (already imported)

agy plugin import gemini --force

What Gets Imported¶

2.2 — Importing from Claude Code 5 min¶

Pattern: Unified Tool Surface — if you use Claude Code alongside agy, import its plugins too.

agy plugin import claude

Same mechanic — agy discovers your Claude Code extension installations and bridges compatible components.

2.3 — Managing Plugins Per-Project 10 min¶

Pattern: Project-Scoped Plugin Config — not every plugin is appropriate for every codebase.

Enable / Disable¶

# 이 세션/프로젝트에 대해 플러그인 비활성화
agy plugin disable gemini-deep-research

# 다시 활성화
agy plugin enable gemini-deep-research

# 현재 상태 확인
agy plugin list

Plugin Locations¶

Plugins can be installed at two levels:

Install a Specific Plugin¶

# 이름으로 설치 (설정된 소스에서)
agy plugin install <plugin-name>

# 특정 버전 설치
agy plugin install <plugin-name>@<version>

2.4 — Validating a Plugin 10 min¶

Pattern: Plugin-as-Code — treat plugin definitions like source code. Validate before shipping.

Validate an Existing Plugin Directory¶

# 플러그인 디렉터리 유효성 검사
agy plugin validate ./path/to/my-plugin

# 또는 현재 디렉터리 유효성 검사
agy plugin validate .

This checks that the plugin's plugin.json manifest is well-formed and all referenced components exist.

Build a Minimal Custom Plugin¶

A valid agy plugin needs a plugin.json manifest. Here's the official structure:

my-plugin/
├── plugin.json          ← 매니페스트 (필수)
├── mcp_config.json      ← MCP 서버 정의 (선택 사항)
├── hooks.json           ← 훅 이벤트 핸들러 (선택 사항)
├── skills/              ← YAML 프런트매터가 있는 SKILL.md 파일
│   └── my-skill/
│       └── SKILL.md
├── agents/              ← 서브에이전트 정의 (선택 사항)
└── rules/               ← 규칙 파일 (선택 사항)
    └── my-rules.md

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "내 사용자 지정 agy 플러그인",
  "components": ["skills"]
}

# 유효성 검사
agy plugin validate ./my-plugin

# 유효한 경우 다음이 표시됩니다: ✔ Plugin manifest is valid

Interacting with Plugin Components¶

Use slash commands to inspect active plugin components in a session:

Exercise: Validate the Workshop Plugin¶

The workshop repo includes a sample plugin at samples/plugins/workshop-helpers/. Validate it:

agy plugin validate samples/plugins/workshop-helpers/

2.5 — Plugin Architecture Overview¶

graph LR
    GC["Gemini CLI\n플러그인"] --> |agy plugin import gemini| S["플러그인 스테이징\n~/.gemini/antigravity/plugins/"]
    CC["Claude Code\n확장 프로그램"] --> |agy plugin import claude| S
    S --> |agy plugin enable/disable| A[agy 세션]
    A --> SK[스킬]
    A --> MCP[MCP 서버]
    A --> AG[에이전트]
    A --> RU[규칙]
    A --> HK[훅]
    A --> SD[사이드카]

Plugin staging directory structure:

~/.gemini/antigravity/plugins/<name>/
├── plugin.json
├── mcp_config.json
├── hooks.json
├── skills/
├── agents/
├── rules/
└── sidecars/          ← 플러그인 범위의 백그라운드 프로세스

2.6 — Sidecars: Persistent Background Processes 15 min¶

Pattern: Always-On Agent — sidecars run alongside AGY CLI, independently of any conversation. Use them for scheduled tasks, event watchers, and persistent background workers.

📖 Source: sidecars

What Sidecars Are¶

A sidecar is a background process that AGY manages for you: it launches automatically when AGY starts, restarts on crash, and runs independently of your active conversation. Unlike hooks (which fire in response to conversation events), sidecars are always running.

Three use cases:

Configuration¶

Sidecars are discovered from two locations:

# 전역 사이드카 (모든 프로젝트에서 사용 가능)
~/.gemini/config/sidecars/<sidecar-name>/sidecar.json

# 플러그인 범위 사이드카 (플러그인과 함께 제공됨)
~/.gemini/config/plugins/<plugin-name>/sidecars/<sidecar-name>/sidecar.json

The directory name becomes the sidecar's ID. Plugin sidecars get the ID <pluginName>/<sidecarName>.

Sidecars are disabled by default. Enable them explicitly in ~/.gemini/config/config.json:

{
  "sidecars": {
    "pr-triage": {
      "enabled": true
    },
    "my-plugin/log-watcher": {
      "enabled": true,
      "projectId": "<conversation-project-id>"
    }
  }
}

sidecar.json Schema¶

Example 1: Background Worker Script¶

{
  "description": "빌드 대기열을 모니터링하고 실패 시 알림을 보냅니다.",
  "command": "python3",
  "args": ["watch_builds.py"],
  "restart_policy": "on-failure",
  "env": {
    "BUILD_QUEUE_URL": "https://ci.example.com/api/queue"
  }
}

Example 2: Scheduled Recurring Task (the schedule builtin)¶

The schedule builtin takes a cron expression as its first arg, then the command + args to run:

{
  "description": "매시간 PR 분류 — 수신된 리뷰 요청을 요약합니다.",
  "builtin": "schedule",
  "args": [
    "0 * * * *",
    "agentapi",
    "new-conversation",
    "내 리뷰를 기다리는 모든 열린 PR을 요약해 줘. 긴급도에 따라 그룹화해 줘."
  ]
}

agentapi is automatically available to sidecars — it lets them programmatically create or message conversations:

# 사이드카에서 새 대화 시작
agentapi new-conversation "<prompt>"

# 기존 대화에 메시지 보내기
agentapi send-message <conversation_id> "<prompt>"

Runtime Data¶

Sidecar output is stored at:

~/.gemini/antigravity/sidecar_data/<sidecarId>/
├── data/     ← 영구 스토리지 (ANTIGRAVITY_EXECUTABLE_DATA_DIR 환경 변수)
├── logs/     ← 타임스탬프가 기록된 stdout/stderr 로그
└── events/   ← agentapi 호출의 JSON 레코드

Directory Structure for a Plugin Sidecar¶

~/.gemini/config/plugins/my-plugin/
└── sidecars/
    └── pr-triage/
        ├── sidecar.json   ← 설정 (필수)
        └── triage.py      ← 헬퍼 스크립트 (선택 사항, 이 디렉터리에서 실행됨)

모듈 2 연습 문제¶

워크숍으로 돌아가기¶

→ 모듈 1: SDLC 생산성 향상 — 플러그인은 섹션 1.7에서 소개됩니다

→ 치트시트 — 모든 플러그인 및 사이드카 명령어를 한곳에 모아두었습니다