Construa uma Pilha de Habilidades de Agente

Construa a menor pilha útil para o resultado real do usuário. Nunca force um exemplo de domínio ou um ciclo de vida fixo em uma solicitação diferente.

1. Escolha a profundidade voltada para o usuário

Use o modo de linguagem clara por padrão. Presuma que o usuário não precisa entender caminhos, revisões, hashes, manifestos, análise estática ou detalhes de tempo de execução.

No modo de linguagem clara, mostre:

• o que o usuário está tentando realizar;
• os passos em linguagem cotidiana;
• quais capacidades já estão disponíveis;
• quais Habilidades são recomendadas, opcionais, sobrepostas ou inadequadas;
• quão amplamente cada candidato é usado;
• se passou em uma verificação de segurança de instalação e em um teste seguro;
• qual acesso à conta ou ações externas podem ser necessários.

Mantenha caminhos de origem, revisões, impressões digitais de arquivos, pontuações brutas, evidências de auditoria e detalhes de dependência no registro interno. Mostre-os apenas quando o usuário solicitar detalhes técnicos ou quando um fato técnico específico for necessário para consentimento informado.

2. Derive o fluxo de trabalho dinamicamente

Leia references/workflow-model.md. Comece com o resultado final que o usuário deseja, não com as palavras do domínio na solicitação.

Faça apenas perguntas cujas respostas mudem materialmente o resultado, o limite de acesso, o custo ou a pilha. Derive o fluxo de trabalho de trás para frente a partir do sucesso, e então valide-o de frente para trás a partir do ponto de partida disponível.

Não reutilize um fluxo numerado anterior. Não presuma que toda solicitação precisa de pesquisa, criação de conteúdo, publicação, análise, armazenamento ou automação. Adicione um passo apenas quando o resultado do usuário o exigir.

Pare de decompor quando um passo tiver uma ação compreensível, um resultado principal, um limite de acesso e uma condição de sucesso observável. Mantenha as cartas de capacidade técnica internas; mostre ao usuário um fluxo curto em linguagem clara.

3. Pesquise primeiro no índice local

Leia references/local-index-and-profiles.md.

Se um índice de Habilidades local atual existir, pesquise-o antes do sistema de arquivos ou da internet. Se estiver ausente ou desatualizado, reconstrua-o a partir das raízes de Habilidade relevantes:

python3 scripts/skill_index.py build \
  --root ~/.codex/skills \
  --root ~/.codex/plugins/cache \
  --root .codex/skills \
  --root ~/.agents/skills \
  --root ~/.hermes/skills \
  --output ~/.codex/skill-index.json

O índice armazena nomes, resumos, aliases, escopo, termos de capacidade, hora de atualização e impressões digitais de arquivos internos. Ele nunca executa uma Habilidade e não armazena histórico de uso.

Se o projeto atual tiver .codex/skill-stack.json, trate suas Habilidades ativas e regras de roteamento como a pilha de primeira escolha. Pesquise fora do perfil apenas para uma capacidade não coberta ou quando o usuário solicitar alternativas. Trate entradas com o mesmo nome de diferentes raízes locais como um item de revisão; não as mescle silenciosamente.

4. Mapeie capacidades, incluindo auxiliares indiretos

Para cada passo necessário, registre internamente:

• entrada, ação e saída necessárias;
• restrições, frequência e escala;
• limite de acesso local/externo de leitura/externo de escrita;
• necessidades de conta, permissão e aprovação;
• condição de sucesso e fallback;
• passos predecessores e sucessores.

Em seguida, considere necessidades transversais apenas onde relevante: qualidade/estilo, precisão, conformidade, privacidade, localização, qualidade de dados, orquestração e observabilidade.

Combine Habilidades por input -> operation -> output, não por similaridade de título. Isso permite que um Humanizador combine um requisito de escrita natural mesmo quando o domínio do usuário nunca aparece em seu nome.

Não force uma Habilidade por passo. Uma Habilidade pode cobrir vários passos; um passo pode precisar de uma ferramenta, MCP, conector ou capacidade de agente geral em vez de outra Habilidade.

5. Pesquise com quatro lentes

Leia references/discovery-ranking.md. Pesquise cada capacidade não coberta através de:

1. Necessidade direta: o domínio e a ação do usuário.
2. Operação subjacente: a transformação ou tarefa de dados real.
3. Resultado de suporte: qualidade, segurança, estilo, conformidade, avaliação e monitoramento.
4. Método de conexão: CLI, MCP, API, conector, automação de navegador, armazenamento e entrega.

Expanda aliases, verbos, substantivos, saídas e terminologia adjacente em chinês/inglês. Pesquise títulos, descrições, cabeçalhos e o conteúdo completo de SKILL.md quando possível.

Use várias fontes porque nenhum registro está completo:

• o índice local de Habilidades e o inventário instalado;
• conector GitHub ou pesquisa de arquivos/repositório GitHub;
• npx skills find <query> e skills.sh;

…