1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Adicionar componentes a um plugin
6
7> Adicione skills, hooks, servidores MCP e todos os outros tipos de componentes a um plugin Claude Code, com um exemplo que valida cada um.
8
9export const Piece = ({id, children}) => <div className="pe-piece" data-piece={id}>{children}</div>;
10
11export const PluginExplorer = ({children}) => {
12 const PIECES = [{
13 id: 'manifest',
14 name: 'Manifest',
15 path: '.claude-plugin/plugin.json',
16 required: "Required by Anthropic's directory",
17 lines: [{
18 depth: 0,
19 kind: 'folder',
20 text: '.claude-plugin/'
21 }, {
22 depth: 1,
23 kind: 'file',
24 text: 'plugin.json'
25 }],
26 href: '/en/plugins/manifest-reference#manifest-file',
27 linkText: 'Go to the manifest reference'
28 }, {
29 id: 'skills',
30 name: 'Skills',
31 path: 'skills/review/SKILL.md',
32 lines: [{
33 depth: 0,
34 kind: 'folder',
35 text: 'skills/'
36 }, {
37 depth: 1,
38 kind: 'folder',
39 text: 'review/'
40 }, {
41 depth: 2,
42 kind: 'file',
43 text: 'SKILL.md'
44 }],
45 href: '/en/plugins/components#skills',
46 linkText: 'Go to the Skills section'
47 }, {
48 id: 'commands',
49 name: 'Commands',
50 path: 'commands/about.md',
51 lines: [{
52 depth: 0,
53 kind: 'folder',
54 text: 'commands/'
55 }, {
56 depth: 1,
57 kind: 'file',
58 text: 'about.md'
59 }],
60 href: '/en/plugins/components#commands',
61 linkText: 'Go to the Commands section'
62 }, {
63 id: 'agents',
64 name: 'Agents',
65 path: 'agents/security-reviewer.md',
66 lines: [{
67 depth: 0,
68 kind: 'folder',
69 text: 'agents/'
70 }, {
71 depth: 1,
72 kind: 'file',
73 text: 'security-reviewer.md'
74 }],
75 href: '/en/plugins/components#agents',
76 linkText: 'Go to the Agents section'
77 }, {
78 id: 'hooks',
79 name: 'Hooks',
80 path: 'hooks/hooks.json',
81 lines: [{
82 depth: 0,
83 kind: 'folder',
84 text: 'hooks/'
85 }, {
86 depth: 1,
87 kind: 'file',
88 text: 'hooks.json'
89 }],
90 href: '/en/plugins/components#hooks',
91 linkText: 'Go to the Hooks section'
92 }, {
93 id: 'monitors',
94 name: 'Monitors',
95 path: 'monitors/monitors.json',
96 lines: [{
97 depth: 0,
98 kind: 'folder',
99 text: 'monitors/'
100 }, {
101 depth: 1,
102 kind: 'file',
103 text: 'monitors.json'
104 }],
105 href: '/en/plugins/components#monitors',
106 linkText: 'Go to the Monitors section'
107 }, {
108 id: 'output-styles',
109 name: 'Output styles',
110 path: 'output-styles/terse.md',
111 lines: [{
112 depth: 0,
113 kind: 'folder',
114 text: 'output-styles/'
115 }, {
116 depth: 1,
117 kind: 'file',
118 text: 'terse.md'
119 }],
120 href: '/en/plugins/components#themes-and-output-styles',
121 linkText: 'Go to the Themes and output styles section'
122 }, {
123 id: 'themes',
124 name: 'Themes',
125 path: 'themes/dracula.json',
126 lines: [{
127 depth: 0,
128 kind: 'folder',
129 text: 'themes/'
130 }, {
131 depth: 1,
132 kind: 'file',
133 text: 'dracula.json'
134 }],
135 href: '/en/plugins/components#themes-and-output-styles',
136 linkText: 'Go to the Themes and output styles section'
137 }, {
138 id: 'workflows',
139 name: 'Workflows',
140 path: 'workflows/audit-routes.js',
141 lines: [{
142 depth: 0,
143 kind: 'folder',
144 text: 'workflows/'
145 }, {
146 depth: 1,
147 kind: 'file',
148 text: 'audit-routes.js'
149 }],
150 href: '/en/workflows#distribute-a-workflow-in-a-plugin',
151 linkText: 'Go to Distribute a workflow in a plugin'
152 }, {
153 id: 'bin',
154 name: 'Executables',
155 path: 'bin/hello-plugin',
156 lines: [{
157 depth: 0,
158 kind: 'folder',
159 text: 'bin/'
160 }, {
161 depth: 1,
162 kind: 'file',
163 text: 'hello-plugin'
164 }],
165 href: '/en/plugins/components#executables',
166 linkText: 'Go to the Executables section'
167 }, {
168 id: 'scripts',
169 name: 'Scripts',
170 path: 'scripts/format.sh',
171 lines: [{
172 depth: 0,
173 kind: 'folder',
174 text: 'scripts/'
175 }, {
176 depth: 1,
177 kind: 'file',
178 text: 'format.sh'
179 }],
180 href: '/en/plugins/components#hooks',
181 linkText: 'Go to the Hooks section'
182 }, {
183 id: 'settings',
184 name: 'Default settings',
185 path: 'settings.json',
186 lines: [{
187 depth: 0,
188 kind: 'file',
189 text: 'settings.json'
190 }],
191 href: '/en/plugins/components#default-settings',
192 linkText: 'Go to the Default settings section'
193 }, {
194 id: 'mcp',
195 name: 'MCP servers',
196 path: '.mcp.json',
197 lines: [{
198 depth: 0,
199 kind: 'file',
200 text: '.mcp.json'
201 }],
202 href: '/en/plugins/components#mcp-servers',
203 linkText: 'Go to the MCP servers section'
204 }, {
205 id: 'lsp',
206 name: 'LSP servers',
207 path: '.lsp.json',
208 lines: [{
209 depth: 0,
210 kind: 'file',
211 text: '.lsp.json'
212 }],
213 href: '/en/plugins/components#lsp-servers',
214 linkText: 'Go to the LSP servers section'
215 }];
216 const [selectedId, setSelectedId] = useState('manifest');
217 const [isFullscreen, setIsFullscreen] = useState(false);
218 const rootRef = useRef(null);
219 useEffect(() => {
220 const onFsChange = () => setIsFullscreen(!!document.fullscreenElement);
221 document.addEventListener('fullscreenchange', onFsChange);
222 return () => document.removeEventListener('fullscreenchange', onFsChange);
223 }, []);
224 const toggleFullscreen = () => {
225 if (!rootRef.current) return;
226 if (document.fullscreenElement) document.exitFullscreen(); else rootRef.current.requestFullscreen().catch(() => {});
227 };
228 const selected = PIECES.find(p => p.id === selectedId) || PIECES[0];
229 const onTreeKeyDown = e => {
230 const keys = ['ArrowDown', 'ArrowUp', 'Home', 'End'];
231 if (keys.indexOf(e.key) === -1) return;
232 const i = PIECES.findIndex(p => p.id === selectedId);
233 let next = i;
234 if (e.key === 'ArrowDown') next = Math.min(PIECES.length - 1, i + 1);
235 if (e.key === 'ArrowUp') next = Math.max(0, i - 1);
236 if (e.key === 'Home') next = 0;
237 if (e.key === 'End') next = PIECES.length - 1;
238 e.preventDefault();
239 if (next === i) return;
240 const id = PIECES[next].id;
241 setSelectedId(id);
242 const el = document.getElementById('pe-node-' + id);
243 if (el) el.focus();
244 };
245 const FolderIcon = () => <svg className="pe-icon" width="15" height="15" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.3" strokeLinejoin="round" aria-hidden="true">
246 <path d="M1.5 4.5a1 1 0 0 1 1-1h3.2l1.3 1.5h6a1 1 0 0 1 1 1V12a1 1 0 0 1-1 1h-10.5a1 1 0 0 1-1-1z" />
247 </svg>;
248 const FileIcon = () => <svg className="pe-icon" width="15" height="15" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.3" strokeLinejoin="round" aria-hidden="true">
249 <path d="M4 1.5h5.5L13 5v9.5H4z" />
250 <path d="M9.5 1.5V5H13" />
251 </svg>;
252 return <div ref={rootRef} className={isFullscreen ? 'pe-root pe-fullscreen not-prose' : 'pe-root not-prose'} data-selected={selected.id}>
253 <style>{`
254 .pe-root {
255 --pe-mono: var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
256 --pe-accent: #D97757;
257 --pe-accent-text: #A8502F;
258 --pe-accent-bg: rgba(217,119,87,0.10);
259 --pe-bg: #FFFFFF;
260 --pe-surface: #FAFAF7;
261 --pe-hover: #F0EEE6;
262 --pe-border: #E8E6DC;
263 --pe-text: #141413;
264 --pe-text-2: #3D3D3A;
265 --pe-text-3: #5E5D59;
266 font-family: inherit;
267 background: var(--pe-bg);
268 color: var(--pe-text);
269 border: 1px solid var(--pe-border);
270 border-radius: 12px;
271 margin: 1.5rem 0;
272 overflow: hidden;
273 box-sizing: border-box;
274 }
275 .dark .pe-root {
276 --pe-accent-text: #EBA98F;
277 --pe-accent-bg: rgba(217,119,87,0.18);
278 --pe-bg: #1A1918;
279 --pe-surface: #232221;
280 --pe-hover: #2E2D2B;
281 --pe-border: #3A3936;
282 --pe-text: #F1EFE9;
283 --pe-text-2: #D6D4CA;
284 --pe-text-3: #B8B5AD;
285 }
286 .pe-root *, .pe-root *::before, .pe-root *::after { box-sizing: border-box; }
287 .pe-head { display: flex; align-items: flex-start; gap: 12px; padding: 18px 24px 16px; border-bottom: 1px solid var(--pe-border); }
288 .pe-head-text { flex: 1; min-width: 0; }
289 .pe-fs-btn { flex-shrink: 0; width: 32px; height: 32px; display: inline-flex; align-items: center; justify-content: center; border: 1px solid var(--pe-border); border-radius: 6px; background: var(--pe-surface); color: var(--pe-text-2); font-size: 15px; line-height: 1; cursor: pointer; }
290 .pe-fs-btn:hover { background: var(--pe-hover); }
291 .pe-fs-btn:focus-visible { outline: 2px solid var(--pe-accent); outline-offset: 2px; }
292 .pe-fullscreen { border-radius: 0; height: 100vh; display: flex; flex-direction: column; overflow: auto; }
293 .pe-fullscreen .pe-body { flex: 1; }
294 .pe-title { font-size: 19px; font-weight: 600; line-height: 1.3; color: var(--pe-text); margin: 0; }
295 .pe-sub { font-size: 15px; line-height: 1.5; color: var(--pe-text-3); margin: 4px 0 0; }
296 .pe-sub code { font-family: var(--pe-mono); font-size: 0.88em; padding: 1px 5px; border-radius: 4px; background: var(--pe-surface); border: 1px solid var(--pe-border); }
297 .pe-body { display: flex; align-items: stretch; }
298 .pe-tree-pane { width: 270px; flex-shrink: 0; background: var(--pe-surface); border-right: 1px solid var(--pe-border); padding: 16px 0 12px; }
299 .pe-panel { flex: 1; min-width: 0; padding: 16px 24px 24px; }
300 .pe-caption { font-size: 13px; font-weight: 600; color: var(--pe-text-3); margin: 0 0 10px; }
301 .pe-tree-pane .pe-caption { padding: 0 16px; }
302 .pe-rootline { display: flex; align-items: center; gap: 7px; padding: 3px 16px; font-family: var(--pe-mono); font-size: 13.5px; color: var(--pe-text-3); }
303 .pe-node {
304 display: block; width: 100%; margin: 0; padding: 3px 16px 3px 30px; text-align: left; cursor: pointer;
305 background: transparent; color: var(--pe-text-2);
306 border: none; border-left: 3px solid transparent;
307 font-family: var(--pe-mono); font-size: 13.5px; line-height: 1.4;
308 }
309 .pe-node:hover { background: var(--pe-hover); }
310 .pe-node:focus-visible { outline: 2px solid var(--pe-accent); outline-offset: -2px; }
311 .pe-node[aria-pressed="true"] { background: var(--pe-accent-bg); border-left-color: var(--pe-accent); color: var(--pe-accent-text); font-weight: 600; }
312 .pe-line { display: flex; align-items: center; gap: 7px; padding: 2px 0; }
313 .pe-line-tree { flex-wrap: wrap; }
314 .pe-line-tree .pe-req { flex-basis: 100%; margin: 2px 0 0 22px; white-space: normal; width: fit-content; max-width: calc(100% - 22px); }
315 .pe-line span { overflow-wrap: anywhere; }
316 .pe-piece { display: none; font-size: 16px; line-height: 1.6; color: var(--pe-text-2); }
317 .pe-root[data-selected="manifest"] .pe-piece[data-piece="manifest"],
318 .pe-root[data-selected="skills"] .pe-piece[data-piece="skills"],
319 .pe-root[data-selected="commands"] .pe-piece[data-piece="commands"],
320 .pe-root[data-selected="agents"] .pe-piece[data-piece="agents"],
321 .pe-root[data-selected="hooks"] .pe-piece[data-piece="hooks"],
322 .pe-root[data-selected="monitors"] .pe-piece[data-piece="monitors"],
323 .pe-root[data-selected="output-styles"] .pe-piece[data-piece="output-styles"],
324 .pe-root[data-selected="themes"] .pe-piece[data-piece="themes"],
325 .pe-root[data-selected="workflows"] .pe-piece[data-piece="workflows"],
326 .pe-root[data-selected="bin"] .pe-piece[data-piece="bin"],
327 .pe-root[data-selected="scripts"] .pe-piece[data-piece="scripts"],
328 .pe-root[data-selected="settings"] .pe-piece[data-piece="settings"],
329 .pe-root[data-selected="mcp"] .pe-piece[data-piece="mcp"],
330 .pe-root[data-selected="lsp"] .pe-piece[data-piece="lsp"] { display: block; }
331 .pe-piece p { margin: 0 0 10px; }
332 .pe-piece p:last-child { margin-bottom: 0; }
333 .pe-piece code { font-family: var(--pe-mono); font-size: 0.88em; padding: 1px 5px; border-radius: 4px; background: var(--pe-surface); border: 1px solid var(--pe-border); }
334 .pe-piece .code-block { margin: 12px 0 0; }
335 .pe-piece pre code { padding: 0; border: none; background: none; }
336 .pe-piece a { color: var(--pe-accent-text); }
337 .pe-line-compact { display: none; }
338 .pe-icon { flex-shrink: 0; }
339 .pe-req { margin-left: 8px; padding: 0 6px; border-radius: 999px; font-size: 11px; line-height: 18px; letter-spacing: .02em; color: var(--pe-accent-text); border: 1px solid var(--pe-border); background: var(--pe-surface); white-space: nowrap; font-weight: 500; vertical-align: middle; }
340 .pe-name { font-size: 22px; font-weight: 600; line-height: 1.25; letter-spacing: -0.2px; color: var(--pe-text); margin: 0; }
341 .pe-path { font-family: var(--pe-mono); font-size: 13.5px; color: var(--pe-accent-text); margin: 4px 0 0; overflow-wrap: anywhere; }
342 .pe-block { margin: 20px 0 0; }
343 .pe-link {
344 display: inline-block; margin: 24px 0 0; padding: 8px 14px; border-radius: 8px;
345 font-size: 14.5px; font-weight: 600; text-decoration: none;
346 color: var(--pe-accent-text); background: var(--pe-accent-bg); border: 1px solid var(--pe-accent);
347 }
348 .pe-link:hover { filter: brightness(0.97); }
349 .pe-link:focus-visible { outline: 2px solid var(--pe-accent); outline-offset: 2px; }
350 @media (max-width: 700px) {
351 .pe-head { padding: 16px 16px 14px; }
352 .pe-body { flex-direction: column; }
353 .pe-tree-pane { width: 100%; border-right: none; border-bottom: 1px solid var(--pe-border); }
354 .pe-line-tree { display: none; }
355 .pe-line-compact { display: flex; }
356 .pe-panel { padding: 16px 16px 20px; }
357 }
358 `}</style>
359
360 <div className="pe-head">
361 <div className="pe-head-text">
362 <div className="pe-title">What goes in a plugin</div>
363 <div className="pe-sub">This example plugin, <code>my-plugin</code>, has one of every kind of component, each in its default location. Select a file or folder to read what it’s for and see what goes in it.</div>
364 </div>
365 <button type="button" className="pe-fs-btn" onClick={toggleFullscreen} aria-label={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'} title={isFullscreen ? 'Exit fullscreen' : 'Fullscreen'}>
366 {isFullscreen ? '⤡' : '⛶'}
367 </button>
368 </div>
369
370 <div className="pe-body">
371 <div className="pe-tree-pane">
372 <div className="pe-caption" id="pe-tree-caption">Plugin directory</div>
373 <div role="group" aria-labelledby="pe-tree-caption" onKeyDown={onTreeKeyDown}>
374 <div className="pe-rootline"><FolderIcon /><span>my-plugin/</span></div>
375 {PIECES.map(p => <button key={p.id} id={'pe-node-' + p.id} type="button" className="pe-node" aria-pressed={p.id === selected.id} aria-label={p.name + ', ' + p.path} onClick={() => setSelectedId(p.id)}>
376 {p.lines.map((line, i) => <span key={i} className="pe-line pe-line-tree" style={{
377 paddingLeft: line.depth * 18 + 'px'
378 }}>
379 {line.kind === 'folder' ? <FolderIcon /> : <FileIcon />}
380 <span>{line.text}</span>
381 {p.required && i === p.lines.length - 1 ? <span className="pe-req">{p.required}</span> : null}
382 </span>)}
383 <span className="pe-line pe-line-compact">
384 <FileIcon />
385 <span>{p.path}</span>
386 {p.required ? <span className="pe-req">{p.required}</span> : null}
387 </span>
388 </button>)}
389 </div>
390 </div>
391
392 <div className="pe-panel" role="region" aria-labelledby="pe-panel-caption" aria-live="polite" aria-atomic="true">
393 <div className="pe-caption" id="pe-panel-caption">Selected piece</div>
394 <div className="pe-name">{selected.name}{selected.required ? <span className="pe-req">{selected.required}</span> : null}</div>
395 <div className="pe-path">{selected.path}</div>
396
397 <div className="pe-block">{children}</div>
398
399 <a className="pe-link" href={selected.href}>{selected.linkText}</a>
400 </div>
401 </div>
402 </div>;
403};
404
405Um plugin Claude Code é construído a partir de componentes, como skills, agentes, hooks e servidores MCP. Cada componente tem uma pasta padrão no plugin, uma chave de manifesto opcional em `.claude-plugin/plugin.json` que substitui ou adiciona àquela pasta, e um nome que o usuário vê. Para cada tabela de campos completa da chave, consulte a [referência de manifesto](/docs/pt/plugins/manifest-reference#fields).
406
407Use esta página para adicionar um componente a um plugin que já carrega.
408
409Depois de adicionar um componente, execute `/reload-plugins` em uma sessão em execução ou inicie uma nova para que Claude Code o carregue. Para verificar o arquivo do componente antes de carregá-lo, execute [`claude plugin validate .`](/docs/pt/plugins/cli-reference#plugin-validate) no seu shell a partir do diretório do plugin.
410
411<Note>
412 Estes casos são cobertos em outras páginas:
413
414 * **Construindo seu primeiro plugin**: comece com [Criar um plugin](/docs/pt/plugins/create)
415 * **Instalando o plugin de outra pessoa**: consulte [Instalar plugins](/docs/pt/plugins/install)
416 * **Os usuários do seu plugin estão em claude.ai ou em Cowork**: um conjunto diferente de componentes carrega lá. Consulte [Plugins em claude.ai e em Cowork](https://claude.com/docs/plugins/overview)
417</Note>
418
419<h2 id="explore-the-plugin-directory">
420 Explorar o diretório do plugin
421</h2>
422
423O explorador mostra um plugin de exemplo, `my-plugin`, que tem um de cada tipo de componente em sua localização padrão:
424
425* Uma skill de revisão e um comando `about`
426* Um subagente de revisão de segurança
427* Um hook que formata arquivos após Claude editá-los, e a pasta `scripts/` que ele chama
428* Um monitor de log
429* Um estilo de saída e um tema de cor
430* Um workflow de auditoria de rotas
431* Um executável `hello-plugin`
432* Configurações padrão
433* Um servidor MCP local e um servidor de linguagem Go
434
435Cada arquivo é o menor exemplo válido de seu formato, lá para mostrar a forma em vez de ser útil: uma skill ou agente real carrega instruções completas e frequentemente arquivos de suporte, e um hook ou monitor real faz trabalho real. As seções após o explorador usam os mesmos arquivos que seus exemplos e vinculam a versões mais completas. Selecione um arquivo ou pasta para ler para que serve, veja o que entra nele e encontre a seção que o cobre.
436
437<PluginExplorer>
438 <Piece id="manifest">
439 O [manifesto](/docs/pt/plugins/manifest-reference) é o arquivo `plugin.json` no diretório `.claude-plugin/` de um plugin. Ele contém os metadados do plugin e os valores `userConfig` que Claude Code solicita ao usuário. Apenas `name` é obrigatório. Neste, `description` é o texto que os usuários veem para o plugin em `/plugin`, e `version` mantém os usuários nessa versão até você alterá-la:
440
441 ```json theme={null}
442 {
443 "name": "my-plugin",
444 "version": "1.0.0",
445 "description": "Review, formatting, and database tools for this team"
446 }
447 ```
448 </Piece>
449
450 <Piece id="skills">
451 Uma [skill](/docs/pt/skills) é um arquivo `SKILL.md`. Salve cada skill em seu próprio diretório em `skills/`. Claude lê a `description` de cada skill, e quando o que o usuário pede corresponde a ela, como pedir a Claude para revisar um pull request aqui, Claude carrega as instruções da skill e as segue. O usuário também pode executá-la diretamente como `/my-plugin:review`:
452
453 ```markdown theme={null}
454 ---
455 description: Reviews a pull request for style and test coverage. Use when asked to review code.
456 ---
457
458 Review the changed files. Report style problems first, then missing tests.
459 ```
460 </Piece>
461
462 <Piece id="commands">
463 Um comando é um único arquivo Markdown que o usuário executa por nome. Comandos são o formato mais antigo: uma skill é executada por nome da mesma forma e também pode carregar arquivos de suporte em seu próprio diretório, então escreva novos como skills e mantenha `commands/` para arquivos que você já tem. Este arquivo se torna `/my-plugin:about` e usa o mesmo frontmatter que uma skill:
464
465 ```markdown theme={null}
466 ---
467 description: Summarize the repository
468 ---
469
470 Summarize what this repository does in three sentences.
471 ```
472 </Piece>
473
474 <Piece id="agents">
475 Um [subagente](/docs/pt/sub-agents) é um assistente separado, com suas próprias instruções e sua própria janela de contexto, que Claude pode delegar uma tarefa e obter um resultado. Cada arquivo Markdown em `agents/` define um: o frontmatter o nomeia e diz quando usá-lo, e o corpo é seu prompt do sistema. Este é nomeado `my-plugin:security-reviewer`, e o usuário pode invocá-lo com `@agent-my-plugin:security-reviewer`:
476
477 ```markdown theme={null}
478 ---
479 name: security-reviewer
480 description: Reviews code changes for security issues. Use after edits to authentication or input handling.
481 model: sonnet
482 ---
483
484 You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.
485 ```
486 </Piece>
487
488 <Piece id="hooks">
489 Um [hook](/docs/pt/hooks-guide) executa algo automaticamente em um ponto do ciclo de vida do Claude Code, como após cada edição de arquivo: um comando shell, uma solicitação HTTP, uma chamada de ferramenta MCP, um prompt para um modelo ou um subagente. Salve os hooks do plugin em `hooks/hooks.json` na raiz do plugin. Este executa o `scripts/format.sh` do plugin após Claude escrever ou editar um arquivo:
490
491 ```json theme={null}
492 {
493 "hooks": {
494 "PostToolUse": [
495 {
496 "matcher": "Write|Edit",
497 "hooks": [
498 {
499 "type": "command",
500 "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/format.sh\""
501 }
502 ]
503 }
504 ]
505 }
506 }
507 ```
508 </Piece>
509
510 <Piece id="monitors">
511 Um monitor é um comando shell que Claude Code inicia em segundo plano quando a sessão inicia e mantém em execução até que termine, usando a [ferramenta Monitor](/docs/pt/tools-reference#monitor-tool). O que ele imprime chega a Claude como notificações. Um campo `when` pode, em vez disso, iniciá-lo na primeira vez que uma skill nomeada é executada. Este monitora um log de erros:
512
513 ```json theme={null}
514 [
515 {
516 "name": "error-log",
517 "command": "tail -F ./logs/error.log",
518 "description": "Application error log"
519 }
520 ]
521 ```
522 </Piece>
523
524 <Piece id="output-styles">
525 Um plugin pode incluir [estilos de saída](/docs/pt/output-styles), que alteram como Claude formata e expressa suas respostas. Salve cada estilo de saída como `output-styles/<name>.md`. Este aparece em `/output-style` como `my-plugin:terse`:
526
527 ```markdown theme={null}
528 ---
529 name: terse
530 description: Answer in as few words as possible
531 keep-coding-instructions: true
532 ---
533
534 Keep every reply short. Skip preambles and summaries.
535 ```
536 </Piece>
537
538 <Piece id="themes">
539 Um plugin pode incluir [temas de cor](/docs/pt/terminal-config#create-a-custom-theme) para a interface Claude Code. Salve cada tema como `themes/<slug>.json`. Este aparece em `/theme` como `Dracula`, marcado como de `my-plugin`:
540
541 ```json theme={null}
542 {
543 "name": "Dracula",
544 "base": "dark",
545 "overrides": {
546 "claude": "#bd93f9",
547 "error": "#ff5555"
548 }
549 }
550 ```
551 </Piece>
552
553 <Piece id="workflows">
554 A pasta `workflows/` contém arquivos `.js` de [workflow](/docs/pt/workflows): um bloco `meta`, depois um corpo de script que orquestra vários subagentes. Este é executado como `/my-plugin:audit-routes`:
555
556 ```javascript theme={null}
557 export const meta = {
558 name: 'audit-routes',
559 description: 'Audit every route handler for missing auth checks',
560 }
561
562 const found = await agent('List every .ts file under src/routes/.', {
563 schema: { type: 'object', required: ['files'], properties: { files: { type: 'array', items: { type: 'string' } } } },
564 })
565
566 const audits = await pipeline(found.files, file =>
567 agent(`Audit ${file} for missing authentication checks.`, { label: file }),
568 )
569
570 return audits.filter(Boolean)
571 ```
572 </Piece>
573
574 <Piece id="bin">
575 `bin/` é como um plugin envia uma ferramenta de linha de comando. Enquanto o plugin está habilitado, Claude Code coloca esta pasta no `PATH` do shell em que executa comandos, para que Claude, ou as instruções de uma skill, possam executar a ferramenta por nome sem o usuário instalar nada. Com este [executável](#executables) em vigor, `hello-plugin` é um comando que Claude pode executar:
576
577 ```bash theme={null}
578 #!/bin/bash
579 echo "hello from my-plugin"
580 ```
581 </Piece>
582
583 <Piece id="scripts">
584 O hook em `hooks/hooks.json` executa um script, e esta pasta é onde o exemplo o mantém. O nome `scripts/` é uma convenção, não algo que Claude Code procure: o hook aponta para o arquivo por seu caminho, `${CLAUDE_PLUGIN_ROOT}/scripts/format.sh`. Um script de formatação pode parecer assim:
585
586 ```bash theme={null}
587 #!/bin/bash
588 npx prettier --write .
589 ```
590 </Piece>
591
592 <Piece id="settings">
593 Um `settings.json` na raiz do plugin contém [configurações](/docs/pt/settings-reference) que se aplicam enquanto o plugin está habilitado, para que um plugin possa alterar como a sessão se comporta e não apenas adicionar componentes. Apenas duas chaves têm efeito de um plugin, [`agent`](/docs/pt/settings-reference#agent) e [`subagentStatusLine`](/docs/pt/settings-reference#subagentstatusline); todas as outras chaves são descartadas. Consulte [Configurações padrão](#default-settings).
594
595 Este define `agent`, que executa o thread principal da sessão como o agente `security-reviewer` do plugin, para que o prompt do sistema, restrições de ferramentas e modelo desse agente se apliquem a toda a sessão:
596
597 ```json theme={null}
598 {
599 "agent": "security-reviewer"
600 }
601 ```
602 </Piece>
603
604 <Piece id="mcp">
605 Um [servidor MCP](/docs/pt/mcp) fornece a Claude ferramentas de um sistema externo. Declare-o em `.mcp.json` na raiz do plugin. Este inicia um servidor local a partir de um script dentro do plugin e aparece em `/mcp` como `plugin:my-plugin:db`:
606
607 ```json theme={null}
608 {
609 "mcpServers": {
610 "db": {
611 "command": "node",
612 "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
613 }
614 }
615 }
616 ```
617 </Piece>
618
619 <Piece id="lsp">
620 Um servidor LSP fornece a Claude [diagnósticos e navegação de código](/docs/pt/plugins/code-intelligence) para uma linguagem. Declare o servidor em `.lsp.json` na raiz do plugin. Este conecta o servidor de linguagem Go para arquivos `.go`:
621
622 ```json theme={null}
623 {
624 "gopls": {
625 "command": "gopls",
626 "args": ["serve"],
627 "extensionToLanguage": {
628 ".go": "go"
629 }
630 }
631 }
632 ```
633 </Piece>
634</PluginExplorer>
635
636<h2 id="add-each-kind-of-component">
637 Adicionar cada tipo de componente
638</h2>
639
640Cada seção abaixo cobre um tipo de componente: onde seus arquivos vão no plugin, um exemplo que valida, o que o usuário vê uma vez que o plugin carrega, e a chave de manifesto que altera a localização padrão. Adicione os que seu plugin precisa; nenhum é obrigatório.
641
642<h3 id="skills">
643 Skills
644</h3>
645
646Uma [skill](/docs/pt/skills) é um arquivo `SKILL.md` que Claude pode carregar quando sua descrição corresponde à tarefa. O usuário também pode executá-la como um comando. Salve cada skill em seu próprio diretório em `skills/`:
647
648```text theme={null}
649my-plugin/
650├── .claude-plugin/
651│ └── plugin.json
652└── skills/
653 └── review/
654 └── SKILL.md
655```
656
657Dê ao `SKILL.md` uma `description` para que Claude saiba quando usá-la:
658
659```markdown skills/review/SKILL.md theme={null}
660---
661description: Reviews a pull request for style and test coverage. Use when asked to review code.
662---
663
664Review the changed files. Report style problems first, then missing tests.
665```
666
667Depois de carregar o plugin, `/my-plugin:review` executa a skill. O nome do comando e quem pode invocá-lo seguem estas regras:
668
669* **Nome do comando**: `/<plugin>:<directory>`, então `skills/review/SKILL.md` em `my-plugin` é `/my-plugin:review`. Se você definir `name` no frontmatter, ele substitui o último segmento e o prefixo do plugin permanece. Consulte [como uma skill obtém seu nome de comando](/docs/pt/skills#how-a-skill-gets-its-command-name)
670* **Quem a invoca**: Claude, o usuário ou ambos, controlado pelo frontmatter. Consulte [Controlar quem invoca uma skill](/docs/pt/skills#control-who-invokes-a-skill)
671
672Você também pode colocar skills fora do diretório padrão `skills/`:
673
674* **Diretórios adicionais**: liste-os na chave de manifesto `skills`. Eles adicionam à varredura padrão `skills/` em vez de substituí-la, diferentemente de `commands` e `agents`
675* **Uma única skill na raiz do plugin**: sem diretório `skills/` e sem chave de manifesto `skills`, um `SKILL.md` na raiz do plugin carrega como uma skill. Defina `name` em seu frontmatter, porque caso contrário uma instalação de marketplace nomeia a skill após seu [diretório de cache](/docs/pt/plugins/loading#find-plugins-on-disk) em vez de seu plugin
676
677Para incluir instruções em um plugin, escreva-as como uma skill. Claude Code não carrega um `CLAUDE.md` na raiz do plugin, e `claude plugin validate` avisa `CLAUDE.md at the plugin root is not loaded as project context`.
678
679Para campos de frontmatter e arquivos de suporte, consulte [Skills](/docs/pt/skills).
680
681<h3 id="commands">
682 Comandos
683</h3>
684
685Um comando é um único arquivo Markdown que o usuário executa por nome, como `/my-plugin:about`.
686
687<Note>
688 Comandos são o formato mais antigo, e [skills](#skills) os superam para novo trabalho. Uma skill é executada por nome da mesma forma, e também pode carregar arquivos de suporte em seu diretório. Mantenha `commands/` para arquivos que você está movendo de `.claude/commands/`.
689</Note>
690
691Salve um comando em `commands/<file>.md` e ele se torna `/<plugin>:<file>`. Um subdiretório adiciona um segmento, então `commands/db/migrate.md` é `/my-plugin:db:migrate`.
692
693Arquivos de comando usam o mesmo frontmatter que skills.
694
695<h4 id="define-commands-in-the-manifest">
696 Definir comandos no manifesto
697</h4>
698
699Você só precisa disso se quiser manter arquivos de comando em algum lugar diferente de `commands/`, ou para definir um comando curto dentro de `plugin.json` sem um arquivo Markdown separado. Defina a chave de manifesto `commands`, e Claude Code a lê em vez de varrer `commands/`. A chave usa um caminho, uma matriz de caminhos ou um objeto que mapeia cada nome de comando para um arquivo `source` ou `content` inline.
700
701Este manifesto define `/my-plugin:about` inline, sem arquivo Markdown:
702
703```json .claude-plugin/plugin.json theme={null}
704{
705 "name": "my-plugin",
706 "commands": {
707 "about": {
708 "content": "Summarize what this repository does in three sentences.",
709 "description": "Summarize the repository"
710 }
711 }
712}
713```
714
715Carregue o plugin e execute `/my-plugin:about` na sessão para confirmar que carregou.
716
717Para a sintaxe completa da chave, consulte [`commands`](/docs/pt/plugins/manifest-reference#commands).
718
719<h3 id="agents">
720 Agentes
721</h3>
722
723Um [subagente](/docs/pt/sub-agents) é um assistente separado, com suas próprias instruções e janela de contexto, que Claude pode delegar uma tarefa. Cada arquivo Markdown em `agents/` define um:
724
725```markdown agents/security-reviewer.md theme={null}
726---
727name: security-reviewer
728description: Reviews code changes for security issues. Use after edits to authentication or input handling.
729model: sonnet
730---
731
732You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.
733```
734
735Este agente é nomeado `my-plugin:security-reviewer`, e o usuário pode [invocá-lo explicitamente](/docs/pt/sub-agents#invoke-subagents-explicitly) com `@agent-my-plugin:security-reviewer`. A forma do nome é `<plugin>:<name>`, onde `<name>` vem do frontmatter, ou do nome do arquivo quando não há.
736
737A chave `agents` substitui a varredura `agents/`.
738
739<h4 id="organize-agents-in-subfolders">
740 Organizar agentes em subpastas
741</h4>
742
743Você pode colocar arquivos de agente do plugin em subpastas de `agents/`. Claude Code [os carrega recursivamente](/docs/pt/sub-agents#choose-the-subagent-scope) e une o nome do plugin, cada nome de subpasta e o nome do arquivo com dois-pontos para formar o nome com escopo do agente. Por exemplo, `agents/review/security.md` em um plugin nomeado `my-plugin` carrega como `my-plugin:review:security`. Duas configurações alteram esse nome:
744
745* Frontmatter `name`: ele substitui apenas o nome do arquivo, então `name: audit` em `agents/review/security.md` carrega como `my-plugin:review:audit`
746* Campo de manifesto [`agents`](/docs/pt/plugins/manifest-reference#fields): um arquivo que você lista lá carrega sem nomes de subpasta, então `"agents": "./custom/review/security.md"` carrega como `my-plugin:security`
747
748<h4 id="frontmatter-fields-in-plugin-agents">
749 Campos de frontmatter em agentes de plugin
750</h4>
751
752O frontmatter de um agente de plugin segue estas regras:
753
754* **Campos suportados**: `name`, `description`, `model`, `effort`, `maxTurns`, `tools`, `disallowedTools`, `skills`, `memory`, `background`, `omitClaudeMd`, `isolation`, `color` e a chave `cacheTtl` de `experimental`. O único valor `isolation` válido é `"worktree"`. Consulte [campos de frontmatter suportados](/docs/pt/sub-agents#supported-frontmatter-fields) para saber o que cada um faz
755* **Campos ignorados**: `permissionMode`, `hooks`, `mcpServers` e `initialPrompt`. Um arquivo de agente não pode adicionar hooks ou servidores MCP por conta própria, então adicione-os como plugin [hooks](#hooks) e [servidores MCP](#mcp-servers) em vez disso
756* **Frontmatter que não analisa**: o agente ainda carrega com cada campo ignorado. É nomeado após o arquivo, e sua descrição lê `Agent from my-plugin plugin`. Execute [`claude plugin validate`](/docs/pt/plugins/cli-reference#plugin-validate) no seu shell para encontrar esses arquivos
757
758Para saber o que cada campo faz e as regras de precedência, consulte [Subagentes](/docs/pt/sub-agents#supported-frontmatter-fields).
759
760<h3 id="hooks">
761 Hooks
762</h3>
763
764Um [hook](/docs/pt/hooks-guide) executa algo automaticamente em um ponto do ciclo de vida do Claude Code, como após cada edição de arquivo: um comando shell, uma solicitação HTTP, uma chamada de ferramenta MCP, um prompt para um modelo ou um subagente. Salve os hooks do plugin em `hooks/hooks.json` na raiz do plugin, sob uma chave `"hooks"` de nível superior, na mesma forma que o objeto `hooks` em `settings.json`. Isso permite copiar um hook de configurações existente sem alterações.
765
766Este hook executa um script agrupado após cada `Write` ou `Edit`:
767
768```json hooks/hooks.json theme={null}
769{
770 "hooks": {
771 "PostToolUse": [
772 {
773 "matcher": "Write|Edit",
774 "hooks": [
775 {
776 "type": "command",
777 "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/format.sh\""
778 }
779 ]
780 }
781 ]
782 }
783}
784```
785
786Salve o script em `scripts/format.sh` e torne-o executável.
787
788Carregue o plugin e peça a Claude para editar um arquivo. Um hook `PostToolUse` que sai com 0 não mostra nada na transcrição, então confirme que foi executado com [log de depuração](/docs/pt/hooks#debug-hooks) ou pelo que o script em si altera.
789
790Hooks em `hooks/hooks.json` e na chave de manifesto `hooks` ambos carregam. Para cada evento e sua carga útil, consulte [Eventos de hook](/docs/pt/hooks#hook-events).
791
792<h4 id="when-plugin-hooks-fire">
793 Quando os hooks do plugin disparam
794</h4>
795
796Os hooks de um plugin não esperam que uma das skills ou comandos do plugin seja usada. Claude Code os registra quando uma sessão carrega o plugin, e eles disparam em seus eventos a partir de então. Para limitar quando um hook é executado, restrinja seu `matcher`.
797
798Se um hook nunca dispara, consulte [hooks que não disparam](/docs/pt/plugins/troubleshooting#failed-to-load-hooks-from-and-hooks-that-dont-fire).
799
800<h4 id="environment-quoting-and-matching-mcp-tools">
801 Ambiente, citação e correspondência de ferramentas MCP
802</h4>
803
804O ambiente do hook, a citação de `${CLAUDE_PLUGIN_ROOT}` e os matchers para as próprias ferramentas MCP do plugin funcionam da seguinte forma:
805
806* **Ambiente**: cada processo de hook recebe `CLAUDE_PLUGIN_ROOT` e `CLAUDE_PLUGIN_DATA` em seu ambiente, mais `CLAUDE_PLUGIN_OPTION_<KEY>` para cada valor de [configuração do usuário](#user-configuration), para que seu script possa lê-los de lá
807* **Citação**: quando `command` não tem `args`, ele é executado através de um shell, então envolva o caminho `${CLAUDE_PLUGIN_ROOT}` em aspas duplas, como o exemplo `hooks/hooks.json` em [Hooks](#hooks) faz, para manter o caminho expandido como uma palavra de shell. Quando você passa `args` em vez disso, cada elemento é passado como um argumento sem shell e não precisa de citação. Consulte [forma exec e forma shell](/docs/pt/hooks#exec-form-and-shell-form)
808* **Correspondência das próprias ferramentas MCP do plugin**: uma ferramenta de um [servidor MCP que este plugin declara](#mcp-servers) é nomeada `mcp__plugin_<plugin>_<server>__<tool>`, então escreva esse nome completo no matcher. Um matcher apenas no nome do servidor nunca dispara. Consulte [Corresponder ferramentas MCP](/docs/pt/hooks#match-mcp-tools)
809
810<h3 id="mcp-servers">
811 Servidores MCP
812</h3>
813
814Um servidor MCP fornece a Claude ferramentas de um sistema externo. Declare-o em `.mcp.json` na raiz do plugin, na mesma forma que um [`.mcp.json` de projeto](/docs/pt/mcp#project-scope). Este `.mcp.json` declara um servidor nomeado `db`:
815
816```json .mcp.json theme={null}
817{
818 "mcpServers": {
819 "db": {
820 "command": "node",
821 "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"]
822 }
823 }
824}
825```
826
827Você também pode omitir o wrapper `mcpServers` e colocar `db` no nível superior do arquivo.
828
829Carregue o plugin e execute `/mcp` para confirmar que o servidor aparece como `plugin:my-plugin:db`.
830
831`claude plugin validate` verifica `.mcp.json` e relata uma entrada de servidor que Claude Code descartaria no tempo de carregamento como um erro. Requer Claude Code v2.1.281 ou posterior.
832
833Para onde uma entrada ruim aparece no tempo de carregamento, consulte [Servidores MCP que não iniciam](/docs/pt/plugins/troubleshooting#invalid-mcp-server-config-for-and-mcp-servers-that-dont-start).
834
835A chave de manifesto `mcpServers` usa um mapa de servidor inline, um caminho para um arquivo JSON ou uma matriz daqueles. Quando um servidor de manifesto tem o mesmo nome que um em `.mcp.json`, o servidor de manifesto o substitui.
836
837<h4 id="reach-users-on-claude-ai-and-cowork">
838 Alcançar usuários em claude.ai e Cowork
839</h4>
840
841Um servidor stdio local, como o servidor `db` em [Servidores MCP](#mcp-servers), é executado em Claude Code e em uma sessão Cowork que é executada em sua máquina no aplicativo Claude Desktop, mas não em claude.ai. Para alcançar usuários lá também, referencie um servidor remoto por sua URL `https://`, que claude.ai e Cowork oferecem ao usuário como um conector.
842
843<h4 id="server-names-tool-names-and-reloads">
844 Nomes de servidor, nomes de ferramentas e recarregamentos
845</h4>
846
847Os nomes do servidor, substituição de variáveis e comportamento de recarga seguem estas regras:
848
849* **Nome do servidor**: `plugin:<plugin>:<server>`, então o servidor `db` em `my-plugin` é `plugin:my-plugin:db` em `/mcp`. Use a mesma forma para nomear o servidor em um [hook `mcp_tool`](/docs/pt/hooks#mcp-tool-hook-fields)
850* **Nomes de ferramentas**: `mcp__plugin_<plugin>_<server>__<tool>`, então uma ferramenta `query` naquele servidor `db` é `mcp__plugin_my-plugin_db__query`. Esse é o nome a usar em [regras de permissão](/docs/pt/permissions) e [matchers de hook](#hooks)
851* **Substituição**: `${CLAUDE_PLUGIN_ROOT}` e as outras [variáveis de caminho](#path-variables-and-persistent-data) são substituídas em `command`, `args` e `env`. Nenhuma citação é necessária em `args`, porque cada elemento é passado como um argumento
852* **Recarga**: quando o usuário executa `/reload-plugins` e [o recarga se aplica](/docs/pt/plugins/cli-reference#reloads-that-change-mcp-tools), um servidor cuja configuração não foi alterada mantém sua conexão. Um servidor cuja configuração mudou se reconecta, e um que você removeu se desconecta
853
854<h4 id="include-a-packaged-mcpb-server">
855 Incluir um servidor MCPB empacotado
856</h4>
857
858A chave `mcpServers` também aceita um servidor empacotado como um [arquivo MCPB](https://github.com/modelcontextprotocol/mcpb), cuja extensão é `.mcpb` ou a mais antiga `.dxt`. Aponte a chave para o arquivo, como um caminho dentro do plugin ou uma URL `https://`:
859
860```json .claude-plugin/plugin.json theme={null}
861{
862 "name": "my-plugin",
863 "mcpServers": "./servers/db.mcpb"
864}
865```
866
867O servidor usa seu nome do `name` no manifesto do pacote.
868
869Para transportes e autenticação, consulte [MCP](/docs/pt/mcp#plugin-provided-mcp-servers).
870
871<h3 id="lsp-servers">
872 Servidores LSP
873</h3>
874
875Um servidor LSP fornece a Claude diagnósticos e navegação de código para uma linguagem. Se um [plugin oficial de inteligência de código](/docs/pt/plugins/code-intelligence) já cobre sua linguagem, instale esse em vez de escrever um. Caso contrário, declare o servidor em `.lsp.json` na raiz do plugin:
876
877```json .lsp.json theme={null}
878{
879 "gopls": {
880 "command": "gopls",
881 "args": ["serve"],
882 "extensionToLanguage": {
883 ".go": "go"
884 }
885 }
886}
887```
888
889O arquivo mapeia cada nome de servidor diretamente para sua configuração, sem objeto wrapper ao redor do mapa. `command` é o nome do binário, com seus argumentos em `args`. `extensionToLanguage` precisa de pelo menos uma extensão, cada uma começando com `.`.
890
891`claude plugin validate` não lê este arquivo. Quando qualquer entrada é inválida, o arquivo inteiro é ignorado no carregamento e `Invalid LSP server config for ".lsp.json"` aparece na aba **Errors** de `/plugin`.
892
893Seu plugin configura a conexão mas não instala o binário do servidor, e cada extensão de arquivo obtém um servidor:
894
895* **Binário ausente**: Claude Code inicia `command` por nome do `PATH` do usuário. Quando o binário não está lá, o servidor falha ao iniciar e `claude --debug` registra `LSP server <name> failed to start`
896* **Conflitos de extensão**: quando dois servidores habilitados reivindicam a mesma extensão, o primeiro registrado manipula esses arquivos e o outro não é usado para eles, se os servidores vêm de um plugin ou dois. A aba **Errors** de `/plugin` mostra o aviso `LSP server "<name>" is not used for <ext> files`
897
898A chave de manifesto `lspServers` usa o mesmo mapa inline, um caminho para um arquivo JSON ou uma matriz daqueles, e seus servidores adicionam aos em `.lsp.json`. Quando um servidor de manifesto tem o mesmo nome que um em `.lsp.json`, o servidor de manifesto o substitui.
899
900Para `transport`, timeouts, reinicializações e os outros campos, consulte [`lspServers`](/docs/pt/plugins/manifest-reference#lspservers).
901
902Envie a saída de log para stderr, não stdout. Claude Code lê stdout de um servidor apenas como mensagens de protocolo e aceita cabeçalhos de mensagem até 64 KiB e um corpo de mensagem até 32 MiB.
903
904Claude Code desconecta um servidor que excede qualquer limite ou escreve saída não-protocolo para stdout, e conta a desconexão como uma falha para `restartOnCrash` e `maxRestarts`. Quando você executa com `--debug`, Claude Code escreve um erro nomeando a causa para o log de depuração.
905
906<h3 id="executables">
907 Executáveis
908</h3>
909
910Arquivos em `bin/` na raiz do plugin estão no `PATH` do shell da ferramenta Bash enquanto o plugin está habilitado, para que Claude possa executá-los como comandos simples. Adicione um script executável:
911
912```bash bin/hello-plugin theme={null}
913#!/bin/bash
914echo "hello from my-plugin"
915```
916
917Torne-o executável com `chmod +x bin/hello-plugin` e carregue o plugin. Quando você pede a Claude para executar `hello-plugin`, o resultado da ferramenta Bash mostra a saída do script.
918
919Diretórios `bin/` de plugin vêm após as entradas `PATH` do próprio usuário, então um plugin não pode sombrear `git`, `ls` ou outro comando do sistema.
920
921claude.ai e Cowork não instalam um plugin que tem um diretório `bin/` de nível superior, incluindo um que você [distribui através das configurações da organização claude.ai](/docs/pt/plugins/host-marketplace#distribute-through-organization-settings).
922
923<h3 id="default-settings">
924 Configurações padrão
925</h3>
926
927Para definir padrões que se aplicam enquanto o plugin está habilitado, adicione um `settings.json` na raiz do plugin, ou coloque o mesmo objeto inline na chave de manifesto `settings`. Duas chaves têm efeito, `agent` e `subagentStatusLine`, e todas as outras chaves são descartadas.
928
929Defina `agent` para executar um dos próprios agentes do plugin como o thread principal:
930
931```json settings.json theme={null}
932{
933 "agent": "security-reviewer"
934}
935```
936
937Carregue o plugin e inicie uma sessão. Claude então responde na conversa principal com o prompt do sistema e modelo do agente `security-reviewer`.
938
939Para tudo que a chave controla, consulte a [configuração `agent`](/docs/pt/settings-reference#agent).
940
941Quando a mesma chave é definida em mais de um lugar, estas regras decidem qual valor se aplica:
942
943* **Arquivo sobre manifesto**: quando ambos existem e `settings.json` define pelo menos uma chave suportada, `settings.json` se aplica e o `settings` do manifesto é ignorado
944* **Configurações do usuário sobre padrões do plugin**: entre fontes de configurações, padrões de plugin são a camada mais baixa, então um `agent` próprio do usuário em `~/.claude/settings.json` substitui o seu
945* **Dois plugins definem a mesma chave**: o valor do plugin carregado por último se aplica, e `claude --debug` registra `overrides setting`
946
947Para a forma `subagentStatusLine`, consulte [linhas de status de subagente](/docs/pt/statusline#subagent-status-lines).
948
949<h3 id="themes-and-output-styles">
950 Temas e estilos de saída
951</h3>
952
953Um plugin pode incluir temas de cor e estilos de saída. Ambos aparecem nos mesmos seletores que os do usuário. Para qualquer um, definir a chave de manifesto substitui a varredura de pasta.
954
955| Componente | Salvar como | Formato | Aparece em | Chave de manifesto |
956| :-------------- | :------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------- | :-------------------- |
957| Tema | `themes/<slug>.json` | O formato de [arquivo de tema personalizado](/docs/pt/terminal-config#create-a-custom-theme) que os usuários escrevem em `~/.claude/themes/` | `/theme`, sob o `name` do arquivo | `experimental.themes` |
958| Estilo de saída | `output-styles/<name>.md` | O formato de [estilo de saída personalizado](/docs/pt/output-styles#create-a-custom-output-style), com frontmatter `name` e `description` | `/output-style`, como `<plugin>:<name>` | `outputStyles` |
959
960Temas de plugin são somente leitura, então quando um usuário edita um em `/theme`, a edição é salva como uma cópia no diretório de temas próprio.
961
962Este tema recolore o prompt de acento e texto de erro na predefinição escura:
963
964```json themes/dracula.json theme={null}
965{
966 "name": "Dracula",
967 "base": "dark",
968 "overrides": {
969 "claude": "#bd93f9",
970 "error": "#ff5555"
971 }
972}
973```
974
975<h3 id="channels">
976 Canais
977</h3>
978
979Um [canal](/docs/pt/channels) permite que um sistema externo, como um aplicativo de chat, envie mensagens para uma sessão. Em um plugin, um canal é um dos servidores MCP mais uma entrada `channels` que se vincula a ele e pode solicitar sua própria configuração. Este manifesto vincula um canal a um servidor `telegram` e solicita um token de bot:
980
981```json .claude-plugin/plugin.json theme={null}
982{
983 "name": "my-plugin",
984 "mcpServers": {
985 "telegram": {
986 "command": "node",
987 "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
988 "env": { "BOT_TOKEN": "${user_config.bot_token}" }
989 }
990 },
991 "channels": [
992 {
993 "server": "telegram",
994 "userConfig": {
995 "bot_token": {
996 "type": "string",
997 "title": "Bot token",
998 "description": "Telegram bot token",
999 "sensitive": true
1000 }
1001 }
1002 }
1003 ]
1004}
1005```
1006
1007`server` deve corresponder a uma chave em `mcpServers`. O `userConfig` por canal usa a mesma forma que a chave [`userConfig` de nível superior](#user-configuration).
1008
1009Para o que o servidor deve implementar e como os usuários habilitam um plugin de canal, consulte [Empacotar como um plugin](/docs/pt/channels-reference#package-as-a-plugin) na referência de canais. Para a tabela de campos, consulte [`channels`](/docs/pt/plugins/manifest-reference#channels).
1010
1011<h3 id="monitors">
1012 Monitores
1013</h3>
1014
1015Um monitor é um comando shell que é executado em segundo plano para toda a sessão. O que ele imprime chega a Claude como notificações, para que Claude possa reagir a um log ou mudança de status sem ser solicitado a observá-lo. Salve as entradas em `monitors/monitors.json`:
1016
1017```json monitors/monitors.json theme={null}
1018[
1019 {
1020 "name": "error-log",
1021 "command": "tail -F ./logs/error.log",
1022 "description": "Application error log"
1023 }
1024]
1025```
1026
1027O comando é executado em um shell, no diretório de trabalho em que a sessão foi iniciada.
1028
1029O comando de um monitor é limitado em onde inicia e o que pode referenciar:
1030
1031* **Apenas sessões interativas**: monitores de plugin iniciam em uma sessão interativa e nunca em modo não-interativo com a flag `-p`. Eles também iniciam apenas onde a [ferramenta Monitor](/docs/pt/tools-reference#monitor-tool) está disponível
1032* **Sem configuração do usuário**: `command` obtém as [variáveis de caminho](#path-variables-and-persistent-data) e `${ENV_VAR}` do ambiente, mas nunca `${user_config.*}`. Um monitor que referencia um não inicia, e processos de monitor não recebem `CLAUDE_PLUGIN_OPTION_<KEY>` também
1033* **Desabilitação no meio da sessão**: se você desabilitar um plugin no meio da sessão, Claude Code não para monitores que já estão em execução. Eles param quando a sessão termina
1034
1035A chave de manifesto `experimental.monitors` usa a mesma matriz inline ou um caminho para um arquivo JSON, e é lida em vez de `monitors/monitors.json`.
1036
1037Para o gatilho `when` e os outros campos, consulte [`monitors`](/docs/pt/plugins/manifest-reference#monitors).
1038
1039<h2 id="user-configuration">
1040 Solicitar ao usuário valores de configuração
1041</h2>
1042
1043Declare os valores que seu plugin precisa do usuário na chave de manifesto `userConfig`, para que os usuários não editem `settings.json` eles mesmos. Cada opção aparece em um diálogo com seu `title` como o rótulo e sua `description` abaixo.
1044
1045Defina `"sensitive": true` para um token ou senha. O diálogo então mascara a entrada, e o valor é armazenado em armazenamento seguro em vez de `settings.json`.
1046
1047Este manifesto solicita um endpoint e um token:
1048
1049```json .claude-plugin/plugin.json theme={null}
1050{
1051 "name": "my-plugin",
1052 "userConfig": {
1053 "api_url": {
1054 "type": "string",
1055 "title": "API URL",
1056 "description": "Base URL of your team's API"
1057 },
1058 "api_token": {
1059 "type": "string",
1060 "title": "API token",
1061 "description": "Token for your team's API",
1062 "sensitive": true
1063 }
1064 }
1065}
1066```
1067
1068<h3 id="when-the-configuration-dialog-appears">
1069 Quando o diálogo de configuração aparece
1070</h3>
1071
1072O diálogo aparece apenas na interface interativa `/plugin`. Ele abre para qualquer opção que ainda não está definida quando o usuário faz qualquer um dos seguintes:
1073
1074* Instala o plugin em `/plugin`
1075* Executa `/plugin install <plugin>@<marketplace>` dentro de uma sessão
1076* Habilita o plugin da aba **Installed** em `/plugin`
1077
1078Para abrir o mesmo diálogo a qualquer momento, o usuário executa `/plugin configure <plugin>@<marketplace>`.
1079
1080O comando shell `claude plugin install` nunca solicita valores `userConfig`. Para definir valores do shell, passe cada um como `--config KEY=VALUE`. Quando opções permanecem indefinidas, o comando imprime uma linha `userConfig options not yet set` que nomeia ambas as formas de defini-las. [O diálogo `userConfig` nunca aparece](/docs/pt/plugins/troubleshooting#the-userconfig-dialog-never-appears) cita a linha.
1081
1082Para os campos de opção, onde cada valor é armazenado, como um componente referencia um valor salvo e quais campos rejeitam `${user_config.*}`, consulte [Configuração do usuário](/docs/pt/plugins/manifest-reference#user-configuration).
1083
1084<h2 id="path-variables-and-persistent-data">
1085 Referenciar caminhos de plugin e armazenar dados
1086</h2>
1087
1088Você não sabe onde seu plugin será instalado, então refira-se a seus arquivos e dados através destas variáveis em vez de caminhos fixos. Elas são substituídas em conteúdo de skill, comando e agente, em comandos de hook e monitor, e em configurações de servidor MCP e LSP. Elas também são exportadas para processos de hook, MCP e LSP:
1089
1090* **`${CLAUDE_PLUGIN_ROOT}`**: o diretório de instalação do plugin. Cada versão tem seu próprio [diretório de cache](/docs/pt/plugins/loading#find-plugins-on-disk), então o caminho muda quando o plugin é atualizado. Não escreva estado lá
1091* **`${CLAUDE_PLUGIN_DATA}`**: um diretório que sobrevive a atualizações, para `node_modules`, ambientes virtuais e caches. Ele se resolve para `~/.claude/plugins/data/<id>/` e é criado quando primeiro referenciado
1092* **`${CLAUDE_PROJECT_DIR}`**: a raiz do projeto, o mesmo valor que hooks recebem
1093
1094No caminho do diretório de dados, `<id>` é o identificador do plugin com cada caractere diferente de letras, dígitos, `_` e `-` substituído por `-`, então `my-plugin@my-marketplace` se torna `my-plugin-my-marketplace`.
1095
1096No Windows, os caminhos substituídos usam barras para frente para que um shell não leia barras invertidas como escapes.
1097
1098<h3 id="install-dependencies-into-the-data-directory">
1099 Instalar dependências no diretório de dados
1100</h3>
1101
1102Para um plugin instalado no marketplace, Claude Code instala [dependências de pacote Node.js](/docs/pt/plugins/loading#node-js-package-dependencies) elegíveis automaticamente quando armazena em cache o plugin, então você pode não precisar instalá-las você mesmo. Quando você faz, este hook `SessionStart` instala `node_modules` em `${CLAUDE_PLUGIN_DATA}` na primeira execução e novamente após uma atualização alterar `package.json`:
1103
1104```json hooks/hooks.json theme={null}
1105{
1106 "hooks": {
1107 "SessionStart": [
1108 {
1109 "hooks": [
1110 {
1111 "type": "command",
1112 "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
1113 }
1114 ]
1115 }
1116 ]
1117 }
1118}
1119```
1120
1121Após a primeira sessão, `~/.claude/plugins/data/<id>/node_modules` existe. Um servidor MCP pode então definir `NODE_PATH` para `${CLAUDE_PLUGIN_DATA}/node_modules` em seu `env`. Para quais campos substituem qual variável, consulte [Variáveis de ambiente](/docs/pt/plugins/manifest-reference#environment-variables).
1122
1123<h2 id="next-steps">
1124 Próximos passos
1125</h2>
1126
1127* [Referência de manifesto de plugin](/docs/pt/plugins/manifest-reference): campos `plugin.json`, regras de caminho e o layout padrão
1128* [Testar plugins com evals](/docs/pt/plugin-evals): verifique se os componentes que você adicionou alteram o comportamento de Claude da forma que você pretende
1129* [Publicar e distribuir um plugin](/docs/pt/plugins/publish): versione o plugin e coloque-o em um marketplace
1130* [Solucionar problemas de plugins](/docs/pt/plugins/troubleshooting): o que fazer quando um componente não carrega ou um hook não dispara