Skill execution modes
Every skill declares how it runs on your machine. There are exactly two modes: local_plain (the default, transparent) and local_protected (verified, ephemeral content). This page explains what each one means on disk and at runtime, what guarantee the protected mode offers — and what it doesn't. For the security angle, see Protected skills.
The two modes
| Mode | On disk | Integrity | What for |
|---|---|---|---|
local_plain (default) | Open files in ~/.imaginne/skills/<key>/. | — | Transparent skills, easy to inspect. |
local_protected | Only a summary (stub) of the manifest. | Bundle verified by HMAC + digest. | Corporate skills that shouldn't be casually inspected or redistributed. |
The mode is set in the manifest (execution_mode) and in the skill editor (a radio under Metadata). A third value, remote_server, does not exist — it's rejected on import and on publish. The skill runtime is always local. See Anatomy of a skill.
local_plain — transparent
In normal mode, sync writes the skill's files openly to ~/.imaginne/skills/<key>/: the manifest, the prompt, and the scripts sit there, readable. You (and the agent) can open and inspect everything. It's the right choice for most skills, especially those that carry no sensitive logic.
local_protected — verified and ephemeral
In protected mode, what goes to disk permanently is only a summary of the manifest. The real content (prompt + scripts) travels in a separate protected bundle. When the agent is about to invoke the skill, Imaginne:
- Verifies the bundle by HMAC signature and digest (ensuring integrity and origin).
- Extracts the content into a temporary folder with restricted permissions (
0700). - Runs the skill from that folder.
- Removes the temporary folder when it finishes.
Beyond preventing casual inspection and redistribution, protected mode prevents "shadowing": a local skill with the same name can't impersonate the organization's protected skill.
Integrity is not DRM
This point is important and deliberate:
local_protected protects against casual inspection — it is not unbreakable encryptionHMAC + digest verification guarantees integrity (the content hasn't been tampered with) and makes inspection and copying harder. But whoever controls the machine where the skill runs can still, with technical effort, observe the execution. Treat protected mode as an anti-accident and anti-redistribution layer, not as a vault.
In other words: protected mode raises the bar against "someone opens the folder and copies the code" and against "a malicious skill with the same name." It does not make the code invisible to a determined administrator of the machine itself.
When to use each
Use local_plain when… | Use local_protected when… |
|---|---|
| The skill is transparent and you want it to be inspectable. | The skill carries business logic the company doesn't want casually exposed. |
| There's no concern about redistribution. | The skill shouldn't be copied outside the organization. |
| You're developing and iterating. | You want to prevent shadowing by a local skill with the same name. |
The bundled skills use local_plain — they're transparent by design. Corporate skills that touch internal systems usually make more sense in local_protected, combined with env-secrets for the credentials.
Relationship with env-secrets
The execution mode is orthogonal to secrets. A local_protected skill still receives its secrets through the same mechanism: Imaginne injects only the names declared in required_env, only for that execution. See Env-secrets (author).
See also
Was this page helpful?
Report a problem on this pageDo not send passwords, keys, tokens, or customer data.