Skills: o guia

As 57 skills do Éclair, em 8 famílias, ajudam o seu assistente de IA a acrescentar um recurso ao seu site Éclair 2.0 sem quebrar o que funciona. Instale-as no projeto, inicie o agente com o prompt fornecido e não ative nada antes dos 7 controles de qualidade.

Este guia detalha cada etapa e explica como escrever as suas próprias skills. Antes de começar, faça um backup como explica o guia Atualizar, fazer backup, mudar de hospedagem.

Do que você precisa antes de começar?

• Um site Éclair 2.0 e, de preferência, uma cópia de trabalho do código (o repositório oficial clonado), para que o agente possa rodar os testes.
• Python 3 para instalar e validar as skills, PHP 8.1 ou superior para as ferramentas do Éclair.
• Um assistente que lê skills: o Claude Code ou o Codex, por exemplo.
• Um backup recente: Segurança › Baixar uma cópia de segurança.

Como instalar as skills no projeto?

1. Baixe a biblioteca no GitHub (Code › Download ZIP, ou git clone).
2. Na pasta dela, verifique se está íntegra com python3 scripts/validate_skills.py: a mensagem deve anunciar 57 skills válidas.
3. Liste famílias e skills com python3 scripts/install_skills.py --list.
4. Instale o que precisar, por família (--category design) ou por nome (--skill eclair-seo-audit), com --project /caminho/do/meu-site.
5. Para o Claude Code, copie as pastas instaladas de .agents/skills/ para .claude/skills/.

python3 scripts/validate_skills.py
python3 scripts/install_skills.py --list
python3 scripts/install_skills.py --project /caminho/do/meu-site --category foundation
python3 scripts/install_skills.py --project /caminho/do/meu-site --skill eclair-wordpress-migration
python3 scripts/install_skills.py --project /caminho/do/meu-site --all

Como iniciar o agente com o prompt certo?

Abra o assistente na pasta do projeto e dê a ele um prompt inicial claro. Este vem com a biblioteca:

Analise este projeto Éclair CMS começando por eclair/index.php e docs/SKILLS-GUIDE.md. Use as skills eclair-architecture, eclair-extension-builder, eclair-security-audit e eclair-test-suite. Descreva o recurso pedido a partir das capacidades nativas eclair-extension/1. Crie os arquivos da extensão em site/extensions/<id>/ sem alterar o núcleo. Antes de propor a ativação, execute php tools/validate.php <extensão> --json, php tests/run.php e php tools/measure.php --check. Se faltar uma capacidade, pare essa parte e crie uma RFC e testes; não invente API.

Depois acrescente o seu pedido em uma ou duas frases, com as restrições que importam para você: público, idiomas, volume, dados pessoais.

Quais verificações antes de ativar um recurso?

A biblioteca define sete controles de qualidade. Um recurso só é ativado quando todos foram superados.

O que fazer

• Descrever a necessidade do negócio, não a técnica: o agente escolhe as skills.
• Deixar o agente ler as capacidades do site antes de escrever código.
• Testar em uma cópia do site, nunca direto em produção.
• Guardar o registro das decisões: o agente escreve uma breve nota de arquitetura.
• Prever a volta atrás: desativar um recurso mantém os dados dele.

O que não fazer

• Alterar app/, assets/, index.php ou o atualizador: uma atualização apagaria tudo.
• Ativar um recurso que não passou no validador e nos testes.
• Colocar em produção um carrinho, uma área de membros ou um fórum enquanto o núcleo não fornecer o contrato.
• Acreditar que uma pontuação de SEO, GEO ou Lighthouse é garantida: são medições a repetir.
• Passar segredos em texto claro ao agente: eles ficam em data/ext/<id>/secrets.php.

Como criar a sua própria skill?

skills/eclair-meu-ramo/
├── SKILL.md
└── references/
    ├── acceptance.md
    └── native-contract.md

1. Crie uma pasta skills/eclair-<nome>/ com um arquivo SKILL.md.
2. No topo do arquivo, informe name e uma description que diga quando usá-la: é isso que o agente lê para decidir.
3. Escreva o diagnóstico obrigatório, o procedimento, as entregas, as regras de segurança e os critérios de aceitação.
4. Acrescente os documentos úteis em references/: uma skill deve ser autônoma.
5. Declare-a em catalog.json e execute python3 scripts/validate_skills.py e python3 scripts/check_release.py --write.
6. Teste-a em um projeto real e proponha-a à biblioteca com uma pull request.

O que fazer se algo travar?

O validador recusa o pacote: Leia a mensagem JSON: ela indica o arquivo ou o campo do manifesto em questão. Corrija e valide de novo.

O agente quer alterar o núcleo: Recuse e lembre a regra: tudo deve ficar em site/. Se faltar uma capacidade, peça uma RFC e um teste bloqueante.

Falta uma capacidade (contas de clientes, pagamento…): É normal em algumas famílias: guarde o projeto e os testes e espere o núcleo abrir o contrato.

Ver a biblioteca no GitHub

As 57 skills, família por família