Agentes Customizáveis (Personas)

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

Reutilização

Skills podem ser compartilhadas entre múltiplos agentes.

Versionamento

Arquivos .md podem ser versionados no Git.

Colaboração

Equipes podem compartilhar agentes e skills.

Consistência

Regras de coding style aplicadas automaticamente.

Especialização

Crie agentes para Go, Python, DevOps, etc.

Despacho como Worker

Agents customizados são automaticamente registrados no sistema multi-agent e podem ser despachados via agent_call pelo LLM orquestrador.

Auto-ativação de Skills

Skills com triggers: ou paths: no frontmatter são injetadas automaticamente no system prompt quando detectadas na mensagem do usuário.

Modelo e Effort por Agente

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/:

~/.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:

---
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. 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`, `patch`	Edição transacional de múltiplos arquivos com rollback all-or-nothing
`Memory`	`memory-recall`	Busca read-only na memória persistente cross-session (fatos, preferências, histórico de projetos)
`Session`	`session-search`, `session-get`	Busca e leitura paginada read-only de conversas salvas
`Knowledge`	`knowledge-search`, `knowledge-get`	Busca e leitura de documentos read-only nas knowledge bases anexadas

O matching é tolerante: nomes são case-insensitive (bash funciona), aliases comuns são aceitos (Shell → Bash, Patch → Edit) e especificadores de argumento no estilo Claude Code são ignorados (Bash(go build:*) conta como Bash). Tokens que mesmo assim não casam geram um warning no registro do agent em vez de degradá-lo silenciosamente.

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 — Memory, Session e Knowledge são superfícies read-only e nunca concedem escrita. 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`

---
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 <agent_call>, o dispatcher:

Lê `agent.Model()` e `agent.Effort()`

Para custom agents, vem do frontmatter. Para built-ins, vem de BuiltinAgentMeta (defaults + env var override).

Se `Model()` não é vazio, roda pelo Model Router

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.

Se `Effort()` não é vazio, anexa ao `ctx` do worker

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.

`cli.Client`, `cli.Provider` e `cli.Model` **não são mutados**

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

---
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:

---
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

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.

---
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: "<pacote>"              # 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, com dois níveis:

Substring contígua (fast path) — o trigger inteiro aparece como está: servicenow login dispara em “faz o ServiceNow login”.
Todas as palavras, qualquer ordem — triggers multi-palavra também disparam quando toda palavra aparece como token inteiro no texto, em qualquer ordem: servicenow login também dispara em “preciso fazer o login no servicenow”. Só tokens inteiros — palavras curtas nunca casam dentro de outras palavras (message me não dispara em “user message”), e pontuação tokeniza dos dois lados (unit-tests ≈ unit tests).

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, no agent/coder mode, no início da execução e novamente a cada turno do loop ReAct (veja Re-ativação durante a tarefa).

Ativação Automática: `paths`

Globs de arquivos que ativam a skill quando os arquivos correspondentes estão sendo discutidos. Suporta *, ** (doublestar recursivo) e ?.

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).

Re-ativação durante a tarefa (agent/coder)

No agent/coder mode, a ativação não fica limitada à query inicial. A cada turno do loop ReAct, o ChatCLI re-escaneia por skills que ainda não dispararam, casando contra:

o próprio raciocínio do modelo e os paths de arquivo dentro dos args das tool_call — se o agente decide no meio da tarefa “escrever um Helm chart pra isso”, ou começa a tocar arquivos que casam com os globs de paths: de uma skill, ela ativa a tempo de moldar a próxima ação;
instruções de follow-up digitadas no meio da sessão (a fila de type-ahead ou o prompt de continuação do coder).

Skills recém-casadas são injetadas como mensagem append-only [SKILL AUTO-ACTIVATION — MID-TASK] no próximo limite de turno, então o prefixo cacheado do system prompt nunca é invalidado no meio da execução — com drip de no máximo 3 skills novas por injeção (matches excedentes re-candidatam no próximo boundary). Cada skill dispara no máximo uma vez enquanto seu bloco está vivo: após CHATCLI_SKILL_AGE_TURNS turnos o bloco envelhece para um stub compacto (recuperável via @recall) e a skill pode re-ativar após um cooldown se voltar a ser relevante. O set de dedup sobrevive a @park/resume. Hints de model:/effort: de skills mid-task só valem quando nenhuma skill do startup já os reivindicou. Veja Skill Registry › Ciclo de vida. Desative com CHATCLI_AGENT_SKILL_RESCAN=false (ligado por default; listado no /config na seção de skills).

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-name>  >  /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 `/<skill-name>`

Skills com user-invocable: true ficam disponíveis como comandos slash diretos:

/go-testing gera testes para o Handler{}

O ChatCLI intercepta o /<skill-name> 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:

/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 /<skill-name> manual. Skills com disable-model-invocation: true não podem ser fixadas — o flag existe pra proibir injeção automática. Use /<skill-name> manual nesses casos. Detalhes completos, exemplos e a tabela de precedência: Pin Skills no Skill Registry.

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.

/agent
# 📋 help do persona handler + exemplos
# 💡 Uso: /agent <tarefa>  (ex.: /agent investigar erro 500)

Para entrar em modo agente com contexto, passe o task inline:

/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:

# 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/<name>/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 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. O LLM orquestrador pode então despachá-los via <agent_call>:

<agent_call agent="devops-senior" task="Configure CI/CD pipeline with GitHub Actions" />
<agent_call agent="my-strict-reviewer" task="Audit the authentication module for OWASP" />

O que o worker recebe

Quando despachado, o CustomAgent executa com:

System prompt personalizado

Inclui o conteúdo do agent (markdown body), skills carregadas, caminhos de subskills, comandos de scripts e instruções de tool_call.

Mini ReAct loop

O mesmo loop ReAct dos agents embarcados, com raciocínio, ação e observação.

Comandos permitidos

Baseados no campo tools do frontmatter.

Client resolvido por turno

Se o agent declarar model:, o dispatcher chama ResolveModelRouting para obter o client correto antes de cada turno do mini-ReAct.

Effort aplicado ao ctx

Se o agent declarar effort:, o ctx do worker recebe WithEffortHint, que o provider lê dentro do SendPrompt.

Leitura paralela

Tool calls read-only executam em goroutines paralelas.

File locks

Escrita com mutex per-filepath para segurança anti-race.

Recuperação de erros

O orquestrador pode usar tool_call direto para diagnosticar e corrigir falhas.

Exemplo End-to-End

# 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:
# <agent_call agent="devops-senior" task="Set up CI/CD with GitHub Actions" />
# <agent_call agent="file" task="Read current Dockerfile and docker-compose.yml" />
#
# 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 <nome>`	Carrega um agente específico
`/agent attach <nome>`	Anexa um agente adicional à sessão
`/agent detach <nome>`	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 <tarefa>`	Executa uma tarefa no modo agente

Ordem de Montagem do Prompt

Quando um agente é carregado, o system prompt é montado na seguinte ordem:

[ROLE]

Identidade do agente (nome, descrição)

[PERSONALITY]

Conteúdo base do agente (markdown body)

[SKILLS]

Conhecimento das skills importadas (numeradas)

[AUTO-LOADED SKILLS]

Skills ativadas automaticamente por triggers: ou paths: da mensagem atual

[MANUAL SKILL]

Bloco adicional quando a mensagem foi invocada via /<skill-name>

[PLUGINS]

Hints de plugins habilitados

[LEMBRETE]

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:

---
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

# 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

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 <tarefa> — Usa a persona do agente.
/coder <tarefa> — 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

Comece Simples

Crie agentes com poucas skills e vá adicionando conforme necessário.

Versione no Git

Mantenha seus agentes e skills em um repositório.

Compartilhe com a Equipe

Skills de coding style garantem consistência.

Use Descrições Claras

Ajuda a entender o propósito de cada agente/skill.

Teste o Prompt

Use /agent show para ver como o prompt ficou montado.

Atribua `effort` com Cuidado

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.

# 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

Helm
Operator

# 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

# 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

Multi-Agent Orchestration

Como múltiplos agents customizados rodam em paralelo via <agent_call>.

Skill Registry

Publique e descubra skills compartilhadas entre equipes.

Subagent Delegation

Delegação focada para análises concentradas em um payload grande.

Modo Servidor

Distribua agents via ConfigMap para toda a equipe.

​Conceito Fundamental

​Benefícios

Reutilização

Versionamento

Colaboração

Consistência

Especialização

Despacho como Worker

Auto-ativação de Skills

Modelo e Effort por Agente

​Estrutura de Diretórios

​Formato do Arquivo de Agente

​Campo tools — Integração com Multi-Agent

​Exemplo sem o campo tools

​Frontmatter Avançado de Agentes

​Como o Dispatcher Aplica Model/Effort

​Exemplo: Custom Agent com Modelo Ideal

​Formato do Arquivo de Skill

​Skills V2 — Pacotes com Subskills e Scripts

​Estrutura de uma Skill V2

​Subskills

​Scripts

​Skill Frontmatter Avançado

​Ativação Automática: triggers

​Ativação Automática: paths

​Re-ativação durante a tarefa (agent/coder)

​Propagação de model e effort

​Invocação Manual via /<skill-name>

​Controle de Invocação

​Fixar uma Skill na Sessão (/skill pin)

​Comando /agent sem Contexto

​Skills de Registries Remotos

​Despacho como Worker (Multi-Agent)

​O que o worker recebe

​Exemplo End-to-End

​Comandos de Gerenciamento

​Ordem de Montagem do Prompt

​Exemplo Prático Completo

​1. Criar um agente

​2. Usar o agente

​Precedência de Agents e Skills (Projeto > Global)

​Ordem de Busca

​Estrutura do Projeto

​Integração com /coder

​Dicas

Comece Simples

Versione no Git

Compartilhe com a Equipe

Use Descrições Claras

Teste o Prompt

Atribua `effort` com Cuidado

​Exemplos de Skills Úteis

​Agents e Skills Remotos

​Provisionamento via Kubernetes

​Próximos passos

Multi-Agent Orchestration

Skill Registry

Subagent Delegation

Modo Servidor

Conceito Fundamental

Benefícios

Estrutura de Diretórios

Formato do Arquivo de Agente

Campo `tools` — Integração com Multi-Agent

Exemplo sem o campo `tools`

Frontmatter Avançado de Agentes

Como o Dispatcher Aplica Model/Effort

Exemplo: Custom Agent com Modelo Ideal

Formato do Arquivo de Skill

Skills V2 — Pacotes com Subskills e Scripts

Estrutura de uma Skill V2

Subskills

Scripts

Skill Frontmatter Avançado

Ativação Automática: `triggers`

Ativação Automática: `paths`

Re-ativação durante a tarefa (agent/coder)

Propagação de `model` e `effort`

Invocação Manual via `/<skill-name>`

Controle de Invocação

Fixar uma Skill na Sessão (`/skill pin`)

Comando `/agent` sem Contexto

Skills de Registries Remotos

Despacho como Worker (Multi-Agent)

O que o worker recebe

Exemplo End-to-End

Comandos de Gerenciamento

Ordem de Montagem do Prompt

Exemplo Prático Completo

1. Criar um agente

2. Usar o agente

Precedência de Agents e Skills (Projeto > Global)

Ordem de Busca

Estrutura do Projeto

Integração com `/coder`

Dicas

Exemplos de Skills Úteis

Agents e Skills Remotos

Provisionamento via Kubernetes

Próximos passos