Modos de execução de skills
Toda skill declara como ela roda na sua máquina. Há exatamente dois modos: local_plain (o padrão, transparente) e local_protected (conteúdo verificado e efêmero). Esta página explica o que cada um significa no disco e no runtime, qual garantia o modo protegido oferece — e qual ele não oferece. Para o ângulo de segurança, veja Skills protegidas.
Os dois modos
| Modo | No disco | Integridade | Para quê |
|---|---|---|---|
local_plain (padrão) | Arquivos abertos em ~/.imaginne/skills/<key>/. | — | Skills transparentes, fáceis de inspecionar. |
local_protected | Apenas um resumo (stub) do manifesto. | Bundle verificado por HMAC + digest. | Skills corporativas que não devem ser inspecionadas casualmente nem redistribuídas. |
O modo é definido no manifesto (execution_mode) e no editor da skill (radio em Metadata). Um terceiro valor, remote_server, não existe — é rejeitado na importação e na publicação. O runtime de skill é sempre local. Veja Anatomia de uma skill.
local_plain — transparente
No modo normal, a sincronização escreve os arquivos da skill abertos em ~/.imaginne/skills/<key>/: o manifesto, o prompt e os scripts ficam ali, legíveis. Você (e o agente) podem abrir e inspecionar tudo. É a escolha certa para a maioria das skills, especialmente as que não carregam lógica sensível.
local_protected — verificado e efêmero
No modo protegido, o que vai para o disco de forma permanente é só um resumo do manifesto. O conteúdo de verdade (prompt + scripts) viaja em um bundle protegido separado. Quando o agente vai acionar a skill, o Imaginne:
- Verifica o bundle por assinatura HMAC e digest (garantindo integridade e origem).
- Extrai o conteúdo em uma pasta temporária com permissões restritas (
0700). - Executa a skill a partir dessa pasta.
- Remove a pasta temporária ao terminar.
Além de evitar a inspeção casual e a redistribuição, o modo protegido impede o "shadowing": uma skill local de mesmo nome não consegue se passar pela skill protegida da organização.
Integridade não é DRM
Este ponto é importante e deliberado:
local_protected protege contra inspeção casual — não é criptografia inquebrávelA verificação por HMAC + digest garante integridade (o conteúdo não foi adulterado) e dificulta a inspeção e a cópia. Mas quem controla a máquina onde a skill roda ainda pode, com esforço técnico, observar a execução. Trate o modo protegido como uma camada anti-acidente e anti-redistribuição, não como um cofre.
Em outras palavras: o modo protegido eleva a barreira contra "alguém abrir a pasta e copiar o código" e contra "uma skill maliciosa de mesmo nome". Ele não torna o código invisível para um administrador determinado da própria máquina.
Quando usar cada um
Use local_plain quando… | Use local_protected quando… |
|---|---|
| A skill é transparente e você quer que seja inspecionável. | A skill carrega lógica de negócio que a empresa não quer expor casualmente. |
| Não há preocupação com redistribuição. | A skill não deve ser copiada para fora da organização. |
| Você está desenvolvendo e iterando. | Você quer impedir shadowing por uma skill local homônima. |
As skills inclusas usam local_plain — são transparentes por design. Skills corporativas que tocam sistemas internos costumam fazer mais sentido em local_protected, combinadas com env-secrets para as credenciais.
Relação com env-secrets
O modo de execução é ortogonal aos segredos. Uma skill local_protected continua recebendo seus segredos pelo mesmo mecanismo: o Imaginne injeta apenas os nomes declarados em required_env, só naquela execução. Veja Env-secrets (autor).
Veja também
Esta página ajudou?
Reportar um problema nesta páginaNão envie senhas, chaves, tokens ou dados de clientes.