Skip to content
Skills Library
AI & agents · Automation

safe-remove

/safe-remove

Safely remove plugin assets (skill/agent/rule/script/hook) with dependency detection and reference cleanup. Use when: user says 'remove skill', 'delete skill', 'deprecate', 'clean up unused', or /safe-remove. Not for: code refactoring (use /simplify), feature removal requiring architecture changes (manual).

Licence
MIT
Last repository change
08.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 08.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Safely remove plugin assets (skill/agent/rule/script/hook) with dependency detection and reference cleanup. Use when: user says 'remove skill', 'delete skill', 'deprecate', 'clean up unused', or /safe-remove. Not for: code refactoring (use /simplify), feature removal requiring architecture changes (manual).

Triggers from the description

remove skilldelete skilldeprecateclean up unused
Original author description

Safely remove plugin assets (skill/agent/rule/script/hook) with dependency detection and reference cleanup. Use when: user says 'remove skill', 'delete skill', 'deprecate', 'clean up unused', or /safe-remove. Not for: code refactoring (use /simplify), feature removal requiring architecture changes (manual).

How it works

  1. Input
  2. Workflow
  3. Output Format
  4. Prohibited
  5. References
  6. Examples
Original SKILL.md headings · 166 lines, 785 words
SKILL.md preview
---
name: safe-remove
description: "Safely remove plugin assets (skill/agent/rule/script/hook) with dependency detection and reference cleanup. Use when: user says 'remove skill', 'delete skill', 'deprecate', 'clean up unused', or /safe-remove. Not for: code refactoring (use /simplify), feature removal requiring architecture changes (manual)."
disable-model-invocation: true
allowed-tools: Bash(bash:*), Bash(git:*), Read, Grep, Glob, Edit, Write, AskUserQuestion
---

# Safe Remove

Safely remove plugin assets by discovering dependencies, classifying impact, and executing removal with verification.

## Input

`/safe-remove <type> <name> [--execute] [--dry-run]`

| Argument | Description | Default |
|----------|-------------|---------|
| `<type>` | Asset type: `skill`, `agent`, `rule`, `script`, `hook` | Required |
| `<name>` | Asset name (e.g., `create-skill`, `strict-reviewer`) | Required |
| `--execute` | Apply removal (with AskUserQuestion confirmation) | off |
| `--dry-run` | Output plan only (default behavior) | on |

> If both `--dry-run` and `--execute` are provided, `--dry-run` wins (safe default).

## Workflow

```mermaid
sequenceDiagram
    participant U as User
    participant S as /safe-remove
    participant C as Codebase

    S->>C: Phase 1: Resolve target files
    S->>C: Phase 2: Build reference graph
    S->>S: Phase 3: Classify (BLOCKER/PATCHABLE)
    alt Has BLOCKER
        S->>U: HALT — show blockers with file:line
    else Dry-run (default)
        S->>U: Output removal plan
    else --execute
        U->>S: AskUserQuestion approval
        S->>C: Phase 4: Patch → Delete
        S->>C: Phase 5: Verify
        S->>U: Removal complete
    end
```

### Phase 1: Resolve Target

Validate `<type>` and locate canonical files for the asset.

| Type | Primary Files | Secondary Files |
|------|--------------|-----------------|
| `skill` | `skills/<name>/` (entire directory) | — |
| `agent` | `agents/<name>.md` | — |
| `rule` | `rules/<name>.md` | `.claude/rules/<name>.md` (mirror) |
| `script` | `scripts/<name>.*` | — |
| `hook` | Entry in `hooks/hooks.json` | Hook script file |

If target not found, output error: `Target not found: <type> <name>` and stop.

### Phase 2: Build Reference Graph

Scan the entire codebase for references to the target. Use type-specific patterns from `references/removal-policy.md`.

```bash
# Core scan — find all references
grep -rn "^skills:.*<name>" agents/ --include="*.md"
grep -rn "/<name>" CLAUDE.md .claude/CLAUDE.md CLAUDE.template.md
grep -rn "/<name>" README*.md
grep -rn "/<name>\|<name>" rules/ skills/ --include="*.md"
grep -rn "<name>" hooks/hooks.json
grep -rn "<name>" test/ --include="*.test.js"
```

### Phase 3: Classify Impacts

Apply 2-tier classification per `references/removal-policy.md`:

| Tier | Definition | Action |
|------|-----------|--------|
| **BLOCKER** | Structured runtime binding — removal breaks execution | HALT with file:line details |
| **PATCHABLE** | Prose/documentation reference — safe to auto-edit | Include in patch plan |

### Phase 4: Apply (--execute only)

**Requires AskUserQuestion confirmation before any changes.**

Execution order (patches first, deletes last):

1. **Patch** PATCHABLE references:
   - Remove the skill's entry from `docs/skill-catalog.yml` (tracked CLAUDE files carry no command table since R3; still grep them for prose mentions)
   - Remove/update entries in README.md + locale variants (count + detail row)
   - Update prose mentions in other skills/rules
2. **Delete** target files:
   - For `skill` type: remove entire `skills/<name>/` directory + `test/skills/<name>*.test.js`
   - For `script` type: remove `scripts/<name>.*` + `test/scripts/<name>.test.js`
   - For `hook` type: remove hook script + JSON entry + `test/hooks/<name>.test.js`
   - For other types: remove primary + secondary files per Phase 1 table
   - Remove empty directories after deletion

> Note: `.claude/CLAUDE.md` must be patched directly — do not rely on hook auto-sync for content removal.

### Phase 5: Verify

Run type-specific verification from `references/removal-policy.md`:

```bash
# Verify no residual references (excluding archived docs)
grep -rn "^skills:.*<name>" agents/ --include="*.md"
grep -rn "/<name>" CLAUDE.md .claude/CLAUDE.md CLAUDE.template.md README*.md skills/ --include="*.md" | grep -v "archived/"
grep -n "command: /<name>" docs/skill-catalog.yml   # canonical registration surface — must be empty
```

If residual references found, report them. If clean, output `Verification passed`.

## Output Format

### Dry-run Plan

```markdown
## Safe Remove Plan: <type> <name>

### Target Files (to delete)
| File | Status |
|------|--------|
| skills/<name>/SKILL.md | DELETE |
| test/skills/<name>*.test.js | DELETE (if exists) |

### BLOCKER References (must resolve first)
| File:Line | Pattern | Why |
|-----------|---------|-----|
| agents/foo.md:3 | skills: <name> | Agent skills field |

### PATCHABLE References (auto-fix)
| File:Line | Current | Patch |
|-----------|---------|-------|
| CLAUDE.md:90 | \| /name \| desc \| | REMOVE ROW |
| README.md:308 | \| /name \| desc \| | REMOVE ROW |

### Verdict
- BLOCKER count: N → ⛔ HALT (resolve blockers first)
- BLOCKER count: 0, PATCHABLE count: M → ✅ Ready to execute
```

## Prohibited

- Auto-triggering (always explicit invocation only)
- Deleting without `--execute` flag + user confirmation
- Removing assets referenced in auto-loop rules without user acknowledgment
- Force-deleting when BLOCKERs exist
- Modifying files outside the removal scope (no side-effect changes)

## References

| File | Purpose | When to Read |
|------|---------|-------------|
| `references/removal-policy.md` | BLOCKER/PATCHABLE classification rules + per-asset-type matrix | Always (Phase 2-5) |

## Examples

```
/safe-remove skill create-skill
→ Dry-run plan showing skill dir + tests to delete + 12 PATCHABLE references

/safe-remove skill create-skill --execute
→ AskUserQuestion → patch 12 refs → delete skill dir + test/skills → verify clean

/safe-remove agent unused-agent
→ Dry-run: 1 file to delete, check for BLOCKER in agents skills: field
```
Files in this package (2)
  • SKILL.md 6 KB
  • references/removal-policy.md 5 KB

Versions

The database has no other skills named safe-remove.

Database snapshot: 13.11.2026 · package version c363178ed317 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 84analyze-dead-code
    Find and remove dead code — unused exports, unreachable modules, and stale files. Always use this skill whenever the user says "find dead code", "remove unused code", "clean up unused exports", "what code can we delete", "detect unreachable code", "what files are no longer…
  • 100agent-remove
    Remove an agent from the system — deletes the agent file, cleans up all registry entries, removes cross-references, and updates documentation. Use when the user says "remove the X agent", "delete X-review", "retire the X role", or "we no longer need X". Handles both team agents…
  • 100updating-plugin-assets
    Use when adding or editing any plugin asset in this repo — a SKILL.md, agent definition, slash command, MCP server prompt, hook script, or eval — so the change ships with the required eval coverage and a RED→GREEN paper trail
  • 100remove-worktree
    Use when user wants to safely remove an autonomy worktree while preserving the branch
  • 90prune
    Audit a codebase for dead code, duplication, unused dependencies, and cruft, then safely remove what no longer earns its place. Evidence-based (runs real dead-code analyzers, not vibes), confidence-tiered, and verification-gated. Use when the user wants to clean up / declutter /…
  • 90deprecate-and-remove
    Use when a ticket retires something — a feature flag, an endpoint, a config option, a module, a column, a CLI command — and the removal must not break callers, data, or operators who still depend on it. Invoke for "remove the legacy X", "delete dead code", "drop the old API", or…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.