Extract lessons

Anyone running several projects wants the toolkit to get better from each one. This turns a finished session into whatever small, general thing it actually produced, and most often that is nothing.

This is not improve-skill. That one fixes a skill that misbehaved. This one looks for knowledge the toolkit does not have yet.

The rule that makes this worth running

The default outcome is nothing, and that is a success. A skill that finds something every time fills a public repo with one project's anecdotes, and the next person reads them as advice. Expect to extract from maybe one session in four. If you find yourself reaching, stop.

1. List the candidates

From the session, write down every thing learned, in one line each. Include the mistakes, which are usually the best material. Do not filter yet.

Then, for each one, answer the only question that matters first:

Would this still be true for an app that is not this one?

If no, it belongs in the project's own rules file (CLAUDE.md or AGENTS.md) and nowhere else. Write it there and strike it off. This removes most of the list, and removing it is the point.

2. Apply the evidence bar

What is left has to survive a second test, and it is stricter than it looks.

Extract these:

Do not extract these:

• "This worked for us." Six posts, one campaign, one account. A result is not a method, and a stranger acting on your anecdote is the harm this bar exists to prevent.
• Anything still contested. If the session ended with two sources disagreeing and no measurement settling it, it is not knowledge yet. Leave it in the project's research notes.
• Anything that only makes sense with your numbers in it. If stripping the project's metrics leaves nothing, there was nothing.

A useful phrasing test: could you write it as a trap or a formula with no reference to your app at all? If not, it fails.

3. Find each survivor a home

When several lessons have nowhere to live, that is the finding. It means the toolkit has a gap, not that the lessons are weak. Say so plainly rather than forcing them into the nearest skill that half fits.

4. A new skill, or a different repo

Before writing a new skill, ask what the cluster is actually about.

This repo is about getting an app shipped and found. A cluster inside that subject becomes a skill here.

A cluster that is its own domain does not. Content marketing, hiring, fundraising, customer support: each is a field with its own practice, and absorbing one into a shipping toolkit makes both worse. The honest move is to say: "this is three skills' worth of a different subject, it wants its own repo." Then stop and let the user decide. Never create a repo unprompted.

Two signals that it is a separate domain rather than a skill here:

• Somebody could want this toolkit and not want that one at all.
• Explaining the cluster needs vocabulary this repo's other skills never use.

If it IS a skill here, write it the way the others are written: a short description that says when to use it, numbered steps, tables over prose, and the honest limits stated in the skill rather than discovered by the user.

5. Strip the project out

The repo is public. Before anything is committed, remove:

• The app's name, the user's name, handles, URLs and repo paths
• Every metric: revenue, user counts, view counts, conversion rates
• Screenshots, file paths and command output that identify the project
• Anything a competitor would find interesting

The lesson has to stand with all of that gone. If it does not, it was step 2's "only makes sense with your numbers in it" and should not have reached here.

6. Open the pull request

1. Add one line under the unreleased heading in CHANGELOG.md.
2. Add the skill to the table in README.md if it is a new one.
3. Run node scripts/validate.mjs and fix what fails. It checks, among other things, that no Markdown file contains a long dash.
4. Commit only what you changed, push the branch, open a pull request following .github/pull_request_template.md.

If you cannot push to the repo, fork it and open the pull request from there.

7. Tell the user

A few lines, and be specific about what you threw away:

• What you extracted, and where it went.
• What you considered and rejected, and why. This is the most useful half. "Four things looked like lessons and were one project's results" tells the user their session was normal, not empty.
• The pull request link.
• If a cluster suggested a new repo, say so as a question, not a decision.

Then note that the project picks the change up on its next sync, and that the synced copy under .claude/skills/ must never be edited by hand.