Understanding SKILL.md

Folder layout

Each skill is one folder, and that folder must contain a SKILL.md.

<slug>/
├── SKILL.md        (required) name, description, instructions
├── scripts/        (optional) scripts the skill uses
├── references/     (optional) reference documents
└── assets/         (optional) templates, example files, images, etc.

The top of SKILL.md: name and description

---
name: price-compare
description: Checks prices and shipping costs across several product pages and summarizes them in a table. Use when the user asks to "compare prices".
---

• name: The skill's name. We recommend matching the folder name and using lowercase letters, numbers, and hyphens (-).
• description: This is what Aside uses to decide when to use the skill. Include what it does and when to use it.

Writing the body

Below the closing ---, write the instructions Aside should follow.

1. List the steps in order, with numbers.
2. State clearly what not to do. For example: "Do not sign in or make payments."
3. Tell Aside to ask instead of guessing when information is missing.
4. Show the output format (table, list, etc.) with an example.

Supporting files: scripts, references, and assets

• Put reusable templates, examples, and images in assets/, reference documents in references/, and scripts in scripts/.
• Supporting files only help if the body of SKILL.md says when and how to use them, using relative paths. For example: "Format the result using assets/report-template.md."
• Install the skill in Aside and confirm how the supporting files are actually used before describing them.

Uploading a whole folder (zip)

If your skill has supporting files, choose Folder (zip) on the submit a skill page and upload the whole folder. A skill that is just SKILL.md can still be uploaded as a single file.

1. Zip the skill folder. You can zip the folder itself (<slug>/SKILL.md) or just the files inside it (SKILL.md).
2. When you pick the zip, the page previews the file list and explains anything that can't be accepted.
3. The name in SKILL.md must match the skill's address (slug), because it becomes the folder name Aside installs into.

What you can upload

• Hidden files (such as .DS_Store) and the __MACOSX/ folder are rejected. The Mac "Compress" menu adds them, so zip from the terminal instead, e.g. zip -r my-skill.zip my-skill -x "*/.*", or delete those files first.
• Size limits may change with server capacity. The values shown on the submit page are the current ones.

If it includes scripts

Skills with a scripts/ folder get an Includes scripts badge and a warning on their detail page, and people are asked to confirm once more before copying the install line. Describe what each script does and what access it needs in the description. If you're installing, read the files in the file list on the detail page first.

Reviewed before publishing

Uploaded skills are not published right away; they are published after a review.

1. An automatic rule check runs as soon as you upload. Content that tells the agent to ignore other instructions (ignore previous instructions), secretly sends data elsewhere, or runs downloaded scripts directly (curl … | sh) is rejected immediately.
2. If it passes, an AI review publishes it within a few minutes. Skills with a scripts/ folder or flagged items are published after a moderator checks them.
3. If it's rejected, the detail page shows why (the matched rule and line), and you can appeal once if you think it's a mistake.
4. When you upload a new version, the previously published version stays visible until the review finishes.

Uploaded content may be sent to the OpenAI API for this safety review (Privacy Policy).

Releasing a new version

• When you change the files, you must raise the version to save (e.g. 1.0.0 → 1.1.0). The new version must be greater than the current one.
• A published version never changes, and earlier versions stay downloadable from the version list on the detail page.
• Bundles pin each skill's version, so publishing a new version of a skill doesn't change bundles that already include it.