🧩 Capabilities: Sabe fazer o trabalho
Uma frase dispara um artefato. Capabilities é a camada que transforma intenção em execução: skills determinísticas, skills IA-assistidas e sub-agents — cada um no lugar certo.
Conteúdo detalhado
O teste do Capabilities
Um AIOS passou no teste de Capabilities quando você digita uma frase curta — /audit, /level-up, /onboard — e um workflow multi-passo executa sozinho, produzindo um artefato concreto: relatório, plano, código, rascunho. Nenhuma instrução adicional. Nenhuma microgestão.
🎯 Definição operacional
Capabilities = skills + agents registrados e prontos. Não é o que o Claude poderia fazer — é o que ele sabe fazer sem pedir ajuda. A diferença está na existência de um SKILL.md (ou agent file) com instruções explícitas de quando e como executar.
Skills vs Agents
São dois tipos de capability com propósitos distintos. Entender a diferença evita supercomplexidade: a maioria dos casos não precisa de agent — uma skill bem escrita resolve em segundos, com custo zero de modelo.
✓ Skills (.claude/skills/)
- ✓Arquivo SKILL.md com frontmatter + instruções
- ✓Roda na sessão principal (contexto compartilhado)
- ✓Ideal para tarefas sequenciais e determinísticas
- ✓Pode ser 0-chamadas LLM (script puro)
- ✓Custo baixo, latência mínima
⚠ Agents (.claude/agents/)
- →Sub-assistente com modelo próprio (geralmente mais barato)
- →Contexto isolado — não polui a sessão principal
- →Ideal para trabalho iterativo com ferramentas
- →Sempre envolve chamadas LLM (custo maior)
- →Último recurso: use skill primeiro
💡 Regra de ouro
Se a tarefa tem passos fixos e previsíveis → skill. Se precisa de raciocínio iterativo com ferramentas (ler arquivo, executar comando, ler resultado, decidir próximo passo) → agent. Na dúvida: comece com skill e evolua só se necessário.
As 3 skills que vêm no kit
O kit AIS-OS vem com três skills de propósito enxuto — cada uma resolve um problema real do ciclo de trabalho com IA. São ponto de partida, não teto: você constrói por cima.
Inicializa o AIOS num projeto novo: cria a estrutura de pastas, gera o CLAUDE.md com contexto do projeto, configura as permissões básicas. Roda uma vez — depois fica pronto.
Audita o estado atual do AIOS: verifica Context, Connections, Capabilities e Cadence. Produz um relatório com lacunas e próximos passos priorizados. Rode toda vez que o sistema travar.
O motor de crescimento. Cada run identifica 1 tarefa manual repetitiva e a transforma em artefato (skill, agent, script). Todo artefato nasce com bike-method-phase: 1 para rastrear maturidade.
Anatomia de um SKILL.md
Toda skill é um arquivo Markdown com frontmatter YAML no topo e corpo com instruções de execução. O Claude lê o frontmatter para saber quando disparar e o corpo para saber como executar.
---
name: minha-skill
description: |
Quando disparar: descreva o gatilho em linguagem
natural. O Claude usa isso para decidir se invoca
esta skill. Seja específico — evite sobreposição
com outras skills.
---
# Execução
Passo 1: Leia o contexto atual em CLAUDE.md
Passo 2: Execute [ação específica]
Passo 3: Produza o artefato em [formato/path]
Passo 4: Confirme ao usuário com resumo do feito💡 Dica: description é o cérebro da skill
O campo description é o que o Claude lê para decidir se uma skill é relevante para a mensagem atual. Quanto mais claro o gatilho, menor a chance de confusão com outras skills. Use exemplos de frases que disparam: "Use quando o usuário pedir /onboard ou setup inicial do projeto."
Determinístico vs IA-assistido
Nem toda skill precisa de IA. O princípio Boring-is-Beautiful diz: use a solução mais simples que resolve. Suba a escada de complexidade só quando o degrau abaixo não for suficiente.
⚙️ Skill Determinística
- ✓Script bash/python — zero chamadas LLM
- ✓Resultado 100% previsível e reproduzível
- ✓Custo zero, latência mínima (<1s)
- ✓Ótimo para: formatar, mover arquivos, gerar boilerplate
- ✓Fácil de testar e debugar
🤖 Skill IA-assistida
- →Instrução para o Claude + 1 chamada LLM
- →Resultado adaptado ao contexto atual
- →Custo de 1 chamada, latência de segundos
- →Ótimo para: redigir, resumir, analisar, classificar
- →Quando o script sozinho não consegue raciocinar
🪜 Escada Boring-is-Beautiful
Construir capabilities via /level-up
O motor de crescimento do AIOS é o /level-up. A lógica é simples: 1 run = 1 artefato novo. Com o tempo, cada artefato reduz fricção e aumenta velocidade.
💡 Como construir uma skill nova
Dois caminhos: (1) use a skill-creator do Anthropic — descreva o que você quer e ela gera o SKILL.md; (2) escreva à mão seguindo a anatomia do tópico anterior. A segunda opção é mais rápida quando você já sabe o que quer.
🚲 bike-method-phase
Todo artefato criado pelo /level-up nasce com o frontmatter bike-method-phase: 1. Isso sinaliza que está na fase de bicicleta — funciona, mas ainda precisa de atenção manual. Conforme amadurece, a fase sobe.
Sub-agents (.claude/agents/)
Quando a tarefa exige raciocínio iterativo com ferramentas — ler arquivo, executar comando, interpretar resultado, decidir próximo passo, repetir — um sub-agent é a ferramenta certa. A vantagem chave: roda em contexto próprio, sem poluir a sessão principal.
🤖 Por que contexto isolado importa
Cada sub-agent tem sua própria janela de contexto. Isso significa que operações longas (auditar 50 arquivos, iterar sobre uma lista de tarefas) não consomem o contexto da sessão principal. O operador continua livre para conversar e dirigir enquanto o agent trabalha.
Use skill quando:
- ✓Passos são fixos e conhecidos antes de executar
- ✓Não precisa raciocinar sobre o resultado intermediário
- ✓Tarefa é curta (minutos, não horas)
- ✓Contexto compartilhado é desejável
Use agent quando:
- →Precisa de loop: ler → executar → decidir → repetir
- →Tarefa é longa e consumiria o contexto principal
- →Modelo mais barato é suficiente para a sub-tarefa
- →Paralelismo: múltiplos agents simultâneos
💡 Agent file: mesma estrutura, localização diferente
Um agent file segue a mesma anatomia do SKILL.md (frontmatter name + description + corpo), mas fica em .claude/agents/. O Claude sabe que deve rodá-lo como sub-assistente com contexto isolado, não como instrução inline.
🧩 Resumo do Módulo
Próximo Módulo:
2.4 — Cadence: Roda sem ser pedido ⏰
A última camada dos 4 Cs: automações que disparam sozinhas, sem você precisar pedir.