> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onyx.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Review, publish, share, and maintain reusable Craft instructions

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.

<Note>
  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.
</Note>

## 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](/admins/actions/image_generation). |

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.

<Info>
  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.
</Info>

```text theme={null}
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.

```md theme={null}
---
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/`.       |

<Warning>
  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](/admins/managing_features/craft_apps) for authenticated external access.
</Warning>

## Publish a Skill

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Choose sharing permissions

| 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.

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

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="Skills for users" icon="wand-magic-sparkles" href="/overview/core_features/craft_skills">
    Show users how to find, select, create, and refine Skills.
  </Card>

  <Card title="Managing Apps" icon="plug" href="/admins/managing_features/craft_apps">
    Configure authenticated access and action policies for external services.
  </Card>
</CardGroup>