Customise a sourced skill

You've added someone else's skill — airskills add chrismdp/code-review — and it works, but you want to tweak it. Maybe you want different defaults, or to add a step that's specific to your workflow.

You can. Editing a sourced skill locally is fine and supported. Your local copy becomes your customised version — a tweaked variant of the original. Customisation is a first-class flow in airskills, not a workaround.

It stays one skill on your machine: the original, with your changes as an overlay. On push, airskills transparently backs your edits up to a hidden copy in your account (so they can never be lost — even from a fresh machine) and asks the only question that matters: suggest your edits to the owner? (Headless — an agent, a cron job — the question is deferred rather than answered for you; push --force-suggest submits it without asking.) If you're an owner or admin of the skill, your push just updates it in place. You never need to know the backup exists; it retires itself when your edits land upstream, and if you ever lose access to the original, it surfaces as a personal skill so your work survives.

Four actions you can take with a sourced skill

Action	What it does	When
Customise	Edit local files	You want changes; this is just normal editing
Incorporate	Have your agent read the new version of the original and bring across only the parts you want	The author has improvements you want — but not all of them
Resolve	Acknowledge the original's current version and stop the prompt	You've reviewed and decided to stay on your customised copy
Suggest	Ask the author to consider a change. They decide whether to take it.	You want to contribute back, not just keep it private

These are independent. You can resolve without suggesting. You can suggest without resolving. You can incorporate one part of the original and stay on your customised copy for the rest.

What happens when the original changes

The author of a sourced skill keeps publishing. At some point they'll release a new version while you have local edits. airskills detects this on your next sync and surfaces a modified, pending review state.

The CLI deliberately doesn't try to combine the two versions automatically, and it doesn't make you read a line-by-line comparison. Skills aren't code — a mechanical diff is the wrong way to think about what changed and what to keep. Your agent reads both versions and explains what the author changed in plain language; you decide what to bring across. See incorporation for the full pattern.

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
  Acknowledge (keep your customised copy):      airskills resolve heartbeat
  Incorporate some, keep some:                  edit local, then airskills resolve

The third option is the customisation power move. See Incorporate upstream changes for how that flow works in practice.

States: pending vs resolved

Your customised skill is always in one of two states once it has diverged from the original:

• modified, pending review (modified* in airskills list) — there's a newer version of the original you haven't acknowledged yet. The CLI prompts you on every sync until you act.
• modified, resolved (modified in airskills list) — you've reviewed against the original's current version and chose to stay on your customised copy. Quiet until the original moves again.

airskills resolve flips you from pending → resolved. The original changing flips you back from resolved → pending. That's the loop.

Resolve doesn't care what you did locally

airskills resolve is purely an evaluation ack. It records "you've seen the original at version V" — nothing more. What you did with your local copy in the meantime is your business:

• Took nothing from the original, kept your customised copy as-is → resolve.
• Took some of the original's ideas (manually or with AI assistance), edited your local accordingly → resolve.
• Took the whole original, replacing your customised copy → that's an airskills add <owner>/<skill> --force, which makes you synced. No resolve needed.

The CLI doesn't try to be clever about which case you're in. It just acknowledges the original's version when you ask it to.

Suggest: contribute back to the author

Resolve is for you. Suggest is for the author.

airskills suggest chrismdp/code-review --message "Could we support Rust?"

A suggestion is a plain-text message, not a proposed change set. The author sees it as a request: "Alice asked for X." They decide whether to act on it — it's their skill, their call. Your customised copy is unaffected; sending a suggestion doesn't change your files.

You can suggest before resolving (want their input first) or after (decided your customised copy is the answer for you, but want others to benefit too). They're independent.

When customisation isn't right

If you find yourself maintaining a heavily-modified copy, ask whether you should own a version instead. Three paths:

• Keep the customised copy — you want their improvements but with your changes on top. The flow described above.
• Own a separate copy — copy the skill's folder to a new name, update the name: field in its SKILL.md, and push. You get an independent skill in your namespace with no link to the original: edits push straight to it, no suggestion loop. (There is no fork command — forks only exist as the automatic backups described above.)
• Take ownership of the original — have the current author transfer it to you. Heavy step; rare.

If you're doing something the original genuinely doesn't aim to support ("their skill is for Rust devs, I want a Python variant"), copy and own. If you're tweaking around the edges, customise and resolve.