shane9coy/Agent-Skill-Architecture-Guide

O que Agent-Skill-Architecture-Guide faz?

Um guia de referência abrangente para construir e organizar skills de agentes de IA em Claude Code, KiloCode, OpenClaw e OpenAI Codex. Abrange especificações SKILL.md, estruturas de pastas, skills com escopo de modo, orquestração de agentes e configuração de modelos auto-hospedados.

Índice

• Visão Geral
• Estrutura de Pastas
• Especificação SKILL.md
• Skills com Escopo de Modo
• Orquestração de Agentes
• Configuração de Modelos Auto-Hospedados
• Exemplos

Visão Geral

Este guia foi projetado para desenvolvedores que criam agents de IA modulares e reutilizáveis. Ele padroniza a criação de skills, garantindo que funcionem perfeitamente em diferentes plataformas e mantenham alta qualidade.

Estrutura de Pastas

A estrutura de pastas recomendada para um skill de agente é:

meu-skill/
├── SKILL.md
├── src/
│   ├── comandos/
│   │   └── exemplo.js
│   └── utils/
│       └── helpers.js
├── config/
│   └── default.json
├── testes/
│   └── test_exemplo.py
└── README.md

• SKILL.md: Metadados e instruções principais do skill.
• src/: Código-fonte do skill.
• config/: Arquivos de configuração.
• testes/: Testes unitários e de integração.
• README.md: Documentação adicional.

Especificação SKILL.md

O arquivo SKILL.md usa frontmatter YAML para metadados. Exemplo:

---
nome: meu-skill-exemplo
descrição: Um skill de exemplo para demonstração.
versão: 1.0.0
plataformas:
  - claude-code
  - kilocode
  - openclaw
  - openai-codex
dependências:
  - requests>=2.25.0
comandos:
  - comando: executar
    descrição: Executa a tarefa principal.
---

Campos Obrigatórios

• nome: Nome único do skill.
• descrição: Breve descrição do propósito.
• versão: Número de versão semântica.
• plataformas: Lista de plataformas suportadas.

Campos Opcionais

• dependências: Pacotes ou bibliotecas necessários.
• comandos: Lista de comandos expostos pelo skill.

Skills com Escopo de Modo

Skills com escopo de modo permitem ativar comportamentos específicos apenas em determinados modos do agente (por exemplo, modo editor, modo debug). Defina no SKILL.md:

---
modos:
  - editor
  - debug
---

O skill só será carregado quando o agente estiver em um dos modos listados.

Orquestração de Agentes

A orquestração de agentes permite que múltiplos skills colaborem. Use o campo orquestração no SKILL.md:

---
orquestração:
  dependências:
    - outro-skill
  papéis:
    - principal
    - assistente
---

Os skills podem ser designados como principal (orquestrador) ou assistente (executor).

Configuração de Modelos Auto-Hospedados

Para usar modelos auto-hospedados, configure as variáveis de ambiente:

export MODEL_ENDPOINT=http://localhost:8000/v1
export MODEL_NAME=meu-modelo-personalizado
export API_KEY=sua-chave-api

No SKILL.md, referencie essas variáveis:

---
config:
  modelo:
    endpoint: ${MODEL_ENDPOINT}
    nome: ${MODEL_NAME}
---

Exemplos

Exemplo 1: Skill Simples

---
nome: saudação
descrição: Um skill que cumprimenta o usuário.
versão: 1.0.0
plataformas:
  - claude-code
comandos:
  - comando: ola
    descrição: Diz olá.
---

Exemplo 2: Skill com Dependências

---
nome: analisador-dados
descrição: Analisa dados de arquivos CSV.
versão: 2.1.0
plataformas:
  - kilocode
  - openclaw
dependências:
  - pandas>=1.3.0
  - numpy>=1.21.0
comandos:
  - comando: analisar
    descrição: Executa análise nos dados.
---

Contribuições

Contribuições são bem-vindas! Veja o arquivo CONTRIBUTING.md para mais detalhes.

Licença

Este projeto está licenciado sob a Licença MIT. Consulte o arquivo LICENSE para mais informações.