Env-secrets para autores de skills

Uma skill que fala com um sistema interno — um CRM, uma API corporativa, um certificado — precisa de segredos. No Imaginne, a skill declara de que segredos precisa; a organização cadastra os valores; e o Imaginne injeta apenas os nomes declarados, só na hora de rodar. Esta página é o lado do autor: como declarar e consumir segredos. O cadastro dos valores é tarefa do admin — veja Env-secrets (admin).

Como o fluxo funciona

A skill declara os nomes → a org guarda os valores → o Imaginne injeta só o declarado, só naquela execução.

A regra central: os valores dos segredos nunca chegam ao cliente como dados livres. O autor da skill nunca vê o valor — só referencia o nome. No momento em que o agente aciona a skill, o Imaginne resolve apenas os nomes que a skill declarou e os injeta como variáveis de ambiente no processo daquela skill. Quando a skill termina, eles somem com o processo.

Declarar os segredos

Há duas formas de declarar, e o validador exige que sejam consistentes entre si quando ambas aparecem.

Forma 1 — required_env (contrato simples)

Uma lista de nomes de variáveis de ambiente:

name: lead_proposal
version: "1.0.0"
description: Gera uma proposta a partir de um CSV de leads.
required_env:
  - CRM_API_TOKEN
  - CRM_BASE_URL

Forma 2 — env.secrets[] (bloco estruturado)

Cada segredo aponta para uma referência (secret_ref) e marca se é obrigatório:

schema_version: 1
skill_key: lead-proposal
name: lead_proposal
version: "1.0.0"
description: Gera uma proposta a partir de um CSV de leads.
env:
  secrets:
    - name: CRM_API_TOKEN
      secret_ref: crm-api-token
      required: true
    - name: CRM_BASE_URL
      secret_ref: crm-base-url
      required: true

Se usar as duas formas, elas precisam concordar

Quando o manifesto traz required_env e env.secrets[] ao mesmo tempo, os nomes precisam ser coerentes. Uma divergência é rejeitada na importação/publicação. Na dúvida, use só uma forma.

Os nomes de variável seguem a convenção de ambiente: maiúsculas, dígitos e sublinhado (^[A-Z][A-Z0-9_]{0,127}$). É o mesmo formato que o admin usa ao cadastrar o segredo na organização.

Como o Imaginne injeta

No acionamento da skill, o Imaginne:

1. Lê os nomes que a skill declarou (required_env / env.secrets).
2. Resolve apenas esses nomes contra os segredos da organização.
3. Filtra para o conjunto declarado e os injeta como variáveis de ambiente no processo da skill.

No seu script, você lê os segredos como qualquer variável de ambiente:

import os

token = os.environ["CRM_API_TOKEN"]
base_url = os.environ["CRM_BASE_URL"]

Sem carry-over entre skills

Cada skill recebe só os segredos que ela declarou. Não há vazamento de uma skill para outra: o que a skill A declara não fica disponível para a skill B. Cada execução começa limpa.

Quando falta um segredo

Se a skill declara um segredo obrigatório que a organização ainda não cadastrou (ou não anexou à skill), a execução falha com missing_required_env. Esse é um erro de configuração, não de código: o admin precisa cadastrar o segredo e anexá-lo à skill. Veja Env-secrets (admin) e a solução de problemas.

Documente os segredos no prompt

No SKILL.md, liste os segredos de que a skill precisa e o que cada um representa ("CRM_API_TOKEN — token de leitura do CRM"). Assim o agente sabe o contexto e o admin sabe o que cadastrar.

Checklist do autor

• Declarei cada segredo em required_env ou env.secrets[] (sem divergência).
• Os nomes seguem ^[A-Z][A-Z0-9_]{0,127}$.
• Os scripts leem os segredos via os.environ (nunca hardcoded).
• O SKILL.md documenta cada segredo.
• Avisei o admin de quais segredos cadastrar e anexar à skill.

Veja também

🔑Env-secrets (admin)

Cadastrar, rotacionar e anexar segredos à skill.

Abrir →🧩Anatomia de uma skill

Onde required_env e env.secrets entram no manifesto.

Abrir →🔒Credenciais & segredos

Como as credenciais nunca chegam ao cliente.

Abrir →