Start from a repeated real workflow

The fastest way to write a weak skill is to ask an AI to invent “best practices” for a job it has never done. You get sentences that sound responsible and change nothing about the work.

Start from a real task instead.

Find the workflow

Pick something you did more than once. For this course the running project is a release-readiness skill: it inspects a repository before a release and tells you whether it’s safe to ship. It never publishes anything.

If you have a project with releases, use it. If you don’t, imagine a small one: a test command, a build command, a changelog, a few deployment notes. Then walk the path from “we want to release” to “we have enough evidence to decide”.

Collect the raw material

Go through what you actually did, not what you think you should have done. Good places to look:

• shell history, for the commands that worked
• Git log, for what changed right before a release
• review comments, for what a colleague caught
• incident notes, for what went wrong after a release

Those last two are gold. They record decisions made under pressure, and that’s the knowledge an agent can’t infer.

A typical pre-release history, cleaned up, looks like this:

git status
npm test
npm run build
git diff --stat main
head -20 CHANGELOG.md

Nothing fancy. But the order matters, and so does the reason behind each step.

Mark where the agent would guess wrong

Now read that list again and ask: where would a smart agent still make a mistake?

A few common ones:

• it runs npm test when the project’s real test command is npm run test:ci
• it treats a build warning as a failure, or a failure as a warning
• it includes an untracked .env file in the release
• it pushes before anyone approved

Those corrections are the valuable part of the skill. The happy path is easy. The mistakes are what you’re paying for.

Write the extraction note

Don’t write the skill yet. Write a one-page note with four headings:

Successful steps:
Corrections:
Required context:
Proof:

Under Proof, write what convinced you the release was ready. “Tests passed” is not enough. “npm test exited 0 with 142 tests passing” is.

Try this with a release you did in the last month. If you can’t fill the Corrections section, you haven’t looked hard enough. Every release has at least one thing you’d do differently.