633</PluginExplorer>633</PluginExplorer>
634 634
635<h2 id="add-each-kind-of-component">635<h2 id="add-each-kind-of-component">
636 각 종류의 컴포넌트 추가636 각 유형의 구성 요소 추가하기
637</h2>637</h2>
638 638
639아래의 각 섹션은 한 종류의 컴포넌트를 다룹니다: 플러그인에서 파일이 어디로 가는지, 검증하는 예제, 플러그인이 로드된 후 사용자가 보는 것, 기본 위치를 변경하는 manifest 키. 플러그인이 필요한 것들을 추가합니다; 아무것도 필수가 아닙니다.639아래 각 섹션은 한 가지 유형의 구성 요소를 다룹니다. 플러그인에서 해당 파일을 두는 위치, 검증을 통과하는 예시, 플러그인이 로드된 후 사용자에게 보이는 내용, 기본 위치를 변경하는 매니페스트 키를 설명합니다. 플러그인에 필요한 것만 추가하면 되며, 필수 항목은 없습니다.
640 640
641<h3 id="skills">641<h3 id="skills">
642 Skills642 Skills
643</h3>643</h3>
644 644
645[skill](/docs/ko/skills)은 설명이 작업과 일치할 때 Claude가 로드할 수 있는 `SKILL.md` 파일입니다. 사용자는 또한 명령으로 실행할 수 있습니다. 각 skill을 `skills/` 아래의 자신의 디렉토리에 저장합니다:645[스킬](/docs/ko/skills)은 설명이 작업과 일치할 때 Claude가 로드할 수 있는 `SKILL.md` 파일입니다. 사용자가 명령으로 직접 실행할 수도 있습니다. 각 스킬은 `skills/` 아래의 개별 디렉터리에 저장합니다.
646 646
647```text theme={null}647```text theme={null}
648my-plugin/648my-plugin/
653 └── SKILL.md653 └── SKILL.md
654```654```
655 655
656`SKILL.md`에 `description`을 제공하여 Claude가 언제 사용할지 알 수 있도록 합니다:656Claude가 언제 사용할지 알 수 있도록 `SKILL.md`에 `description`을 지정합니다.
657 657
658```markdown skills/review/SKILL.md theme={null}658```markdown skills/review/SKILL.md theme={null}
659---659---
663Review the changed files. Report style problems first, then missing tests.663Review the changed files. Report style problems first, then missing tests.
664```664```
665 665
666플러그인을 로드한 후, `/my-plugin:review`는 skill을 실행합니다. 명령 이름과 누가 호출할 수 있는지는 다음 규칙을 따릅니다:666플러그인을 로드하면 `/my-plugin:review`가 스킬을 실행합니다. 명령 이름과 호출 주체는 다음 규칙을 따릅니다.
667 667
668* **명령 이름**: `/<plugin>:<directory>`, 따라서 `my-plugin`의 `skills/review/SKILL.md`는 `/my-plugin:review`입니다. frontmatter에서 `name`을 설정하면, 마지막 세그먼트를 대체하고 플러그인 접두사는 유지됩니다. [skill이 명령 이름을 얻는 방법](/docs/ko/skills#how-a-skill-gets-its-command-name)을 참조합니다668* **명령 이름**: `/<plugin>:<directory>` 형식이므로 `my-plugin`의 `skills/review/SKILL.md`는 `/my-plugin:review`가 됩니다. frontmatter에서 `name`을 설정하면 마지막 세그먼트가 대체되고 플러그인 접두사는 유지됩니다. [스킬의 명령 이름이 정해지는 방식](/docs/ko/skills#how-a-skill-gets-its-command-name)을 참조하십시오
669* **누가 호출하는가**: Claude, 사용자, 또는 둘 다, frontmatter로 제어됩니다. [skill 호출을 제어하는 사람](/docs/ko/skills#control-who-invokes-a-skill)을 참조합니다669* **호출 주체**: Claude, 사용자 또는 둘 다이며, frontmatter로 제어합니다. [스킬 호출 주체 제어하기](/docs/ko/skills#control-who-invokes-a-skill)를 참조하십시오
670 670
671기본 `skills/` 디렉토리 외부에 skills를 배치할 수도 있습니다:671기본 `skills/` 디렉터리 외부에 스킬을 둘 수도 있습니다.
672 672
673* **추가 디렉토리**: `skills` manifest 키에 나열합니다. 이들은 `commands`와 `agents`와 달리 기본 `skills/` 스캔을 대체하지 않고 추가합니다673* **추가 디렉터리**: `skills` 매니페스트 키에 나열합니다. `commands` 및 `agents`와 달리, 기본 `skills/` 스캔을 대체하지 않고 여기에 추가됩니다
674* **플러그인 루트의 단일 skill**: `skills/` 디렉토리가 없고 `skills` manifest 키가 없으면, 플러그인 루트의 `SKILL.md`는 하나의 skill로 로드됩니다. frontmatter에서 `name`을 설정합니다, 그렇지 않으면 마켓플레이스 설치가 플러그인 이름이 아닌 [캐시 디렉토리](/docs/ko/plugins/loading#find-plugins-on-disk) 이름으로 skill을 이름 지정합니다674* **플러그인 루트의 단일 스킬**: `skills/` 디렉터리와 `skills` 매니페스트 키가 모두 없으면 플러그인 루트의 `SKILL.md`가 하나의 스킬로 로드됩니다. frontmatter에 `name`을 설정하십시오. 그렇지 않으면 마켓플레이스 설치 시 스킬 이름이 플러그인이 아닌 [캐시 디렉터리](/docs/ko/plugins/loading#find-plugins-on-disk) 이름을 따르게 됩니다
675 675
676플러그인에 지침을 포함하려면, 이를 skill로 작성합니다. Claude Code는 플러그인 루트의 `CLAUDE.md`를 로드하지 않으며, `claude plugin validate`는 `CLAUDE.md at the plugin root is not loaded as project context` 경고를 표시합니다.676플러그인에 지침을 포함하려면 스킬로 작성하십시오. Claude Code는 플러그인 루트의 `CLAUDE.md`를 로드하지 않으며, `claude plugin validate`는 `CLAUDE.md at the plugin root is not loaded as project context` 경고를 표시합니다.
677 677
678규칙이 매번 유지되어야 하는 경우(예: [보호된 파일에 대한 편집 차단](/docs/ko/hooks-guide#block-edits-to-protected-files)), 이를 skill이 아닌 플러그인에 [hook](#hooks)으로 추가합니다. 둘 중 선택하려면, [유사한 기능 비교](/docs/ko/features-overview#compare-similar-features) 아래의 Hook vs Skill 탭을 참조합니다.678[보호된 파일 편집 차단](/docs/ko/hooks-guide#block-edits-to-protected-files)처럼 항상 지켜져야 하는 규칙이라면 스킬이 아닌 [훅](#hooks)으로 플러그인에 추가하십시오. 둘 중 무엇을 선택할지는 [유사한 기능 비교](/docs/ko/features-overview#compare-similar-features)의 Hook vs Skill 탭을 참조하십시오.
679 679
680frontmatter 필드 및 지원 파일의 경우, [Skills](/docs/ko/skills)를 참조합니다.680frontmatter 필드와 보조 파일에 대해서는 [Skills](/docs/ko/skills)를 참조하십시오.
681 681
682<h3 id="commands">682<h3 id="commands">
683 명령683 Commands
684</h3>684</h3>
685 685
686명령은 사용자가 이름으로 실행하는 단일 Markdown 파일입니다(예: `/my-plugin:about`).686명령은 사용자가 `/my-plugin:about`처럼 이름으로 실행하는 단일 Markdown 파일입니다.
687 687
688<Note>688<Note>
689 명령은 이전 형식이며, [skills](#skills)는 새로운 작업을 위해 이를 대체합니다. skill은 같은 방식으로 이름으로 실행되고, 디렉토리에 지원 파일을 포함할 수도 있습니다. `.claude/commands/`에서 이동하는 파일에 대해 `commands/`를 유지합니다.689 명령은 이전 형식이며, 새로운 작업에서는 [스킬](#skills)이 이를 대체합니다. 스킬도 같은 방식으로 이름으로 실행되며, 디렉터리에 보조 파일을 함께 담을 수도 있습니다. `commands/`는 `.claude/commands/`에서 옮겨 오는 파일에만 사용하십시오.
690</Note>690</Note>
691 691
692`commands/<file>.md`에 명령을 저장하면 `/<plugin>:<file>`이 됩니다. 서브디렉토리는 세그먼트를 추가하므로, `commands/db/migrate.md`는 `/my-plugin:db:migrate`입니다.692명령을 `commands/<file>.md`에 저장하면 `/<plugin>:<file>`이 됩니다. 하위 디렉터리는 세그먼트를 추가하므로 `commands/db/migrate.md`는 `/my-plugin:db:migrate`가 됩니다.
693 693
694명령 파일은 skills와 동일한 frontmatter를 사용합니다.694명령 파일은 스킬과 동일한 frontmatter를 사용합니다.
695 695
696<h4 id="define-commands-in-the-manifest">696<h4 id="define-commands-in-the-manifest">
697 manifest에서 명령 정의697 매니페스트에서 명령 정의하기
698</h4>698</h4>
699 699
700명령 파일을 `commands/` 이외의 다른 곳에 유지하거나, 별도의 Markdown 파일 없이 `plugin.json` 내부에 짧은 명령을 정의하려는 경우에만 필요합니다. `commands` manifest 키를 설정하면, Claude Code는 `commands/`를 스캔하는 대신 이를 읽습니다. 키는 경로, 경로 배열, 또는 각 명령 이름을 `source` 파일 또는 인라인 `content`로 매핑하는 객체를 사용합니다.700이 방법은 명령 파일을 `commands/`가 아닌 다른 위치에 두거나, 별도의 Markdown 파일 없이 `plugin.json` 안에 짧은 명령을 정의하려는 경우에만 필요합니다. `commands` 매니페스트 키를 설정하면 Claude Code는 `commands/`를 스캔하는 대신 이 키를 읽습니다. 이 키는 경로, 경로 배열, 또는 각 명령 이름을 `source` 파일이나 인라인 `content`에 매핑하는 객체를 받습니다.
701 701
702이 manifest는 `/my-plugin:about`을 인라인으로 정의하며, Markdown 파일이 없습니다:702다음 매니페스트는 Markdown 파일 없이 `/my-plugin:about`을 인라인으로 정의합니다.
703 703
704```json .claude-plugin/plugin.json theme={null}704```json .claude-plugin/plugin.json theme={null}
705{705{
715 715
716플러그인을 로드하고 세션에서 `/my-plugin:about`을 실행하여 로드되었는지 확인합니다.716플러그인을 로드하고 세션에서 `/my-plugin:about`을 실행하여 로드되었는지 확인합니다.
717 717
718전체 키 구문의 경우, [`commands`](/docs/ko/plugins/manifest-reference#commands)를 참조합니다.718전체 키 구문은 [`commands`](/docs/ko/plugins/manifest-reference#commands)를 참조하십시오.
719 719
720<h3 id="agents">720<h3 id="agents">
721 Agents721 Agents
722</h3>722</h3>
723 723
724[서브에이전트](/docs/ko/sub-agents)는 자신의 지침과 컨텍스트 윈도우를 가진 별도의 어시스턴트로, Claude가 작업을 위임할 수 있습니다. `agents/` 아래의 각 Markdown 파일은 하나를 정의합니다:724[서브에이전트](/docs/ko/sub-agents)는 자체 지침과 컨텍스트 윈도우를 가진 별도의 어시스턴트로, Claude가 작업을 위임할 수 있습니다. `agents/` 아래의 각 Markdown 파일이 하나의 서브에이전트를 정의합니다.
725 725
726```markdown agents/security-reviewer.md theme={null}726```markdown agents/security-reviewer.md theme={null}
727---727---
733You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.733You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.
734```734```
735 735
736이 에이전트는 `my-plugin:security-reviewer`로 이름 지정되고, 사용자는 `@agent-my-plugin:security-reviewer`로 [명시적으로 호출](/docs/ko/sub-agents#invoke-subagents-explicitly)할 수 있습니다. 이름 형식은 `<plugin>:<name>`이며, `<name>`은 frontmatter `name` 필드에서 오거나, 해당 필드가 없을 때 파일 이름에서 옵니다.736이 에이전트의 이름은 `my-plugin:security-reviewer`이며, 사용자는 `@agent-my-plugin:security-reviewer`로 [명시적으로 호출](/docs/ko/sub-agents#invoke-subagents-explicitly)할 수 있습니다. 이름 형식은 `<plugin>:<name>`이며, `<name>`은 frontmatter의 `name` 필드에서 가져오고, 해당 필드가 없으면 파일 이름에서 가져옵니다.
737 737
738`agents` manifest 키는 `agents/` 스캔을 대체합니다.738`agents` 매니페스트 키는 `agents/` 스캔을 대체합니다.
739 739
740<h4 id="organize-agents-in-subfolders">740<h4 id="organize-agents-in-subfolders">
741 agents의 서브폴더에서 agents 구성741 하위 폴더로 에이전트 정리하기
742</h4>742</h4>
743 743
744플러그인 agent 파일을 `agents/`의 서브폴더에 넣을 수 있습니다. Claude Code는 [재귀적으로 로드](/docs/ko/sub-agents#choose-the-subagent-scope)하고 플러그인 이름, 각 서브폴더 이름, 파일 이름을 콜론으로 결합하여 에이전트의 범위 지정 이름을 형성합니다. 예를 들어, `my-plugin`이라는 플러그인의 `agents/review/security.md`는 `my-plugin:review:security`로 로드됩니다. 두 가지 설정이 해당 이름을 변경합니다:744플러그인 에이전트 파일을 `agents/`의 하위 폴더에 둘 수 있습니다. Claude Code는 이를 [재귀적으로 로드](/docs/ko/sub-agents#choose-the-subagent-scope)하며, 플러그인 이름, 각 하위 폴더 이름, 파일 이름을 콜론으로 연결하여 에이전트의 범위 지정 이름을 만듭니다. 예를 들어 `my-plugin`이라는 플러그인의 `agents/review/security.md`는 `my-plugin:review:security`로 로드됩니다. 다음 두 가지 설정이 이 이름을 변경합니다.
745 745
746* Frontmatter `name`: 파일 이름만 대체하므로, `agents/review/security.md`의 `name: audit`은 `my-plugin:review:audit`로 로드됩니다746* Frontmatter `name`: 파일 이름만 대체하므로 `agents/review/security.md`의 `name: audit`는 `my-plugin:review:audit`로 로드됩니다
747* Manifest [`agents`](/docs/ko/plugins/manifest-reference#fields) 필드: 거기에 나열한 파일은 서브폴더 이름 없이 로드되므로, `"agents": "./custom/review/security.md"`는 `my-plugin:security`로 로드됩니다747* 매니페스트 [`agents`](/docs/ko/plugins/manifest-reference#fields) 필드: 여기에 나열한 파일은 하위 폴더 이름 없이 로드되므로 `"agents": "./custom/review/security.md"`는 `my-plugin:security`로 로드됩니다
748 748
749<h4 id="frontmatter-fields-in-plugin-agents">749<h4 id="frontmatter-fields-in-plugin-agents">
750 플러그인 agents의 Frontmatter 필드750 플러그인 에이전트의 frontmatter 필드
751</h4>751</h4>
752 752
753플러그인 agent의 frontmatter는 다음 규칙을 따릅니다:753플러그인 에이전트의 frontmatter는 다음 규칙을 따릅니다.
754 754
755* **지원되는 필드**: `name`, `description`, `model`, `effort`, `maxTurns`, `tools`, `disallowedTools`, `skills`, `memory`, `background`, `omitClaudeMd`, `isolation`, `color`, 그리고 `experimental`의 `cacheTtl` 키. 유일한 유효한 `isolation` 값은 `"worktree"`입니다. 각각이 무엇을 하는지는 [지원되는 frontmatter 필드](/docs/ko/sub-agents#supported-frontmatter-fields)를 참조합니다755* **지원되는 필드**: `name`, `description`, `model`, `effort`, `maxTurns`, `tools`, `disallowedTools`, `skills`, `memory`, `background`, `omitClaudeMd`, `isolation`, `color`, 그리고 `experimental`의 `cacheTtl` 키입니다. 유효한 `isolation` 값은 `"worktree"`뿐입니다. 각 필드의 역할은 [지원되는 frontmatter 필드](/docs/ko/sub-agents#supported-frontmatter-fields)를 참조하십시오
756* **무시되는 필드**: `permissionMode`, `hooks`, `mcpServers`, `initialPrompt`. agent 파일은 자신의 hooks나 MCP 서버를 추가할 수 없으므로, 이들을 플러그인 [hooks](#hooks)와 [MCP 서버](#mcp-servers)로 추가합니다756* **무시되는 필드**: `permissionMode`, `hooks`, `mcpServers`, `initialPrompt`입니다. 에이전트 파일은 자체적으로 훅이나 MCP 서버를 추가할 수 없으므로, 대신 플러그인 [훅](#hooks)과 [MCP 서버](#mcp-servers)로 추가하십시오
757* **파싱되지 않는 Frontmatter**: agent는 여전히 모든 필드가 무시된 상태로 로드됩니다. 파일 이름으로 이름 지정되고, 설명은 `Agent from my-plugin plugin`을 읽습니다. 셸에서 [`claude plugin validate`](/docs/ko/plugins/cli-reference#plugin-validate)를 실행하여 이러한 파일을 찾습니다757* **파싱되지 않는 frontmatter**: 에이전트는 모든 필드가 무시된 채로 로드됩니다. 이름은 파일 이름을 따르며, 설명은 `Agent from my-plugin plugin`으로 표시됩니다. 이러한 파일을 찾으려면 셸에서 [`claude plugin validate`](/docs/ko/plugins/cli-reference#plugin-validate)를 실행하십시오
758 758
759각 필드가 무엇을 하는지와 우선순위 규칙의 경우, [Subagents](/docs/ko/sub-agents#supported-frontmatter-fields)를 참조합니다.759각 필드의 역할과 우선순위 규칙은 [Subagents](/docs/ko/sub-agents#supported-frontmatter-fields)를 참조하십시오.
760 760
761<h3 id="hooks">761<h3 id="hooks">
762 Hooks762 Hooks
763</h3>763</h3>
764 764
765[hook](/docs/ko/hooks-guide)은 Claude Code의 라이프사이클의 한 지점(예: 모든 파일 편집 후)에서 자동으로 무언가를 실행합니다: 셸 명령, HTTP 요청, MCP 도구 호출, 모델에 대한 프롬프트, 또는 서브에이전트. 플러그인의 hooks를 플러그인 루트의 `hooks/hooks.json`에 저장하고, 최상위 `"hooks"` 키 아래에, `settings.json`의 `hooks` 객체와 동일한 형태로 저장합니다. 이를 통해 기존 설정 hook을 변경 없이 복사할 수 있습니다.765[훅](/docs/ko/hooks-guide)은 파일을 편집할 때마다와 같이 Claude Code 수명 주기의 특정 시점에 셸 명령, HTTP 요청, MCP 도구 호출, 모델에 대한 프롬프트 또는 서브에이전트를 자동으로 실행합니다. 플러그인의 훅은 플러그인 루트의 `hooks/hooks.json`에 최상위 `"hooks"` 키 아래에, `settings.json`의 `hooks` 객체와 동일한 형태로 저장합니다. 따라서 기존 설정 훅을 그대로 복사해 넣을 수 있습니다.
766 766
767이 hook은 모든 `Write` 또는 `Edit` 후에 번들된 스크립트를 실행합니다:767다음 훅은 모든 `Write` 또는 `Edit` 이후에 번들된 스크립트를 실행합니다.
768 768
769```json hooks/hooks.json theme={null}769```json hooks/hooks.json theme={null}
770{770{
784}784}
785```785```
786 786
787`scripts/format.sh`에 스크립트를 저장하고 실행 가능하게 만듭니다.787스크립트를 `scripts/format.sh`에 저장하고 실행 가능하게 만듭니다.
788 788
789플러그인을 로드하고 Claude에 파일을 편집하도록 요청합니다. 종료 코드 0인 `PostToolUse` hook은 트랜스크립트에 아무것도 표시하지 않으므로, [디버그 로깅](/docs/ko/hooks#debug-hooks)으로 또는 스크립트 자체가 변경하는 것으로 실행되었는지 확인합니다.789플러그인을 로드하고 Claude에게 파일 편집을 요청합니다. 0으로 종료되는 `PostToolUse` 훅은 트랜스크립트에 아무것도 표시하지 않으므로, [디버그 로깅](/docs/ko/hooks#debug-hooks)을 사용하거나 스크립트 자체가 변경한 내용을 통해 실행 여부를 확인하십시오.
790 790
791`hooks/hooks.json`과 `hooks` manifest 키의 Hooks는 모두 로드됩니다. 모든 이벤트와 그 페이로드의 경우, [Hook 이벤트](/docs/ko/hooks#hook-events)를 참조합니다.791`hooks/hooks.json`의 훅과 `hooks` 매니페스트 키의 훅은 모두 로드됩니다. 모든 이벤트와 해당 페이로드는 [Hook events](/docs/ko/hooks#hook-events)를 참조하십시오.
792 792
793JavaScript 함수로 hooks를 작성하여 Claude Code 내부에서 실행되고 인터페이스에 그릴 수 있도록 하려면, 동일한 `hooks/hooks.json`의 `modules` 키 아래에 모듈 파일을 나열합니다. 하나를 가진 플러그인은 mod입니다. [mod 만들기](/docs/ko/plugins/mods/create)를 참조합니다.793Claude Code 내부에서 실행되고 인터페이스에 그릴 수 있는 JavaScript 함수로 훅을 작성하려면, 같은 `hooks/hooks.json`의 `modules` 키 아래에 모듈 파일을 나열합니다. 이러한 모듈이 있는 플러그인이 mod입니다. [mod 만들기](/docs/ko/plugins/mods/create)를 참조하십시오.
794 794
795<h4 id="when-plugin-hooks-fire">795<h4 id="when-plugin-hooks-fire">
796 플러그인 hooks가 발생할 때796 플러그인 훅이 실행되는 시점
797</h4>797</h4>
798 798
799플러그인의 hooks는 플러그인의 skills나 명령 중 하나가 사용될 때까지 기다리지 않습니다. Claude Code는 세션이 플러그인을 로드할 때 이들을 등록하고, 그 이후로 이벤트에서 발생합니다. hook이 실행되는 시기를 제한하려면, `matcher`를 좁힙니다.799플러그인의 훅은 플러그인의 스킬이나 명령이 사용될 때까지 기다리지 않습니다. Claude Code는 세션이 플러그인을 로드할 때 훅을 등록하며, 그 이후부터 해당 이벤트에서 훅이 실행됩니다. 훅의 실행 시점을 제한하려면 `matcher`의 범위를 좁히십시오.
800 800
801hook이 발생하지 않으면, [발생하지 않는 hooks](/docs/ko/plugins/troubleshooting#failed-to-load-hooks-from-and-hooks-that-dont-fire)를 참조합니다.801훅이 전혀 실행되지 않는다면 [실행되지 않는 훅](/docs/ko/plugins/troubleshooting#failed-to-load-hooks-from-and-hooks-that-dont-fire)을 참조하십시오.
802 802
803<h4 id="environment-quoting-and-matching-mcp-tools">803<h4 id="environment-quoting-and-matching-mcp-tools">
804 환경, 인용, MCP 도구 일치804 환경, 따옴표 처리 및 MCP 도구 매칭
805</h4>805</h4>
806 806
807hook의 환경, `${CLAUDE_PLUGIN_ROOT}`의 인용, 플러그인의 자신의 MCP 도구에 대한 매처는 다음과 같이 작동합니다:807훅의 환경, `${CLAUDE_PLUGIN_ROOT}`의 따옴표 처리, 플러그인 자체 MCP 도구에 대한 matcher는 다음과 같이 작동합니다.
808 808
809* **환경**: 모든 hook 프로세스는 환경에서 `CLAUDE_PLUGIN_ROOT`와 `CLAUDE_PLUGIN_DATA`를 받고, 각 [사용자 구성](#user-configuration) 값에 대해 `CLAUDE_PLUGIN_OPTION_<KEY>`를 받으므로, 스크립트는 거기서 이들을 읽을 수 있습니다809* **환경**: 모든 훅 프로세스는 환경 변수로 `CLAUDE_PLUGIN_ROOT`와 `CLAUDE_PLUGIN_DATA`를 받으며, 각 [사용자 구성](#user-configuration) 값에 대해 `CLAUDE_PLUGIN_OPTION_<KEY>`도 받으므로 스크립트에서 이를 읽을 수 있습니다
810* **인용**: `command`에 `args`가 없으면, 셸을 통해 실행되므로, `${CLAUDE_PLUGIN_ROOT}` 경로를 큰따옴표로 감싸십시오, [Hooks](#hooks) 아래의 `hooks/hooks.json` 예제처럼, 확장된 경로를 하나의 셸 단어로 유지하려면. `args`를 대신 전달하면, 각 요소는 셸 없이 하나의 인수로 전달되고 인용이 필요하지 않습니다. [exec 형식과 셸 형식](/docs/ko/hooks#exec-form-and-shell-form)을 참조합니다810* **따옴표 처리**: `command`에 `args`가 없으면 셸을 통해 실행되므로, [Hooks](#hooks)의 `hooks/hooks.json` 예시처럼 `${CLAUDE_PLUGIN_ROOT}` 경로를 큰따옴표로 감싸 확장된 경로가 하나의 셸 단어로 유지되도록 하십시오. 대신 `args`를 전달하면 각 요소가 셸 없이 하나의 인수로 전달되므로 따옴표가 필요하지 않습니다. [exec 형식과 셸 형식](/docs/ko/hooks#exec-form-and-shell-form)을 참조하십시오
811* **플러그인의 자신의 MCP 도구 일치**: 이 플러그인이 선언하는 [MCP 서버](#mcp-servers)의 도구는 `mcp__plugin_<plugin>_<server>__<tool>`로 이름 지정되므로, 매처에 전체 이름을 작성합니다. 서버 이름만의 매처는 발생하지 않습니다. [MCP 도구 일치](/docs/ko/hooks#match-mcp-tools)를 참조합니다811* **플러그인 자체 MCP 도구 매칭**: [이 플러그인이 선언한 MCP 서버](#mcp-servers)의 도구 이름은 `mcp__plugin_<plugin>_<server>__<tool>`이므로, matcher에 이 전체 이름을 작성하십시오. 서버 이름만으로 된 matcher는 절대 실행되지 않습니다. [MCP 도구 매칭](/docs/ko/hooks#match-mcp-tools)을 참조하십시오
812 812
813<h3 id="mcp-servers">813<h3 id="mcp-servers">
814 MCP 서버814 MCP servers
815</h3>815</h3>
816 816
817MCP 서버는 Claude에 외부 시스템의 도구를 제공합니다. 플러그인 루트의 `.mcp.json`에서 선언하고, [프로젝트 `.mcp.json`](/docs/ko/mcp#project-scope)과 동일한 형태로 선언합니다. 이 `.mcp.json`은 `db`라는 하나의 서버를 선언합니다:817MCP 서버는 외부 시스템의 도구를 Claude에 제공합니다. 플러그인 루트의 `.mcp.json`에 [프로젝트 `.mcp.json`](/docs/ko/mcp#project-scope)과 동일한 형태로 선언합니다. 다음 `.mcp.json`은 `db`라는 서버 하나를 선언합니다.
818 818
819```json .mcp.json theme={null}819```json .mcp.json theme={null}
820{820{
827}827}
828```828```
829 829
830`mcpServers` 래퍼를 생략하고 `db`를 파일의 최상위 수준에 넣을 수도 있습니다.830`mcpServers` 래퍼를 생략하고 `db`를 파일의 최상위에 둘 수도 있습니다.
831 831
832플러그인을 로드하고 `/mcp`를 실행하여 서버가 `plugin:my-plugin:db`로 나타나는지 확인합니다.832플러그인을 로드하고 `/mcp`를 실행하여 서버가 `plugin:my-plugin:db`로 표시되는지 확인합니다.
833 833
834`claude plugin validate`는 `.mcp.json`을 확인하고 Claude Code가 로드 시간에 삭제할 서버 항목을 오류로 보고합니다. Claude Code v2.1.281 이상이 필요합니다.834`claude plugin validate`는 `.mcp.json`을 검사하고, Claude Code가 로드 시점에 제외할 서버 항목을 오류로 보고합니다. Claude Code v2.1.281 이상이 필요합니다.
835 835
836잘못된 항목이 로드 시간에 나타나는 위치의 경우, [시작하지 않는 MCP 서버](/docs/ko/plugins/troubleshooting#invalid-mcp-server-config-for-and-mcp-servers-that-dont-start)를 참조합니다.836잘못된 항목이 로드 시점에 어디에 표시되는지는 [시작되지 않는 MCP 서버](/docs/ko/plugins/troubleshooting#invalid-mcp-server-config-for-and-mcp-servers-that-dont-start)를 참조하십시오.
837 837
838`mcpServers` manifest 키는 인라인 서버 맵, JSON 파일 경로, 또는 이들의 배열을 사용합니다. manifest 서버가 `.mcp.json`의 것과 동일한 이름을 가지면, manifest 서버가 이를 대체합니다.838`mcpServers` 매니페스트 키는 인라인 서버 맵, JSON 파일 경로, 또는 이들의 배열을 받습니다. 매니페스트 서버가 `.mcp.json`의 서버와 이름이 같으면 매니페스트 서버가 이를 대체합니다.
839 839
840<h4 id="reach-users-on-claude-ai-and-cowork">840<h4 id="reach-users-on-claude-ai-and-cowork">
841 claude.ai 및 Cowork의 사용자에게 도달841 claude.ai 및 Cowork 사용자에게 제공하기
842</h4>842</h4>
843 843
844`db` 서버 아래의 [MCP 서버](#mcp-servers)와 같은 로컬 stdio 서버는 Claude Code에서 실행되고 Claude Desktop 앱에서 머신에서 실행되는 Cowork 세션에서 실행되지만, claude.ai에서는 실행되지 않습니다. 거기에도 사용자에게 도달하려면, `https://` URL로 원격 서버를 참조하십시오, 이는 claude.ai와 Cowork이 사용자에게 커넥터로 제공합니다. [MCP 커넥터를 skill과 함께 번들](https://claude.com/docs/plugins/build#bundle-an-mcp-connector-with-its-skill)에서 보여주는 대로입니다.844[MCP servers](#mcp-servers)의 `db` 서버와 같은 로컬 stdio 서버는 Claude Code와 Claude Desktop 앱에서 사용자의 컴퓨터로 실행되는 Cowork 세션에서는 실행되지만 claude.ai에서는 실행되지 않습니다. 해당 사용자에게도 제공하려면 [Bundle an MCP connector with its skill](https://claude.com/docs/plugins/build#bundle-an-mcp-connector-with-its-skill)에 나온 것처럼 `https://` URL로 원격 서버를 참조하십시오. claude.ai와 Cowork는 이를 사용자에게 커넥터로 제공합니다.
845 845
846<h4 id="server-names-tool-names-and-reloads">846<h4 id="server-names-tool-names-and-reloads">
847 서버 이름, 도구 이름, 재로드847 서버 이름, 도구 이름 및 다시 로드
848</h4>848</h4>
849 849
850서버의 이름, 변수 대체, 재로드 동작은 다음 규칙을 따릅니다:850서버의 이름, 변수 치환, 다시 로드 동작은 다음 규칙을 따릅니다.
851 851
852* **서버 이름**: `plugin:<plugin>:<server>`, 따라서 `my-plugin`의 `db` 서버는 `/mcp`에서 `plugin:my-plugin:db`입니다. [`mcp_tool` hook](/docs/ko/hooks#mcp-tool-hook-fields)에서 서버를 이름 지정할 때 동일한 형식을 사용합니다852* **서버 이름**: `plugin:<plugin>:<server>` 형식이므로 `my-plugin`의 `db` 서버는 `/mcp`에서 `plugin:my-plugin:db`로 표시됩니다. [`mcp_tool` 훅](/docs/ko/hooks#mcp-tool-hook-fields)에서 서버를 지정할 때도 같은 형식을 사용합니다
853* **도구 이름**: `mcp__plugin_<plugin>_<server>__<tool>`, 따라서 해당 `db` 서버의 `query` 도구는 `mcp__plugin_my-plugin_db__query`입니다. 이것은 [권한 규칙](/docs/ko/permissions)과 [hook 매처](#hooks)에서 사용할 이름입니다853* **도구 이름**: `mcp__plugin_<plugin>_<server>__<tool>` 형식이므로 해당 `db` 서버의 `query` 도구는 `mcp__plugin_my-plugin_db__query`입니다. [권한 규칙](/docs/ko/permissions)과 [훅 matcher](#hooks)에서는 이 이름을 사용합니다
854* **대체**: `${CLAUDE_PLUGIN_ROOT}`와 다른 [경로 변수](#path-variables-and-persistent-data)는 `command`, `args`, `env`에서 대체됩니다. `args`에서는 각 요소가 하나의 인수로 전달되므로 인용이 필요하지 않습니다854* **치환**: `${CLAUDE_PLUGIN_ROOT}`와 기타 [경로 변수](#path-variables-and-persistent-data)는 `command`, `args`, `env`에서 치환됩니다. `args`에서는 각 요소가 하나의 인수로 전달되므로 따옴표가 필요하지 않습니다
855* **재로드**: 사용자가 `/reload-plugins`를 실행하고 [재로드가 적용](/docs/ko/plugins/cli-reference#reloads-that-change-mcp-tools)되면, 구성이 변경되지 않은 서버는 연결을 유지합니다. 구성이 변경된 서버는 재연결되고, 제거한 서버는 연결을 끊습니다855* **다시 로드**: 사용자가 `/reload-plugins`를 실행하고 [다시 로드가 적용되면](/docs/ko/plugins/cli-reference#reloads-that-change-mcp-tools), 구성이 변경되지 않은 서버는 연결을 유지합니다. 구성이 변경된 서버는 다시 연결되고, 제거한 서버는 연결이 해제됩니다
856 856
857<h4 id="include-a-packaged-mcpb-server">857<h4 id="include-a-packaged-mcpb-server">
858 패키지된 MCPB 서버 포함858 패키징된 MCPB 서버 포함하기
859</h4>859</h4>
860 860
861`mcpServers` 키는 또한 [MCPB 파일](https://github.com/modelcontextprotocol/mcpb)로 패키지된 서버를 수용하며, 확장자는 `.mcpb` 또는 이전 `.dxt`입니다. 키를 파일로 가리키십시오, 플러그인 내부의 경로 또는 `https://` URL:861`mcpServers` 키는 확장자가 `.mcpb` 또는 이전 형식인 `.dxt`인 [MCPB 파일](https://github.com/modelcontextprotocol/mcpb)로 패키징된 서버도 받습니다. 키가 플러그인 내부 경로 또는 `https://` URL로 파일을 가리키도록 지정합니다.
862 862
863```json .claude-plugin/plugin.json theme={null}863```json .claude-plugin/plugin.json theme={null}
864{864{
867}867}
868```868```
869 869
870서버는 번들의 manifest에서 `name`을 가져옵니다.870서버 이름은 번들 매니페스트의 `name`을 따릅니다.
871 871
872번들의 자신의 manifest는 서버가 필요로 하는 설정을 `user_config` 블록에서 선언할 수 있습니다. 저장된 값이 없는 필수 설정을 가진 번들된 서버는 시작되지 않습니다. `/plugin` **Errors** 탭은 `Bundled MCP server "<name>" was not started: it needs configuration`을 표시합니다.872번들 자체의 매니페스트는 `user_config` 블록에서 서버가 사용자로부터 필요로 하는 설정을 선언할 수 있습니다. 필수 설정에 저장된 값이 없는 번들 서버는 시작되지 않습니다. `/plugin` **Errors** 탭에 `Bundled MCP server "<name>" was not started: it needs configuration`이 표시됩니다.
873 873
874사용자는 두 가지 방법 중 하나로 값을 제공합니다:874사용자는 다음 두 가지 방법 중 하나로 값을 제공합니다.
875 875
876* **`/plugin`에서**: 플러그인을 **Installed** 탭에서 선택하고 **Configure**를 선택합니다876* **`/plugin`에서**: **Installed** 탭에서 플러그인을 선택하고 **Configure**를 선택합니다
877* **설치 시, 셸에서**: [`--config <server>.<key>=<value>`](/docs/ko/plugins/cli-reference#plugin-install)를 `claude plugin install`에 전달합니다. Claude Code v2.1.285 이상이 필요하고, 플러그인 내부에 패키지된 번들에만 작동합니다.877* **설치 시 셸에서**: `claude plugin install`에 [`--config <server>.<key>=<value>`](/docs/ko/plugins/cli-reference#plugin-install)를 전달합니다. Claude Code v2.1.285 이상이 필요하며, 플러그인 내부에 패키징된 번들에서만 작동합니다.
878 878
879전송 및 인증의 경우, [MCP](/docs/ko/mcp#plugin-provided-mcp-servers)를 참조합니다.879전송 방식과 인증에 대해서는 [MCP](/docs/ko/mcp#plugin-provided-mcp-servers)를 참조하십시오.
880 880
881<h3 id="lsp-servers">881<h3 id="lsp-servers">
882 LSP 서버882 LSP servers
883</h3>883</h3>
884 884
885LSP 서버는 Claude에 언어에 대한 진단 및 코드 네비게이션을 제공합니다. [공식 코드 인텔리전스 플러그인](/docs/ko/plugins/code-intelligence)이 이미 언어를 다루면, 하나을 작성하는 대신 설치합니다. 그렇지 않으면 플러그인 루트의 `.lsp.json`에서 서버를 선언합니다:885LSP 서버는 특정 언어에 대한 진단과 코드 탐색 기능을 Claude에 제공합니다. [공식 코드 인텔리전스 플러그인](/docs/ko/plugins/code-intelligence)이 이미 해당 언어를 지원한다면 직접 작성하는 대신 그 플러그인을 설치하십시오. 그렇지 않으면 플러그인 루트의 `.lsp.json`에 서버를 선언합니다.
886 886
887```json .lsp.json theme={null}887```json .lsp.json theme={null}
888{888{
896}896}
897```897```
898 898
899파일은 각 서버 이름을 직접 구성에 매핑하며, 맵 주위에 래퍼 객체가 없습니다. `command`는 바이너리의 이름이고, 인수는 `args`에 있습니다. `extensionToLanguage`는 최소한 하나의 확장이 필요하며, 각각은 `.`로 시작합니다.899이 파일은 맵을 감싸는 래퍼 객체 없이 각 서버 이름을 해당 구성에 직접 매핑합니다. `command`는 바이너리 이름이며, 인수는 `args`에 지정합니다. `extensionToLanguage`에는 `.`으로 시작하는 확장자가 하나 이상 필요합니다.
900 900
901`claude plugin validate`는 이 파일을 읽지 않습니다. 항목이 유효하지 않으면, 전체 파일은 로드 시 건너뛰고 `Invalid LSP server config for ".lsp.json"`이 `/plugin` **Errors** 탭에 나타납니다.901`claude plugin validate`는 이 파일을 읽지 않습니다. 항목 중 하나라도 유효하지 않으면 로드 시 파일 전체를 건너뛰며, `/plugin` **Errors** 탭에 `Invalid LSP server config for ".lsp.json"`이 표시됩니다.
902 902
903플러그인은 연결을 구성하지만 서버 바이너리를 설치하지 않으며, 각 파일 확장자는 하나의 서버를 가집니다:903플러그인은 연결을 구성하지만 서버 바이너리를 설치하지는 않으며, 각 파일 확장자에는 하나의 서버만 할당됩니다.
904 904
905* **누락된 바이너리**: Claude Code는 사용자의 `PATH`에서 이름으로 `command`를 시작합니다. 바이너리가 없으면, 서버는 시작하지 못하고 `claude --debug`는 `LSP server <name> failed to start`를 로깅합니다905* **바이너리 누락**: Claude Code는 사용자의 `PATH`에서 이름으로 `command`를 시작합니다. 바이너리가 없으면 서버 시작에 실패하고 `claude --debug`가 `LSP server <name> failed to start`를 로그에 기록합니다
906* **확장자 충돌**: 두 개의 활성화된 서버가 동일한 확장자를 주장하면, 처음 등록된 것이 해당 파일을 처리하고 다른 것은 이들에 대해 사용되지 않습니다, 서버가 하나의 플러그인에서 오든 두 개에서 오든. `/plugin` **Errors** 탭은 경고 `LSP server "<name>" is not used for <ext> files`를 표시합니다906* **확장자 충돌**: 활성화된 두 서버가 같은 확장자를 지정하면, 서버가 한 플러그인에서 왔든 두 플러그인에서 왔든 먼저 등록된 서버가 해당 파일을 처리하고 다른 서버는 해당 파일에 사용되지 않습니다. `/plugin` **Errors** 탭에 `LSP server "<name>" is not used for <ext> files` 경고가 표시됩니다
907 907
908`lspServers` manifest 키는 동일한 맵을 인라인으로, JSON 파일 경로로, 또는 이들의 배열로 사용하며, 서버는 `.lsp.json`의 것에 추가됩니다. manifest 서버가 `.lsp.json`의 것과 동일한 이름을 가지면, manifest 서버가 이를 대체합니다.908`lspServers` 매니페스트 키는 같은 맵을 인라인으로, JSON 파일 경로로, 또는 이들의 배열로 받으며, 해당 서버는 `.lsp.json`의 서버에 추가됩니다. 매니페스트 서버가 `.lsp.json`의 서버와 이름이 같으면 매니페스트 서버가 이를 대체합니다.
909 909
910`transport`, 타임아웃, 재시작, 다른 필드의 경우, [`lspServers`](/docs/ko/plugins/manifest-reference#lspservers)를 참조합니다.910`transport`, 타임아웃, 재시작 및 기타 필드는 [`lspServers`](/docs/ko/plugins/manifest-reference#lspservers)를 참조하십시오.
911 911
912로그 출력을 stdout이 아닌 stderr로 보냅니다. Claude Code는 서버의 stdout을 프로토콜 메시지로만 읽고, 메시지 헤더는 최대 64 KiB, 메시지 본문은 최대 32 MiB를 수용합니다.912로그 출력은 stdout이 아닌 stderr로 보내십시오. Claude Code는 서버의 stdout을 프로토콜 메시지로만 읽으며, 최대 64 KiB의 메시지 헤더와 최대 32 MiB의 메시지 본문을 허용합니다.
913 913
914Claude Code는 어느 한계를 초과하거나 stdout에 비프로토콜 출력을 작성하는 서버를 연결 해제하고, `restartOnCrash`와 `maxRestarts`에 대해 연결 해제를 충돌로 계산합니다. `--debug`로 실행하면, Claude Code는 원인을 이름 지정하는 오류를 디버그 로그에 작성합니다.914Claude Code는 두 제한 중 하나를 초과하거나 stdout에 프로토콜이 아닌 출력을 쓰는 서버의 연결을 끊고, 이 연결 해제를 `restartOnCrash` 및 `maxRestarts`에 대한 충돌로 집계합니다. `--debug`로 실행하면 Claude Code가 원인을 명시한 오류를 디버그 로그에 기록합니다.
915 915
916<h3 id="executables">916<h3 id="executables">
917 실행 파일917 Executables
918</h3>918</h3>
919 919
920플러그인 루트의 `bin/` 파일은 플러그인이 활성화되어 있는 동안 Bash 도구의 셸의 `PATH`에 있으므로, Claude는 이들을 베어 명령으로 실행할 수 있습니다. 실행 가능한 스크립트를 추가합니다:920플러그인 루트의 `bin/`에 있는 파일은 플러그인이 활성화된 동안 Bash 도구 셸의 `PATH`에 포함되므로, Claude가 이를 단독 명령으로 실행할 수 있습니다. 실행 가능한 스크립트를 추가합니다.
921 921
922```bash bin/hello-plugin theme={null}922```bash bin/hello-plugin theme={null}
923#!/bin/bash923#!/bin/bash
924echo "hello from my-plugin"924echo "hello from my-plugin"
925```925```
926 926
927`chmod +x bin/hello-plugin`으로 실행 가능하게 만들고 플러그인을 로드합니다. Claude에 `hello-plugin`을 실행하도록 요청하면, Bash 도구 결과는 스크립트의 출력을 표시합니다.927`chmod +x bin/hello-plugin`으로 실행 가능하게 만들고 플러그인을 로드합니다. Claude에게 `hello-plugin` 실행을 요청하면 Bash 도구 결과에 스크립트의 출력이 표시됩니다.
928 928
929플러그인 `bin/` 디렉토리는 사용자의 자신의 `PATH` 항목 뒤에 오므로, 플러그인은 `git`, `ls`, 또는 다른 시스템 명령을 섀도우할 수 없습니다.929플러그인 `bin/` 디렉터리는 사용자 자체의 `PATH` 항목 뒤에 위치하므로, 플러그인이 `git`, `ls` 또는 기타 시스템 명령을 가릴 수 없습니다.
930 930
931claude.ai와 Cowork은 최상위 `bin/` 디렉토리를 가진 플러그인을 설치하지 않습니다, [claude.ai 조직 설정을 통해 배포](https://claude.com/docs/plugins/org-sync#keep-executables-out-of-the-top-level-bin-directory)하는 것을 포함합니다.931claude.ai와 Cowork는 최상위 `bin/` 디렉터리가 있는 플러그인을 설치하지 않으며, [claude.ai 조직 설정을 통해 배포](https://claude.com/docs/plugins/org-sync#keep-executables-out-of-the-top-level-bin-directory)하는 플러그인도 마찬가지입니다.
932 932
933<h3 id="default-settings">933<h3 id="default-settings">
934 기본 설정934 Default settings
935</h3>935</h3>
936 936
937플러그인이 활성화되어 있는 동안 적용되는 기본값을 설정하려면, 플러그인 루트에 `settings.json`을 추가하거나, 동일한 객체를 `settings` manifest 키에 인라인으로 넣습니다. 두 개의 키가 효과를 발휘합니다, `agent`와 `subagentStatusLine`, 다른 모든 키는 삭제됩니다.937플러그인이 활성화된 동안 적용되는 기본값을 설정하려면 플러그인 루트에 `settings.json`을 추가하거나, 같은 객체를 `settings` 매니페스트 키에 인라인으로 넣습니다. 적용되는 키는 `agent`와 `subagentStatusLine` 두 가지이며, 그 외의 키는 모두 제외됩니다.
938 938
939플러그인의 자신의 agents 중 하나를 주 스레드로 실행하도록 `agent`를 설정합니다:939플러그인 자체 에이전트 중 하나를 메인 스레드로 실행하려면 `agent`를 설정합니다.
940 940
941```json settings.json theme={null}941```json settings.json theme={null}
942{942{
944}944}
945```945```
946 946
947플러그인을 로드하고 세션을 시작합니다. Claude는 주 대화에서 `security-reviewer` 에이전트의 시스템 프롬프트와 모델로 응답합니다.947플러그인을 로드하고 세션을 시작합니다. 그러면 Claude가 메인 대화에서 `security-reviewer` 에이전트의 시스템 프롬프트와 모델로 응답합니다.
948 948
949키가 제어하는 모든 것의 경우, [`agent` 설정](/docs/ko/settings-reference#agent)을 참조합니다.949이 키가 제어하는 모든 항목은 [`agent` 설정](/docs/ko/settings-reference#agent)을 참조하십시오.
950 950
951동일한 키가 하나 이상의 위치에서 설정되면, 이 규칙들이 어느 값이 적용되는지 결정합니다:951같은 키가 여러 곳에 설정된 경우 다음 규칙에 따라 적용할 값이 결정됩니다.
952 952
953* **파일이 manifest보다 우선**: 둘 다 존재하고 `settings.json`이 최소한 하나의 지원되는 키를 설정하면, `settings.json`이 적용되고 manifest의 `settings`는 무시됩니다953* **매니페스트보다 파일 우선**: 둘 다 존재하고 `settings.json`이 지원되는 키를 하나 이상 설정하면 `settings.json`이 적용되고 매니페스트의 `settings`는 무시됩니다
954* **사용자 설정이 플러그인 기본값보다 우선**: 설정 소스 전체에서, 플러그인 기본값은 가장 낮은 계층이므로, 사용자의 자신의 `agent`는 `~/.claude/settings.json`에서 당신의 것을 재정의합니다954* **플러그인 기본값보다 사용자 설정 우선**: 설정 소스 전체에서 플러그인 기본값이 가장 낮은 계층이므로, 사용자가 `~/.claude/settings.json`에 설정한 `agent`가 플러그인의 값을 재정의합니다
955* **두 개의 플러그인이 동일한 키를 설정**: 마지막에 로드된 플러그인의 값이 적용되고, `claude --debug`는 `overrides setting`을 로깅합니다955* **두 플러그인이 같은 키를 설정하는 경우**: 마지막으로 로드된 플러그인의 값이 적용되며, `claude --debug`가 `overrides setting`을 로그에 기록합니다
956 956
957`subagentStatusLine` 형태의 경우, [서브에이전트 상태 라인](/docs/ko/statusline#subagent-status-lines)을 참조합니다.957`subagentStatusLine`의 형태는 [서브에이전트 상태줄](/docs/ko/statusline#subagent-status-lines)을 참조하십시오.
958 958
959<h3 id="themes-and-output-styles">959<h3 id="themes-and-output-styles">
960 테마 및 출력 스타일960 Themes and output styles
961</h3>961</h3>
962 962
963플러그인은 색상 테마와 출력 스타일을 포함할 수 있습니다. 둘 다 사용자의 자신의 것과 동일한 선택기에 나타납니다. 둘 중 하나의 경우, manifest 키를 설정하면 폴더 스캔을 대체합니다.963플러그인에는 색상 테마와 출력 스타일을 포함할 수 있습니다. 둘 다 사용자 자체의 항목과 같은 선택기에 표시됩니다. 두 경우 모두 매니페스트 키를 설정하면 폴더 스캔이 대체됩니다.
964 964
965| 컴포넌트 | 다음으로 저장 | 형식 | 다음에 나타남 | Manifest 키 |965| 구성 요소 | 저장 위치 | 형식 | 표시 위치 | 매니페스트 키 |
966| :- | :- | :- | :- | :- |966| :- | :- | :- | :- | :- |
967| 테마 | `themes/<slug>.json` | 사용자가 `~/.claude/themes/`에 작성하는 [사용자 정의 테마 파일](/docs/ko/terminal-config#create-a-custom-theme) 형식 | `/theme`, 파일의 `name` 아래 | `experimental.themes` |967| 테마 | `themes/<slug>.json` | 사용자가 `~/.claude/themes/`에 작성하는 [사용자 지정 테마 파일](/docs/ko/terminal-config#create-a-custom-theme) 형식 | `/theme`, 파일의 `name`으로 표시 | `experimental.themes` |
968| 출력 스타일 | `output-styles/<name>.md` | [사용자 정의 출력 스타일](/docs/ko/output-styles#create-a-custom-output-style) 형식, `name`과 `description` frontmatter 포함 | `/output-style`, `<plugin>:<name>`으로 | `outputStyles` |968| 출력 스타일 | `output-styles/<name>.md` | `name` 및 `description` frontmatter를 포함하는 [사용자 지정 출력 스타일](/docs/ko/output-styles#create-a-custom-output-style) 형식 | `/output-style`, `<plugin>:<name>`으로 표시 | `outputStyles` |
969 969
970플러그인 테마는 읽기 전용이므로, 사용자가 `/theme`에서 하나를 편집하면, 편집은 자신의 테마 디렉토리에 복사본으로 저장됩니다.970플러그인 테마는 읽기 전용이므로, 사용자가 `/theme`에서 편집하면 편집 내용은 사용자 자체의 테마 디렉터리에 사본으로 저장됩니다.
971 971
972이 테마는 어두운 사전 설정에서 프롬프트 악센트와 오류 텍스트를 다시 칠합니다:972다음 테마는 dark 프리셋에서 프롬프트 강조 색상과 오류 텍스트 색상을 변경합니다.
973 973
974```json themes/dracula.json theme={null}974```json themes/dracula.json theme={null}
975{975{
983```983```
984 984
985<h3 id="channels">985<h3 id="channels">
986 채널986 Channels
987</h3>987</h3>
988 988
989[채널](/docs/ko/channels)은 채팅 앱과 같은 외부 시스템이 메시지를 세션으로 보낼 수 있게 합니다. 플러그인에서, 채널은 MCP 서버 중 하나와 이를 바인딩하고 자신의 구성을 프롬프트할 수 있는 `channels` 항목입니다. 이 manifest는 채널을 `telegram` 서버에 바인딩하고 봇 토큰을 요청합니다:989[채널](/docs/ko/channels)을 사용하면 채팅 앱과 같은 외부 시스템이 세션으로 메시지를 보낼 수 있습니다. 플러그인에서 채널은 MCP 서버 중 하나와, 이에 바인딩되며 자체 구성을 요청할 수 있는 `channels` 항목으로 구성됩니다. 다음 매니페스트는 채널을 `telegram` 서버에 바인딩하고 봇 토큰을 요청합니다.
990 990
991```json .claude-plugin/plugin.json theme={null}991```json .claude-plugin/plugin.json theme={null}
992{992{
1014}1014}
1015```1015```
1016 1016
1017`server`는 `mcpServers`의 키와 일치해야 합니다. 채널별 `userConfig`는 [최상위 `userConfig` 키](#user-configuration)와 동일한 형태를 사용합니다.1017`server`는 `mcpServers`의 키와 일치해야 합니다. 채널별 `userConfig`는 [최상위 `userConfig` 키](#user-configuration)와 같은 형태를 가집니다.
1018 1018
1019서버가 구현해야 하는 것과 사용자가 채널 플러그인을 활성화하는 방법의 경우, 채널 참조의 [플러그인으로 패키지](/docs/ko/channels-reference#package-as-a-plugin)를 참조합니다. 필드 테이블의 경우, [`channels`](/docs/ko/plugins/manifest-reference#channels)를 참조합니다.1019서버가 구현해야 하는 사항과 사용자가 채널 플러그인을 활성화하는 방법은 채널 레퍼런스의 [플러그인으로 패키징하기](/docs/ko/channels-reference#package-as-a-plugin)를 참조하십시오. 필드 표는 [`channels`](/docs/ko/plugins/manifest-reference#channels)를 참조하십시오.
1020 1020
1021<h3 id="monitors">1021<h3 id="monitors">
1022 모니터1022 Monitors
1023</h3>1023</h3>
1024 1024
1025모니터는 전체 세션 동안 백그라운드에서 실행되는 셸 명령입니다. 이것이 인쇄하는 것은 Claude에 알림으로 도달하므로, Claude는 보도록 요청받지 않고도 로그나 상태 변경에 반응할 수 있습니다. 항목을 `monitors/monitors.json`에 저장합니다:1025모니터는 세션 전체 동안 백그라운드에서 실행되는 셸 명령입니다. 모니터가 출력하는 내용은 알림으로 Claude에 전달되므로, Claude는 감시하라는 요청을 받지 않아도 로그나 상태 변경에 대응할 수 있습니다. 항목은 `monitors/monitors.json`에 저장합니다.
1026 1026
1027```json monitors/monitors.json theme={null}1027```json monitors/monitors.json theme={null}
1028[1028[
1034]1034]
1035```1035```
1036 1036
1037명령은 셸에서 실행되고, 세션이 시작된 작업 디렉토리에서 실행됩니다.1037명령은 세션의 현재 작업 디렉터리에서 셸로 실행됩니다. 사용자의 전체 권한으로 [샌드박스](/docs/ko/sandboxing) 외부에서 실행됩니다.
1038 1038
1039모니터의 명령은 시작 위치와 참조할 수 있는 것에서 제한됩니다:1039모니터의 명령은 시작 위치와 참조할 수 있는 항목이 제한됩니다.
1040 1040
1041* **대화형 세션만**: 플러그인 모니터는 대화형 세션에서 시작되고 `-p` 플래그를 사용한 비대화형 모드에서는 시작되지 않습니다. 또한 API 제공자 또는 텔레메트리 설정으로 인해 [Monitor 도구](/docs/ko/tools-reference#monitor-tool)를 사용할 수 없는 세션에서도 시작되지 않습니다1041* **대화형 세션 전용**: 플러그인 모니터는 대화형 세션에서 시작되며, `-p` 플래그를 사용하는 비대화형 모드에서는 절대 시작되지 않습니다. API 제공자 또는 텔레메트리 설정으로 인해 [Monitor 도구](/docs/ko/tools-reference#monitor-tool)를 사용할 수 없는 세션에서도 시작되지 않습니다
1042* **사용자 구성 없음**: `command`는 [경로 변수](#path-variables-and-persistent-data)와 환경의 `${ENV_VAR}`을 가져오지만, `${user_config.*}`는 절대 가져오지 않습니다. 하나을 참조하는 모니터는 시작되지 않으며, 모니터 프로세스는 `CLAUDE_PLUGIN_OPTION_<KEY>`도 받지 않습니다1042* **사용자 구성 사용 불가**: `command`는 [경로 변수](#path-variables-and-persistent-data)와 환경의 `${ENV_VAR}`를 받지만 `${user_config.*}`는 절대 받지 않습니다. 이를 참조하는 모니터는 시작되지 않으며, 모니터 프로세스는 `CLAUDE_PLUGIN_OPTION_<KEY>`도 받지 않습니다
1043* **세션 중 비활성화**: 세션 중에 플러그인을 비활성화하면, Claude Code는 이미 실행 중인 모니터를 중지하지 않습니다. 세션이 끝날 때 중지됩니다1043* **세션 중 비활성화**: 세션 도중 플러그인을 비활성화해도 Claude Code는 이미 실행 중인 모니터를 중지하지 않습니다. 모니터는 세션이 종료될 때 중지됩니다
1044 1044
1045`experimental.monitors` manifest 키는 동일한 배열을 인라인으로 또는 JSON 파일 경로로 사용하고, `monitors/monitors.json` 대신 읽습니다.1045`experimental.monitors` 매니페스트 키는 같은 배열을 인라인으로 또는 JSON 파일 경로로 받으며, `monitors/monitors.json` 대신 읽힙니다.
1046 1046
1047`when` 트리거 및 다른 필드의 경우, [`monitors`](/docs/ko/plugins/manifest-reference#monitors)를 참조합니다.1047`when` 트리거와 기타 필드는 [`monitors`](/docs/ko/plugins/manifest-reference#monitors)를 참조하십시오.
1048 1048
1049<h2 id="user-configuration">1049<h2 id="user-configuration">
1050 사용자에게 구성 값을 요청합니다1050 사용자에게 구성 값을 요청합니다