Skill errors

These are errors from opening a skill in Claude, syncing skills from GitHub, publishing a skill through the API or SDK, uploading a batch, downloading a bundle, and reading a skill’s usage. Start from the status code or the symptom: each section below starts from one of them. For errors that brain reports, see Atlan errors in brain.

​

Claude does not open from Open in

You choose Claude Code or Claude Desktop under Open in on a skill profile, and the client does not open or shows no prompt.

​

Cause

The handoff uses a link that only an installed client version that recognizes it can open.

​

Solution

1. Return to Open in on the skill profile and select Copy agent prompt.
2. Paste the prompt into Claude Code or Claude Desktop.
3. Confirm the prompt names the skill you reviewed, then submit it.

---

​

--changed-since names missing commit

The sync workflow fails because brain publish --changed-since names a commit that is not in the checkout.

​

Cause

The checkout has only the latest commit, so the previous one is missing.

​

Solution

1. Keep fetch-depth: 0 on actions/checkout.
2. Run the workflow again. See --changed-since in the brain CLI reference.

---

​

brain reports authentication required

brain exits with status 4 and reports that authentication is required.

​

Cause

The ATLAN_API_KEY secret is missing, does not reach the publish step as REGISTRY_TOKEN_ATLAN, or is no longer valid.

​

Solution

1. Confirm the repository or Environment secret ATLAN_API_KEY exists.
2. Confirm the publish step sets REGISTRY_TOKEN_ATLAN: ${{ secrets.ATLAN_API_KEY }}, and that a job using an Environment secret sets environment.
3. If the key was revoked or expired, create a new one and update the secret. See Atlan errors in brain.

---

​

Skill published to wrong workspace

The log says <name> went to your default workspace ….

​

Cause

No workspace the key can reach matches the one in --to, so brain published to its default workspace, which for a key is usually the first workspace the key can list.

​

Solution

1. Run brain registry show atlan and confirm the workspace name.
2. Confirm the key has access to that workspace.
3. Fix --to and publish again.

---

​

brain installer fails

The install step in the workflow fails.

​

Cause

Usually a transient network error while downloading the installer.

​

Solution

1. Run the workflow again.
2. Do not replace the installer with an unverified download.

---

​

Security scan blocked skill

brain prints blocked <name>: its security scan rejected this skill, so it was not published.

​

Cause

The skill’s security scan rejected it. The skill stays unavailable, and brain refuses to publish new files over a skill whose scan blocked it.

​

Solution

1. Open the skill in Atlan to see why the scan blocked it.
2. Resolve the finding.
3. Publish the skill again.

---

​

422 validation_failed on publish

The publish request returns 422 and no skill is created.

​

Cause

The bundle fails validation. The most common reason is a SKILL.md without YAML front matter, or a SKILL.md that is not at the root of the ZIP.

​

Solution

1. Open SKILL.md and confirm it starts with front matter carrying name and description.
2. List the ZIP contents and confirm SKILL.md is at the root, not inside a folder.
3. Rebuild the ZIP and publish again.

---

​

Bulk slot returns 409 with existing_artifact_id

A bulk upload returns 207 Multi-Status, and one or more slots carry 409.

​

Cause

Either the bundle is byte-identical to a skill the workspace already has, or two items in the same batch name the same skill. A batch cannot add two versions to one skill.

​

Solution

1. If the problem carries existing_artifact_id, use the skill that ID names instead of uploading again.
2. If two items name the same skill, remove one and send it in a later batch.
3. Retry only the failed indexes, not the whole batch.

---

​

Bulk slot reports missing body_part

A bulk upload returns 207 Multi-Status, and a slot reports that its bundle is missing.

​

Cause

The request has no ZIP part whose name matches the item’s body_part. The SDK bulk_create method sends only the items part, so every slot fails this way when you call it.

​

Solution

1. Send the bulk request over HTTP, with one ZIP part per item.
2. Name each ZIP part exactly as the item’s body_part.
3. Retry only the failed indexes.

---

​

Downloaded bundle does not open

The file saved from a bundle request is not a valid ZIP.

​

Cause

The request failed, and the client saved the JSON problem document as the file.

​

Solution

1. Check the response status before writing the file.
2. Confirm the Content-Type is application/zip.
3. Read the problem document’s detail for the actual error, fix it, and download again.

---

​

No traces for skill in use

A skill you know is in use shows no traces, stats, or insights.

​

Cause

The runtime that loads the skill does not report traces to Atlan. Usage appears only for runs that are traced.

​

Solution

1. Instrument the runtime with the tracing SDK, or install the Claude Code trace plugin.
2. Run a task that uses the skill.
3. List the skill’s traces again and confirm the run appears.

---

​

See also

• Publish and retrieve skills through API: The recipe these errors come from.
• Errors and retries: Other status codes and safe retries.

​

Need help

If you need assistance after trying these steps, contact Atlan support.