Personal kit and `/ak-dogfood`: tweak your own skills without an update wiping them out

Article 20 in the AgentKit v3 onboarding series. About a 10 minute read. This one goes deeper into the personal kit introduced in article 5.

Anyone who has used a kit for a while hits this: the ak-plan skill works fine, but your team has one convention it keeps forgetting. You open SKILL.md, edit it, and it runs great. Next week you run ak update and your edit vanishes 😂

v3 solves this with two things:

• Personal kit: a layer that is "yours", sitting on top of the upstream kit. When the upstream kit updates, you rebase instead of redoing your edits from scratch.

• /ak-dogfood: reviews the session you just finished, points out which skill made the agent go in circles, then proposes a fix at exactly that spot.

Put the two together and you get a loop: work → dogfood → record the fix in your personal kit → keep working with a better skill.

🧪 Every ak skills kit ..., ak skills improve and ak skills evolution ... command in this article is preview in ak 3.0.0. Publishing/syncing to SkillX is still behind a server-side flag (see article 5, section 5). Every command below is pasted from the real --help of version 3.0.0.

1/ Three kinds of skill, three ways to edit

Before editing any skill, ask one question: whose skill is this? The answer decides where you are allowed to edit.

For ak-* skills specifically: if you edit files directly in ~/.claude/skills/ak-plan/, the next update treats them as user-modified files and you have to sort it out yourself. The personal kit exists so you don't have to play that game.

2/ What a personal kit is, in plain words

Picture the Engineer kit as a printed book. The personal kit is a stack of sticky notes you put on top: on any page you want to change, you stick a note, and the original book stays intact. When the publisher prints a new edition, you peel the notes off and stick them on the new one (rebase). Where a page changed a lot, it reports a conflict and you decide.

Concretely, a personal kit is a folder AGENTKIT_HOME/kits/personal/<name>/ with a personal-kit.yaml file:

schema: agentkit.personal-kit/v1
name: mine
extends:
  - kit: engineer
    version: 0.2.0          # exactly one version, no ^ or ~ ranges
overlays:
  - identity: "@agentkit/plan"
    dir: overlays/plan
forks:
  - from: "@agentkit/brainstorm"
    identity: "@local/my-brainstorm"
    alias: my-brainstorm    # must not start with ak-
    overlay: overlays/my-brainstorm

Two ways to customize:

• Overlay: edit a skill that belongs to one kit (for example ak-plan in Engineer). The skill name stays the same.

• Fork: for shared skills (skills in kits/core, or present in more than one kit). Overlays are not allowed on these, because editing one would edit it for the other kits too. You fork it under a new name without the ak- prefix, for example my-brainstorm.

The overlay folder only contains what you changed, in 4 forms:

• files/<path>: whole-file replacement content;

• patches/<path>.diff: an exact unified diff;

• delete.txt: files to delete;

• modes.txt: file permission changes.

Any file identical to the original is skipped. Unknown file names, symlinks and anything that is not a regular file are rejected, so a typo can't silently lose your edit.

3/ Create and update a personal kit, step by step

Step 1: create the kit. The kit must extend exactly one version of an upstream kit.

ak skills kit init mine --extends engineer@0.2.0 --dry-run   # preview the manifest first
ak skills kit init mine --extends engineer@0.2.0

If the mine folder already exists, the command refuses and overwrites nothing.

Step 2: add an overlay or fork by editing personal-kit.yaml and creating the overlay folder as in section 2. The easier way is to let /ak-dogfood do it for you (section 4).

Step 3: preview.

ak skills kit inspect mine
ak skills kit status mine

Step 4: apply to the runtime.

ak skills kit apply mine --dry-run
ak skills kit apply mine

apply pushes all of the kit's skills into the runtime's skill folder (Claude Code, Codex...). If the plan has anything that needs a second look (changed scripts, permissions, license...), it only runs when you pass --plan <token> taken from the --dry-run output. In other words: a sensitive change has to be seen by you before it is applied.

Step 5: when the upstream kit ships a new version, rebase.

ak skills kit rebase mine --to engineer@0.3.0 --dry-run

Conflicts are written out explicitly, and it never picks a winner on its own. After the rebase, remember to update version in personal-kit.yaml, because apply refuses if the manifest still pins the old version (error personal_kit.pin_behind).

Slipped up? Go back:

ak skills kit revisions mine
ak skills kit rollback mine --dry-run
ak skills kit rollback mine

4/ /ak-dogfood: turn mistakes in a session into skill fixes

"Dogfooding" means eating your own dog food, i.e. using your own product to find where it is weak. /ak-dogfood does exactly that with skills: at the end of a session, it re-reads the session that just ran and answers: which skill cost time, cost tokens, forced a redo, or got corrected by you?

For each such spot, it proposes the smallest fix at the exact line in the skill, with evidence, expected benefit and risk.

Modes

--apply and --ask don't go together. If you type both, it picks --ask, the safer one.

It classifies the mistake before proposing anything

Not every mistake is the skill's fault. Each finding falls into one of four classes:

1. The skill is faulty (wrong, missing or ambiguous instructions);

2. The agent did something wrong that the skill could have prevented;

3. Environment or tool failure (network drop, broken CLI...);

4. A one-off.

Only classes 1 and 2 become skill-fix proposals. Classes 3 and 4 get a single logged line. I like this part: it doesn't pin everything on the skill and then edit randomly.

Where does the fix go?

This is where it connects to the personal kit. For ak-* skills where you don't have push access to the AgentKit repo, dogfood takes the personal fork path:

# 1. get the brief: evidence with sensitive info redacted + the overlay layout
ak skills improve ak-plan --session latest --dry-run --brief --json

# 2. the agent writes an overlay draft into an empty folder, then compile and score it
ak skills improve ak-plan --session latest --candidate ./draft --dry-run
ak skills improve ak-plan --session latest --candidate ./draft

# 3. review and apply the candidate to the personal kit
ak skills evolution list
ak skills evolution apply <candidateId>          # preview
ak skills evolution apply <candidateId> --yes    # apply for real

# 4. push the personal kit into the runtime
ak skills kit apply mine

To undo: ak skills evolution rollback <candidateId>.

A few things worth the money on this path:

• ak calls no model. Your agent writes the draft, while ak only compiles, checks and scores it offline, with deterministic results.

• Real scoring, not gut feeling. The candidate is compared with the original on the very tasks in the evidence. Other skills are used as a control, so the fix doesn't break something elsewhere. The result is one of four: improved, inconclusive, regressed, blocked. The last two can't be applied.

• Security is a hard block. A draft containing a secret or an absolute path on your machine is rejected outright. Changing scripts, permissions or license becomes a point that needs review.

• Redaction is best-effort. --help says it plainly: secrets in unusual formats can still slip through, so read the preview before sharing it with anyone.

• Recorded does not mean applied. improve only records the candidate. It reaches the personal kit through evolution apply, then the runtime through kit apply. Publishing to SkillX is yet another separate command: ak skills kit publish mine --private.

If you are a contributor with push access to the AgentKit repo, dogfood takes the contributor path: edit the source directly in kits/, verify, and open a PR into dev. Push access is actually checked with gh, not guessed.

5/ The loop I use every day

work with the agent
  → end of session: /ak-dogfood --ask
  → pick the proposals worth applying
  → candidate goes into the personal kit "mine"
  → ak skills kit apply mine
  → next session, the skill is better

Some lessons:

• Don't --apply from day one. Run dry-run a few times to get used to how it thinks, then move to --ask. Save --apply for when you trust it.

• One mistake isn't worth fixing a skill for. Recurring ones are. Every weekend, run --all --since <last week> to see which mistakes repeat the most.

• Keep the personal kit thin. The fewer overlays, the lighter the rebase. If you find a fix that helps everyone, open an issue or become a contributor so it lands in the upstream kit.

Wrap-up

1/ Don't edit installed ak-* skill files directly. Record the fix in your personal kit.

2/ Personal kit = a personal-kit.yaml manifest + overlays (kit-specific skills) or forks (shared skills, new name without ak-).

3/ Lifecycle: init → inspect → apply → rebase when the upstream kit ships a new version → rollback when you slip.

4/ /ak-dogfood reads the session, classifies mistakes, and proposes the smallest fix. By default it only proposes.

5/ Fixes go through ak skills improve → evolution apply → kit apply, scored offline and with secrets blocked. All of it is still preview in 3.0.0.

Sources

• ak skills improve --help, ak skills evolution --help, ak skills evolution apply --help, ak skills kit init|apply|rebase|rollback|revisions|publish --help (ak 3.0.0, run in a temporary HOME).

• Skill ak-dogfood v1.2.0: SKILL.md, references/apply-lanes.md.

• Personal kit spec: agentkit/docs/specs/personal-kit-contract.md.