本文へ移動
cccskills
無料GitHub で公開

api-deprecation-and-migration

Deprecate APIs, features, or systems safely — announce, migrate consumers, sunset on a timeline, and document alternatives. Load when removing an old API, migrating users between implementations, sunsetting a feature, or the user asks about deprecation policy, migration guides, or breaking changes. Not for deleting dead code with zero consumers (use code-simplification). Distinct from meta `deprecate-skill` (skill library retirement).

インストール方法を見る

含まれるファイル(2)

  • SKILL.md4.2 KB
  • references/examples.md2.3 KB

SKILL.md(原文)

インストールする前に、エージェントに与えられる指示の中身を確認できます。

API Deprecation and Migration

Code is a liability. Deprecation removes systems that no longer earn their keep; migration moves consumers safely to replacements.

Hard Rules

  • Replacement before removal — working alternative with docs and migration path.
  • Default advisory — warnings and timelines; compulsory only for security or unsustainable cost.
  • Quantify consumers — usage metrics, client lists, or repo search before dates.
  • Hyrum's Law — undocumented behavior will be depended on; plan for stragglers.
  • Telemetry on migration — track who still calls deprecated surfaces.

Workflow

Step 1 — Deprecation decision

Answer: unique value remaining? consumer count? replacement ready? migration cost vs maintenance cost?

Step 2 — Announce

Publish notice: what, why, timeline, replacement, migration guide link, contact.

Step 3 — Migrate

Provide codemods, dual-write/read periods, feature flags, or versioned endpoints as appropriate.

Step 4 — Sunset

After deadline: return structured errors on old surface; keep read-only tombstone period if needed.

Step 5 — Remove and document

Delete code; update changelog; postmortem on straggler pain for next time.


Advisory vs compulsory

TypeWhenMechanism
AdvisoryStable old path, low riskDocs + warnings + metrics
CompulsorySecurity, blocking progressHard deadline + tooling + support

When NOT to use

  • Internal dead code with zero callers (delete with tests)
  • Retiring a skill from agent-loom library (deprecate-skill instead)

Gotchas

  • Announcing without migration guide guarantees support churn.
  • Breaking changes in patch versions destroy trust.
  • Dual-write without reconciliation causes data drift.
  • "We'll remove it someday" with no metric never happens.

Common Rationalizations

ExcuseReality
"Nobody uses the old API"Check logs — Hyrum's Law says otherwise.
"Just delete it"Forced migrations without notice become incidents.
"We'll support both forever"Two systems = double security and cognitive cost.
"Migration guide is enough"Tooling and deadlines drive completion.
"Breaking change in minor is fine"Semver exists so clients can plan.

Output Format

## Deprecation plan — [surface]

Consumers: [count/evidence]
Replacement: [link]
Type: [advisory/compulsory]
Timeline: [dates]
Migration: [steps/tooling]
Removal criteria: [metric or date]

Examples

<examples> <example> <input>"Remove REST v1 `/users` in favor of v2."</input> <output>90-day advisory → `Sunset` header → v1 returns 410 with link; codemod for internal clients; dashboard on v1 traffic.</output> </example> </examples>

Verification

  • Replacement documented and production-proven
  • Consumer impact quantified
  • Timeline and notice published
  • Migration tooling or guide available
  • Telemetry proves traffic at zero before code removal

Red Flags

  • Sunset announced without working replacement and docs
  • Breaking change shipped in patch or minor version
  • Dual-write path has no reconciliation or drift checks
  • Deprecation timeline set without consumer usage evidence

Prune Log

Last pruned: 2026-07-04

  • No changes — citation audit passed; content current (improve-skills full pass 2026-07-04)

Impact Report

Surface: [name] | Consumers: [N]
Type: [advisory/compulsory] | Sunset: [date]
Migration: [ready/partial]

レビュー

まだレビューはありません。使ってみた感想をお寄せください。

同じリポジトリのスキル

概要と使いどころ

Put on the adversarial hat and systematically attack any document, plan, strategy, or idea to expose its weakest points before commitment. Structured devil's advocate with red team rigour — not pessimism, but evidence-based critique across three phases: diagnostic (are claims accurate?), creative (is the problem artificially constrained?), challenge (are solutions robust?). Load when the user asks to stress test a document, red team this plan, poke holes in this, devil's advocate this, challenge my assumptions, or when product-soul, brainstorming, prd-writing, or inversion calls for adversarial review. Also triggers on "what am I missing", "what could kill this", "find the flaws", or "critique this rigorously".

日本語の概要は準備中です。原文の説明を表示しています。

dvy1987/agent-loom32026年8月8日 更新

Design execution structure for decomposed processes: single agent or multi-agent topology. Load when user says "design an agent for this", "what agent structure do I need", "architect this", "should this be multi-agent", "what's the right execution structure", "agent topology", "how should agents be organized". Takes process-decomposer output as primary input. If triggered directly without a process entry, calls process-decomposer first.

日本語の概要は準備中です。原文の説明を表示しています。

dvy1987/agent-loom32026年8月8日 更新

Internal skill. Called by setup-evaluation after a PASS. Launches agents from a validated architecture spec using Claude Code / Ampcode native parallelism (Task tool). Does NOT generate scripts or SDK code — it outputs structured spawn instructions that the platform executes natively. Never invoked directly by the user. Never launches without a setup-evaluation PASS.

日本語の概要は準備中です。原文の説明を表示しています。

dvy1987/agent-loom32026年8月8日 更新

Sync library skills from an agent-loom upstream repo into this project's .agents/skills while preserving project-local and forked skills. Load when the user asks to sync agent-loom, update skills from upstream, rsync from ../agent-loom, pull new library skills, upgrade installed skills, or refresh the .agents folder without losing custom project skills. Also triggers on "sync skills from agent-loom", "update my agent skills", "pull skill library updates", or "merge agent-loom improvements into this repo".

日本語の概要は準備中です。原文の説明を表示しています。

dvy1987/agent-loom32026年8月8日 更新

Instrument a shipped product's AI agents with tracing and observability so you can see what they did, why outputs happened, and what each run cost. Plain-language primer plus free-tier-first backend selection (Langfuse, Phoenix, LangSmith, Braintrust) and OpenTelemetry/OpenInference instrumentation. Load when the user asks to add observability, add tracing, instrument my agents, see what my agent is doing in production, set up Langfuse or Phoenix or LangSmith, debug why my agent gave a bad answer, or track LLM cost per request. Also fires when agent-system-architecture or setup-evaluation requires an observability plan for an agent-chain product. NOT for tracing the coding agent itself — that is run-trace. Precondition for runtime-learning-loop.

日本語の概要は準備中です。原文の説明を表示しています。

dvy1987/agent-loom32026年8月8日 更新

Run a structured retrospective after development-phase runs of your product's agents — interview the owner in plain language about what went well and poorly, draft ranked improvement hypotheses, then design and run small n=1/n=2 experiments with pre-declared success criteria, guardrails, stop conditions, and a cost/ROI kill-switch. Load when the user says how did that run go, retro this run, the agent output was bad, what should we improve, draft hypotheses, run a small experiment, or after repeated dev runs of an agentic system produce uneven quality. Priority: output quality over performance over cost, each with diminishing-returns stops. NOT a product A/B test (experimentation), NOT coding-agent harness repair (harness-evolution), NOT production-scale learning (runtime-learning-loop).

日本語の概要は準備中です。原文の説明を表示しています。

dvy1987/agent-loom32026年8月8日 更新

dvy1987 のスキルをすべて見る

このスキルの問題を報告する