Writing and uploading skills

A skill is made of instructions (the body of a SKILL.md file) and, optionally, attached files: reference docs, forms and sample data the AI pulls when it needs them. There are two ways to get one in: write it straight on the web, or upload a package.

Way 1: Write it on the web

1. 1

   Open a server → the Skills tab → hit New skill.

2. 2

   Fill in Skill name.

   Letters, digits, dashes and underscores only; 2–100 characters; the first character has to be a letter or a digit. This is the name the AI sees when it lists skills. Valid examples: weekly-report, quy_trinh_sales, SOP2024.

3. 3

   Fill in Description (optional, up to 500 characters) with one sentence that tells the AI when to reach for this skill.

4. 4

   Write the Instructions and hit Create.

   This is exactly what the AI reads and follows, so write it the way you'd brief a new hire: context, steps, examples, and what not to do.

After that, open the skill to edit it in the Editor. The editor counts lines and characters, flags Unsaved changes, saves fast with Ctrl + S (macOS: ⌘ + S) and stops you leaving the page while changes are still unsaved.

Way 2: Upload a package

A package is a .zip or a .skill file (a .skill file really is just a ZIP). Hit Upload a package on the Skills tab.

The package must contain `SKILL.md`. The system looks for SKILL.md at the shallowest level (case doesn't matter) and treats the folder holding it as the root, so both layouts below give exactly the same result:

weekly-report.zip               weekly-report.zip
└─ weekly-report/               ├─ SKILL.md
   ├─ SKILL.md                  └─ references/
   └─ references/                  └─ guide.md
      └─ guide.md

Every other text file becomes an attached file, keeping its relative path (references/guide.md). The AI reads them with the get_skill_file tool.

The top of SKILL.md can carry a frontmatter block that declares a name and a description. The system reads exactly two fields, name and description, one line each:

---
name: weekly-report
description: How to write the weekly report for the Sales team
---

# Weekly report

When you are asked to write the weekly report, follow these steps...

The name field is only used when creating a skill and you left Skill name empty. On an update, the skill name stays as it is.

Updating with a package: read this part carefully

To change or add exactly one file without touching the others, use the Add file button on the Attached files card. That one only ever adds, and overwrites by name.

Attached files

Text files only, meaning Markdown, JSON, CSV, txt, YAML… Binary files (images, fonts, PDFs, Excel) are skipped and reported back to you in the yellow Some files were skipped card.

File names may include subfolders (references/guide.md), under these rules:

• 200 characters total at most, and 6 segments deep at most (5 folder levels plus the file name).
• Each segment starts with a letter or a digit, then letters, digits, dots, underscores and dashes.
• No accented characters, no spaces, no .., no backslashes.
• No segment may start with a dot, so .env, .gitignore and the .git/ folder are all rejected.
• __MACOSX and .DS_Store are dropped outright, so you don't have to clean them out first.

The size limits

How a skill reaches the AI

You hit Save and that's it. There's no review step and no publish step. The very next call from anyone allowed to read that server gets the new version.

Skill content always reaches the AI wrapped in a frame that demands it apply the content and never reveal it verbatim. That's the strongest fence anyone can build, but once content sits inside a user's chat window nothing is absolute, so don't put real secrets (passwords, API keys, personal data) in a skill.

Seeing how much a skill gets used

Open a skill and the Usage card shows Reads, last 30 days. Hit See who read it to jump into the logs, already filtered to that skill.