Pular para o conteúdo principal

Skills

O AI Cockpit - Reasoning implementa Agent Skills, um formato aberto e leve para estender as capacidades de agentes de IA com conhecimento especializado e fluxos de trabalho.

O Que São Agent Skills?​

Agent Skills empacotam expertise de domínio, novas capacidades e fluxos de trabalho reutilizáveis que os agentes podem usar. Em sua essência, uma skill é uma pasta contendo um arquivo SKILL.md com metadados e instruções que dizem ao agente como executar uma tarefa específica.

Esta abordagem mantém os agentes rápidos enquanto lhes dá acesso a mais contexto sob demanda. Quando uma tarefa corresponde à descrição de uma skill, o agente lê as instruções completas no contexto e as segue—opcionalmente carregando arquivos referenciados ou executando código incluído conforme necessário.

Principais Benefícios​

  • Auto-documentado: Um autor ou usuário de skill pode ler um arquivo SKILL.md e entender o que ele faz, tornando as skills fáceis de auditar e melhorar
  • Interoperável: Skills funcionam em qualquer agente que implemente a especificação Agent Skills
  • Extensível: Skills podem variar em complexidade desde instruções de texto simples até scripts empacotados, templates e materiais de referência
  • Compartilhável: Skills são portáteis e podem ser facilmente compartilhadas entre projetos e desenvolvedores

Como as Skills Funcionam no AI Cockpit - Reasoning​

As skills podem ser:

  • Genéricas - Disponíveis em todos os modos
  • Específicas de modo - Carregadas apenas ao usar um modo específico (ex: code, architect)

O fluxo de trabalho é:

  1. Descoberta: Skills são escaneadas dos diretórios designados quando o AI Cockpit - Reasoning inicializa. Apenas os metadados (nome, descrição e caminho do arquivo) são lidos nesta etapa—não as instruções completas.
  2. Inclusão no prompt: Quando um modo está ativo, os metadados das skills relevantes são incluídos no prompt do sistema. O agente vê uma lista de skills disponíveis com suas descrições.
  3. Carregamento sob demanda: Quando o agente determina que uma tarefa corresponde à descrição de uma skill, ele lê o arquivo SKILL.md completo no contexto e segue as instruções.

Como o Agente Decide Usar uma Skill​

O agente (LLM) decide se deve usar uma skill com base no campo description da skill. Não há correspondência de palavras-chave ou busca semântica—o agente avalia sua solicitação contra todas as descrições de skills disponíveis e determina se uma "se aplica clara e inequivocamente."

Isso significa:

  • A redação da descrição importa: Escreva descrições que correspondam a como os usuários formulam solicitações
  • Invocação explícita sempre funciona: Dizer "use a skill api-design" irá acioná-la, já que o agente vê o nome da skill
  • Descrições vagas levam a correspondência incerta: Seja específico sobre quando a skill deve ser usada

Localizações de Skills​

Skills são carregadas de múltiplas localizações, permitindo tanto skills pessoais quanto instruções específicas de projeto.

Skills Globais (Nível de Usuário)​

Skills globais estão localizadas no diretório .aicockpitcode dentro do seu diretório Home.

  • Mac e Linux: ~/.aicockpitcode/skills/
  • Windows: \Users\<seuUsuario>\.aicockpitcode\
~/.aicockpitcode/
├── skills/                    # Skills genéricas (todos os modos)
│   ├── my-skill/
│   │   └── SKILL.md
│   └── another-skill/
│       └── SKILL.md
├── skills-code/              # Apenas modo Code
│   └── refactoring/
│       └── SKILL.md
└── skills-architect/         # Apenas modo Architect
    └── system-design/
        └── SKILL.md

Skills de Projeto (Nível de Workspace)​

Localizadas em .aicockpitcode/skills/ dentro do seu projeto:

seu-projeto/
└── .aicockpitcode/
    ├── skills/               # Skills genéricas para este projeto
    │   └── project-conventions/
    │       └── SKILL.md
    └── skills-code/          # Skills do modo Code para este projeto
        └── linting-rules/
            └── SKILL.md

Skills Específicas de Modo​

Para criar uma skill que aparece apenas em um modo específico:

# Apenas para o modo Code
mkdir -p ~/.aicockpitcode/skills-code/typescript-patterns

# Apenas para o modo Architect
mkdir -p ~/.aicockpitcode/skills-architect/microservices

O padrão de nomenclatura do diretório é skills-{mode-slug} onde {mode-slug} corresponde ao identificador do modo (ex: code, architect, ask, debug).

Prioridade e Sobrescritas​

Quando múltiplas skills compartilham o mesmo nome, o AI Cockpit - Reasoning usa estas regras de prioridade:

  1. Skills de projeto sobrescrevem skills globais - Uma skill de projeto com o mesmo nome tem precedência
  2. Skills específicas de modo sobrescrevem skills genéricas - Uma skill em skills-code/ sobrescreve a mesma skill em skills/ quando no modo Code

Isso permite que você:

  • Defina skills globais para uso pessoal
  • Sobrescreva-as por projeto quando necessário
  • Personalize o comportamento para modos específicos

Quando as Skills São Carregadas​

Skills são descobertas quando o AI Cockpit - Reasoning inicializa:

  • Quando o VSCode inicia
  • Quando você recarrega a janela do VSCode (Cmd+Shift+P → "Developer: Reload Window")

Os diretórios de skills são monitorados para mudanças em arquivos SKILL.md. No entanto, a maneira mais confiável de carregar novas skills é recarregar o VS Code ou a extensão AI Cockpit - Reasoning.

Adicionar ou modificar skills requer recarregar o VSCode para que as mudanças tenham efeito.

Você pode criar symlinks para diretórios de skills para compartilhar skills entre máquinas ou de um repositório central. Ao usar symlinks, o campo name da skill deve corresponder ao nome do symlink, não ao nome do diretório de destino.

Formato do SKILL.md​

O arquivo SKILL.md usa frontmatter YAML seguido de conteúdo Markdown contendo as instruções:

---
name: my-skill-name
description: Uma breve descrição do que esta skill faz e quando usá-la
---

# Instruções

Suas instruções detalhadas para o agente de IA vão aqui.

O agente lerá este conteúdo quando decidir usar a skill com base em
sua solicitação correspondendo à descrição acima.

## Exemplo de Uso

Você pode incluir exemplos, diretrizes, trechos de código, etc.

Campos do Frontmatter​

De acordo com a especificação Agent Skills:

CampoObrigatórioDescrição
nameSimMáx 64 caracteres. Apenas letras minúsculas, números e hífens. Não deve começar ou terminar com hífen.
descriptionSimMáx 1024 caracteres. Descreve o que a skill faz e quando usá-la.
licenseNãoNome da licença ou referência a um arquivo de licença incluído
compatibilityNãoRequisitos de ambiente (produto pretendido, pacotes do sistema, acesso à rede, etc.)
metadataNãoMapeamento chave-valor arbitrário para metadados adicionais

Exemplo com Campos Opcionais​

---
name: pdf-processing
description: Extrair texto e tabelas de arquivos PDF, preencher formulários, mesclar documentos.
license: Apache-2.0
metadata:
    author: example-org
    version: 1.0.0
---

## Como extrair texto

1. Use pdfplumber para extração de texto...

## Como preencher formulários

...

Regra de Correspondência de Nome​

No AI Cockpit - Reasoning, o campo name deve corresponder ao nome do diretório pai:

✅ Correto:
skills/
└── frontend-design/
    └── SKILL.md  # name: frontend-design

❌ Incorreto:
skills/
└── frontend-design/
    └── SKILL.md  # name: my-frontend-skill  (não corresponde!)

Recursos Empacotados Opcionais​

Embora SKILL.md seja o único arquivo obrigatório, você pode opcionalmente incluir diretórios adicionais para suportar sua skill:

my-skill/
├── SKILL.md           # Obrigatório: instruções + metadados
├── scripts/           # Opcional: código executável
├── references/        # Opcional: documentação
└── assets/            # Opcional: templates, recursos

Esses arquivos adicionais podem ser referenciados nas instruções da sua skill, permitindo que o agente leia documentação, execute scripts ou use templates conforme necessário.

Exemplo: Criando uma Skill​

  1. Crie o diretório da skill:

    mkdir -p ~/.aicockpitcode/skills/api-design

  2. Crie SKILL.md:

    ---
    name: api-design
    description: Melhores práticas e convenções de design de API REST
    ---

    # Diretrizes de Design de API

    Ao projetar APIs REST, siga estas convenções:

    ## Estrutura de URL

    - Use substantivos no plural para recursos: `/users`, `/orders`
    - Use kebab-case para recursos com múltiplas palavras: `/order-items`
    - Aninhe recursos relacionados: `/users/{id}/orders`

    ## Métodos HTTP

    - GET: Recuperar recursos
    - POST: Criar novos recursos
    - PUT: Substituir recurso inteiro
    - PATCH: Atualização parcial
    - DELETE: Remover recurso

    ## Códigos de Resposta

    - 200: Sucesso
    - 201: Criado
    - 400: Requisição Inválida
    - 404: Não Encontrado
    - 500: Erro do Servidor

  3. Recarregue o VSCode para carregar a skill

  4. A skill agora estará disponível em todos os modos

Encontrando Skills​

Você pode descobrir e instalar skills criadas pela comunidade através de:

  • Marketplace do AI Cockpit - Navegue pelas skills diretamente na extensão AI Cockpit - Reasoning através da aba Marketplace
  • Especificação Agent Skills - A especificação aberta que as skills seguem, permitindo interoperabilidade entre diferentes agentes de IA

Solução de Problemas​

Skill Não Está Carregando?​

  1. Verifique o painel Output: Abra View → Output → Selecione "AI Cockpit - Reasoning" no dropdown. Procure por erros relacionados a skills.

  2. Verifique o frontmatter: Certifique-se de que name corresponde exatamente ao nome do diretório e que description está presente.

  3. Recarregue o VSCode: Skills são carregadas na inicialização. Use Cmd+Shift+P → "Developer: Reload Window".

  4. Verifique a localização do arquivo: Certifique-se de que SKILL.md está diretamente dentro do diretório da skill, não aninhado mais profundamente.

Verificando se uma Skill Está Disponível​

Para confirmar que uma skill está devidamente carregada e disponível para o agente, você pode perguntar diretamente ao agente. Simplesmente envie uma mensagem como:

  • "Você tem acesso à skill X?"
  • "A skill chamada X está carregada?"
  • "Quais skills você tem disponíveis?"

O agente responderá com informações sobre se a skill está carregada e acessível. Esta é a maneira mais confiável de verificar se uma skill está disponível após adicioná-la ou recarregar o VSCode.

Se o agente confirmar que a skill está disponível, você está pronto para usá-la. Caso contrário, verifique as etapas de solução de problemas acima para identificar e resolver o problema.

Verificando se uma Skill Foi Usada​

Para ver se uma skill foi realmente usada durante uma conversa, procure por uma chamada da ferramenta read_file no chat que tenha como alvo um arquivo SKILL.md. Quando o agente decide usar uma skill, ele lê o arquivo completo da skill no contexto—isso aparece como uma operação de leitura de arquivo na conversa.

Atualmente não há um indicador dedicado na UI mostrando "Skill X foi ativada." A chamada read_file é a maneira mais confiável de confirmar que uma skill foi usada.

Erros Comuns​

ErroCausaSolução
"missing required 'name' field"Sem name no frontmatterAdicione name: nome-da-sua-skill
"name doesn't match directory"Incompatibilidade entre frontmatter e nome da pastaFaça o name corresponder exatamente
Skill não apareceEstrutura de diretório incorretaVerifique se o caminho segue skills/nome-da-skill/SKILL.md

Relacionado​