--- title: "Skills: o guia" description: "O guia das skills do Éclair: requisitos, instalação, prompt inicial, controles de qualidade, o que fazer e evitar, e como criar a sua própria skill." url: "https://eclaircms.org/pt/documentacao/skills" lang: "pt" author: "Thierry Gustin" published: "2026-11-08" updated: "2026-11-10" --- # Skills: o guia > **O essencial** — Este guia explica passo a passo como usar as skills do Éclair: instalar a biblioteca no projeto, iniciar um agente com o prompt certo, seguir os sete controles de qualidade antes de qualquer ativação, evitar os erros comuns e criar as suas próprias skills. Ele é para quem quer acrescentar um recurso a um site Éclair 2.0 com o Claude Code, o Codex ou o ChatGPT. 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](https://eclaircms.org/pt/baixar) 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](https://eclaircms.org/pt/documentacao/atualizacoes). ## 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](https://github.com/Jacckisback/eclair-skills) (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/`. ```bash 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 ``` > **Dica** — Comece pela família `foundation`: as suas oito skills fixam as regras comuns (arquitetura, armazenamento, permissões, rotas, cache, segurança, testes) das quais todas as outras dependem. ## 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: ```text 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// sem alterar o núcleo. Antes de propor a ativação, execute php tools/validate.php --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. | Controle | O que é verificado | | --- | --- | | 0 | Versão do Éclair, commit e capacidades reais do site (API capabilities) | | 1 | Pacote em site/extensions/<id>/, manifesto eclair-extension/1, impressões dos arquivos, núcleo intacto | | 2 | Validador oficial: php tools/validate.php <pasta> --json retorna valid: true | | 3 | Bateria de testes completa: php tests/run.php | | 4 | Orçamentos de desempenho: php tools/measure.php --check | | 5 | Testes de segurança negativos, permissões por objeto, cache privado isolado, backup e restauração | | 6 | Revisão humana, ativação pela administração e volta atrás testada | ## 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//secrets.php`. ## Como criar a sua própria skill? ```text skills/eclair-meu-ramo/ ├── SKILL.md └── references/ ├── acceptance.md └── native-contract.md ``` 1. Crie uma pasta `skills/eclair-/` 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. ## Perguntas sobre o uso das skills ### Onde as skills são instaladas? Na pasta `.agents/skills/` do projeto. Para o Claude Code, copie-as para `.claude/skills/`. ### Posso instalar uma só skill? Sim, com `--skill eclair-`. Você pode repetir a opção para instalar várias. ### Como atualizo uma skill? Baixe a nova versão da biblioteca, revise as mudanças e reinstale com `--force`. ### As skills funcionam sem conexão com o site no ar? Sim. Elas trabalham na sua cópia do projeto; aliás, é o recomendado. [Ver a biblioteca no GitHub](https://github.com/Jacckisback/eclair-skills) [As 57 skills, família por família](https://eclaircms.org/pt/skills)