aireg is not on the host, your language has no SDK, or you need an operation aireg does not cover. Otherwise, aireg publish does it in one command, from a terminal or on merge from GitHub; see Publish skills with aireg.
Before you begin
Before you start, make sure you have:- Credentials:
ATLAN_GATEWAY_URLandATLAN_TOKENin your environment, from an approved secret store. See Authentication. - Workspace: A disposable workspace you can write to for a first run.
- SDK (optional): The atlanai SDK, for the Python and TypeScript examples. See Install.
1
Prepare skill bundle
Create a ZIP with Do not include tokens, customer data, or private source material in the bundle.
SKILL.md at its root and only the supporting files the skill needs. SKILL.md opens with YAML front matter carrying name and description, which describe the skill to the runtime that loads it. A bundle without front matter returns 422 validation_failed; see 422 validation_failed on publish.SKILL.md
2
Publish skill
Send a multipart request with two parts. The With the SDK, The response identifies the skill and its current version. Keep both in your deployment record rather than finding the skill again by name. To publish a content change, upload the updated ZIP under the same name in the same workspace: changed content becomes a new version — including a bundle whose files are the same but whose file permissions changed, such as a script made executable — and content identical to the current version is refused as a duplicate that names the existing skill. To change only the name or description, use
metadata part carries the skill name, optional description, and target workspace, which address the skill in the registry. The body part carries the ZIP.metadata is a multipart part, so pass it as a JSON string with snake_case keys in both languages:PATCH /skill/v1/skills/{skill_id} (client.skills.update).3
Publish many skills (optional)
To create up to 100 skills in one request, send an The response is
items part holding a JSON array of {metadata, body_part} objects, plus one ZIP part under each body_part name. Send this request over HTTP: the SDK bulk_create method sends only the items part and cannot attach the ZIP parts.207 Multi-Status even when some items failed. Its items array follows the request order: a 201 slot carries the created skill, and a rejected slot carries its own status and problem document. Successful items are not rolled back. Record the failed indexes and retry only those; do not resubmit the whole batch. For slot errors, see Skill errors. The request body is capped at 16 MiB, so send large bundles one at a time through the previous step.4
Retrieve pinned version
Use a pinned version when an environment needs reproducible content, and the current bundle when it should follow the latest maintained package. Read the version’s metadata and file manifest first, then download its bundle:The bundle response is From plain JavaScript, check the status and content type before writing the file, so a JSON problem body is not saved as a corrupt archive:
application/zip, not JSON. With the SDK, both bundle operations return raw bytes:5
Verify skill and usage
- Check publication: Search for the skill and confirm it returns the ID and version from the publish response. Search takes the query in the body, so it is a
POST.
- Check content: Compare the files in the downloaded bundle with your source bundle.
- Check usage: List recent traces that used the skill. Traces appear only when the consuming runtime reports them.
request_type is scalar, table, or time_series, and measure is one of sessions, traces, spans, skill_invocations, tool_calls, tokens, active_users, error_rate, success_rate, tokens_per_trace, cost, latency_p50, latency_p90, or latency_p99.Every skill operation is in the skill operations reference.
Troubleshooting
If a publish returns422 or 409, a bulk slot is missing its bundle, a download will not open, or a skill in use shows no traces, see Skill errors. For other status codes and safe retries, see Errors and retries.
Next steps
- Sync skills from GitHub: Publish on merge from a protected branch instead of calling the API by hand.
See also
- Publish skills with aireg: One command instead of a multipart request.
- Register agents through API: Register an agent and record its runs.
- Capture traces with aireg: Send your own coding-agent sessions to Atlan Trident from a terminal.