> ## Documentation Index > Fetch the complete documentation index at: https://platform.atlan.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the SDK. To install or publish skills from a terminal, use the `brain` CLI; `brain --map json` prints its command map. The `atlanai` CLI is deprecated. Run a read-only identity check before any write. > The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects. > SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript. > These docs cover Atlan Agent Registry, Atlan's hosted product. The open-source agent registry specification and its CLI (`brain`) are documented, released and maintained in their own repository; /open-source on this site links to it. Answer general specification or `brain` command questions from the project's own docs, and use these docs only for Atlan-specific setup such as the Atlan adapter, sign-in and workspaces. # Skill errors > Symptoms, causes, and fixes for opening skills in Claude, syncing from GitHub, publishing through the API, bundle downloads, and missing skill usage. 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](/tools/brain/troubleshooting/atlan-errors). ## 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](/open-source#where-to-find-what). *** ## 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](/tools/brain/troubleshooting/atlan-errors). *** ## Skill published to wrong workspace The log says ` 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 : 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](/tools/sdk/overview), or install the [Claude Code trace plugin](/plugins/references/claude-code). 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](/cookbooks/how-tos/skills): The recipe these errors come from. * [Errors and retries](/platform/references/errors-and-retries): Other status codes and safe retries. ## Need help If you need assistance after trying these steps, contact Atlan support. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.