2.4 Tuning Skills: When Standard Isn't Enough
Turn Team Experience into Skills Everyone Can Use at Work
An installed Skill is rarely right the first time. After a few uses you notice it is always slightly off: a field is missing, the terminology does not match your industry, the output format needs a manual fix every time.
This lesson explains how to locate the rule to change, update the Skill, and compare the results.
When to Improve It
These signals say the Skill is due for an update:
| Signal | What it means |
|---|---|
| You keep adding the same sentence by hand | That rule belongs in the Skill |
| You reformat the output every time | The output template was never pinned down |
| It does not recognise your industry terms | Terminology notes are missing |
| The same class of mistake keeps recurring | The step description is ambiguous |
What these share is repetition. One-off drift is not a problem; repeated manual patching is — because repetition means it can be written down.
Choose the Change for the Problem
| Problem | Action |
|---|---|
| Required fields are missing from the input | Complete the material and run the existing process |
| The same output needs changes repeatedly | Add the requirement to the Skill |
| The task belongs to another business activity | Create a new Skill |
| The result differs from the expected output | List the differences and compare runs using the same input |
Start with 2.2 Understanding a Skill to inspect the current files. See New Tasks and Conversations for follow-up requests and Resource Preview for opening the revised file.
How to Improve It: Three Kinds of Change
Every improvement goes in through the same door — tell it in natural language what to change.
| Kind of change | When it fits | Example |
|---|---|---|
| Add a rule | Your experience is missing | "The product copy Skill needs a footwear variant, with extra fields: size range, heel height, occasion" |
| Add a constraint | It did something it should not | "Keep the original file name as a note when renaming; confirm with me before executing" |
| Correct terminology | Industry terms got translated or altered | "Keep fashion terms in their original language, e.g. stiletto, derby, loafer" |
A ready-to-use example:
add the fields "size range", "heel height", and "occasion";
keep industry terms untranslated;
check for banned phrasing before output.
After a task, consolidate the requested changes in a revised file:
The Six-Step Loop
| Step | What you do |
|---|---|
| 1 | Locate the problem: which step needs manual adjustment every time |
| 2 | State the change: describe the rule in plain language |
| 3 | Read the current state: confirm how it is written today (see 2.2) |
| 4 | Test small: validate against one or two real tasks |
| 5 | Compare before and after: confirm you changed what you meant to |
| 6 | Settle the version: promote it once you are satisfied |
Step 3 is the one people skip, and it matters most for complex Skills — without knowing how it reads today, you cannot tell whether what you are changing already exists.
For the complete same-input comparison, see 2.3 Creating a Skill: draft and revision demo. It keeps SKILL-v1.md, SKILL-v2.md, and Comparison.md so you can inspect the color prefix and output-column changes.
Versions and Rollback
A Skill is a file, and that brings an underrated benefit: changes are traceable and reversible.
| Benefit | What it means |
|---|---|
| Version history | Save a revised file or retain the update through resource version management |
| Rollback | If the new version performs worse, return to the previous one |
| Comparison | Run both versions on the same input and let the results decide |
| Sharing | Hand a tuned Skill to a colleague and the capability transfers |
The right mindset is running an experiment, not editing a config — a failed attempt can be undone.
Four Common Failure Modes
Tuning often goes sideways, and the problems fall into four buckets:
| Symptom | Root cause | What to change |
|---|---|---|
| It does not activate when it should | The description is too narrow | Add the keywords a user would actually say |
| It activates when it should not | The description is too broad | Narrow the scope and say "only for…" |
| It activates but runs the steps wrongly | The steps are ambiguous or miss a branch | Write each action and decision point concretely |
| You re-explain the same thing every time | The experience never made it into SKILL.md | Write the spoken rule into the file instead of repeating it |
The first two share a root cause in a single field — the description decides when a Skill is selected. Too narrow and it misses; too broad and it misfires. That is the first place to look when tuning.
Summary
The hard part of tuning a Skill is not the edit; it is deciding whether an edit is warranted. Recurring problems are worth fixing; one-off drift means checking the input first.
Four principles: change only on repetition, validate in small steps, keep it reversible, and read the description first.
That completes the method layer. The next lesson moves to composition: assembling several Skills into one business chain.
2.3 Creating a Skill: From One Success to a Reusable Method
Adding and using Skills was covered in 1.5. This section focuses on creating your own.
2.5 Designing a Work: Assemble Skills Into One Business Chain
You installed a few Skills and they work well. But every task still starts with 'which ones do I need this time?'