Incorporate updates from the original

The original has a new version. You've customised. You like some of the new updates but want to keep your local edits too. Incorporation is how you bring across the parts you want.

This is one of the core ideas in airskills. Skills are not code. The CLI does not try to combine both versions automatically, and it does not make you pick through a line-by-line comparison. Instead, your AI agent reads both versions, explains what changed in plain language, and you decide what — if anything — to bring in. The CLI's job is to put both versions in front of your agent. Yours is to decide what stays.

Why no automatic combining

Skills are instructions written for an agent. A line-by-line comparison doesn't capture what matters — intent does. "The author added a snooze feature and rewrote the way it handles login" is the level you want to think at, not "lines 40 to 58 changed." A mechanical tool can't tell you which of those is the upgrade you want and which is the change you'd rather skip. Your agent can.

That's why we don't try. The CLI puts both versions in reach, your agent reads them like a person would, and the decision stays with you.

When incorporation kicks in

It's the third option on the action menu when a customised skill is in modified, pending review state — i.e. the original has moved since you last resolved:

heartbeat — customised copy of chrismdp/heartbeat. Original moved
1.2.0 → 1.3.0 since you last resolved at 1.2.0.

  Take all of the original, drop your edits:    airskills add chrismdp/heartbeat --force
  Keep your customised copy:                    airskills resolve heartbeat
  Bring across part of the update:              ask your agent (see below)

Incorporation lives between the first two. It's "not all of the original, not none — the right combination for me." The way you do it is to tell your agent what to do — see the flow below — and let airskills sync sort out the mechanics.

The flow

You don't drive this by hand. You tell your agent to run airskills sync and incorporate anything pending. The agent reads the CLI's output (which already names where each version lives), reads both versions, makes the changes you asked for, and runs airskills resolve at the end. The whole loop is one instruction from you.

What the agent does under the hood:

1. Runs airskills sync. The CLI surfaces any modified* skills and saves the upstream version into a temporary folder so it sits on disk next to your local copy.
2. Reads the temporary folder and your local skill folder, side by side, and works out what changed in plain language — what the author changed and why it might matter to you, not line numbers.
3. Updates your local files according to whatever you said ("take the snooze feature, skip the login change").
4. Runs airskills resolve <name> so the CLI knows you've seen this upstream version and stops prompting until the next one.

You can also stay where you are: tell the agent "run sync and acknowledge anything pending without changing my files" and it will just resolve, leaving your customised copy as-is.

What the conversation with your agent looks like

You stay at the level of intent:

Run airskills sync. For anything modified*, take the snooze feature from heartbeat 1.3.0 but skip the login change — it gets in the way of my Slack bit. Then resolve.

Or even shorter, if you trust the agent's judgement:

Run airskills sync and incorporate anything pending into my customised skills. Keep my local edits where they conflict.

Because skill files are written in plain language — instructions, not code — the agent can reason about what each change is for, not just where it sits in the file. That's why incorporation works as a conversation rather than a mechanical merge.

Suggest the change back

If incorporation makes you think "actually, the original should have done this differently" — say so. Tell your agent:

Send a suggestion to the heartbeat owner — the new login bit in 1.3.0 makes it harder to plug in your own integration; could they leave a hook for that?

The agent runs airskills suggest for you. A suggestion is a plain-text message to the skill's owner. They decide whether to act on it. Your local copy is unaffected. See Customise a sourced skill.

If you just want the upstream version

The only time you'd skip incorporation is if you've actively decided you don't want your local tweaks anymore. In that case airskills add <owner>/<skill> --force overwrites your copy with the upstream version, no agent conversation needed. (Not pull --force — pull only resolves conflicts against your own account's copy; taking an upstream's bytes always goes through add.)

Otherwise, just ask the agent. Whether the upstream change is one sentence or a full rewrite, the agent does the lifting; there's no "too small to be worth it" case.

Resolve always finishes the flow

Whatever you do during incorporation, end with airskills resolve <name>. That's how the CLI knows you're done evaluating against the current version of the original. Skip the resolve and the prompt stays — every future sync re-surfaces the same conflict, even if your local files now match.