engpro-advpl-tlpp-skills

Estas skills foram desenvolvidas para o uso em agentes de IA seguindo o padrão aberto Agent Skills.

Vale ressaltar que apenas o uso destas skills não garante a qualidade final de um código, e que na TOTVS acreditamos na integração Humanos e IA, por isso é recomendado que sempre haja uma curadoria humana.

IAs podem errar.

---

Sumário

• O que são Agent Skills?
  • Categorias de Uso
• Agentes Suportados
• Coleções Disponíveis
• Como Usar
  • Onde as Skills Ficam
• CLAUDE.md e AGENTS.md — Instruções de Contexto
  • O que são CLAUDE.md e AGENTS.md?
  • Como Usar o CLAUDE.md e AGENTS.md
• Agentes Customizados
• Contribuindo
• Segurança
• Licença

---

O que são Agent Skills?

Agent Skills são instruções estruturadas empacotadas como pastas simples contendo um arquivo SKILL.md — que orientam agentes de IA a executar tarefas de engenharia de software de forma consistente e com qualidade. Cada skill define um fluxo de trabalho completo — incluindo quando usar, instruções passo a passo, formato de saída e critérios de validação — permitindo que o agente atue como um especialista no domínio.

As skills funcionam através de um sistema de progressive disclosure em três níveis:

1. Frontmatter YAML — sempre carregado no contexto do agente. Contém apenas o necessário para o agente saber quando cada skill deve ser usada.
2. Corpo do SKILL.md — carregado quando o agente determina que a skill é relevante para a tarefa atual. Contém as instruções completas.
3. Arquivos vinculados — arquivos adicionais no diretório da skill que o agente pode navegar e consultar apenas quando necessário (referências, templates, scripts).

Esse design minimiza o uso de tokens enquanto mantém expertise especializada disponível.

Skills ensinam agentes de IA uma vez, e eles aplicam esse conhecimento de forma consistente em cada tarefa. Em vez de re-explicar preferências, processos e expertise de domínio a cada conversa, skills permitem ensinar o agente uma vez e se beneficiar sempre.

Categorias de Uso

Skills são versáteis e cobrem três grandes categorias:

Categoria	Descrição	Exemplos
Criação de Documentos e Assets	Gerar outputs consistentes e de alta qualidade — código, documentação, relatórios	Geração de telas MVC, endpoints REST, documentação ProtheusDOC
Automação de Workflows	Processos multi-etapas que se beneficiam de metodologia consistente	Migração de código, revisão de qualidade, planejamento de implementação
Inteligência de Domínio	Conhecimento especializado aplicado a decisões de engenharia	Otimização SQL, refatoração com code smells, revisão de segurança

Agentes Suportados

Instale skills em qualquer um desses agentes de IA para desenvolvimento de software:

Populares	Promissores	Corporativos
Claude Code	Aider	Amazon Q
Cline	Antigravity	Augment
Cursor	Gemini CLI	Droid (Factory.ai)
GitHub Copilot	Kilo Code	OpenCode
Windsurf	Kiro	Sourcegraph Cody
	OpenAI Codex	Tabnine

Coleções Disponíveis

Cada diretório na raiz do repositório representa uma coleção de skills voltada para uma linguagem, framework ou domínio específico.

Coleção	Descrição	Skills
advpl-tlpp	Skills para o ecossistema TOTVS Protheus ERP — linguagens AdvPL e TLPP	20
superpowers	Skills genéricas para agentes (recomendado o uso em conjunto com as outras skills)	14

Novas coleções para outras linguagens e frameworks serão adicionadas progressivamente.

Como Usar

Faça download do pacote de skills e coloque as pastas de skills no local apropriado para que seu agente de IA possa acessá-las.

Pacote	Descrição	Versão

Para outras versões, consulte a página de releases.

Onde as Skills Ficam

Escopo	Caminhos suportados	Aplica-se a
Pessoal	~/.claude/skills/<skill>/SKILL.md~/.agents/skills/<skill>/SKILL.md~/.copilot/skills/<skill>/SKILL.md	Todos os seus projetos
Projeto	.claude/skills/<skill>/SKILL.md.github/skills/<skill>/SKILL.md.agents/skills/<skill>/SKILL.md	Apenas este projeto
Plugin	<plugin>/skills/<skill>/SKILL.md	Onde o plugin está habilitado

CLAUDE.md e AGENTS.md — Instruções de Contexto

Além das skills, este repositório fornece CLAUDE.md e AGENTS.md — arquivos de instruções de contexto que configuram o agente de IA com conhecimento fundamental sobre um ecossistema antes mesmo de ele começar a trabalhar. Enquanto skills ensinam como fazer tarefas específicas, CLAUDE.md e AGENTS.md ensinam o que o agente precisa saber sobre o projeto.

⚠️ Importante: Os arquivos CLAUDE.md e AGENTS.md possuem o mesmo conteúdo — são equivalentes. A diferença é apenas o nome do arquivo, que existe para compatibilidade com diferentes agentes de IA. Use apenas um deles, conforme o agente que você utiliza:

• CLAUDE.md — reconhecido nativamente pelo Claude Code.
• AGENTS.md — reconhecido nativamente pelo GitHub Copilot, Cursor, Windsurf e outros agentes que seguem o padrão aberto.

Não é necessário (nem recomendado) usar ambos ao mesmo tempo no mesmo workspace.

O que são CLAUDE.md e AGENTS.md?

Os arquivos CLAUDE.md e AGENTS.md são o mesmo conjunto de instruções de contexto para workspaces do ecossistema TOTVS Protheus ERP, disponibilizados com dois nomes diferentes para compatibilidade com múltiplos agentes. Eles contêm:

Seção	Conteúdo
Linguagem e Ecossistema	Identificação das linguagens AdvPL e TLPP, extensões de arquivo, idioma padrão
Estrutura de Projeto	Layout de diretórios típico de um projeto Protheus (fontes, testes, skills)
Convenções de Código	Notação Húngara, nomenclatura de arquivos, tabelas, campos e constantes multilíngue
Padrões Obrigatórios	Soft-delete, filtro por filial, prevenção de SQL injection, boas práticas de performance
Padrão MVC	Estrutura MenuDef → ModelDef → ViewDef → BrowseDef do framework Protheus
TLPP Moderno	Namespaces, type annotations, REST via annotations
Build e Compilação	RDMake, arquivos .PRJ, RPO
Testes	Framework TIR com estruturas e convenções
Skills Disponíveis	Catálogo resumido das skills de AdvPL/TLPP
ProtheusDOC	Padrão de documentação obrigatório para novo código

Com essas informações carregadas, o agente já entende as convenções, restrições e boas práticas do projeto — sem que você precise explicar a cada conversa.

Como Usar o CLAUDE.md e AGENTS.md

Escolha um dos dois arquivos conforme o agente que você utiliza e copie-o para a raiz do seu repositório ou workspace. A maioria dos agentes de IA detecta automaticamente arquivos de instruções na raiz do projeto.

Arquivo	Agentes que reconhecem nativamente
CLAUDE.md	Claude Code
AGENTS.md	GitHub Copilot, Cursor, Windsurf, Cline, Kilo Code, Roo Code e outros

Caso o seu agente exija um caminho ou nome de arquivo específico, crie um link simbólico ou copie o arquivo para o local adequado.

Dica: O CLAUDE.md e AGENTS.md complementam as skills. Use-os para dar contexto permanente ao agente e as skills para ensinar fluxos de trabalho específicos.

---

Contribuindo

Quer contribuir com novas skills ou melhorar as existentes? Consulte o guia completo em CONTRIBUTING.md — com estrutura do projeto, anatomia de uma skill, regras obrigatórias, frontmatter, boas práticas e muito mais.

Segurança

Este repositório segue uma política de segurança rigorosa — todas as skills são open source, auditáveis e revisadas manualmente. Para detalhes sobre o modelo de ameaças e como reportar vulnerabilidades, consulte SECURITY.md.

Licença

Este projeto é distribuído sob a licença MIT.