> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Agentes Customizáveis (Personas)
> Sistema modular para criar personalidades e conhecimentos especializados para a IA, com despacho automático como workers no sistema multi-agent, auto-ativação de skills por triggers/paths e seleção de modelo por agente.
O ChatCLI permite que você crie **Agentes Customizáveis** (também chamados de Personas) que definem comportamentos específicos para a IA. Este sistema transforma o ChatCLI de uma ferramenta com um "System Prompt" estático para uma **plataforma polimórfica**.
## Conceito Fundamental
A ideia central é a **composição de prompts**:
* **Agentes** definem *"quem"* a IA é (personalidade, especialização, tom).
* **Skills** definem *"o que"* ela deve saber/obedecer (regras, knowledge, compliance).
Um Agente pode importar múltiplas Skills, criando um **"Super System Prompt"** composto automaticamente. Tanto Skills quanto Agentes suportam preferências de modelo e effort per-turno, honradas automaticamente pelo dispatcher quando são ativados.
## Benefícios
Skills podem ser compartilhadas entre múltiplos agentes.
Arquivos `.md` podem ser versionados no Git.
Equipes podem compartilhar agentes e skills.
Regras de coding style aplicadas automaticamente.
Crie agentes para Go, Python, DevOps, etc.
Agents customizados são automaticamente registrados no sistema multi-agent e podem ser despachados via `agent_call` pelo LLM orquestrador.
Skills com `triggers:` ou `paths:` no frontmatter são injetadas automaticamente no system prompt quando detectadas na mensagem do usuário.
Cada skill e cada agente podem declarar `model:` e `effort:` ideais — o dispatcher faz o roteamento correto sem mudar a escolha do usuário.
## Estrutura de Diretórios
Os arquivos ficam no diretório `~/.chatcli/`:
```text theme={"system"}
~/.chatcli/
|-- agents/ # Arquivos de agentes
| |-- go-expert.md
| |-- devops-senior.md
| |-- security-auditor.md
| +-- python-data-scientist.md
+-- skills/ # Arquivos de skills (.md ou diretórios V2)
|-- clean-code/ # Skill V2 (pacote com subskills + scripts)
| |-- SKILL.md
| |-- naming-rules.md
| +-- scripts/
| +-- lint_check.py
|-- error-handling.md # Skill V1 (arquivo único)
|-- docker-master.md
+-- clean-scripts.md
```
## Formato do Arquivo de Agente
Os agentes são arquivos Markdown com frontmatter YAML:
```yaml theme={"system"}
---
name: "devops-senior"
description: "DevOps Senior com foco em CI/CD e infraestrutura"
tools: Read, Grep, Glob, Bash, Write, Edit # Define quais ferramentas o agent pode usar como worker
skills: # Lista de skills a importar
- clean-code
- bash-linux
- architecture
plugins: # Plugins habilitados (opcional)
- "@coder"
# Preferências de LLM (opcional) — aplicadas quando este agent roda como worker
model: "claude-opus-4-6" # Modelo ideal; troca transparente se estiver em outro
effort: "high" # low | medium | high | max
# Metadados opcionais
category: "devops"
version: "2.1.0"
author: "Edilson Freitas"
tags: devops, cicd, k8s
---
# Personalidade Base
Você é um Engenheiro DevOps Senior, especialista em CI/CD,
containers, infraestrutura como código e observabilidade.
```
### Campo `tools` — Integração com Multi-Agent
O campo `tools` no frontmatter YAML é a chave para a integração com o sistema de [orquestração multi-agent](/pt/features/multi-agent-orchestration). Ele define quais comandos o agent pode usar quando despachado como **worker** pelo LLM orquestrador.
| Tool no YAML | Comando(s) @coder | Descrição |
| ------------ | -------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `Read` | `read` | Ler conteúdo de arquivos |
| `Grep` | `search` | Buscar padrões em arquivos |
| `Glob` | `tree` | Listar diretórios |
| `Bash` | `exec`, `test`, `git-status`, `git-diff`, `git-log`, `git-changed`, `git-branch` | Execução de comandos e operações git |
| `Write` | `write` | Criar/sobrescrever arquivos |
| `Edit` | `patch` | Edição precisa (search/replace) |
| `MultiEdit` | `multipatch` | Edição transacional de múltiplos arquivos com rollback all-or-nothing |
Agents **sem** o campo `tools` recebem automaticamente `read`, `search`, `tree` e são marcados como **read-only**. Agents com `Write`, `Edit`, `MultiEdit` ou `Bash` tem **acesso de escrita/execução**. Os 12 nomes de agents embarcados (`file`, `coder`, `shell`, `git`, `search`, `planner`, `reviewer`, `tester`, `refactor`, `diagnostics`, `formatter`, `deps`) são **protegidos** e não podem ser sobrescritos.
### Exemplo sem o campo `tools`
```yaml theme={"system"}
---
name: "go-expert"
description: "Especialista em Go/Golang com foco em código limpo"
skills:
- clean-code
- error-handling
plugins:
- "@coder"
---
# Personalidade Base
Você é um Engenheiro de Software Senior, especialista em Go/Golang.
## Princípios Fundamentais
1. **Simplicidade**: Prefira código simples e legível.
2. **Composição**: Use interfaces pequenas e composição ao invés de herança.
3. **Erros**: Trate erros explicitamente, nunca ignore.
4. **Testes**: Escreva testes com table-driven tests.
```
Este agent será registrado como **read-only** no sistema multi-agent (apenas `read`, `search`, `tree`).
***
## Frontmatter Avançado de Agentes
Desde a versão recente, agentes suportam os mesmos campos de preferência de LLM que as skills. Eles são **opcionais** e **retrocompatíveis** — agents sem esses campos continuam funcionando exatamente como antes.
| Campo | Tipo | Padrão | Descrição |
| :--------- | :----------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model` | string | — | Modelo preferido quando este agent roda como worker. Se o usuário estiver em outro modelo/provider, o dispatcher tenta swap transparente (mesmo provider → catálogo → família; cross-provider quando disponível). |
| `effort` | string | — | Nível de esforço: `low`, `medium`, `high`, `max`. Mapeado para *extended thinking* (Anthropic) / *reasoning\_effort* (OpenAI) nos providers compatíveis. |
| `category` | string | — | Categoria para organização (ex.: `devops`, `security`, `review`). |
| `version` | string | — | Versão do agent (SemVer recomendado). |
| `author` | string | — | Autor do agent. |
| `tags` | list\|string | — | Tags para busca e classificação. Aceita lista YAML ou string separada por vírgula. |
### Como o Dispatcher Aplica Model/Effort
Quando o LLM orquestrador despacha um agent via ``, o dispatcher:
Para custom agents, vem do frontmatter. Para built-ins, vem de `BuiltinAgentMeta` (defaults + env var override).
O resolver tenta, em ordem: API cache do provider ativo → catálogo estático → heurística de família (`claude-*`, `gpt-*`, `gemini-*`, etc.) → fallback otimista no provider do usuário. Se o provider-alvo não estiver configurado (sem API key), cai de volta no client do usuário e loga um aviso claro.
O provider lê o hint via `client.EffortFromContext(ctx)` dentro do `SendPrompt` e injeta `thinking.budget_tokens` (Anthropic) ou `reasoning.effort` / `reasoning_effort` (OpenAI) no request body — apenas em modelos que suportam.
O swap é escopo de turno do worker. Quando o worker termina, o próximo agent dispatch ou turno do chat usa a escolha original do usuário.
### Exemplo: Custom Agent com Modelo Ideal
```yaml theme={"system"}
---
name: "my-strict-reviewer"
description: "Revisor crítico com foco em bugs sutis e design issues"
tools: Read, Grep, Glob
skills:
- go-testing
- golangci
model: "claude-opus-4-6" # sempre roda em Opus, mesmo que o user esteja em Sonnet
effort: "high" # ativa extended thinking
category: "review"
version: "1.0.0"
author: "Edilson Freitas"
---
# Personalidade
Você é um revisor extremamente rigoroso. Foque em bugs sutis, design issues,
violações SOLID e pontos de complexidade ciclomática alta. Evite comentários de
nit-picking sobre formatação.
```
Se o usuário estiver com `CLAUDEAI` configurado mas em `claude-sonnet-4-6`, este agent vai rodar em `claude-opus-4-6` automaticamente. Se o usuário estiver em `OPENAI` com `gpt-5` e **não** tiver `ANTHROPIC_API_KEY`, o dispatcher cai graciosamente no modelo do usuário e imprime um aviso claro explicando por quê.
***
## Formato do Arquivo de Skill
As skills contem conhecimento puro ou regras de compliance:
```yaml theme={"system"}
---
name: "clean-code"
description: "Princípios de Clean Code e boas práticas"
---
# Regras de Clean Code
## Nomenclatura
1. **Nomes significativos**: Variáveis e funções devem revelar seu propósito.
2. **Evite desinformação**: Não use nomes que possam confundir.
3. **Nomes pronunciáveis**: Use nomes que possam ser discutidos verbalmente.
## Funções
1. **Pequenas**: Funções devem fazer uma coisa só.
2. **Poucos argumentos**: Idealmente 0-2 argumentos, máximo 3.
3. **Sem efeitos colaterais**: Funções devem fazer somente o que prometem.
```
## Skills V2 — Pacotes com Subskills e Scripts
Além das skills V1 (arquivo único `.md`), o ChatCLI suporta **Skills V2**: diretórios contendo múltiplos documentos e scripts executáveis.
### Estrutura de uma Skill V2
```text theme={"system"}
skills/
+-- clean-code/
|-- SKILL.md # Conteúdo principal (frontmatter + body)
|-- naming-rules.md # Subskill: regras de nomenclatura
|-- formatting.md # Subskill: regras de formatação
+-- scripts/
+-- lint_check.py # Script executável
```
### Subskills
Arquivos `.md` dentro do diretório da skill (exceto `SKILL.md`) são registrados como **subskills**. Quando o agent é despachado como worker, os caminhos dos subskills aparecem no system prompt do worker, que pode lê-los com o comando `read` conforme necessário.
### Scripts
Arquivos em `scripts/` são registrados como **skills executáveis** no worker. O sistema infere automaticamente o comando de execução com base na extensão:
| Extensão | Comando Inferido |
| -------- | ---------------------------- |
| `.sh` | `bash script.sh` |
| `.py` | `python3 script.py` |
| `.js` | `node script.js` |
| `.ts` | `npx ts-node script.ts` |
| `.rb` | `ruby script.rb` |
| Outros | `./script` (execução direta) |
Os scripts são executados via o comando `exec` do @coder e seus resultados retornam ao worker para processamento.
***
## Skill Frontmatter Avançado
Além dos campos básicos (`name`, `description`, `allowed-tools`), skills suportam frontmatter avançado para controle fino de comportamento. **Todos os campos avançados são opcionais e retrocompatíveis** — skills existentes continuam funcionando normalmente.
```yaml theme={"system"}
---
name: "go-testing"
description: "Padrões e boas práticas para testes em Go"
allowed-tools: Read, Grep, Glob, Bash
# Preferências de LLM (propagadas ao turno que ativa a skill)
model: "sonnet" # Modelo preferido
effort: "high" # Nível de esforço: low, medium, high, max
# Metadados
category: "testing"
version: "1.2.0"
author: "Edilson Freitas"
tags: testing, go, unit-tests, tdd
# Ativação automática
triggers: test, testing, tdd, unittest # Keywords que auto-ativam
paths: ["*_test.go", "test/**"] # Globs que auto-ativam por arquivo
# Controle de invocação
user-invocable: true # Pode ser invocada com /skill-name
disable-model-invocation: false # Se true, apenas invocação manual
argument-hint: "" # Hint de args no autocomplete
---
## Padrões de Teste em Go
...
```
### Ativação Automática: `triggers`
Keywords que ativam a skill automaticamente quando detectadas na mensagem do usuário. Case-insensitive, match por substring.
```yaml theme={"system"}
triggers: test, testing, tdd
```
Se o usuário digitar *"como escrever **testes** para este handler?"*, a skill é injetada automaticamente no system prompt do turno — junto com o descritivo e o conteúdo completo da skill. O LLM passa a seguir as instruções automaticamente.
Implementado em `pkg/persona/manager.go#FindTriggeredSkills`. A detecção roda em todo turno no chat mode e uma vez no início do agent/coder mode.
### Ativação Automática: `paths`
Globs de arquivos que ativam a skill quando os arquivos correspondentes estão sendo discutidos. Suporta `*`, `**` (doublestar recursivo) e `?`.
```yaml theme={"system"}
paths: ["*_test.go", "test/**", "src/**/*.ts"]
```
O ChatCLI extrai tokens que parecem caminhos de arquivo do input do usuário (`@file path/...`, `@path/to/file.go`, ou tokens bare como `pkg/foo/bar_test.go` e `main.go`) e casa cada um contra os padrões `paths:` de todas as skills instaladas.
Exemplos que disparam `*_test.go`:
* `"rode os testes em pkg/foo/bar_test.go"`
* `"@file pkg/foo/bar_test.go"`
* `"@pkg/foo/bar_test.go"`
Implementado em `pkg/persona/types.go#MatchesPath` (com matcher doublestar próprio, sem dependência externa) e `pkg/persona/manager.go#FindPathMatchedSkills`. A extração de paths do input está em `cli/skill_activation.go#extractFilePaths`.
Quando uma mesma skill casa tanto por `triggers` quanto por `paths`, ela é injetada uma única vez (dedup por nome).
### Propagação de `model` e `effort`
Quando uma skill é auto-ativada (via `triggers` ou `paths`), fixada (`/skill pin`) ou invocada manualmente, seus campos `model:` e `effort:` são propagados para o turno atual:
* **`model:`** — o dispatcher/resolver troca o client da LLM para este turno. Funciona dentro do mesmo provider (ex.: `sonnet` → `opus` no Claude) ou cross-provider (ex.: usuário em Claude, skill quer `gpt-5` em OpenAI). Se o provider-alvo não estiver configurado, cai de volta no client do usuário com aviso visível.
* **`effort:`** — mapeado para `thinking.budget_tokens` (Anthropic, modelos Opus 4.x / Sonnet 4.x / 3.7) ou `reasoning_effort` / `reasoning.effort` (OpenAI, modelos o1/o3/o4/gpt-5). Modelos sem suporte ignoram silenciosamente.
**Precedência quando múltiplos modos disparam no mesmo turno:**
```
manual / > /skill pin > auto-activation (triggers/paths)
```
O primeiro `model:` não-vazio na ordem acima ganha; conflitos subsequentes são logados como warning mas não forçam swap adicional.
### Invocação Manual via `/`
Skills com `user-invocable: true` ficam disponíveis como comandos slash diretos:
```bash theme={"system"}
/go-testing gera testes para o Handler{}
```
O ChatCLI intercepta o `/` antes do router padrão, valida que a skill existe e tem `user-invocable: true`, carrega o conteúdo, mostra o `argument-hint` (se os args estiverem vazios) e dispara o turno injetando a skill como bloco "# Manually Invoked Skill" no system prompt — com precedência sobre skills auto-ativadas.
A lista de comandos protegidos (`/agent`, `/coder`, `/run`, `/switch`, `/help`, `/skill`, etc.) **nunca** pode ser shadowed por uma skill — mesmo que exista uma skill chamada `agent`, o comando built-in sempre vence.
O autocomplete do `/<...>` também inclui todas as skills `user-invocable: true`, mostrando o `description` e o `argument-hint` lado a lado.
### Controle de Invocação
| Campo | Tipo | Padrão | Descrição |
| :------------------------- | :----- | :------ | :------------------------------------------------------------------------------------------------------------------- |
| `user-invocable` | bool | `false` | Habilita invocação via `/skill-name` |
| `disable-model-invocation` | bool | `false` | Bloqueia ativação automática por triggers/paths (o usuário ainda pode invocar manualmente se `user-invocable: true`) |
| `argument-hint` | string | — | Texto exibido no autocomplete e como dica ao invocar sem args |
`disable-model-invocation: true` e `user-invocable: true` juntos = a skill **só** roda quando o usuário digitar `/skill-name`, nunca por detecção automática. Útil para skills destrutivas ou específicas demais para auto-ativar.
### Fixar uma Skill na Sessão (`/skill pin`)
Quando você precisa que uma skill se aplique a **todos** os turnos da sessão — não só os que casam com `triggers:`/`paths:` — fixe ela:
```bash theme={"system"}
/skill pin go-testing # Fixa
/skill pinned # Lista as fixadas
/skill unpin go-testing # Desfixa
```
Pin é uma intenção de sessão (não persiste entre execuções) e fica num bloco `# Pinned Skills` separado no system prompt, cacheável via `cache_control: ephemeral`. Em conflito de hints, pinned ganha de auto-activation mas perde para `/` manual.
Skills com `disable-model-invocation: true` **não podem** ser fixadas — o flag existe pra proibir injeção automática. Use `/` manual nesses casos.
Detalhes completos, exemplos e a tabela de precedência: [Pin Skills no Skill Registry](/pt/features/skill-registry#fixar-skills-na-sessao).
***
## Comando `/agent` sem Contexto
Antes: digitar `/agent` sozinho entrava em modo agente imediatamente e enviava uma mensagem vazia à LLM.
Agora: digitar `/agent` (ou `/run`) sem um task inline imprime o help do persona handler mais um hint de uso e **não** inicia o ReAct loop. O mesmo vale para `/coder`. Isso evita burns de tokens em mensagens vazias e torna a UX mais previsível.
```bash theme={"system"}
/agent
# 📋 help do persona handler + exemplos
# 💡 Uso: /agent (ex.: /agent investigar erro 500)
```
Para entrar em modo agente com contexto, passe o task inline:
```bash theme={"system"}
/agent refatore o módulo auth
```
***
## Skills de Registries Remotos
Além de criar skills manualmente, você pode **buscar e instalar** skills de registries remotos com o comando `/skill`:
```bash theme={"system"}
# Buscar skills de kubernetes
/skill search kubernetes
# Instalar uma skill
/skill install k8s-ops
# Verificar que aparece nas skills disponíveis
/agent skills
```
Skills instaladas via registry são salvas em `~/.chatcli/skills//SKILL.md` como pacotes V2 e ficam imediatamente disponíveis para uso com agentes. O ChatCLI suporta múltiplos registries simultaneamente (ChatCLI.dev, ClawHub, registries corporativos) com busca paralela fan-out. Veja [Skill Registry](/pt/features/skill-registry) para detalhes completos.
***
## Despacho como Worker (Multi-Agent)
Ao iniciar o `/coder` ou `/agent`, **todos os agents customizados** são automaticamente registrados no sistema de [orquestração multi-agent](/pt/features/multi-agent-orchestration). O LLM orquestrador pode então despachá-los via ``:
```xml theme={"system"}
```
### O que o worker recebe
Quando despachado, o CustomAgent executa com:
Inclui o conteúdo do agent (markdown body), skills carregadas, caminhos de subskills, comandos de scripts e instruções de tool\_call.
O mesmo loop ReAct dos agents embarcados, com raciocínio, ação e observação.
Baseados no campo `tools` do frontmatter.
Se o agent declarar `model:`, o dispatcher chama `ResolveModelRouting` para obter o client correto antes de cada turno do mini-ReAct.
Se o agent declarar `effort:`, o ctx do worker recebe `WithEffortHint`, que o provider lê dentro do `SendPrompt`.
Tool calls read-only executam em goroutines paralelas.
Escrita com mutex per-filepath para segurança anti-race.
O orquestrador pode usar `tool_call` direto para diagnosticar e corrigir falhas.
### Exemplo End-to-End
```bash theme={"system"}
# 1. Crie o agent em ~/.chatcli/agents/devops-senior.md (com model/effort)
# 2. Inicie o coder mode
/coder configure o pipeline de deployment e o monitoramento
# O LLM orquestrador pode despachar:
#
#
#
# Ambos rodam em paralelo com seus próprios ReAct loops.
# devops-senior pode rodar em opus-4-6 com effort=high enquanto o file roda em
# sonnet com effort=low — respeitando as preferências de cada agent.
```
***
## Comandos de Gerenciamento
Todos os comandos de gerenciamento estão integrados ao `/agent`:
| Comando | Descrição |
| ---------------------- | -------------------------------------------------------------------------------- |
| `/agent` | Mostra status do agente ativo e ajuda (não entra em modo agente sem task) |
| `/agent list` | Lista todos os agentes disponíveis |
| `/agent status` | Lista apenas os agentes anexados (resumido) — alias: `attached`, `list-attached` |
| `/agent load ` | Carrega um agente específico |
| `/agent attach ` | Anexa um agente adicional à sessão |
| `/agent detach ` | Remove um agente anexado |
| `/agent skills` | Lista todas as skills disponíveis |
| `/agent show [--full]` | Mostra o agente ativo com exemplo de prompts (use `--full` para exibir tudo) |
| `/agent off` | Desativa todos os agentes atualmente ativos |
| `/agent ` | Executa uma tarefa no modo agente |
## Ordem de Montagem do Prompt
Quando um agente é carregado, o system prompt é montado na seguinte ordem:
Identidade do agente (nome, descrição)
Conteúdo base do agente (markdown body)
Conhecimento das skills importadas (numeradas)
Skills ativadas automaticamente por `triggers:` ou `paths:` da mensagem atual
Bloco adicional quando a mensagem foi invocada via `/`
Hints de plugins habilitados
Anchor com instruções de aplicação
Essa ordem garante que a IA receba o contexto de forma estruturada, com intenção explícita do usuário (manual) tendo precedência sobre auto-ativação.
## Exemplo Prático Completo
### 1. Criar um agente
Crie o arquivo `~/.chatcli/agents/python-data.md`:
```yaml theme={"system"}
---
name: "python-data"
description: "Cientista de Dados especialista em Python"
skills:
- clean-code
plugins:
- "@coder"
model: "claude-opus-4-6" # roda sempre em Opus
effort: "medium"
category: "data-science"
tags: python, ml, data
---
# Personalidade Base
Você é um Cientista de Dados Senior, especialista em Python.
## Ferramentas Preferidas
- Pandas para manipulação de dados
- NumPy para cálculos numéricos
- Matplotlib/Seaborn para visualização
- Scikit-learn para ML clássico
- PyTorch para deep learning
```
### 2. Usar o agente
```bash theme={"system"}
# Listar agentes
/agent list
# Available Agents:
# go-expert - Especialista em Go/Golang [2 skills]
# python-data - Cientista de Dados [1 skills]
# Carregar o agente
/agent load python-data
# Agente 'python-data' carregado com sucesso!
# Cientista de Dados especialista em Python
# Skills anexadas:
# - clean-code
# Usar no modo agente
/agent análise este dataset e crie visualizações
# Ou no modo coder
/coder crie um pipeline de ML para classificação
```
## Precedência de Agents e Skills (Projeto > Global)
Tanto agents quanto skills suportam **diretórios por projeto** com precedência sobre os globais. O ChatCLI detecta a raiz do projeto automaticamente buscando um diretório `.agent/` ou `.git/` a partir do diretório atual.
### Ordem de Busca
| Recurso | 1. Projeto (prioridade) | 2. Global (fallback) |
| ---------- | ----------------------- | ------------------------ |
| **Agents** | `./.agent/agents/*.md` | `~/.chatcli/agents/*.md` |
| **Skills** | `./.agent/skills/` | `~/.chatcli/skills/` |
Se um agent ou skill com o mesmo nome existir em ambos os diretórios, a versão do projeto prevalece.
### Estrutura do Projeto
```text theme={"system"}
meu-projeto/
|-- .agent/ # Marca a raiz do projeto para o ChatCLI
| |-- agents/ # Agents específicos do projeto
| | +-- backend.md # Sobrescreve ~/.chatcli/agents/backend.md
| +-- skills/ # Skills específicas do projeto
| +-- team-rules.md # Regras específicas da equipe
|-- src/
+-- ...
```
Se seu projeto já tem `.git/`, o ChatCLI usa esse diretório como raiz do projeto automaticamente. O `.agent/` é opcional — use-o quando quiser agents/skills por projeto sem depender do Git.
## Integração com `/coder`
Quando um agente está carregado:
* `/agent ` — Usa a persona do agente.
* `/coder ` — Combina a persona do agente com o prompt do coder.
Isso permite que você tenha um agente especialista em Go usando as ferramentas do `@coder` para editar arquivos, executar testes etc. As preferências `model:` e `effort:` do agente são honradas em ambos os modos.
## Dicas
Crie agentes com poucas skills e vá adicionando conforme necessário.
Mantenha seus agentes e skills em um repositório.
Skills de coding style garantem consistência.
Ajuda a entender o propósito de cada agente/skill.
Use `/agent show` para ver como o prompt ficou montado.
`effort: high` custa mais tokens. Reserve para agentes que realmente precisam de raciocínio profundo (revisores, planners, diagnostics).
## Exemplos de Skills Úteis
* **clean-code** — Princípios de código limpo
* **error-handling** — Padrões de tratamento de erros
* **testing-patterns** — Padrões de testes automatizados
* **docker-master** — Best practices para Dockerfiles
* **clean-scripts** — Padrões para scripts Bash seguros
* **aws-security** — Regras de segurança para AWS
* **team-conventions** — Convenções específicas da equipe
## Agents e Skills Remotos
Quando conectado a um servidor ChatCLI via `chatcli connect`, o client descobre automaticamente os agents e skills disponíveis no servidor. Eles são transferidos ao client e compostos localmente, permitindo merge com resources locais.
Desde a atualização recente, o wire gRPC (`pb.AgentInfo`) carrega **todos** os campos avançados — `model`, `effort`, `category`, `version`, `author`, `tags` — então agents remotos têm exatamente o mesmo comportamento de roteamento que os locais.
```bash theme={"system"}
# Ao conectar, o client mostra os recursos disponíveis
Connected to ChatCLI server (version: 1.3.0, provider: CLAUDEAI, model: claude-sonnet-4-6)
Server has 3 plugins, 2 agents, 4 skills available
# Agents remotos aparecem na listagem
/agent list
# Available Agents:
# go-expert - Especialista em Go/Golang [local]
# devops-senior - DevOps Senior com foco em K8s [remote]
# Carregar um agent remoto funciona da mesma forma
/agent load devops-senior
```
### Provisionamento via Kubernetes
```bash theme={"system"}
# Helm: agents e skills inline
helm install chatcli oci://ghcr.io/diillson/charts/chatcli \
--set agents.enabled=true \
--set-file agents.definitions.devops-senior\\.md=agents/devops-senior.md \
--set skills.enabled=true \
--set-file skills.definitions.k8s-best-practices\\.md=skills/k8s-best-practices.md
```
```yaml theme={"system"}
# Operator: referência a ConfigMaps existentes
apiVersion: platform.chatcli.io/v1alpha1
kind: Instance
metadata:
name: chatcli-prod
spec:
provider: CLAUDEAI
agents:
configMapRef: chatcli-agents
skillsConfigMapRef: chatcli-skills
```
Os ConfigMaps são montados em `/home/chatcli/.chatcli/agents/` e `/home/chatcli/.chatcli/skills/`, e ficam disponíveis para descoberta remota automaticamente. Campos avançados de frontmatter (`model`, `effort`, `category`, etc.) são lidos pelo chatcli dentro do pod — o CRD e o operator não precisam ser alterados para suportá-los.
***
## Próximos passos
Como múltiplos agents customizados rodam em paralelo via ``.
Publique e descubra skills compartilhadas entre equipes.
Delegação focada para análises concentradas em um payload grande.
Distribua agents via ConfigMap para toda a equipe.