Turn a Task You Repeat Into a Skill a Colleague Can Run | Heidelberg AI Curriculum
T21-L02
Turn a Task You Repeat Into a Skill a Colleague Can Run
Do a task once in OpenWork, then save the way you did it as a skill: a short text file the agent follows the next time someone asks. Read the file, test it on new material, and hand it to a colleague who runs it without you.
Every Monday, Mira builds the maintenance overview for the group meeting. She opens OpenWork, points it at last week's notes and types the request. By now the request is long, because she has learned what goes wrong: use the date of the breakdown and not the file date, write "not stated" where a note is silent, quote times as written. Some Mondays she forgets one of these, and the table comes out a little different.
Then she is away for a week. Tarek covers. He types "make an overview of the notes", gets a table with other columns, and the group spends ten minutes of the meeting working out why the numbers don't match last week's.
In a company, the same thing happens to Jonas's weekly comparison of supplier quotes, the week a colleague builds it.
What Mira knows is in her head and in a long message she retypes. This book moves it into a file that OpenWork follows every time, and that Tarek can use too. You are at Level 2 Power user: the table goes to your team, so a wrong figure is now seen by others.
After this you can
Say what belongs in a skill, a saved routine for the agent: when to use it, the steps, the output format, the limits and the checks.
Do a task once in chat, have OpenWork save it as a skill file in the folder, and read what it wrote.
Test the skill on a second set of files, and on a request that should not use it.
Hand the skill folder to a colleague and watch them run it without your help.
Say when a skill is the wrong tool, and what to use then.
A task you repeat on a folder of files, with a result that goes to colleagues: a weekly overview, a comparison, a summary in a fixed form.
Two sets of practice files for it, six to ten files each: set A to build the skill, set B to test it. Let the agent make them, as in the first book.
One colleague with fifteen minutes, who has OpenWork installed with a model and a practice folder of their own.
About 75 minutes: 14 to read, about an hour to do.
Last verified 12 October 2026 against OpenWork's documentation and version 0.18.57. A skill saved in your folder is free and needs no account. Sharing skills with a whole team needs the vendor's online service, OpenWork Cloud, which the next book covers. Details for experts at the end of this book.
The idea in one page
A skill is a written routine. It is a text file called SKILL.md with two parts. The first is short: a name, and one sentence that says when to use it. The second is the routine itself, in plain words. The agent sees only the name and that one sentence of each of your skills. When a request matches one, it loads that file and follows it.
Five things go in.
Part
What you write
Mira's example
When to use it
One sentence with the words people really use
"Use when asked for the weekly maintenance overview."
Steps
What to read, in which order, what to produce
List the notes, read each, write one row per note
Output format
File name, columns, order
overview.csv, five named columns
Limits
What must never happen
Don't change, rename or delete a note
Checks
What the agent verifies before it says "done"
Count rows against notes and report both numbers
Do it once first. A skill written before the task has worked is a guess. Run the task in chat, correct it until the result is right, and only then save the way you did it. Every correction you made on the way belongs in the skill.
It is a file, so you can read it. The skill lives inside your workspace: in a folder skills, inside a folder called .opencode. You can read it, correct a line and give it to a colleague. OpenCode, the coding assistant this course teaches, reads the same file from the same place, so colleagues who write code can use your skill too.
A skill makes the agent consistent. It doesn't make it right. The same routine with a weaker model gives a weaker table. You still count rows and check three of them, and so does whoever runs it after you.
Not everything should be a skill. A skill suits work that needs judgment each time: reading notes written by six people. If the steps never vary, such as fetching a file, renaming it and mailing it, a fixed sequence of steps that a program runs does it more reliably. T05-L02 · Put AI in the Middle of a Workflow, and Check Every Answer shows that route.
Worked example: the maintenance overview as a skill
1. Structure it. Mira writes down what changes from week to week and what stays the same. The notes change. The file name, the columns and her three rules stay: the breakdown date, "not stated", times as written. She also writes down who relies on the table: the group, on Monday at ten. A breakdown missing from it means an instrument doesn't get serviced.
2. Understand it. She asks the agent to put eight new practice notes into a folder week-41 inside her practice workspace. Then she does the task once in chat, the way the first book showed: list first, then the table, then her three checks: rows counted against notes, three rows compared with their notes, and the one not stated. She corrects the date column once. She keeps the chat open.
You should see: overview.csv in week-41, with eight rows, three of which you have compared with their notes.
3. Choose tools. There are two places a skill can live. A local skill is a file in this workspace: free, no account, and she can read it. A Cloud skill is stored in OpenWork Cloud, the vendor's online service for teams, and is the subject of the next book. For one colleague, the file is enough, and she learns what a skill is by reading one.
4. Build it. In the same chat she writes: "Turn what we just did into a reusable skill. Save it as a local skill in this workspace, not in OpenWork Cloud. Name it weekly-maintenance-overview."
You should see: a window titled Modify files? naming a file that ends in .opencode/skills/weekly-maintenance-overview/SKILL.md. Mira clicks Allow once. OpenWork then confirms the skill's name and description.
5. Build it: read the file. She asks: "Show me the full text of the skill file you just wrote."
You should see: something like this in the chat.
---
name: weekly-maintenance-overview
description: Summarise files into a table.
---
# Weekly maintenance overview
1. List the note files in the folder the user names. Say how many there are.
2. Read every note. Don't change, rename or delete any of them.
3. Write overview.csv in the same folder, one row per note: file name,
date of the breakdown as given in the text, instrument, problem, action taken.
4. Quote dates and times as written. Write "not stated" where a note doesn't say.
5. Before you finish, count the rows and the notes, and report both numbers.
The two lines between the dashes are the skill's name and its when-to-use sentence. Everything below is the routine. The format is Markdown, plain text with a few marks for headings and lists. Mira looks for her own corrections among the numbered steps. If one is missing, the skill will repeat the mistake she fixed by hand.
6. Build it: fix the description. Mira finds one weak spot. "Summarise files into a table" would match almost any request. She asks: "Change the skill's description to: Use when asked for the weekly maintenance overview of the instrument notes in a folder." She allows the change and asks to see the file again.
You should see: the new sentence after description:.
Reading the file sent her back to Structure it: she had never written down when the routine applies. In the method this is the loop Structure it ⇄ Understand it.
7. Understand it again: test on new files. Mira has the agent make set B in a folder week-42. Then she clicks New session on the left, which opens an empty chat, so the agent starts without the earlier conversation. She asks the way Tarek would: "Make this week's maintenance overview for the notes in week-42."
You should see: the chat names the skill it used, and overview.csv appears in week-42. The closing message gives two numbers, rows and notes, because step 5 of the skill asks for them. If no skill is named, close OpenWork, open it again so that it reads the new skill, and check that it is listed under Settings, then Library, with the Skills filter.
She runs her three checks on the new table.
8. Understand it: a request that shouldn't use it. In another new session she asks: "Summarise this paragraph in three sentences" and pastes a paragraph from a newsletter.
You should see: a summary, and no skill named in the chat.
9. Build it: pack it for a colleague. The folder .opencode begins with a dot, and a Mac hides such folders. So Mira lets the agent do the packing: "Copy the folder .opencode/skills/weekly-maintenance-overview and the file opencode.jsonc into a new folder named handover in this workspace." She adds a note to handover, a text file with five lines: what the skill is for; which model she tested it with; how to check the result; "copy both things into your OpenWork folder"; and the sentence Tarek should send his agent, from step 10. Then she puts handover on the shared drive.
You should see: a folder handover with the skill folder, the settings file and the note in it.
10. Build it: the colleague installs it. Tarek follows the note. He copies the skill folder and the settings file from handover into his own workspace folder and asks his OpenWork: "Move the folder weekly-maintenance-overview into .opencode/skills in this workspace. Create those folders if they don't exist." He closes OpenWork and opens it again, so that it reads the new skill and the settings.
You should see: on Tarek's computer, under Settings, then Library, with the Skills filter, the skill is listed. Under How agents run here, File edits says Asks you, because the settings file came along.
11. Understand it: watch the colleague run it. Tarek has his agent make practice notes and asks for the overview in his own words. Mira watches and says nothing. He gets the table, counts the rows and checks three. He hesitated once, at the Modify files? window, because nobody had told him which file to expect. Mira adds one line to the note: "When you ask for the overview, expect one request, for overview.csv."
Company: Jonas's quote comparison
Jonas saves his weekly comparison the same way, as weekly-quote-comparison, with the rule "quote delivery times as written" from his first run. His description reads: "Use when asked to compare this week's supplier quotes."
His colleague Dana uses a small model that runs on her own laptop, because quotes may not leave the company. The skill is used, but the table stops after four of seven quotes. The routine is the same on both computers; the model differs. Step 5 of the skill catches it: the agent reports "4 rows, 7 quotes". Dana switches to the more capable model the company has approved, and the table is complete. Jonas writes the model's name into the hand-over note.
What goes wrong
The skill is written before the task worked.Symptom: a tidy file that produces the mistakes you haven't met yet. Fix: do the task once in chat and check the result before you save anything.
The description is too wide or too narrow.Symptom: the skill is used for unrelated requests, or never. Fix: start it with "Use when…" and the words your colleagues will type. Test one request that should use it and one that shouldn't.
Your corrections stayed in your head.Symptom: the colleague's table has the mistake you fixed by hand in week one. Fix: each time you correct a result, ask OpenWork to add the rule to the skill, then read the file.
The colleague's OpenWork doesn't ask.Symptom: files change on their computer with no request. Fix: the setting belongs to the folder. Hand over opencode.jsonc with the skill, as in step 9 of the worked example.
Two copies drift apart.Symptom: you improved your copy; your colleague's still has the old rule. Fix: keep one master copy on the shared drive, ask OpenWork to write the date of the last change into the skill's first step, and copy from there. When more than two or three people use it, move to the shared library in T21-L03 · Share Skills and Connections With Your Team, and Decide Who Gets What.
The skill went to the cloud.Symptom: no file appears in the folder. Fix: if you are signed in to OpenWork Cloud and ask for a skill "for me", it is saved there, visible only to you. Say "local skill in this workspace".
A password or a person's name in the skill.Symptom: the file travels by mail and shared drive with a login or a patient's name in it. Fix: a skill describes a routine. Keep logins, names and real data out of it.
Do it yourself (60 minutes)
Structure it (5 minutes). Write down what changes each time and what stays: columns, rules, file name. Write who relies on the result and what a wrong one would cost them.
Understand it (15 minutes). Do the task once in chat on set A. You should end with a table whose rows equal the files and three rows that match their sources.
Choose tools (2 minutes). Decide: a local skill for now. Note who else will need it.
Build it (5 minutes). Ask for a local skill with a name. You should see one Modify files? window, for SKILL.md.
Read it (5 minutes). Ask to see the file. You should find each of your corrections as a step. Change the description so it starts with "Use when…".
Understand it again (13 minutes). New session, set B, a request in a colleague's words. You should see the skill named in the chat. Run your three checks. Then send one request that should not use the skill.
Hand over (15 minutes). Pack the skill folder, the settings file and the note as in step 9 of the worked example. Your colleague installs it from the note alone, as in step 10, and runs it. You watch. Add what they stumbled on to the note or the skill.
Exit check
Hand in the skill folder and a one-page test sheet with four entries:
your run on set A: files, rows, and the result of three rows checked;
your run on set B in a new session: the same counts and checks, and whether the chat named the skill;
one request that correctly did not use the skill;
your colleague's run: who, which model, files and rows, and where they hesitated.
It passes when the colleague produced the result without your help and the three rows they checked match the sources.
Rule to remember
Do it once, write down what made it right, and let a colleague prove the file works without you.
Details for experts
Checked on 12 October 2026. You don't need this to follow the book; it's for setting things up or answering a colleague.
What
Details
What it means for you
Where a local skill lives
.opencode/skills/<name>/SKILL.md inside the workspace folder. OpenWork lists it under Settings › Library, and the + button next to the message box has a Skills section. On a Mac, Command, Shift and the full stop together show hidden folders in Finder.
One folder per skill. Copy the whole folder.
The first lines
name and description, between two lines of three dashes. The name uses lower-case letters, digits and single hyphens, and must equal the folder's name. The description may be up to 1,024 characters.
If you rename the folder, change name to match.
How the agent picks a skill
The agent gets a list of names and descriptions and loads a skill's full text only when it decides to use it.
The description decides whether your skill is found.
Cost
The skill's text is read by the model each time it is used, which counts against your allowance or your bill with the model's company. OpenWork keeps no stored results: the same request runs the model again.
A short, exact skill costs less than a long exploratory chat.
Signed in to OpenWork Cloud
Asking for a skill "for me" creates a private plugin in the cloud, a package that holds the skill, and no file. Asking for a local skill creates only the file.
Say which one you want.
The same file in OpenCode
OpenCode reads .opencode/skills too, as well as .claude/skills and .agents/skills in the folder it works in.
A skill written for desk work can be used by colleagues who work in OpenCode.
Sharing without the cloud
The vendor's own advice: copy the skill folder to a colleague's workspace, or keep it in a folder the team shares. Nobody controls who has it, and nothing updates by itself.
Fine for two or three people. Beyond that, see the next book.
What was checked
OpenWork's documentation, the interface text of version 0.18.57 and OpenCode's documentation on skills.