Esta página é uma tradução da documentação em inglês. Comandos, identificadores e exemplos permanecem iguais. Runtime 7.24.4 · SDK 2.6.7. Original em inglês

Catálogo de habilidades e plugins

Status: Ativo Escopo: público, estado atual Última revisão: 2026-08-12 Responsável: runtime do AX Code

Registro descobrível de habilidades internas e de como acrescentar habilidades de projeto.

O menu padrão / é um plano de controle (/plan, /review, /debug, /status, /model). Habilidades internas mais antigas permanecem somente para o agente (ferramenta de habilidade). O pacote de confiabilidade do backend também aparece como comandos de barra.

Habilidades internas (entregues em `packages/ax-code/skills/`)

Habilidade	Finalidade	Barra
`debug-n-fix`	Depurar e depois corrigir com verificação	Use `/debug`
`debug-only`	Investigação sem mudanças de código	Somente agente
`improve-overall`	Melhorias amplas de qualidade	Somente agente
`improve-security`	Melhorias com foco em segurança	Somente agente
`mcp`	Orientação de configuração do MCP	Use `/mcp`
`run`	Iniciar e observar o aplicativo	Somente agente
`simplify`	Tornar mais estrito o código alterado há pouco	Somente agente
`verify`	Relatório de verificação de runtime	Somente agente
`verified-change`	Editar apenas depois de um sinal de falha e, em seguida, executar de novo a mesma verificação	`/verified-change`
`safe-db-migration`	Mudanças de esquema de expansão, preenchimento retroativo e contração, com notas de reversão	`/safe-db-migration`
`api-contract`	Evolução de API pública e de esquema, com prioridade ao que é aditivo	`/api-contract`
`incident-observability`	Diagnóstico de incidente com evidência primeiro, antes de um patch	`/incident-observability`
`auth-boundaries`	Autenticação e autorização, isolamento de tenant, testes negativos	`/auth-boundaries`
`queue-worker`	Mudanças idempotentes de fila e de worker, e entrega duplicada	`/queue-worker`
`ruby-on-rails`	Convenções Rails sem iniciar o processo Rails	Somente agente

As habilidades usam SKILL.md com frontmatter YAML (name, description, opcionais paths e allowed-tools).

Habilidades de projeto

Coloque habilidades em qualquer um destes caminhos:

.ax-code/skill/<name>/SKILL.md ou .ax-code/skills/<name>/SKILL.md
.agents/skills/<name>/SKILL.md (compatível com Agents / Codex)
.claude/skills/<name>/SKILL.md (compatível com Claude Code)
.opencode/skills/<name>/SKILL.md

Liste e valide:

ax-code            # TUI skill dialog
# or use the skill tool from a session

Controles de invocação

O AX Code lê estes controles opcionais ao descobrir uma habilidade:

Local	Campo	Efeito
frontmatter de `SKILL.md`	`disable-model-invocation: true`	Mantém o comando explícito `/skill-name`, mas exclui a habilidade da descoberta pelo modelo e de cargas diretas da ferramenta do modelo.
frontmatter de `SKILL.md`	`user-invocable: false`	Omite a habilidade dos comandos de barra; a invocação pelo modelo permanece disponível, salvo desativação separada.
`agents/openai.yaml` irmão	`policy.allow_implicit_invocation: false`	Exige invocação explícita por barra, inclusive para habilidades importadas por `.agents/skills`.

Use booleanos YAML true e false. Controles ausentes preservam os padrões. Se várias fontes discordam, vence a declaração mais restritiva. Tipos de controle inválidos ou uma política de sidecar malformada desativam os dois modos de invocação e produzem diagnósticos de invocação no inventário de habilidades e nos logs de runtime. Corrija os metadados antes de usar a habilidade. O sidecar opcional precisa ter menos de 64 KiB; delimitadores de documento YAML e aliases não são aceitos ali.

Estes controles regem a invocação da habilidade, de forma independente das permissões existentes do agente. Uma menção em linguagem natural a uma habilidade somente manual não autoriza o modelo a carregá-la; invoque o comando de barra dela. allowed-tools declarados permanecem instruções de fluxo de trabalho e não concedem permissões.

Descoberta limitada

O modelo recebe de início resumos de habilidades, não as instruções completas. Cada bloco de metadados de habilidade no prompt de sistema e na descrição da ferramenta tem um orçamento de 8.000 caracteres. As descrições são encurtadas antes de as entradas serem omitidas; recomendações correspondentes a arquivos têm prioridade quando a lista ainda excede esse orçamento. Um aviso de omissão explica como obter mais resumos. Isto é um limite de caracteres, não uma contagem de tokens nem uma garantia de desempenho.

A ferramenta skill tem dois modos mutuamente exclusivos:

{"name":"api-contract"} carrega uma habilidade pela verificação de permissão existente.
{"query":"database"} busca nomes e descrições elegíveis sem carregar os corpos das habilidades.
{"query":"","offset":20} continua uma listagem usando o nextOffset exato do resultado anterior.

A busca é literal e sem distinção de maiúsculas. Consultas vazias listam as habilidades elegíveis. Siga nextOffset até ele estar ausente. Habilidades somente manuais e habilidades com permissão negada ficam fora da descoberta pelo modelo. Entradas individuais de metadados grandes demais são puladas com um aviso. Nomes e precedência de origem permanecem sem alteração.

Plugins

Configure plugins em ax-code.json:

{
  "plugin": ["file:///absolute/path/to/plugin.js"]
}

Os plugins implementam hooks @ax-code/plugin (tool.execute.before, tool.execute.after, shell.env, autenticação etc.).

Vida do callback

As fábricas de plugin recebem lifecycle opcional na entrada. lifecycle.signal aborta quando a instância é descartada ou o plugin é aposentado. Registre temporizadores, observadores e assinaturas com lifecycle.onDispose(cleanup). A função devolvida cancela esse registro de limpeza. Os registros rodam no máximo uma vez; registrar depois do descarte inicia a limpeza na hora. Os callbacks de limpeza começam na ordem inversa de registro, cada um com um orçamento de um segundo, e podem terminar de forma concorrente.

Hooks de transformação recebem um terceiro argumento opcional, { signal }; hooks de configuração e de evento o recebem como segundo argumento. Este sinal cancela o trabalho enquanto o callback está pendente; use lifecycle.signal para trabalho de que o plugin é dono além de um callback. Passe sinais a operações que podem ser abortadas. Callbacks de inicialização, configuração, evento e transformação têm um prazo de 15 segundos. Um tempo esgotado aposenta o plugin para aquela instância e aborta a vida dele. Fábricas existentes e hooks de transformação de dois argumentos continuam a funcionar. A execução de ferramenta personalizada e a autenticação interativa mantêm os contratos de execução existentes.

As entradas de transformação são observações somente leitura de dados simples. Altere o rascunho de saída e aguarde todas as mudanças antes de retornar. Mutações de saída bem-sucedidas ficam visíveis na ordem de registro; mudanças com falha ou tardias são descartadas. Mudanças de carga de evento nunca são publicadas. Uma negação de permissão permanece uma negação, e hooks de permissão com falha ou aposentados exigem perguntar, salvo se uma negação já existir.

Arrays e objetos simples são destacados do estado do runtime. Esquemas, funções e instâncias de classe mantêm a identidade e devem ser tratados como somente leitura. Os plugins permanecem JavaScript confiável em execução no processo do runtime: o cancelamento é cooperativo e não consegue parar laços infinitos síncronos nem desfazer efeitos externos.

Pacotes de hooks

Veja Hooks de ciclo de vida para os cinco pacotes oficiais de ciclo de vida (format-after-edit, block-force-push, require-tests-on-stop, protect-env-files, log-bash-commands).

Harness de avaliação

Execute a suíte de gates do runtime agêntico e a suíte de política de conjunto multimodo:

cd packages/ax-code
pnpm exec vitest run test/harness/agentic-runtime-eval.test.ts
pnpm exec vitest run test/harness/multi-mode-ensemble-eval.test.ts

Veja também Modos de execução para local, nuvem, híbrido, council e arena.