Skills - Onyx Documentation

Skills package reusable instructions and supporting files that teach Craft how to perform a kind of work. Open Craft → Skills to review, upload, share, and manage Skills.

Curators can also upload Skills and manage Skills they own or can edit. Admins can inspect and manage all custom Skills, including private personal Skills.

Understand the Skills library

Type	Where it comes from	What an admin can do
Built-in	Shipped and maintained by Onyx	Preview its instructions and identify missing dependencies. Built-ins are not editable.
Custom	Uploaded by an admin or user	Edit, share, replace files, enable or disable, transfer ownership, or delete.

New custom Skills start private. Share a Skill with people, groups, or the organization when others should use it.

Built-in Skills

Skill	Availability
Presentations	Available with Craft and provides the workflow for creating and validating `.pptx` files.
Company search	Available with Craft and searches Onyx knowledge using the current user’s document permissions.
Browser	Available when the deployment’s browser runtime is enabled.
Image generation	Available after an admin configures a supported image model.

An unavailable built-in remains visible to Admins with the reason it cannot be used. Configure the missing dependency rather than uploading a custom Skill with the same slug.

Prepare a custom Skill

A custom Skill is a ZIP archive with SKILL.md at its root. The ZIP filename becomes the permanent slug, so choose a stable lowercase, hyphenated filename.

Onyx removes .zip from the filename and uses the remaining text as the Skill slug. Skill slugs must be unique. If an existing Skill already uses that slug, the upload fails. Rename the ZIP to create a separate Skill, or replace the files on the existing Skill.

weekly-customer-update.zip
├── SKILL.md
├── examples/
│   └── finished-update.md
├── templates/
│   └── update-template.md
└── scripts/
    └── validate.py

SKILL.md must begin with YAML frontmatter containing a non-empty name and description. The description should state when Craft should choose the Skill.

---
name: Weekly customer update
description: Create a weekly customer update from account activity and meeting notes.
---

# Weekly customer update

1. Summarize material changes since the previous update.
2. Separate decisions, risks, and next steps.
3. Name an owner and due date for each next step.
4. Follow `templates/update-template.md`.
5. Run `scripts/validate.py` before returning the final file.

Bundle requirements

Requirement	Default
Slug	ZIP filename without `.zip`; lowercase letters, numbers, and hyphens; starts with a letter; maximum 64 characters.
Root instructions	One UTF-8 `SKILL.md` file with valid YAML frontmatter.
Maximum file size	25 MB per file in the extracted bundle.
Maximum bundle size	100 MB total.

Self-hosted operators can change the size limits with SKILL_BUNDLE_PER_FILE_MAX_BYTES and SKILL_BUNDLE_TOTAL_MAX_BYTES. The upload is rejected when the archive has unsafe paths, symbolic links, files ending in .template, missing or invalid frontmatter, an invalid filename, a duplicate Skill slug, or a slug reserved by a built-in Skill or App.

Review a Skill before publishing

Treat a Skill bundle as code and policy, not only as prompt text. Craft can follow scripts and commands included in the archive.

Review area	What to check
Purpose and selection	The name and description clearly identify when the Skill should and should not be used.
Instructions	The workflow is bounded, internally consistent, and does not tell Craft to evade approvals or organization policy.
Scripts	Every executable file is expected, readable, and safe to run on user-provided or company data.
External access	The bundle contains no embedded tokens and uses a configured App for authenticated services.
Examples and templates	Included files contain no confidential data and represent the quality users should expect.
Output handling	The Skill names the expected format and writes finished deliverables to a clear location such as `outputs/`.

Never publish a bundle containing passwords, API keys, OAuth tokens, private certificates, or production credentials. Skill files are copied into the sandboxes of users who can access the Skill. Use Apps for authenticated external access.

Publish a Skill

Upload the bundle

Open Craft → Skills, select Create skill, choose the ZIP archive, and upload it. The new Skill starts private and is owned by the uploader.

Review the rendered instructions

The editor shows the Skill’s name, description, and SKILL.md instructions. Switch between raw Markdown and preview to catch formatting or content issues.

Choose who can use it

Select Edit sharing and grant Viewer access to specific users, groups, or the organization. Use Editor access only for people responsible for maintaining it.

Test with the intended audience

Start a Craft session as a user in the target audience, select the Skill, and test representative inputs, missing-data cases, and the final output.

Scope	Viewer	Editor
Specific people	Selected users can use and preview the Skill.	Selected users can also modify and manage the Skill.
Groups	Members of selected groups can use and preview the Skill.	Members can also modify and manage the Skill.
Organization	Everyone can use and preview the Skill.	Everyone can modify and manage it. Use this only for intentionally collaborative Skills.

Editors can change instructions and files, update sharing within their permissions, enable or disable the Skill, and delete it. Only the owner can transfer ownership; an Admin can transfer ownership after the existing owner becomes inactive or is otherwise vacant.

Prefer organization-wide Viewer access with a small maintainer group as Editors. This keeps the Skill broadly usable without making its behavior broadly editable.

Maintain a Skill

Open a custom Skill to manage its lifecycle:

Action	Effect
Edit details	Updates the name, description, or Markdown instructions and rewrites `SKILL.md` in the stored bundle.
Replace files	Replaces the complete ZIP. The slug stays the same; metadata and instructions are read from the new `SKILL.md`.
Disable	Prevents Craft from using the Skill without deleting its configuration or sharing.
Edit sharing	Changes who can view or maintain the Skill.
Transfer ownership	Assigns responsibility to another active standard user.
Delete	Permanently removes the Skill and its stored bundle.

Changes are synchronized to affected running sandboxes. A turn already in progress may have loaded the previous instructions, so validate important changes in a new turn or session before announcing them.

Ownership

Every custom Skill has one owner. The owner can transfer it to another active standard user. If ownership becomes vacant because the owner is inactive, an Admin can open the Skill and transfer it. Do not transfer ownership to bots, service accounts, limited accounts, or inactive users.

Troubleshooting

A ZIP will not upload

Confirm that SKILL.md is at the archive root, uses UTF-8, and begins with valid YAML containing non-empty name and description fields. Check the filename and bundle limits, and remove symbolic links or unsafe archive paths.

A built-in Skill is unavailable

Open its preview to read the unavailable reason. Configure Image Generation for the image Skill, or ask the deployment operator to verify the browser runtime for the Browser Skill. Built-in Skills cannot be replaced or enabled from the Skills editor.

Users cannot find a shared Skill

Confirm that the Skill is enabled and that the user or one of their groups has Viewer or Editor access. If it was shared during an active session, start a new turn or session and check the picker again.

Craft does not choose the Skill automatically

Rewrite its description to name the covered tasks and outputs more concretely. Test again, and have users select it explicitly when the workflow must be followed.

A former employee still owns a Skill

After the account is inactive, an Admin can open the Skill, select Edit sharing, and transfer the vacant ownership to an active standard user.

Skills for users

Show users how to find, select, create, and refine Skills.

Managing Apps

Configure authenticated access and action policies for external services.

​Understand the Skills library

​Built-in Skills

​Prepare a custom Skill

​Bundle requirements

​Review a Skill before publishing

​Publish a Skill

​Choose sharing permissions

​Maintain a Skill

​Ownership

​Troubleshooting

Skills for users

Managing Apps

Understand the Skills library

Built-in Skills

Prepare a custom Skill

Bundle requirements

Review a Skill before publishing

Publish a Skill

Choose sharing permissions

Maintain a Skill

Ownership

Troubleshooting