Skills

Crie skills com instruções reutilizáveis que você ou seus agentes podem carregar quando necessário.

Crie uma skill no workspace

Crie um diretório em .clarvis/skills com um arquivo SKILL.md:

.clarvis/skills/release-notes/
├── SKILL.md
├── references/
│   └── style-guide.md
└── examples/
    └── release.md

Use frontmatter YAML para a descoberta e Markdown para as instruções:

---
name: release-notes
description: Elabore notas de versão concisas a partir de um intervalo de commits do Git.
argument-hint: "<from>..<to>"
user-invocable: true
allowed-tools:
  - shell
  - grep
  - read_file
---

Elabore notas de versão para `$ARGUMENTS`.

1. Leia `references/style-guide.md` antes de escrever.
2. Agrupe as mudanças visíveis para o usuário por resultado.
3. Omita refatorações internas, a menos que alterem o comportamento.
4. Siga o tom e a estrutura de `examples/release.md`.

Execute a skill pelo campo de entrada:

/release-notes v0.0.0..HEAD

Todo espaço reservado $ARGUMENTS ou é substituído pelo texto após o comando com barra. Se o corpo não tiver nenhum espaço reservado, o Clarvis anexará a tarefa em uma seção Target.

Na etapa 3 de /extensions, você escolhe as skills independentes que quer incluir. Cada uma mostra seu escopo e origem (user|workspace / agents|clarvis), para distinguir instalações com o mesmo nome. Pressione Enter para adicionar ou remover a skill do rascunho.

Skills fornecidas por um plugin são selecionadas junto com ele, não individualmente. A etapa 4 mostra esses dois grupos separadamente antes da ativação.

Etapa 3 do Extension Profile. Selecione uma origem exata de skill independente ou o plugin completo que contém uma skill empacotada.

Etapa 4 do Extension Profile. Skills empacotadas permanecem visíveis na revisão atômica de capacidades do plugin.

Escolha onde uma skill fica

builtin:default lê skills destes locais, da menor para a maior precedência:

1. ~/.agents/skills
2. <workspace>/.agents/skills
3. ~/.clarvis/skills
4. <workspace>/.clarvis/skills

A skill de maior precedência vence quando há nomes iguais. O Clarvis lê .agents/skills para interoperabilidade com o ecossistema, mas grava seu próprio conteúdo em .clarvis.

Um Extension Profile personalizado lista o escopo, a origem e o nome exatos de cada skill independente a ativar; raízes sem uma dessas referências permanecem inativas. Um plugin selecionado fornece todas as suas skills como parte da contribuição atômica do plugin. Skills de plugins ficam abaixo das diretórios de skills independentes selecionadas, preservam o nome definido por seus autores e, por isso, podem ser substituídas deliberadamente por uma skill independente.

Controle a invocação e as ferramentas

• user-invocable: true é o padrão e disponibiliza /<name> na conclusão de comandos com barra.
• user-invocable: false oculta o comando com barra, mas não remove a skill do carregamento progressivo conduzido por agentes.
• allowed-tools é um metadado de compatibilidade. O Clarvis o preserva e valida, mas atualmente não o usa para alterar permissões em tempo de execução. O agente selecionado determina as ferramentas efetivas.
• agent: reviewer executa uma skill invocada por comando com barra como uma execução própria desse agente. Sem agent, a skill é inserida no turno atual. Agentes de plugins usam a forma qualificada agent: quality-kit:reviewer.

allowed-tools também aceita uma string separada por vírgulas, e tools é um alias aceito. Prefira o formato de lista acima, pois ele é mais fácil de revisar.

Skills dentro de um pacote portátil Agent Plugins v1 seguem a forma Agent Skills mais estrita: allowed-tools é uma única string separada por espaços, o nome precisa coincidir com o diretório e usar o formato portátil em minúsculas com hífens, e metadados portáteis opcionais inválidos removem somente essa skill. Skills independentes e nativas do Clarvis mantêm as formas tolerantes descritas acima.

Adicione metadados do host e uma dependência MCP

O primeiro arquivo .yaml ou .yml dentro do diretório agents/ de uma skill é metadado do host, não um recurso legível pelo modelo. Ele pode adicionar apresentação, ocultar a skill do catálogo implícito e declarar dependências MCP:

display-name: Pesquisa de documentação
short-description: Pesquise o serviço de documentação conectado.
dependencies:
  tools:
    - type: mcp
      value: docs
      description: Pesquisa de documentação
      transport: http
      url: https://docs.example.com/mcp

Se o servidor docs, ou o servidor qualificado pelo plugin nesse arquivo de metadados, não estiver disponível na execução, a skill não aparece para o modelo. Declarar a dependência não instala, conecta nem concede acesso ao servidor. Tipos de dependência sem suporte são preservados como metadados, mas não têm efeito.

Empacote recursos e helpers com segurança

Um recurso de skill pode ter no máximo 8 MiB, e um snapshot de plugin admite até 32 MiB de recursos de skills. Leituras para o modelo são paginadas em 256 KiB e 50.000 caracteres decodificados, com um cursor exato em bytes para continuar textos grandes sem reter o arquivo inteiro em memória. Assets binários participam do fingerprint imutável do Extension Profile, mas não são decodificados em um prompt.

Skills empacotadas selecionadas podem expor seu diretório exato como raiz de execução de helpers. Isso não executa nada automaticamente: o agente precisa chamar shell ou monitor_start, a revisão de comandos continua valendo e um sandbox nativo monta a raiz do pacote como somente leitura. Sem um sandbox nativo, o comando é um processo comum do host com segredos filtrados; admissão de caminho sozinha não torna helpers de terceiros imutáveis.

Mantenha o primeiro carregamento pequeno

O Clarvis descobre os nomes e as descrições das skills sem carregar antecipadamente todos os corpos. Coloque material detalhado em references, auxiliares executáveis em scripts, entradas reutilizáveis em assets e exemplos em examples. Um agente pode carregar esses recursos somente depois de escolher a skill.

Skills são instruções, não um sandbox

Uma skill pode orientar um agente a usar as ferramentas do agente selecionado. Revise as instruções e os scripts incluídos antes de adicionar uma skill de terceiros. Não trate allowed-tools como um limite de imposição de permissões.

Veja também

• Extension Profiles
• Plugins
• Hooks
• Referência de extensões
• Servidores MCP