Remove deleted skills from the profile

Remove skill resources from the Machine Profile file when you delete their directories on the Source Machine, once or while you work.

When you delete a skill directory on the Source Machine, the Machine Profile still declares it, and publishing fails because its source is missing. canonfig source reconcile-skills removes those skill resources from the profile file.

It edits the profile file only. It does not publish a Profile Revision, change any Follower Machine, or delete any skill directory. Follower Machines lose the skill only after you publish the edited profile.

Before you start

reconcile-skills removes a resource only when it recorded the skill's directory while that directory existed. Record your directories once, as described in the next section, before you delete anything. A directory that is missing the first time Canonfig looks, for example because of a typo in source, is never treated as deleted.

A skill resource is in scope when its SKILL.md and every other file it lists come from source paths in one directory inside the profile file's directory, for example:

a skill resource in ~/canonfig.profile.jsonc

{
  "id": "claude-review-skill",
  "kind": "skill",
  "target": "~/.claude/skills/code-review",
  "spec": {
    "kind": "skill",
    "name": "code-review",
    "files": [{ "path": "SKILL.md", "source": ".claude/skills/code-review/SKILL.md" }]
  },
  "verify": { "method": "digest" }
}

Canonfig skips, and never removes, a skill that uses inline content, symlinkTo, files from more than one directory, or a source outside the profile file's directory. The output counts these as "outside automatic scope". Remove them by hand.

When several resources use the same source directory, as the Claude Code and Codex copies of a skill do in Sync your first two machines, Canonfig removes all of them together.

Record your skill directories

Do this once, while every skill directory still exists. On the Source Machine:

canonfig source reconcile-skills --profile-file ~/canonfig.profile.jsonc
canonfig source reconcile-skills --profile-file ~/canonfig.profile.jsonc --apply

The first command is a preview and writes nothing. The second records the directories it found:

Applied: 0 removed resource(s), 1 observed, 0 outside automatic scope. No publication.

Remove a deleted skill from the profile

Stop other writers first

Close editors and stop any job that writes the profile file or restores skill directories before you run --apply. Canonfig's lock only keeps two reconcile-skills processes apart. An edit saved at the same moment can be overwritten.

Delete the skill directory, for example ~/.claude/skills/code-review.

Preview the change. --json lists the resource IDs:

canonfig source reconcile-skills --profile-file ~/canonfig.profile.jsonc --json

{"schema":"canonfig.cli/v1","command":"source.reconcile-skills","status":"success","exitCode":0,"message":"Source skill reconciliation preview","data":{"applied":false,"observed":[],"removed":["claude-review-skill"],"skipped":[]}}

Apply it:
```
canonfig source reconcile-skills --profile-file ~/canonfig.profile.jsonc --apply
```
```
Applied: 1 removed resource(s), 0 observed, 0 outside automatic scope. No publication.
```
Canonfig saves the previous profile as ~/canonfig.profile.jsonc.skills-backup-<id>.jsonc, then removes the resource entries. Comments and every other resource stay as they were. With --json, the backup field gives the backup's path.
Compare the backup with the edited profile, then publish.

At their next apply, Follower Machines remove the skill only if it still matches what Canonfig last applied there. A skill someone edited on a Follower Machine stays.

Keep the profile in step while you work

To remove skills as you delete them, run a watcher in a terminal you keep open:

canonfig source reconcile-skills --profile-file ~/canonfig.profile.jsonc --apply --watch

It checks every 5 seconds; --interval 60 changes that to any whole number of seconds from 1 to 86400. Press Ctrl+C to stop it. It runs only while that terminal is open: Canonfig installs no background service for it. It stops at the first error, so check the terminal after you delete a skill.

The warning above applies for as long as the watcher runs.

Files kept next to the profile

File	Purpose
`<profile>.skills-observed.json`	The skill directories Canonfig has recorded.
`<profile>.skills-reconcile.lock`	Present while a run with `--apply` is writing.
`<profile>.skills-backup-<id>.jsonc`	The profile as it was before each edit.

The files are readable only by you. Keep them private, and do not commit them or copy them to another machine. Delete old backups once you have published.

If something fails

When reconcile-skills stops, the profile file is unchanged unless the message says otherwise.

Message	Cause	Fix
"Missing skill has no matching prior observation, its profile declaration changed, or its parent changed; nothing was reconciled" (exit 4)	A skill directory is missing, and Canonfig cannot prove you deleted it: it never recorded that directory, you edited the resource entry after it was recorded, or the parent directory was replaced or unmounted.	Fix the `source` path, mount the parent again, or remove the resource from the profile by hand.
"SKILL.md is missing but its directory remains; this is not an unambiguous skill deletion" (exit 4)	Only `SKILL.md` was deleted.	Delete the whole skill directory, or restore its `SKILL.md`.
"Skill parent directory is unavailable or unsafe; nothing was reconciled" (exit 4)	The directory that contains the skill is missing or is a symlink.	Restore it.
"Skill source is no longer a regular directory; nothing was reconciled" (exit 4)	The skill path is a file or a symlink.	Restore the directory, or remove the resource by hand.
"Another reconciliation or interrupted operation holds the profile lock; inspect it before removing a stale lock" (exit 4)	Another `reconcile-skills --apply` is running, or one was interrupted.	If none is running, delete `<profile>.skills-reconcile.lock` and run the command again.
"Profile or observation state changed during reconciliation; nothing was written" (exit 4)	Something else wrote the profile while Canonfig worked.	Stop it and run the command again.
"A removed skill reappeared; nothing was written" (exit 4)	The directory came back before Canonfig wrote the profile.	Run the preview again.
"Observation state belongs to a different profile; inspect it before initializing a new one" (exit 4)	The profile's `id` changed since the directories were recorded.	If the change is intended, delete `<profile>.skills-observed.json` and record the directories again.
"Authored profile is invalid (including resource dependencies); inspect it locally before reconciliation" (exit 2)	The profile file does not parse or validate, or another resource's `dependsOn` names a skill Canonfig would remove.	Fix the file, or remove that `dependsOn` entry first.
"Skill observation state is invalid; it was not reset or overwritten" (exit 2)	`<profile>.skills-observed.json` is damaged.	Delete it and record the directories again while they all exist.
"Profile was updated and backed up at `<backup>`, but removed skill claude-review-skill reappeared during commit; observation state was not refreshed. ..." (exit 3)	The profile was edited, but the skill directory came back at the same moment. Canonfig does not restore the backup for you.	Compare the backup with the profile and decide which to keep before you run the command again.
"Profile was updated and backed up at `<backup>`, but observation refresh failed; inspect before retrying" (exit 3)	The profile was edited, but the record of directories was not updated.	Check the profile against the backup, then run the command again.
"--watch requires explicit --apply", "--interval requires --watch", or "--interval must be whole seconds from 1 to 86400" (exit 2)	The options do not fit together.	Correct the options.