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

# Auto-autoria de Skills (@skill)

> O agente escreve e evolui as próprias skills a partir do que aprende — criar, atualizar, ver, analytics de uso e packs compartilháveis.

O tool **`@skill`** deixa o agente **crescer as próprias capacidades**: quando ele aprende um procedimento reutilizável, uma convenção do projeto ou um fluxo que você repete, ele grava uma skill que **auto-ativa pelos triggers** nesta e em todas as sessões futuras. É a camada de skills viva do hermes-agent, nativa ao formato de skill do ChatCLI.

<Info>
  **`@memory` vs `@skill`**: `@memory` guarda **fatos** ("o user prefere tabs"); `@skill` guarda **procedimento/conhecimento reutilizável com triggers** ("como deployar este projeto"). Fato curto → memória; "como fazer X" → skill. E para criar skills **a partir de documentação**, anexe o corpus como [knowledge base](/pt/features/knowledge-base): o agente pesquisa com `@knowledge` e escreve a skill com `@skill`.
</Info>

***

## Subcomandos

```text theme={"system"}
<tool_call name="@skill" args='{"cmd":"create","args":{
  "name":"deploy-acme-api",
  "description":"Como deployar a Acme API. Use ao pedir deploy da Acme.",
  "triggers":["deploy acme","ship the api"],
  "content":"# Deploy\n1. make test\n2. git tag vX.Y.Z\n...",
  "allowed_tools":["@coder","Bash"]
}}' />
```

| Subcomando                                                       | Função                                       |
| ---------------------------------------------------------------- | -------------------------------------------- |
| `create {name, description, content, triggers?, allowed_tools?}` | cria uma skill nova                          |
| `update {name, ...}`                                             | evolui uma skill existente (não duplica)     |
| `list`                                                           | lista as skills salvas                       |
| `show {name}`                                                    | imprime o conteúdo de uma skill              |
| `remove {name}`                                                  | apaga uma skill                              |
| `stats`                                                          | **analytics de uso** (quais skills se pagam) |
| `export {names?, out}`                                           | empacota skills num pack JSON compartilhável |
| `import {path}`                                                  | instala skills de um pack                    |

`name` é um slug kebab-case validado (sem path traversal). `create` não sobrescreve; `update` exige existir.

***

## Loop de evolução

```text theme={"system"}
agente aprende → @skill create/update → grava ~/.chatcli/skills/<nome>/SKILL.md
                                          │
                                          ▼
              loader descobre na próxima rodada → auto-ativa pelos triggers
```

A skill embutida **`skill-authoring`** orienta o agente sobre *quando* e *como* autorar (capturar workflow repetido, boas descrições/triggers, evoluir em vez de duplicar).

***

## Auto-evolução (self-evolution)

Antes, skills só nasciam quando o modelo lembrava de chamar `@skill` — então você precisava *pedir*. Agora elas se auto-criam e evoluem sozinhas, **pegando carona na mesma passada de extração de memória** (sem chamada extra de LLM): por turno o prompt carrega só um *index card* compacto das skills; quando a passada detecta um procedimento reutilizável novo, ela **autora** a skill, e quando uma melhoria aperfeiçoa uma skill existente, ela **reusa o nome exato** e puxa só o corpo daquela skill sob demanda para um **merge aditivo** (preserva o que já funciona).

Segurança e reversibilidade:

* Cada escrita do engine é rastreada por um manifest de hash (igual ao seed dos built-ins).
* Uma skill **sua** (escrita à mão) ou editada por você é **copiada para backup uma vez** antes da primeira modificação — `@skill restore <nome>` desfaz e volta à sua original.
* Falha de backup vira sugestão, nunca sobrescreve sem rede.

Controle por `CHATCLI_SELFEVOLVE_MODE`:

| Valor           | Comportamento                                                         |
| --------------- | --------------------------------------------------------------------- |
| `auto` (padrão) | Detecta e cria/evolui skills automaticamente (edit-safe, reversível). |
| `suggest`       | Detecta e **sugere** numa linha; nunca escreve em disco.              |
| `off`           | Desliga a detecção (a memória continua aprendendo normalmente).       |

Observabilidade em **`/config selfevolve`** (modo + quantas skills o engine criou vs. o total); analytics de ativação por skill em `@skill stats`.

***

## Analytics de uso

`@skill stats` mostra o ranking de ativações (mais usadas primeiro, com `last used`) e sinaliza skills autoradas que **nunca ativaram** — candidatas a evoluir ou remover. Os dados ficam em `~/.chatcli/skill-usage.json`, gravados de forma assíncrona pelo manager a cada ativação (`FindAutoActivatedSkills`), sem atrasar o turno.

***

## Packs compartilháveis

```text theme={"system"}
@skill export {names:["deploy-acme-api"], out:"team-pack.json"}   # empacota
@skill import {path:"team-pack.json"}                              # instala
```

O pack é um JSON que carrega cada `SKILL.md` cru (round-trip sem perdas). No import, skills existentes são **puladas** a menos que `overwrite:true`. Útil para levar skills entre máquinas e times.

***

## Segurança

* Nome validado por slug → sem escrita fora do diretório de skills.
* Nunca guarde segredos/tokens numa skill (isso é ambiente/credencial).
* O seeding das [skills embutidas](/pt/features/builtin-skills) **nunca** sobrescreve skills autoradas pelo agente.