Agentes Customizaveis (Personas)

O ChatCLI permite que voce crie Agentes Customizaveis (tambem chamados de Personas) que definem comportamentos especificos para a IA. Este sistema transforma o ChatCLI de uma ferramenta com um “System Prompt” estatico para uma plataforma polimorfica.

Conceito Fundamental

A ideia central e a composicao de prompts:

Agentes definem “quem” a IA e (personalidade, especializacao, tom)
Skills definem “o que” ela deve saber/obedecer (regras, knowledge, compliance)

Um Agente pode importar multiplas Skills, criando um “Super System Prompt” composto automaticamente.

Beneficios

Reutilizacao

Skills podem ser compartilhadas entre multiplos agentes

Versionamento

Arquivos .md podem ser versionados no Git

Colaboracao

Equipes podem compartilhar agentes e skills

Consistencia

Regras de coding style aplicadas automaticamente

Especializacao

Crie agentes para Go, Python, DevOps, etc.

Despacho como Worker

Agents customizados sao automaticamente registrados no sistema multi-agent e podem ser despachados via agent_call pelo LLM

Servidor Remoto

Ao conectar a um servidor, agents e skills remotos sao descobertos automaticamente e mesclados com os locais

Estrutura de Diretorios

Os arquivos ficam no diretorio ~/.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 diretorios V2)
    |-- clean-code/    # Skill V2 (pacote com subskills + scripts)
    |   |-- SKILL.md
    |   |-- naming-rules.md
    |   +-- scripts/
    |       +-- lint_check.py
    |-- error-handling.md  # Skill V1 (arquivo unico)
    |-- docker-master.md
    +-- clean-scripts.md

Formato do Arquivo de Agente

Os agentes sao 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"
---
# Personalidade Base

Voce e um Engenheiro DevOps Senior, especialista em CI/CD,
containers, infraestrutura como codigo e observabilidade.

Campo `tools` — Integracao com Multi-Agent

O campo tools no frontmatter YAML e a chave para a integracao com o sistema de orquestracao multi-agent. Ele define quais comandos o agent pode usar quando despachado como worker pelo LLM orquestrador.

Tool no YAML	Comando(s) @coder	Descricao
`Read`	`read`	Ler conteudo de arquivos
`Grep`	`search`	Buscar padroes em arquivos
`Glob`	`tree`	Listar diretorios
`Bash`	`exec`, `test`, `git-status`, `git-diff`, `git-log`, `git-changed`, `git-branch`	Execucao de comandos e operacoes git
`Write`	`write`	Criar/sobrescrever arquivos
`Edit`	`patch`	Edicao precisa (search/replace)

Agents sem campo tools recebem automaticamente read, search, tree e sao marcados como read-only. Agents com Write, Edit ou Bash tem acesso de escrita/execucao. Nomes de agents embarcados (file, coder, shell, git, search, planner) sao protegidos e nao podem ser sobrescritos.

Exemplo sem o campo `tools`

---
name: "go-expert"
description: "Especialista em Go/Golang com foco em codigo limpo"
skills:
  - clean-code
  - error-handling
plugins:
  - "@coder"
---
# Personalidade Base

Voce e um Engenheiro de Software Senior, especialista em Go/Golang.

## Principios Fundamentais

1. **Simplicidade**: Prefira codigo simples e legivel.
2. **Composicao**: Use interfaces pequenas e composicao ao inves de heranca.
3. **Erros**: Trate erros explicitamente, nunca ignore.
4. **Testes**: Escreva testes com table-driven tests.

Este agent sera registrado como read-only no sistema multi-agent (apenas read, search, tree).

Formato do Arquivo de Skill

As skills contem conhecimento puro ou regras de compliance:

---
name: "clean-code"
description: "Principios de Clean Code e boas praticas"
---
# Regras de Clean Code

## Nomenclatura

1. **Nomes significativos**: Variaveis e funcoes devem revelar seu proposito.
2. **Evite desinformacao**: Nao use nomes que possam confundir.
3. **Nomes pronunciaveis**: Use nomes que possam ser discutidos verbalmente.

## Funcoes

1. **Pequenas**: Funcoes devem fazer uma coisa so.
2. **Poucos argumentos**: Idealmente 0-2 argumentos, maximo 3.
3. **Sem efeitos colaterais**: Funcoes devem fazer somente o que prometem.

Skills V2 — Pacotes com Subskills e Scripts

Alem das skills V1 (arquivo unico .md), o ChatCLI suporta Skills V2: diretorios contendo multiplos documentos e scripts executaveis.

Estrutura de uma Skill V2

skills/
+-- clean-code/
    |-- SKILL.md            # Conteudo principal (frontmatter + body)
    |-- naming-rules.md     # Subskill: regras de nomenclatura
    |-- formatting.md       # Subskill: regras de formatacao
    +-- scripts/
        +-- lint_check.py   # Script executavel

Subskills

Arquivos .md dentro do diretorio da skill (exceto SKILL.md) sao registrados como subskills. Quando o agent e despachado como worker, os caminhos dos subskills aparecem no system prompt do worker, que pode le-los com o comando read conforme necessario.

Scripts

Arquivos em scripts/ sao registrados como skills executaveis no worker. O sistema infere automaticamente o comando de execucao com base na extensao:

Extensao	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` (execucao direta)

Os scripts sao executados via o comando exec do @coder e seus resultados retornam ao worker para processamento.

Skills de Registries Remotos

Alem de criar skills manualmente, voce 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 disponiveis
/agent skills

Skills instaladas via registry sao salvas em ~/.chatcli/skills/<name>/SKILL.md como pacotes V2 e ficam imediatamente disponiveis para uso com agentes. O ChatCLI suporta multiplos 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 sao automaticamente registrados no sistema de orquestracao multi-agent. O LLM orquestrador pode entao despacha-los via <agent_call>:

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

O que o worker recebe

Quando despachado, o CustomAgent executa com:

System prompt personalizado

Inclui o conteudo do agent (markdown body), skills carregadas, caminhos de subskills, comandos de scripts, e instrucoes de tool_call

Mini ReAct loop

O mesmo loop ReAct dos agents embarcados, com raciocinio, acao e observacao

Comandos permitidos

Baseados no campo tools do frontmatter

Leitura paralela

Tool calls read-only executam em goroutines paralelas

File locks

Escrita com mutex per-filepath para seguranca anti-race

Recuperacao 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
# 2. Inicie o coder mode
/coder configure the deployment pipeline and monitoring

# 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 proprios ReAct loops

Comandos de Gerenciamento

Todos os comandos de gerenciamento estao integrados ao /agent:

Comando	Descricao
`/agent`	Mostra status do agente ativo e ajuda
`/agent list`	Lista todos os agentes disponiveis
`/agent status`	Lista apenas os agentes anexados (resumido) - alias: attached/list-attached
`/agent load <nome>`	Carrega um agente especifico
`/agent attach <nome>`	Anexa um agente adicional a sessao
`/agent detach <nome>`	Remove um agente anexado
`/agent skills`	Lista todas as skills disponiveis
`/agent show [--full]`	Mostra os agente ativo com exemplo de prompts (use —full para exibir tudo)
`/agent off`	Desativa todos agente atualmente ativados
`/agent <tarefa>`	Executa uma tarefa no modo agente

Ordem de Montagem do Prompt

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

[ROLE]

Identidade do agente (nome, descricao)

[PERSONALITY]

Conteudo base do agente (markdown body)

[SKILLS]

Conhecimento das skills importadas (numeradas)

[PLUGINS]

Hints de plugins habilitados

[LEMBRETE]

Anchor com instrucoes de aplicacao

Essa ordem garante que a IA receba o contexto de forma estruturada.

Exemplo Pratico 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"
---
# Personalidade Base

Voce e um Cientista de Dados Senior, especialista em Python.

## Ferramentas Preferidas

- Pandas para manipulacao de dados
- NumPy para calculos numericos
- Matplotlib/Seaborn para visualizacao
- Scikit-learn para ML classico
- 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 analise este dataset e crie visualizacoes

# Ou no modo coder
/coder crie um pipeline de ML para classificacao

Precedencia de Agents e Skills (Projeto > Global)

Tanto agents quanto skills suportam diretorios por projeto com precedencia sobre os globais. O ChatCLI detecta a raiz do projeto automaticamente buscando um diretorio .agent/ ou .git/ a partir do diretorio 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 diretorios, a versao do projeto prevalece.

Estrutura do Projeto

meu-projeto/
|-- .agent/                  # Marca a raiz do projeto para o ChatCLI
|   |-- agents/              # Agents especificos do projeto
|   |   +-- backend.md       # Sobrescreve ~/.chatcli/agents/backend.md
|   +-- skills/              # Skills especificas do projeto
|       +-- team-rules.md    # Regras especificas da equipe
|-- src/
+-- ...

Se seu projeto ja tem .git/, o ChatCLI usa esse diretorio como raiz do projeto automaticamente. O .agent/ e opcional — use-o quando quiser agents/skills por projeto sem depender do Git.

Integracao com /coder

Quando um agente esta carregado:

/agent <tarefa> — Usa a persona do agente
/coder <tarefa> — Combina a persona do agente com o prompt do coder

Isso permite que voce tenha um agente especialista em Go usando as ferramentas do @coder para editar arquivos, executar testes, etc.

Dicas

Comece Simples

Crie agentes com poucas skills e va adicionando conforme necessario.

Versione no Git

Mantenha seus agentes e skills em um repositorio.

Compartilhe com a Equipe

Skills de coding style garantem consistencia.

Use Descricoes Claras

Ajuda a entender o proposito de cada agente/skill.

Teste o Prompt

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

Exemplos de Skills Uteis

clean-code - Principios de codigo limpo
error-handling - Padroes de tratamento de erros
testing-patterns - Padroes de testes automatizados
docker-master - Best practices para Dockerfiles
clean-scripts - Padroes para scripts Bash seguros
aws-security - Regras de seguranca para AWS
team-conventions - Convencoes especificas da equipe

Agents e Skills Remotos

Quando conectado a um servidor ChatCLI via chatcli connect, o client descobre automaticamente os agents e skills disponiveis no servidor. Eles sao transferidos ao client e compostos localmente, permitindo merge com resources locais.

# Ao conectar, o client mostra os recursos disponiveis
Connected to ChatCLI server (version: 1.3.0, provider: CLAUDEAI, model: claude-sonnet-4-5)
 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 deploy/helm/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: referencia 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 sao montados em /home/chatcli/.chatcli/agents/ e /home/chatcli/.chatcli/skills/, e ficam disponiveis para descoberta remota automaticamente.

Início

Primeiros Passos

Conceitos Fundamentais

Funcionalidades

Suporte

​Conceito Fundamental

​Beneficios

Reutilizacao

Versionamento

Colaboracao

Consistencia

Especializacao

Despacho como Worker

Servidor Remoto

​Estrutura de Diretorios

​Formato do Arquivo de Agente

​Campo tools — Integracao com Multi-Agent

​Exemplo sem o campo tools

​Formato do Arquivo de Skill

​Skills V2 — Pacotes com Subskills e Scripts

​Estrutura de uma Skill V2

​Subskills

​Scripts

​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 Pratico Completo

​1. Criar um agente

​2. Usar o agente

​Precedencia de Agents e Skills (Projeto > Global)

​Ordem de Busca

​Estrutura do Projeto

​Integracao com /coder

​Dicas

Comece Simples

Versione no Git

Compartilhe com a Equipe

Use Descricoes Claras

Teste o Prompt

​Exemplos de Skills Uteis

​Agents e Skills Remotos

​Provisionamento via Kubernetes

Conceito Fundamental

Beneficios

Estrutura de Diretorios

Formato do Arquivo de Agente

Campo `tools` — Integracao com Multi-Agent

Exemplo sem o campo `tools`

Formato do Arquivo de Skill

Skills V2 — Pacotes com Subskills e Scripts

Estrutura de uma Skill V2

Subskills

Scripts

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

1. Criar um agente

2. Usar o agente

Precedencia de Agents e Skills (Projeto > Global)

Ordem de Busca

Estrutura do Projeto

Integracao com /coder

Dicas

Exemplos de Skills Uteis

Agents e Skills Remotos

Provisionamento via Kubernetes