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
New custom Skills start private. Share a Skill with people, groups, or the organization when others should use it.
Built-in Skills
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
UploadSKILL.md directly when the Skill does not need supporting files. For a Skill with scripts, examples,
or other supporting files, create a folder with SKILL.md at its top level. Drag the folder into Onyx,
or upload it as a ZIP.
For a standalone
SKILL.md, Onyx creates the slug from the frontmatter name. For a folder,
the folder name becomes the slug. For a ZIP, the filename without .zip becomes the slug.
Folder and ZIP names must start with a lowercase letter, contain only lowercase letters, numbers, and hyphens,
and be no more than 64 characters. Slugs must be unique. If an existing Skill already uses the slug,
update that Skill or change the source name before uploading.SKILL.md at the archive root or directly inside one enclosing folder.
When you use an enclosing folder, keep every Skill file inside it. Upload only one Skill at a time.
SKILL.md must begin with YAML frontmatter containing a non-empty name and description.
The description should state when Craft should choose the Skill.
Bundle requirements
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 bundle has unsafe paths, symbolic links, files ending in .template,
missing or invalid frontmatter, an invalid slug source, 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.Publish a Skill
Admins and curators create Skills through the same personal creation flow as other users. A new Skill belongs to its creator and starts private. Publishing means reviewing that Skill and then sharing it with the intended audience.1
Create the personal Skill
Open Craft → Skills and select Create skill. Choose Start from scratch to write the Skill in Onyx,
or choose Upload a skill to import
SKILL.md, a ZIP, or a Skill folder.
Complete the editor and select Create.2
Review the Skill
Review the name, description, rendered instructions, and supporting-file tree.
Confirm that Craft can understand when to use the Skill and that every included file is expected.
3
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.
4
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.
Choose sharing permissions
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.
Maintain a Skill
Open a custom Skill to manage its lifecycle:
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 Skill bundle will not upload
A Skill bundle will not upload
Confirm that the upload contains one Skill.
SKILL.md must be at the top level of a folder. In a ZIP,
place it at the archive root or directly inside one enclosing folder.
Check that it uses UTF-8 and begins with valid YAML containing non-empty name and description fields.
For a standalone SKILL.md, make sure name contains at least one letter or number. Otherwise,
check the folder or ZIP name. Check the bundle limits, and remove symbolic links or unsafe paths.Craft does not choose the Skill automatically
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
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.