<!-- Generated by scripts/generate-site-content.py — do not edit by hand -->


# agentskill-rename-refs

Update stale skill name references after a rename

| | |
|---|---|
| **Severity** | warning (auto) |
| **Autofix** | auto |
| **Since** | v0.1.0 |
| **Repo Types** | agent-plugin, agentskills, antigravity-plugin, codex-marketplace, codex-plugin, dot-claude, grok-marketplace, grok-plugin, marketplace, single-plugin |
| **Category** | [agentskills.io](agentskills.md) |

## Why

When a skill is renamed, references to the old name in other files
(CLAUDE.md, other skills, configuration) become stale. The skill
loader will not find the old name, so any instruction referencing it
is silently broken.

## Examples

**Bad (skill renamed from `deploy` to `deploy-staging`):**

```markdown
Use the /deploy skill to ship to staging.
```

**Good:**

```markdown
Use the /deploy-staging skill to ship to staging.
```

## How to fix

Update references to the old skill name to use the new name. The
violation message identifies the stale reference and the current
skill name.

A name match in prose is not always a skill reference — a skill named
`api` renamed to `api-v2` does not make every mention of the word
"api" stale. Before rewriting a flagged line, verify the mention
actually refers to the skill (invocations like `/name`, paths like
`skills/name/`, or prose such as "the name skill") and leave generic
uses of the word alone.

`skillsaw fix --suggest` rewrites references automatically only when
the old name has at least `autofix-min-segments` hyphen-separated
segments (default 2) — multi-segment kebab-case names essentially
never collide with ordinary prose. Single-word names are reported but
never rewritten automatically; fix those by hand (or with a coding
agent) using the judgment above.

## Configuration

```yaml
rules:
  agentskill-rename-refs:
    enabled: auto  # true | false | auto
    severity: warning
```

| Parameter | Description | Default |
|-----------|-------------|---------|
| `autofix-min-segments` | Minimum hyphen-separated segments in the old name for autofix to apply (single-word names are too ambiguous to fix safely) | `2` |


*Run `skillsaw explain agentskill-rename-refs` to see this documentation and the rule's effective configuration in your terminal.*