Agent Skills

Agent Skills são um mecanismo leve para estender as capacidades do modelo no Jarvis Code CLI. Uma skill é um documento Markdown com frontmatter YAML que descreve uma área de conhecimento especializada ou um fluxo de trabalho — por exemplo, as diretrizes de estilo de código de um projeto, um processo de revisão de PR ou um formato de mensagem de commit.

Comparadas a colar as mesmas instruções em um prompt toda vez, as skills têm a vantagem de manter o conteúdo em um arquivo, permitindo reúso entre projetos e times, carregamento imediato por um comando de barra e invocação automática pelo modelo quando necessário.

Criar uma skill

Arquivos de skill precisam ficar em um diretório de varredura conhecido. Duas estruturas de arquivo são suportadas:

• Forma de diretório (recomendada): crie um subdiretório dentro do diretório de skills, nomeie o arquivo principal como SKILL.md e coloque scripts, materiais de referência e outros arquivos de apoio no mesmo diretório. Quando existirem <name>/SKILL.md e um <name>.md de mesmo nome no mesmo diretório, o subdiretório tem precedência.
• Forma plana: use um único arquivo .md; o nome da skill vem do nome do arquivo (sem .md).

Formato do arquivo

O SKILL.md tem duas partes: o frontmatter YAML e o corpo em Markdown:

---
name: code-style
description: Diretrizes de estilo de código do projeto, definindo nomes, indentação, comentários e organização de arquivos
type: prompt
whenToUse: Quando o usuário me pedir para escrever, modificar ou revisar código-fonte do projeto
disableModelInvocation: false
arguments:
  - target
  - mode
---

Trate o código conforme as diretrizes a seguir:

- Use indentação de 2 espaços
- Nomes de variáveis em `camelCase`, nomes de tipo em `PascalCase`
- Funções públicas devem ter comentários TSDoc
- Linhas não podem passar de 100 caracteres

Campos do frontmatter

Campo	Descrição
name	Nome da skill. Obrigatório em um SKILL.md na forma de diretório; quando omitido em um arquivo .md plano, o nome do arquivo é usado. Nomes não diferenciam maiúsculas de minúsculas
description	Um resumo de uma linha; o modelo o usa para decidir quando usar a skill. Obrigatório em um SKILL.md na forma de diretório; quando omitido em um arquivo .md plano, recorre à primeira linha não vazia do corpo (até 240 caracteres)
type	Tipo da skill: prompt (padrão), inline (mesma semântica de prompt), flow (apenas invocação manual; não fica disponível para invocação automática pelo modelo). Outros valores são ignorados
whenToUse	Descrição de quando a skill deve ser acionada. Também aceita when-to-use e when_to_use
disableModelInvocation	Quando true, impede o modelo de invocar esta skill automaticamente. Também aceita disable-model-invocation e disable_model_invocation
arguments	Lista de parâmetros nomeados; pode ser escrita como array de strings ou como string separada por espaços (por exemplo, arguments: target mode). Uma vez declarados, os parâmetros podem ser lidos no corpo com $<name>

Nota

Em um SKILL.md na forma de diretório, name e description precisam ser informados explicitamente. Omitir qualquer um deles faz a análise falhar.

Marcadores no corpo

Antes de o corpo ser enviado ao modelo, um pequeno conjunto de marcadores é expandido:

• $ARGUMENTS: a string bruta completa de argumentos passada na invocação
• $ARGUMENTS[0], $ARGUMENTS[1] e as formas curtas $0, $1: argumentos posicionais após a tokenização por espaços (índice a partir de zero)
• $<name>: parâmetros nomeados declarados em arguments
• ${JARVIS_SKILL_DIR}: o diretório que contém o arquivo de skill atual

Argumentos posicionais aceitam aspas simples e duplas, então em /skill:commit "fix login" patch o $0 expande para fix login. Se o corpo não contém marcadores de argumento, o texto passado na invocação é acrescentado ao final do corpo como \n\nARGUMENTS: <text>.

Locais de skill

O Jarvis Code CLI varre quatro camadas por escopo; escopos mais específicos têm prioridade maior: Projeto > Usuário > Extra > Embutido

Nível de usuário (vale para todos os projetos):

• $JARVIS_CODE_HOME/skills/ (padrão: ~/.jarvis-code/skills/)
• ~/.agents/skills/

O diretório de skills de usuário específico do Jarvis Code acompanha JARVIS_CODE_HOME, então raízes de dados isoladas também têm skills específicas isoladas. O diretório genérico ~/.agents/skills/ permanece no home real do sistema operacional, para ser compartilhado entre ferramentas.

Nível de projeto (raiz do projeto = o diretório mais próximo que contém .git, subindo a partir do diretório de trabalho):

• .jarvis-code/skills/
• .agents/skills/

Diretórios extras: declarados por extra_skill_dirs no nível superior do config.toml:

extra_skill_dirs = ["~/team-skills", ".agents/team-skills"]

Skills embutidas são distribuídas com o CLI e têm a prioridade mais baixa. Elas oferecem fluxos prontos para tarefas comuns — por exemplo, configurar servidores MCP, personalizar o tema da TUI e editar arquivos de configuração. Veja Comandos de skills embutidas para a lista completa. As que descrevem o próprio Jarvis Code podem ser desligadas pelo campo de nível superior builtin_product_skills.

Invocar uma skill

Você pode invocar uma skill manualmente com um comando de barra:

/skill:code-style
/skill:git-commits corrige problema de concorrência no endpoint de login

O modelo também pode invocar uma skill automaticamente com base em description e whenToUse (a menos que disableModelInvocation seja true ou type seja flow). Invocações de skill aceitam até 3 níveis de aninhamento; além disso, são encerradas.

Exemplo completo

---
name: review-pr
description: Revisa um Pull Request segundo os padrões do time e produz um relatório estruturado de revisão
type: prompt
whenToUse: Quando o usuário me pedir para revisar um PR, inspecionar alterações de código ou avaliar a qualidade de um commit
arguments:
  - pr_ref
---

Revise o PR que o usuário especificou: $pr_ref

1. Busque e leia o diff completo de `$pr_ref`.
2. Verifique cada um dos itens a seguir:
   - Se há casos de teste correspondentes
   - Se a documentação de API pública foi atualizada
   - Se novas dependências foram introduzidas; em caso positivo, informe o motivo
   - Se o tratamento de erros cobre os casos de borda
3. Consulte o checklist no mesmo diretório: `references/checklist.md`
4. Produza um relatório de revisão contendo:
   - Conclusão geral (aprovar / solicitar mudanças / comentar)
   - Mudanças obrigatórias (bloqueantes)
   - Melhorias sugeridas (não bloqueantes)
   - Pontos positivos dignos de nota

Salve isso em $JARVIS_CODE_HOME/skills/review-pr/SKILL.md (ou ~/.jarvis-code/skills/review-pr/SKILL.md quando JARVIS_CODE_HOME não estiver definido), coloque o checklist em references/checklist.md no mesmo diretório e, depois de iniciar uma nova sessão, invoque com /skill:review-pr #1234, onde #1234 é expandido em $pr_ref.

Próximos passos

• Plugins — empacote skills em unidades instaláveis para compartilhar com seu time
• Agentes e subagentes — como as skills influenciam o comportamento dos subagentes