# How a Skill Is Written

A skill is a folder. The only required file is `SKILL.md`: a short header that tells the AI what the skill is for, followed by the method in plain words. Scripts and reference files are optional.

## The folder

```text
weekly-summary/
├── SKILL.md          required: header + method
├── scripts/          optional: code the skill runs
│   └── run.mjs
└── references/       optional: material the AI reads when needed
    └── format.md
```

The folder name is the skill's name. Use lowercase letters, digits and hyphens, for example `weekly-summary` or `check-invoices`.

## SKILL.md

```markdown
---
name: weekly-summary
description: Summarise the last 7 days of meeting notes into decisions, open
  questions and actions with owners. Use when asked for a weekly summary,
  a recap of meetings, or what was decided this week.
---

# Weekly summary

## Inputs and outcome
- Input: meeting notes (.md, .docx or .pdf) in the workspace, dated in the
  file name or first line.
- Outcome: weekly-summary-YYYY-MM-DD.md in the workspace.

## Procedure
1. List notes from the last 7 days. If there are none, say so and stop.
2. From each note take decisions, open questions and actions.
3. Write the summary in three sections. Actions as a table:
   owner (first name) · action · due date. Group by owner.
4. Save the file. Do not change the notes.

## Representative check
Every action in the summary appears in one of the notes, and every note
from the last 7 days is listed under Sources.
```

### The header

| Field | Required | What it does |
|---|---|---|
| `name` | Yes | The skill's name; the same as the folder name. You can run it as `/name` |
| `description` | Yes | What the skill does **and when to use it**. The AI reads only this to decide whether a request matches, so put the words people actually use in it |
| `entry` | No | The main script, for example `scripts/run.mjs` |
| `resources` | No | A list of other files in the folder the skill uses |
| `disable-model-invocation` | No | `true` means the AI never picks the skill by itself; it runs only when you type `/name` |

### The body

Write the method the way you would brief a new colleague. Three parts work well, and they are what Cowork's skill creator starts you with:

- **Inputs and outcome**: what the skill needs and what "done" looks like
- **Procedure**: the steps, the limits ("do not change the notes") and the expected output
- **Representative check**: one example input and the result you would expect, so the AI can tell whether it worked

The AI reads the full body only when it uses the skill, so it can be as long as the job needs.

## Scripts

Add a script when part of the job must be exact every time: a calculation, a file conversion, a call to a system. The AI runs it and uses what it prints.

- Scripts are JavaScript or TypeScript (`.mjs`, `.js`, `.ts`). Cowork runs them with its own bundled runtime; nothing extra to install.
- Running a script on your computer always asks you first
- Scripts run with your normal permissions. Only use scripts you or someone you trust wrote.

### A command that runs without the AI

A skill can also be a plain command: typing `/name` and some words runs its script directly, without the model, and shows what the script prints. The header for that is:

```yaml
---
name: count-files
description: Count files in the workspace by type.
entry: scripts/run.mjs
x-shortcut:
  run: scripts/run.mjs
---
```

The words after `/count-files` reach the script as command-line arguments. Ask the AI to "make a command skill" and it sets this up for you.

## Where the folder goes

| Location | Who gets it |
|---|---|
| `.agents/skills/` in a workspace | Everyone who opens that workspace |
| This computer's skills (Cowork's `skills/` folder) | Only you, in every workspace |
| `~/.agents/skills` in your home folder | Only you; also read by other tools that use this folder |

Published platform and institution skills are read-only. To change one, copy it to your own skills first. See [What Skills Are](https://docs.micromeet.ai/skills/what-are-skills.md).

## Check a skill

Ask "check the weekly-summary skill". Cowork verifies the header, that declared files exist and that no template placeholders are left. A format check does not prove the skill works: test it on a real request.