add skillctl remove and release v0.2.0

Until now there was no way to take a skill back out of a project: an
operator could install, push, and pull, but removing a skill meant
hand-deleting the folder and editing `.skills.toml` by hand. `remove`
closes that gap. It lists every removable skill — installed via skillctl,
created locally, or an orphaned manifest entry whose folder is already
gone — distinguishes the three kinds in the picker, and deletes the
chosen folders while dropping their `.skills.toml` entries. It is
project-only and never touches the library or git.

Minor bump rather than patch because it adds a command. The feature went
through the standard pre-release audit pass (FS-safety, untrusted-input,
logic); the deletion path re-checks for a symlink immediately before
unlinking so a swapped folder can't redirect the recursive delete outside
the project, and `--skill` fails closed on unknown or ambiguous names.

Author: Fernando Pinho

.claude/CLAUDE.md

@@ -23,6 +23,7 @@ Core flows the CLI must support:
 - `push`     — project → library (propagate local edits)
 - `fork`     — project → library as a *new* skill (when local edits should not overwrite the original)
 - `detect`   — project → library (find new skills created locally and offer to add them)
+- `remove`   — project-only (delete installed/local skill folders and drop their `.skills.toml` entries; never touches the library or git)
 
 ## Conventions
 - Prefer typed errors (`thiserror` / `anyhow` at the binary edge) over `unwrap`/`expect` outside tests.

.claude/skills/skillctl-usage/SKILL.md

@@ -40,6 +40,9 @@ Per-command top-level shape:
 
 // detect
 {"command":"detect","target":"…|null","results":[{"name":"…","status":"added|skipped","library_path":"…","local_path":"…","source_sha":"…"}],"commit":{"sha":"…","message":"…"}|null,"summary":{"added":N,"skipped":N}}
+
+// remove
+{"command":"remove","results":[{"name":"…","status":"removed|failed","path":"…","removed_folder":true|false,"removed_entry":true|false,"reason":"…"}],"summary":{"removed":N,"failed":N}}
 ```
 
 Stable rules:
@@ -190,6 +193,26 @@ skillctl detect --tag <tag> [--tag <tag> …] [--all-tags] --target <library-pat
 
 `skillctl detect` walks the current directory for `SKILL.md` files, drops anything already declared in `.skills.toml`, copies the leftovers into the library cache under `<target>/<skill-folder-name>`, single-commits with a `add skill(s): …` message, pushes, and appends the new entries to `.skills.toml`.
 
+### `skillctl remove` — remove skills from the current project
+
+```sh
+skillctl remove --skill <name> [--skill <name> …]
+skillctl remove --all
+```
+
+| Flag | Purpose | Required in non-interactive |
+|---|---|---|
+| `--skill <name>` | Remove a specific skill by name (repeatable). Mutually exclusive with `--all`. Errors if the name is unknown or ambiguous (two skills share it). | Yes, unless `--all` |
+| `--all` | Remove every removable skill found in the project. Mutually exclusive with `--skill`. | Yes, unless `--skill` |
+
+`skillctl remove` is **project-only** — it never touches the library or git. It walks the current directory for skill folders (respecting `.gitignore`, skipping `node_modules`/`target`) and cross-references `.skills.toml`, presenting three kinds of removable skill:
+
+- **installed via skillctl** — folder present *and* tracked in `.skills.toml`. Removing it deletes the folder and drops the entry.
+- **created locally, not tracked** — folder present but absent from `.skills.toml`. Removing it deletes the folder only.
+- **orphan** — a `.skills.toml` entry whose folder is already gone. Removing it drops the stale entry only (nothing to delete on disk).
+
+In each `results[]` item, `removed_folder` and `removed_entry` report which of the two actions actually happened. `.skills.toml` is only rewritten when at least one tracked entry is dropped. In an interactive TTY, a confirmation prompt is shown before anything is deleted; in non-interactive/`--json` mode the explicit `--skill`/`--all` flags are the authorisation. A symlinked destination is never followed — it is treated as "no folder on disk" so removal can only ever drop its manifest entry, never delete through the link.
+
 ## Skill identity
 
 A "skill" is any folder containing a file literally named `SKILL.md`. The skill's `name` comes from the YAML frontmatter `name:` field at the top of `SKILL.md`; if absent, the folder name is used. All `--skill <name>` flags match against this resolved name.
@@ -212,7 +235,7 @@ Errors always go to stderr regardless of mode.
 
 ## Interactive prompt (multi-select with live filter)
 
-When a multi-select prompt opens (in `add`, `push`, `pull`, `detect` without flags or `--all` and a TTY), the prompt has a live filter:
+When a multi-select prompt opens (in `add`, `push`, `pull`, `detect`, `remove` without flags or `--all` and a TTY), the prompt has a live filter:
 
 - **Type any character** — appends to the filter; the list filters in real time on the skill name (substring, case-insensitive).
 - **Backspace** — edits the filter.
@@ -312,6 +335,18 @@ skillctl detect --all --target skills
 skillctl push --skill review --skill security-review --message "polish: tighter reviewer prompts"
 ```
 
+### Remove specific skills from a project
+
+```sh
+skillctl remove --skill claude-api --skill review
+```
+
+### Remove every skill from a project (folders + manifest entries)
+
+```sh
+skillctl remove --all
+```
+
 ## Failure modes worth checking before invoking
 
 1. **No library configured.** Calls fail with `no library configured — run skillctl init <github-url> first`. Run `skillctl init` (or check for an existing library URL via inspecting `~/.config/skills-cli/config.toml` on Linux or the equivalent under `~/Library/Application Support/dev.umanio-agency.skills-cli/` on macOS).

CHANGELOG.md

@@ -6,6 +6,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-05-27
+
+### Added
+
+- **`skillctl remove`** — remove skills from the current project. Lists every removable skill (installed via skillctl, created locally, or an orphaned `.skills.toml` entry whose folder is already gone), with each kind distinguished in the selection list, and lets you pick by interactive multi-select, by name (`--skill <name>`, repeatable), or all at once (`--all`). Deletes the selected skill folders and drops their `.skills.toml` entries; `.skills.toml` is only rewritten when a tracked entry actually changes. The command is project-only — it never touches the library or git.
+
+### Security
+
+- The removal path refuses to follow a symlink: the destination's type is re-checked immediately before deletion, so a folder swapped for a symlink cannot redirect the recursive delete outside the project (closes a TOCTOU window surfaced by the pre-release audit). A symlinked destination is treated as "no folder on disk" — only its manifest entry can be dropped, never deleted through.
+- `--skill <name>` fails closed: an unknown name errors, and a name shared by two skills errors as ambiguous rather than silently deleting the wrong folder. The project root, `.git`, and `.skills.toml` can never be selected for deletion.
+
+`skillctl remove` was reviewed before release with the project's standard multi-agent security audit pass (FS-safety / untrusted-input / logic dimensions). 5 new unit tests; `cargo test`: 158 pass; clippy clean; `cargo audit` clean.
+
 ## [0.1.8] - 2026-05-25
 
 ### Security & robustness

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "skillctl"
-version = "0.1.8"
+version = "0.2.0"
 edition = "2024"
 rust-version = "1.85"
 description = "CLI to manage your personal agent skills library across projects"

Cargo.toml

@@ -39,6 +39,8 @@ pub enum Command {
     Pull(PullArgs),
     /// Find skills created locally and offer to add them to the library.
     Detect(DetectArgs),
+    /// Remove skills from the current project (folder + any .skills.toml entry).
+    Remove(RemoveArgs),
 }
 
 #[derive(Args, Debug)]
@@ -199,6 +201,18 @@ pub struct DetectArgs {
     pub include_vendored: bool,
 }
 
+#[derive(Args, Debug)]
+pub struct RemoveArgs {
+    /// Skill to remove, by name. Repeatable. Mutually exclusive with --all.
+    #[arg(long = "skill", value_name = "NAME", conflicts_with = "all")]
+    pub skills: Vec<String>,
+
+    /// Remove every removable skill found in the project (installed via
+    /// skillctl, created locally, or orphaned .skills.toml entries).
+    #[arg(long, conflicts_with = "skills")]
+    pub all: bool,
+}
+
 #[derive(Clone, Copy, Debug, ValueEnum)]
 pub enum OnConflict {
     /// Replace the existing destination folder with the library version.

src/cli.rs

@@ -5,4 +5,5 @@ pub mod init;
 pub mod list;
 pub mod pull;
 pub mod push;
+pub mod remove;
 pub mod shared;