extending-managed-skills

name	extending-managed-skills
description	Use when reviewing, renaming, editing, overriding, extending, or cleaning up installed skills that may be managed by plugins, lockfiles, upstream repos, generated skill managers, byte-identical local copies, or local extension policies.

Extending Managed Skills

Overview

Managed skills are upstream artifacts. Keep plugin, lockfile, generated, and byte-identical upstream copies immutable unless the user explicitly asks to update them through their owning manager.

When local behavior needs to differ, create or edit a separate user-local extension skill with strong trigger overlap instead of changing the managed base skill.

Ownership Check

Before editing a skill, classify it. Use the commands that fit the current installation and inspect any manager metadata present on the machine:

jq -r '.skills | keys[]' ~/.local/state/skills/.skill-lock.json 2>/dev/null
find ~/.codex/plugins/cache -name SKILL.md -print
find ~/.agents/skills .agents/skills -maxdepth 2 -name SKILL.md -print
sha256sum <candidate-skill> <possible-upstream-copy>

Treat a local skill that is byte-identical to a plugin, lockfile, generated, or other manager-owned source as an orphaned upstream copy, not local policy.

Extension Pattern

For managed-skill behavior changes:

• Keep the base skill immutable.
• Use an action-led extension name that describes the local behavior.
• Match the base skill's trigger terms and the exact phrases users say.
• State the base skill it extends and that it applies after the base skill.
• Rename old local extension skills instead of leaving compatibility shims, unless another agent or tool still depends on the old name.

Recommended shape:

---
name: local-extension-name
description: Use when [same or narrower trigger as base skill, plus exact user phrases]
---

# Local Extension Name

This skill extends `<base-skill-name>`.

Read the base skill first. Then apply these local modifications:

- ...

Discovery Rules

Skill loading is not transitive. A base skill firing does not automatically load its extension. If an extension must apply whenever a base skill applies, its description must include the base skill name, base trigger language, and the local failure mode it prevents.

Cleanup Policy

Before deleting or moving skills, classify each copy as plugin-managed, lockfile-managed, repo-local, user-local, generated, or orphaned. Preserve discoverability for agents that do not load Codex plugins. Remove an orphaned copy only when losing that discovery path is acceptable.

Common Mistakes

• Editing plugin cache skills directly.
• Editing lockfile-managed skills outside their manager.
• Treating a byte-identical upstream copy as local policy.
• Creating an extension whose trigger does not overlap the base skill.
• Leaving old compatibility shims that compete with the canonical skill.