Skills From Expertise

Designing a methodology

What this is and what is not here

The official specification answers "how to shape it". Frontmatter, file length, progressive disclosure, description, testing, scripts: all of that lives there and does not need repeating.

Here is the question "what to put inside". It is harder, and covered almost nowhere. A model knows the format natively. What it does not know is what separates a method from a collection of useful notes.

The check for why this matters at all. A skill written perfectly to format is useless if there is no deciding procedure inside. It will load correctly, organise knowledge neatly, and change not a single action.

How to use this

What not to do:

• Don't turn assembly into a questionnaire. Most of this file covers hard cases, not a mandatory procedure.
• Don't start assembling before the digest is written.
• Don't argue with the author of the source inside the skill. A limitation is recorded as a condition of use, not as a rebuttal.
• Don't pass a guess off as an inference, especially when it is shaped as a prohibition or as a number.
• Don't publish material from someone else's source without going through the legal framing.

Order: digest, then four extraction steps, then mandatory parts, then four checks, then the format line. In full, see "Order of work" at the end of the file.

What to ask when data is missing: the purpose of the result, meaning publication, private use, or commercial distribution. That is the only thing that does not follow from the request itself, and both the license and the strictness of the legal framing depend on it. Everything else is determined from the material. Whose source it is shows in what was sent; whether a skill is needed at all is covered in "When a skill is not needed".

When this is the wrong place: you need format, field limits, and file mechanics, which belong to the Agent Skills specification; or you need to write the subject text itself rather than the method underneath it.

What counts as done

The result of a build is not one file but three things. A skill without the first and the third does not count as done.

1. The digest file, a separate .md, written before assembly of the skill begins. What goes into chat is a link to it plus two short sections: what was said in passing and what was left out.
2. The skill file.
3. The format line in the report, with counted values rather than checkmarks.

⚠️ This is the composition of the result, not the stages of a procedure, and that difference decides everything. A stage can be skipped unnoticed, because it exists only in your memory of an instruction you read. An incomplete result is visible at the moment of delivery.

⚠️ The digest is delivered before assembly, not together with the finished skill. At that moment the user can still say "the important part here is something else", and that costs far less than rewriting an assembled file.

This is the only place where stopping is justified, and it does not contradict the rule "don't ask permission to continue" below. The difference is in price. An ordinary question costs a turn and saves nothing; a remark about the digest cancels an entire wrong assembly. Having delivered the digest, wait for an answer. In everything else work without stopping.

Why exactly those two sections go into chat. A full retelling in chat costs tokens and time, and nobody is going to reread it. The user can object at exactly two points: where you judged something secondary, and where you dropped it. The rest they will check in the file if they want to.

Details: how the digest is built is covered in the "Cross-check against the source" check, and what goes into the format line is at the end of the file.

The fast path

Don't turn building a skill into a questionnaire. Most of this file covers hard cases, not a mandatory procedure.

If everything is clear from the request, work straight away. Own material, a skill for yourself, a simple subject: take the four steps from "How to extract a method", run the four mandatory checks, and deliver.

The proportionality rule: the size of the procedure matches the size of the material. A hundred-line skill from a single conversation does not require what a set of thirty sources requires.

⚠️ Proportionality concerns the size of the parts, not whether they exist. On small material the digest is short, not absent, and the format line is equally short at any size. The three-part composition of the result does not shrink. What shrinks is what is inside them.

How to run the conversation

Ask questions in a batch, not one at a time. Five questions in one message cost the user less than five messages with one question each. Number them so they can be answered as a list.

Don't ask what you can decide yourself. If a sensible option is obvious, take it and say so out loud: "I'm taking this option, tell me if that's wrong." A question belongs where different answers produce different results.

Don't ask permission to continue. Ask only when a choice is needed that you cannot make for the user. The only planned stop is after delivering the digest, see "What counts as done".

Work while work is possible. If part of the material is unclear and part is understood, assemble what is understood and put the question about the unclear part at the end, rather than instead of the work.

What to show at the end

Having handed over the file, say briefly:

• what came out, meaning which forks and rules were extracted;
• where you had to fill gaps, meaning what was inferred rather than taken from the source;
• what remained uncovered, meaning areas where the method did not reconstruct;
• what was dropped deliberately, with a reason for each item. Everything from the "said in passing" section that did not make it into the skill belongs here;
• what the user decides: publication, license, contact with the author of the source;
• the format line, with counted values.

Don't retell the contents in sequence, but do show the structure. The user has the file. What they cannot do is see it whole in a terminal, because several hundred lines do not read by scrolling. A map of sections with one line about each solves that in ten lines.

When you are editing an existing file

⚠️ A separate requirement, and it is broken almost every time. During an edit the user does not see the result. They see only your report, and a report saying "did such and such" without showing it means there is nothing to check and nothing to object to.

Show with every edit:

The rule about deletions: always show cuts explicitly; additions may be summarised. The user will see what was added while reading. What was deleted they will never see.

If there are many edits, collect them into a table: version, what was done, what prompted it. A list of fifteen paragraphs does not get read. A fifteen-row table does.

What not to do: don't announce a substantive decision as a result ("removed duplicates") without listing what exactly you judged to be a duplicate. A duplicate is a judgement, and it can be wrong.

After an edit, check what else it touched

⚠️ An edit in one place leaves traces in others, and the file starts contradicting itself. This is the main way a file degrades during long refinement: each individual edit is correct, but together they diverge. And they diverge silently. There is no error, there are two instructions, and the one encountered first is the one carried out.

What to check after every substantive edit:

⚠️ Summaries diverge first. A rule gets changed in its own section, because that is where it is being thought about. The line about the same rule in the "always do this" table sits elsewhere and survives the edit untouched.

One check after all edits: take what you changed and find every place in the file where it is mentioned. By search, not from memory.

The opening fork

Ask only if it does not follow from the request. "Make a skill from my experience" means the source is the user's own and no question is needed. "Break down this video" means the source is someone else's, and the licensing question is asked only when publishing.

Clarify before assembly:

• the origin of the material: the user's own expertise, someone else's public material, or mixed;
• the purpose: publication for the community, private use, or commercial distribution.

The answers determine the working mode.

Don't apply an open license before establishing the purpose. It is irreversible for copies that have already spread.

The source's license overrides that table

Check before choosing a license for the result: what license the source itself carries. It can remove your choice entirely.

With several sources, check compatibility. Material under CC BY-SA and material under a proprietary license do not combine in one file: the first requires opening the result, the second forbids it.

If the source's license is unknown, treat it as absent and work in "all rights reserved" mode.

⚠️ A separate note about videos and talks. Public availability is not an open license. A video posted publicly is "all rights reserved" by default: the method may be extracted, the text may not be carried over.

With a commercial purpose and someone else's sources, say so plainly: the extraction rules are mandatory, and the share of your own expression has to be the decisive one.

If the origin cannot be established, work in full mode. When there are clear signs of someone else's text (address to an audience, the author's own metaphors, traces of speech), tell the user and clarify the source before including it in the file.

When a skill is not needed, and what to do instead

⚠️ This is a fork, not a reason to refuse the work. Material is almost always good for something. The question is the form, not whether to do it at all. Hedging with "it all depends here" instead of working is worse than an imperfect method.

There is only one case where a method genuinely does not exist

The decision is made by taste, and the people who hold the expertise disagree with each other systematically on the same inputs. Not "sometimes differently" but systematically: two strong specialists look at the same thing, arrive at opposite answers, and both are right.

Then there is no procedure and nothing to build one from.

Everything else is not "there is no method" but "the method has not been found", and those are different conclusions with different actions.

The method exists, but not in the author's explanations

Two signs that are easy to mistake for the absence of a method. Both mean you should dig further rather than stop.

The result is not reproducible, meaning the same process by the same person gives a different outcome. This is not the absence of a method but a hidden variable you have not found. Look for what differed in the circumstances: a different client, a different deadline, a different stage. The difference you find is the missing criterion.

Success is explained only in hindsight, meaning the explanations appear after the result and do not predict the next one. That means the author's explanations are useless, not that the procedure is absent. Stop taking their explanations and watch their actions instead: what they do the same way every time, and what they change.

A rule covering both: an observation about repeatability is a pattern, not a method. A pattern becomes a method once the conditions are found under which it holds. Until the conditions are found, record it as a pattern with a note, but do not throw it away.

The method covers only some of the decisions

The most common case of all. The procedure reconstructs for some forks and not for others.

Describe it where it exists, and mark the zone where it does not: "here the decision is made from experience, there is no reproducible criterion". Mixing the two is not allowed, because an unmarked zone of intuition reads as a procedure.

What to make instead of a skill

A skill is not the only form. Most often the material fits one of these.

How to choose between the first two. A rule that has to apply to any task in the project belongs in the instructions. Knowledge needed only in a particular situation belongs in a skill or in its files. A sign of confusion: a skill that is "needed always" is actually a project instruction, and it will not fire reliably.

A backlog of skills

Keep a separate backlog for skills, starting with the first piece of material you set aside. Without it, half-assembled work is lost: a month later you will remember neither the topic nor what was missing.

What to record for each deferred topic:

• the topic, in one line, phrased by the user's task rather than by the subject;
• what is already there: which forks and criteria have been found, and from what source;
• what is missing, specifically: how many cases, which questions were not asked, which block of material is absent;
• where to look for what is missing: a source, a person, a type of material;
• the threshold: at what volume the topic becomes a skill.

Record decisions separately, not just tasks. "Established this duplicates such and such" or "decided not to do it, it is a matter of taste" is an entry that saves a repeated round. A backlog made only of tasks turns into a list of debts within six months; a backlog with decisions turns into the project's history.

The closing rule: strike closed entries through, with a date and an outcome, rather than deleting them. A deleted entry comes back: the same material arrives again and the work is redone.

⚠️ Check an entry before adding it. "We don't have this topic" is worth verifying by searching for meaning rather than for the name, otherwise the backlog fills with a gap that does not exist while the topic is already covered under another name.

When to review: with every new piece of material on an adjacent topic, and before any reassembly of the set. A backlog nobody rereads does not work.

The core distinction

A set of tips tells you what exists. A methodology tells you what to do in a specific situation and on what basis to choose.

A practical test. Take any section of the skill and ask: "having read this, what action will I take differently?" No answer means it is reference material, not a method. Reference material has its uses, but it does not replace a procedure.

Signs that there is no method yet

• Everything is listed, nothing is chosen. Ten tools with no indication of when to use which.
• Not a single "don't". A method that forbids nothing decides nothing.
• Every point is true on its own. Truth is not a sign of method; coherence is.
• You cannot get it wrong. If the instructions make it impossible to do the wrong thing, they prescribe nothing.
• The order of the points can be changed without loss. That means there is no sequence.

How to extract a method from expertise

Expertise is almost never laid out as a method. An expert speaks in stories, examples, and asides, while holding the deciding procedure in their head without being aware of it.

How you extract depends on whether the holder of the knowledge is available. That is the first fork, and it changes the whole procedure.

The second axis: the form of the material

The first fork answers where to take the method from. The second answers what you are physically working with. They are independent: a book and a spreadsheet can come from the same unavailable author, and the procedures for taking them apart differ.

Three rules follow from that table:

Structured sources get unfolded, not assembled. In an ordinary source you assemble the procedure out of scattered decisions. In a good table it is already there: the columns are the criteria, and the work runs the other way, unfolding what was compressed and working out what justifies each column. An empty column, or a column filled identically in every row, is a signal that the criterion is formal and not needed in the method.

Convert spatial material to text before analysis, not after. A diagram cannot be searched by word or checked against what you have already written. While it stays a picture it takes no part in the work. Convert it using your own structures: the original diagram cannot be reproduced, since it is protected separately from the text.

Take speech apart by its asides, and writing by its assertions. In speech the boundaries of a method sit in the digressions; in written text editing has cleaned them out and they have to be reconstructed.

A catalogue by specific type, covering books, articles, courses, regulations, tables, boards, forums, research, code, and your own notes, is in references/source-types.md.

Step 1. Find decisions, not topics

Reading the source, look for the points where the expert chooses, not the places where they explain.

Markers of choice in speech: "here I look at…", "it depends on whether…", "if yours is like this, then…", "I wouldn't, because…", "first you need to understand…".

Every such phrase is a candidate fork in the methodology. Everything else is justification.

Step 2. Reconstruct the criterion

An expert names the decision but rarely names what they decided by. That has to be worked out and then checked against their other examples.

An example of reconstruction. The expert says: "for this client I'd suggest an assessment, for that one a quote straight away." Two decisions are named. The criterion is not. From the neighbouring examples it becomes visible: an assessment goes to people who don't understand their own problem, a quote to those who do and are choosing a contractor. The criterion is the stage of awareness. Now it is a method.

If the criterion cannot be reconstructed, write exactly that: "the expert decides this intuitively, there is no reproducible criterion." An honest hole beats an invented rule.

Step 3. Test the criterion against counterexamples

Take the criterion and find a case in the source where it would not work. If no limitation turns up at all, the criterion is phrased too broadly.

A method without boundaries is not a method but a slogan.

Step 4. Assemble into a sequence

Lay the decisions out in the order they are actually made, and check the dependencies: which step cannot precede which, and why.

Order in a methodology carries information. If the steps can be rearranged freely, this is a list, and it should honestly be presented as a list rather than posing as a procedure.

When you can ask the expert

Reconstruction is for when the author is unavailable. When they are available, don't reconstruct the criterion, draw it out. That is faster and more accurate, but it takes the right questions: asked directly how they make a decision, an expert almost always answers wrongly.

Why the direct question fails. Expertise is automated: the decision is made faster than it is noticed. What the person gives back is not their procedure but a rationalisation of it, usually what they were taught rather than what they do.

The technique: two cases with different outcomes

The main instrument.

Find two similar situations in their practice where they decided differently. Show both and ask: what exactly was different?

The answer to that question is the criterion. It usually comes out immediately, because the person is comparing specifics rather than describing an abstraction.

If two such cases cannot be found, ask for a case where their usual decision did not fit. It works the same way: the exception exposes the rule.

What else to ask

• "What told you it had to be different here?" draws out the criterion.
• "What would have to change for you to decide the opposite?" draws out the boundary.
• "Where do you most often get it wrong?" draws out the zone where the method fails.
• "What do beginners do that you don't?" draws out the negative rules, which the expert never states because to them they are obvious.
• "What do you check first?" draws out the order.

What not to do

Don't offer the expert a ready formulation to confirm. They will agree: it sounds reasonable and there is nothing to push back on. Agreement verifies nothing. Ask about cases and draw the conclusion yourself.

Don't accept "it depends on a lot of things" as an answer. That is a signal the question was asked abstractly. Go back to specific cases.

Don't argue with the expert about their own practice. Your job is to record how they decide, not how it ought to be done. If you think they are wrong, see "When the expert is wrong".

When the expertise is your own

The hardest case, and usually underestimated. Your own method is less visible to you than someone else's, because it is automated, and automated things cannot be seen from inside.

The main trap: instead of their own procedure, a person writes down what they read elsewhere. The result restates the industry consensus rather than their own method, when their own method was the one thing that was unique.

The procedure for extracting from yourself

1. Take the five most recent real cases, not a typical scenario. A typical scenario is already a generalisation, and generalising yourself comes after, not before.
2. For each, write down what was done, in the order it actually happened. Not how it should have gone: how it went.
3. Find where the cases diverged. The point of divergence is a fork in the method.
4. For each divergence, answer: what in the situation made you go the other way. That is the criterion.
5. Test on a sixth case that was not in the sample. If the criterion predicted the decision, the method is there.

Questions to put to yourself

• What do I do that others in this role don't? That is yours, not borrowed.
• What do people correct me on most often, where I don't agree? There sits a position rather than a habit.
• What do I refuse to do that everyone else does? Negative rules, the strongest part of a method and the one least often written down.
• What question do I ask first when someone comes to me? The entry point of the procedure.
• Where do I regularly get it wrong myself? The boundary of the method.

What to do with what you could not explain

Mark it, don't invent it. "Here I decide from experience and cannot name what I go by" is a working entry: it shows the reader that this point needs a person, not an instruction.

An invented explanation is worse than a gap. It creates confidence where there should be none, and it breaks the first time it is carried into someone else's context.

A rule and its mechanism

Why a rule ends up looking obvious

The most common damage when knowledge is carried over: the rule arrives without the explanation of why it works, and turns into a platitude.

"Write about the client, not about yourself" is a platitude.

"Write about the client, because nobody chooses in a vacuum. They are comparing you against three others, and the one who wins is the one in whose text they recognised their own situation" is a rule with a mechanism.

The second gets applied, the first does not. Not because the first is wrong, but because nothing follows from it about what to do when you meet an exception.

The rule: every prescription carries its mechanism

The formula: what to do, why it works, when it stops working.

The third part is not decoration. It is what makes the rule applicable in a situation the author never anticipated.

If the mechanism is unknown, say so plainly: "the rule reproduces in practice, the explanation is unknown." That beats inventing a plausible cause, because an invented mechanism creates confidence in exactly the cases where the transfer fails.

How to tell a rule from an observation

Observations are useful and worth keeping, but mark them as observations. An observation presented as a rule breaks in the first unfamiliar context, and the method takes the blame.

Negative rules

The most valuable and least accessible part of any expertise. The expert does not state them: to them they are obvious, and the obvious goes unsaid.

Why they are stronger than prescriptions. A prescription describes one path out of many. A prohibition cuts off a whole class of paths at once, which is why it transfers to situations the author never foresaw. A method built from ten "do this" is weaker than one built from five "do this" and three "never do that".

Where to look for them

The question that draws them out of a live expert: "what do you refuse to do that plenty of people do, and why?" It works better than a direct "what shouldn't be done", because it rests on specific observable behaviour.

Telling a real prohibition from a matter of taste

A real prohibition carries a mechanism of damage: it is clear what breaks and why. "I don't do that, I don't like it" is taste, and it enters the method only as a marked preference.

The check: can the expert name a case where breaking this prohibition led to specific harm? If yes, it is a prohibition. If not, it is a preference.

A prohibition needs grounds in the source

⚠️ A separate rule, because an invented prohibition costs more than an invented explanation. An explanation simply fails to help. A prohibition takes away an option that might have worked.

What counts as grounds: a counterexample in the source, a caveat from the author, a described case of failure, or damage that is named outright. What does not count: the prohibition looking reasonable.

What to do when there are no grounds. Don't ask the user, who usually knows no more than you do, especially with someone else's material. Rephrase it as a recommendation about order, or leave it out.

The right-hand column carries the same practical instruction and takes nothing away.

Tell an inference from a guess. They look alike from outside.

Inferences cannot be forbidden, since extracting a method is itself an act of filling gaps. What is forbidden is passing a guess off as an inference, and above all when the guess is shaped as a prohibition.

A numeric threshold is the same error, but more dangerous

⚠️ A number that is not in the source does not go into the file as a threshold. "Fewer than several tens of thousands of people", "longer than three months", "cheaper than fifteen percent": if the author never named those quantities, they are invented, however reasonable they look.

Why it is worse than a prohibition. A prohibition reads as a judgement and can be disagreed with. A figure reads as the result of a measurement. There is nothing to compare it against, nothing to refute it with, and it starts cutting off decisions immediately.

What to write instead: a qualitative condition with a mechanism, such as "the audience is too small for the algorithm to gather enough volume to learn from". The instruction survives, the false precision disappears.

If a number really is needed, mark it as an estimate inside the file itself, not only in the report to the user. The report gets read by a person once; the file gets read by the model every time.

How to write them

A prohibition without an explanation does not get followed. The formula is the same as for a rule: what not to do, what breaks if you do, whether there are exceptions.

The third part is required. Absolute prohibitions are rare, and one presented as absolute where exceptions exist will be abandoned wholesale at the first encounter with an exception.

Level of abstraction

Two opposite errors, both of which make a method useless. The work sits between them.

How to calibrate

Climb until the rule starts lying. Then come down one step.

1. State the rule at the level it is given at in the source.
2. Widen it: remove one condition and check whether it still holds.
3. Repeat until you find the condition without which the rule breaks.
4. Put that condition back. That is the right level.

A worked example. "Publish on Tuesdays" is narrow, tied to one platform and one audience. Remove the day: "publish regularly at the same time" still holds. Remove the regularity: "publish" has lost its meaning. So regularity is the condition that matters, and the day of the week is the author's particular. The rule: publish on a predictable rhythm, with the exact time chosen for the audience.

The sign you have hit the right level: the rule transfers to neighbouring cases without rewriting, and yet you can still name a case where it is wrong.

When there is little material

One conversation, half an article, three cases from practice. This comes up more often than a full body of material.

Working is fine. Lying about completeness is not.

What to do explicitly: mark the zones built on a single case inside the file itself. "Based on a single observation, needs verification" is a working entry, not an admission of weakness.

What not to do: fill the gaps with industry commonplaces. A skill where half is the author's own method and half is industry consensus with nothing marking the difference is worse than an honestly incomplete one, because the user cannot tell them apart.

When it is better to wait for material: if not a single fork reconstructs from what you have, there is nothing to assemble. Say so plainly and propose what to gather: more cases, a conversation with the person who holds the knowledge, a specific missing piece.

What goes in the "Boundaries" section

A required part of any methodology. The absence of boundaries is not a sign of universality but a sign that nothing has been tested.

What to describe:

Where the method does not work. Direct counterexamples, not hedges of the "it's all individual" kind.

Under what condition the conclusions change. For example: a set of rules derived for a stagnating market, where half of them are unnecessary in a growing one.

What is time-bound. Mark separately any knowledge tied to:

• legislation and jurisdiction;
• specific services, platforms, companies;
• prices, rates, market shares;
• the political situation.

⚠️ A regulation ages differently from a practice. A practice goes out of date gradually and invisibly, which is why the advice for it is "check again". A regulation changes on a specific day: before it the old wording is entirely correct, after it entirely wrong, and there is no "roughly correct" in between.

What follows from this: for knowledge that rests on a regulation, standard, or specification, the file records the revision and the date the method is correct as of. Without that the reader cannot tell whether the file is out of date, and the text itself never shows it. A phrase along the lines of "as of such a date, revision such and such" goes next to the rule itself, not only at the end of the file.

A technique for generalising: take out the mechanics and leave the specifics as illustration. Mechanics do not date; a list of platforms dates within a year. Instead of naming a service, name the function: "a search engine", "a platform with restricted access", "a classifieds aggregator".

The scale the method was tested at. Rules taken from a company of a hundred people do not transfer to a solo worker automatically, or the other way round. Name the scale of the source.

Contradictions in the material

When sources contradict each other

⚠️ First establish whether the sources have a hierarchy. Everything after that depends on it, and the order here is the reverse of the usual one: not "whose arguments are stronger" but "whose source ranks higher".

The order of rank in subjects with a governing rule: the rule itself, then official guidance on it, then establ

…(truncated)