Skills

Support reference for reusable instruction packages used by Alloy AI teammates.

A skill is a folder whose entry point is a `SKILL.md` file. It gives an AI teammate specialised instructions for a task or domain. A skill can also include reference files, scripts, and assets.

A skill is not a workflow. It has no step graph, trigger, run history, or workflow API. Use a workflow when work must execute as a defined process; use a skill when an AI teammate needs reusable guidance for deciding and acting.

Skills live in organization Storage under `.skills`. The runtime recursively discovers entry files matching `.skills/**/SKILL.md`, so skills can be grouped in category subdirectories:

```text .skills/ support/ ticket-summary/ SKILL.md references/ urgency-rules.md ```

The immediate skill folder name and the `name` field in `SKILL.md` must match. Intermediate category folders such as `support/` are organizational only.

Every skill begins with YAML front matter followed by Markdown instructions:

```markdown --- name: ticket-summary description: Use when an AI teammate needs to turn a support transcript into a title, summary, and urgency rating. ---

Ticket summary

Read the complete transcript, then return a concise title, summary, and urgency. ```

Required front matter:

• `name`: 1 to 64 lowercase letters, numbers, or hyphens; it must match the directory name
• `description`: 1 to 1,024 characters explaining what the skill does and when to use it

Optional front matter can include `license`, `compatibility`, `user-invocable`, and `metadata`.

Keep the main file focused. Put detailed lookup material in `references/`, executable helpers in `scripts/`, and reusable output resources in `assets/`.

Skills are discovered recursively through the teammate's readable Storage filesystem. Share the specific skill folder, for example `.skills/support/ticket-summary`, to make one nested skill available. Share a category folder to expose its readable skills, or share `.skills` to make all skills below it available.

Read access is sufficient to use a skill. A teammate needs write access only when it should maintain the skill. Enabling the teammate sandbox does not grant Storage access.

• Skills published in the system organization's storage are shared with system AI teammates that run inside other organizations (for example a user's personal Ally provisioned in a customer organization). Their workspace discovers `.skills/**/SKILL.md` from the system organization read-only in addition to the skills in their own organization's storage.
• Only system AI teammates get this second skill source. An ordinary teammate never reads another organization's storage.
• A system employee that already lives in the system organization discovers those skills through its own storage, so they are not scanned twice.

Use Storage operations to create or update the skill folder and files. Do not use workflow builder or workflow graph operations for skills.

When creating a skill:

1. Choose a short, descriptive, lowercase hyphenated name.
2. Write a precise description that states both the capability and when it should be used.
3. Put the procedure in the Markdown body using direct instructions.
4. Add only the supporting files the skill needs.
5. Share the skill folder with the intended AI teammates.
6. Test the skill by asking a teammate to perform a representative task.

Never place secrets in `SKILL.md` or its supporting files. Store credentials in organization variables or the relevant connector configuration.

Workflows remain the executable automation surface at `/workflows`. Both organization-owned workflows and workflows assigned to an AI teammate are called workflows. See `workflows.md` for builder, API, run, and version-history behavior.

A skill may teach an AI teammate when or how to call a workflow, but the skill and workflow remain separate objects with separate storage and execution models.