Your first skill: turn one fix into forever
The fastest way to feel the value. Solve one annoying thing once, capture it as a skill with real structure, and watch the next agent skip the struggle entirely. A full worked example, plus what makes a first skill stick.
Reading about memory is abstract. Feeling it is not. Do this exercise once with a real problem from your own work and the entire product clicks into place, because you will have personally watched the second agent be better than the first one purely because the first one learned.
This guide is the full loop, start to finish, with a concrete example. Budget about ten minutes the first time. Every time after that it is closer to thirty seconds.
Why a skill is not a note
Most memory tools store text and hope it is findable later. A skill is different in kind: it is an executable process with provenance. It carries the trigger that should fire it, the ordered steps to follow, the checks that prove it worked, and the reasoning that makes it survive small changes in the world. That structure is what lets a future agent load it before it starts reasoning, instead of stumbling onto a stale note halfway through.
The practical consequence: a good skill makes the next attempt cost less context, not more. A bad "skill" is just a paragraph that adds noise. The structure below is how you stay on the right side of that line.
Step 1: pick something that actually bit you
The best first skill is a fix that took you more than one try. Friction is the signal. Good candidates:
- A flaky environment variable or config that breaks deploys until you set it just so.
- A migration or release step everyone on the team forgets in the same place.
- A debugging path that looked like one thing and turned out to be another.
- A non-code example: a sales objection with a known winning answer, or an onboarding step new hires always miss.
Avoid, for your first one, anything you will genuinely never see again. A skill earns its keep through reuse; a one-off has nothing to compound.
Step 2: let Cognition draft it
When a reusable workflow shows up in real work, Cognition will offer, exactly once, to capture it. You can also trigger it yourself at any moment in plain English:
"turn this into a skill"
It drafts a structured SKILL.md with four sections. Here is what a real one looks like for a deploy gotcha, so you can see the shape rather than just the labels:
# When to fire Deploying the API and the build fails on a missing DATABASE_URL even though .env looks correct. # Steps 1. Confirm the var is in the deploy environment, not just .env (the CI runner does not read .env). 2. Set it in the platform dashboard under Settings > Env. 3. Redeploy; the build picks it up at runtime, not build time. # Checks - Build log shows the migration step connecting, not ECONNREFUSED. - `/health` returns 200 within 30s of deploy. # Why it works The failure looks like a code bug but is an environment boundary: .env is local-only. The runner needs the var set in the platform, and it is read at runtime, so a rebuild without the var set still fails the same way.
Step 3: tighten the trigger
This is the one part worth spending an extra minute on. The trigger is how a future agent recognizes the moment to load this skill. Too vague ("deploy problems") and it either never fires or fires on everything. Too narrow ("the exact error string from last Tuesday") and it never matches again. Aim for the recognizable situation: the symptom plus the context that makes it specific.
A good test: read only the "When to fire" section and ask, would an agent who has never seen this problem know that now is the time? If yes, the trigger is doing its job.
Step 4: approve it
Nothing is saved without your explicit yes. Drafts live in your private workspace until you approve them, so a half-baked idea never leaks into the team brain. This is the governance gate that keeps recall trustworthy, and it is not optional, which is the point.
Read the draft, fix anything wrong, and approve. It saves with your name attached as the author, so when a teammate's agent uses it later, the attribution travels with it: they know whose judgment they are applying and when it was last confirmed.
Step 5: watch it fire, then close the loop
Next session, hit the same situation. The agent loads the skill before reasoning, applies the steps, and runs the checks. Then do the one thing most people skip and that matters most:
"that skill helped" → cognition_report_skill_outcome
That single signal is the training data for the whole ranking system. A skill three teammates confirm outranks one nobody has used since you wrote it. Skills that stop working decay and retire. The loop only compounds if the outcome comes back.
Common first-skill mistakes
- Capturing generic advice. "Write tests" is not a skill, it is a fortune cookie. A skill repeats a specific workflow.
- Skipping the "why." Without it, the skill breaks the first time a detail shifts, because the next agent cannot adapt it.
- Never reporting outcomes. An unconfirmed skill is invisible to the ranking; it might as well not exist.
- Putting secrets in it. Summarize sensitive context. If a draft contains PII, a privacy review redacts it before saving.
Do not try to make the first one perfect. A small, true skill that gets reused beats a grand one that never fires. You can refresh it in one command the moment it goes stale.
next steps