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.

Usando Symlinks

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:

Campo	Obrigatório	Descrição
name	Sim	Máx 64 caracteres. Apenas letras minúsculas, números e hífens. Não deve começar ou terminar com hífen.
description	Sim	Máx 1024 caracteres. Descreve o que a skill faz e quando usá-la.
license	Não	Nome da licença ou referência a um arquivo de licença incluído
compatibility	Não	Requisitos de ambiente (produto pretendido, pacotes do sistema, acesso à rede, etc.)
metadata	Não	Mapeamento 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

Erro	Causa	Solução
"missing required 'name' field"	Sem name no frontmatter	Adicione name: nome-da-sua-skill
"name doesn't match directory"	Incompatibilidade entre frontmatter e nome da pasta	Faça o name corresponder exatamente
Skill não aparece	Estrutura de diretório incorreta	Verifique se o caminho segue skills/nome-da-skill/SKILL.md

Relacionado

• Modos Personalizados - Crie modos personalizados que podem usar skills específicas
• Instruções Personalizadas - Instruções globais vs. instruções baseadas em skills
• Regras Personalizadas - Regras de nível de projeto complementando skills