Captain-gated flow to mark a skill as deprecated. Bumps frontmatter, injects a sunset banner, logs to docs/skills/deprecated.md, and opens a PR. Does not delete the skill.
⚠️ Captain-gated. This skill requires explicit Captain confirmation before any changes are made.
Invocation: As your first action, call
crane_skill_invoked(skill_name: "skill-deprecate"). This is non-blocking — if the call fails, log the warning and continue. Usage data drives/skill-audit.
Formal deprecation flow for enterprise skills. Marks a skill for retirement with a 90-day grace period. The skill remains invocable throughout the grace period - this is NOT deletion.
Invoke /skill-deprecate when ALL of the following are true:
/skill-audit as a deprecation candidateDo NOT invoke based on a single low-usage period or minor staleness. The audit surfaces candidates; the Captain decides.
/skill-deprecate <skill-name> [--reason "..."] [--migration "..."]
| Argument | Required | Description |
|---|---|---|
<skill-name> | Yes | Matches the directory name under .agents/skills/ |
--reason | No | If omitted, agent will ask interactively |
--migration | No | If omitted, agent will ask interactively |
Run all checks before any changes. Stop and report if any fail.
Captain confirmation - Ask in chat: "This will deprecate <name>. Confirm you're the Captain authorizing this deprecation? (yes/no)". Do not proceed until the Captain replies "yes" in the chat interface.
Skill exists - Verify .agents/skills/<name>/SKILL.md is present. If missing, stop: "No skill found at .agents/skills/<name>/SKILL.md."
Not already deprecated - Read current frontmatter. If status is already deprecated, stop: "<name> is already deprecated (since <deprecation_date>). Nothing to do."
Scope reminder - Before proceeding, state to the Captain: "Per guardrails.md, deprecation is NOT removal. The skill remains invocable during the 90-day grace period. Removal requires a separate Captain directive after the sunset date."
Read the target SKILL.md. Extract current frontmatter (version, status, description).
If --reason was not provided, ask:
"What's the deprecation reason? (1-2 sentences)"
If --migration was not provided, ask:
"What should callers use instead? (migration path, or 'no direct replacement')"
Once both are collected, echo everything back for confirmation:
About to deprecate: <name>
Reason: <reason>
Migration: <migration>
Sunset: <today + 90 days>
Proceed? (yes/no)
Do not advance to Phase 2 until the Captain confirms.
Get today's date:
date +%Y-%m-%d
Get the sunset date (90 days out):
date -v+90d +%Y-%m-%d # macOS
# or: date -d '+90 days' +%Y-%m-%d # Linux
Bump these fields in the target SKILL.md frontmatter: