Chapter 2 · Advanced Systems — Turn One-Time Wins Into a System

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:

SignalWhat it means
You keep adding the same sentence by handThat rule belongs in the Skill
You reformat the output every timeThe output template was never pinned down
It does not recognise your industry termsTerminology notes are missing
The same class of mistake keeps recurringThe 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

ProblemAction
Required fields are missing from the inputComplete the material and run the existing process
The same output needs changes repeatedlyAdd the requirement to the Skill
The task belongs to another business activityCreate a new Skill
The result differs from the expected outputList 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 changeWhen it fitsExample
Add a ruleYour experience is missing"The product copy Skill needs a footwear variant, with extra fields: size range, heel height, occasion"
Add a constraintIt did something it should not"Keep the original file name as a note when renaming; confirm with me before executing"
Correct terminologyIndustry terms got translated or altered"Keep fashion terms in their original language, e.g. stiletto, derby, loafer"

A ready-to-use example:

Update the product copy Skill:
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:

Summarize my preferences from today's conversation and update this Skill.

The Six-Step Loop

StepWhat you do
1Locate the problem: which step needs manual adjustment every time
2State the change: describe the rule in plain language
3Read the current state: confirm how it is written today (see 2.2)
4Test small: validate against one or two real tasks
5Compare before and after: confirm you changed what you meant to
6Settle 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.

BenefitWhat it means
Version historySave a revised file or retain the update through resource version management
RollbackIf the new version performs worse, return to the previous one
ComparisonRun both versions on the same input and let the results decide
SharingHand 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.

Run the old and new versions on the same input, put the two outputs side by side, and tell me which one meets the requirements better.

Four Common Failure Modes

Tuning often goes sideways, and the problems fall into four buckets:

SymptomRoot causeWhat to change
It does not activate when it shouldThe description is too narrowAdd the keywords a user would actually say
It activates when it should notThe description is too broadNarrow the scope and say "only for…"
It activates but runs the steps wronglyThe steps are ambiguous or miss a branchWrite each action and decision point concretely
You re-explain the same thing every timeThe experience never made it into SKILL.mdWrite 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.