Skip to main content

Skill troubleshooting

This page gathers the errors authors and admins run into when working with skills — from importing and publishing to running on the user's machine. Use the table as an index and see the details right below.

Error table​

Symptom / codeWhat it meansHow to fix
missing_required_envThe skill declared a required secret that isn't available.The admin registers the secret and attaches it to the skill.
Skill doesn't appear / is refusedYou don't have a profile with that skill.Ask the admin to assign the skill to a profile of yours.
Protected executor unavailable (tool_deferred)The local_protected skill couldn't be prepared.Reopen the session; if it persists, ask the admin.
Local execution deniedThe org's policy disabled local skill execution for you.The admin adjusts the permission on the profile/user.
Invalid manifest (422)The manifest didn't pass validation.Fix the manifest; the editor's banner points to the error.
Version conflict (422)Same version, different content.Bump the version in the manifest.
ZIP rejectedThe package violated a limit or the scanner.Adjust the ZIP per the import limits.
Python / OUTPUTS_DIR errorsThe script failed at runtime.Check dependencies and the outputs/ discipline.
Skill disappears from the listA required manifest field is missing.Make sure name, version, and description are present.

missing_required_env​

The skill declared a required secret (in required_env or env.secrets) that the organization hasn't registered yet or hasn't attached to the skill. It's a configuration error, not a code error.

  • Author: check that the declared name matches exactly what the admin registered (uppercase, underscore).
  • Admin: register the secret and use Manage skills to attach it. See Env-secrets (admin).

Contract details in Env-secrets (author).

Skill outside the profile's allowlist​

If a skill doesn't appear for you or is refused when invoked, it's because your profile doesn't include it. Skills reach users through profiles — without a profile that contains the skill, it doesn't make it into the list presented to the model. Ask the admin to assign the skill to a profile of yours. See also Skill governance.

Protected executor unavailable (tool_deferred)​

A skill in local_protected mode depends on Imaginne verifying and extracting the protected bundle. If that doesn't happen, the invocation is deferred (tool_deferred). Try:

  1. Reopening the session to force a fresh skill sync.
  2. Confirming that you have access to the skill (correct profile).
  3. If it persists, ask the admin to check the publication of the protected skill.

For the mode itself, see Execution modes.

Local skill execution denied​

The organization can disable local skill execution by policy (on the profile or the user). In that case, even with access to the skill, the agent won't run it on your machine. It's an admin decision — ask for the "Local skill execution" permission to be adjusted. See Profiles and Users & roles.

Invalid manifest (422)​

On publish, the manifest goes through validation. Common failures:

  • schema_version other than 1.
  • skill_key outside the regex ^[a-z0-9][a-z0-9-]{1,98}[a-z0-9]$.
  • name missing.
  • execution_mode: remote_server (rejected).
  • required_env and env.secrets mismatched.

In the editor, the manifest banner points to the problem and blocks publishing until it turns green. See Anatomy of a skill.

Version conflict (422)​

You tried to publish the same version with different content. Published versions are immutable. Bump the version in the manifest (e.g. 1.0.0 → 1.0.1) and publish again. Re-publishing the same version with the same content is a no-op (idempotent). See Publish and version.

ZIP rejected​

The import fails when the package violates a limit or the scanner blocks a script:

  • Size > 10 MB or more than 50 files.
  • Missing manifest.yaml or prompt.md (both required).
  • Path traversal (.. or an absolute path) or a symlink.
  • Binary (.exe, .dll, .so, .dylib, .com, .msi).
  • Script blocked by the scanner — the message points to the file and the reason (destructive command, secret exfiltration, etc.).

Adjust the package per Import via ZIP and resubmit.

Python / OUTPUTS_DIR errors​

When the skill's script fails at runtime, the most common culprits are:

  • ImportError — a dependency isn't installed. In web chat, the runtime image may not have the package; locally, install it with pip install -r requirements.txt.
  • "absolute path … outside OUTPUTS_DIR" — the script tried to write outside outputs/. Always write to OUTPUTS_DIR; relative paths are joined under it.
  • "create OUTPUTS_DIR" — a permission problem with the output directory.

The outputs/ discipline is described in Anatomy of a skill.

Skill disappears from the list​

If a skill stops appearing after an edit, a required field of the local manifest is almost always missing: name, version, or description. Without all three, the skill isn't loaded. Restore them and the skill comes back.

Collecting diagnostics​

If the problem persists and you need help:

  • Desktop — Export Support Bundle (redacted, no tokens) and /fb <message> to send feedback.
  • Terminal (TUI) — /diagnostics and /feedback.

See also the general troubleshooting page.

See also​

Import via ZIP

The limits and the scanner that reject a package.

Open →Publish and version

Idempotency and the version bump rule.

Open →Env-secrets (author)

Declare secrets and avoid missing_required_env.

Open →