skill-deprecator

name	skill-deprecator
description	Use when deprecating or removing a skill from SkillOverflow: a SAP version removed a feature, a pattern is now natively handled by the model, a skill is outdated after a major CAP, UI5, BTP or Fiori release, or when re-evaluating skills after a new AI model ships to determine what can be removed or simplified.
metadata	{"category":"meta","version":"1.0.0","keywords":["deprecate skill","remove skill","outdated skill","model update","baseline comparison","skill decay","version update"],"related":{"skill-reviewer":"reviewer may flag skills for deprecation","skill-contributor":"deprecation follows similar PR process to contribution"}}

Skill Deprecator — Deprecation & Removal Workflow

Primary reference: See CONTRIBUTING.md and CHANGELOG.md in this repository. CAP release notes: https://cap.cloud.sap/docs/releases/ UI5 release notes: https://ui5.sap.com/#/topic/99ac68a5b1c3416ab5c84c99fefa250d

Skills should get smaller as SAP frameworks evolve and models improve. Deprecating outdated content is as important as adding new skills.

---

When to deprecate

The skill is outdated:

• A SAP feature the skill describes has been removed or replaced in a new version
• The recommended pattern has changed (e.g. @sap/cds-mtx → @sap/cds-mtxs)
• The skill references APIs that no longer exist

The model has learned it:

• After a new AI model ships, re-run the full eval suite
• If a skill now passes 100% of its evals WITHOUT the skill active, the model knows the pattern natively
• That skill can be simplified or removed entirely

The skill is never triggering:

• Run baseline tests — if with-skill and without-skill output are identical, the skill adds no value
• Either fix the description or remove the skill

---

Step 1: Confirm the deprecation reason

Before making any changes, confirm one of these:

# Check which SAP version removed the feature
# Reference the official release notes:
# CAP: https://cap.cloud.sap/docs/releases/
# UI5: https://ui5.sap.com/#/topic/99ac68a5b1c3416ab5c84c99fefa250d
# BTP: https://help.sap.com/whats-new/cf0cb2cb149647329b5d02aa96303f56

# Re-run baseline test for the skill
# 1. Disable skill temporarily
mv skillOverflow/skills/<skill>  skillOverflow/skills/<skill>.disabled
# 2. Run the eval prompt → note output A
# 3. Re-enable
mv skillOverflow/skills/<skill>.disabled  skillOverflow/skills/<skill>
# 4. Run same prompt → note output B
# If A == B, the skill adds no value

---

Step 2: Determine action — deprecate notice OR full removal

Option A: Add deprecation notice (safe — keep for older version users)

When some users may still be on the older version:

> ⚠️ **Deprecated since [SAP product] [version]**: [Brief explanation].
> Use [`replacement-skill`](../replacement-skill/SKILL.md) instead.
> This skill will be removed once all users have migrated.

Add this block at the very top of the skill body, directly after the frontmatter.

Option B: Full removal (when everyone is on the new version)

Proceed to Step 3.

---

Step 3: Full removal checklist

Execute all steps — do not skip any:

3a. Remove the skill folder:

rm -rf skillOverflow/skills/<skill-name>/

3b. Remove from README.md:

• Delete the row from the category skills table
• Update the skill count in the summary table

3c. Remove eval from skillOverflow-evals.json:

• Delete the eval object for this skill
• Renumber remaining IDs if needed to keep them sequential

3d. Remove from skill-test-checklist.html:

• Delete the corresponding eval object from the EVALS array

3e. Search for any remaining references:

grep -r "<skill-name>" skillOverflow/ --include="*.md" --include="*.json" --include="*.sh" --include="*.html"

Fix any remaining references found. (The smoke test auto-discovers skills from skills/*/ on disk, so there's no separate registry to clean up there.)

3f. Run the smoke test:

bash ~/skillOverflow/tests/smoke-test.sh ~/skillOverflow

---

Step 4: Draft the PR description

## Deprecation: `<skill-name>`

**Reason**: [one of: SAP version change / model now handles natively / skill never triggering]

**Evidence:**
- [e.g. "CAP 9 removed @sap/cds-mtx — see https://cap.cloud.sap/docs/releases/may25"]
- [e.g. "Baseline test shows identical output with and without skill (tested with claude-sonnet-4)"]

**Action taken**: [Deprecation notice added / Full removal]

**Replacement**: [Link to replacement skill if applicable, or "none needed"]

**Checklist:**
- [ ] README.md updated
- [ ] skillOverflow-evals.json updated
- [ ] skill-test-checklist.html updated
- [ ] Smoke test passes
- [ ] No remaining references to deprecated skill

---

Model update re-evaluation workflow

When a new AI model ships (Claude, GPT, Gemini), run this process:

1. Open tests/skill-test-checklist.html
2. For each skill — disable it, run the eval prompt, re-enable it, run again
3. If outputs are identical → candidate for removal
4. If outputs differ AND with-skill is better → keep the skill
5. If outputs differ but difference is minor → simplify the skill (remove what the model knows)
6. Document results in a PR: "Re-evaluated after [model] update"

Aim to reduce the total number of skills after every major model update. A leaner SkillOverflow is a better SkillOverflow.

---

Common mistakes to avoid

• ❌ Removing a skill without checking if anyone is still on the old version

• ✅ Use deprecation notice first, full removal after team-wide migration

• ❌ Assuming a skill is working just because it exists

• ✅ Re-run baselines periodically — skills decay without maintenance

• ❌ Removing just the SKILL.md without cleaning up README, evals, and checklist

• ✅ Follow the full removal checklist in Step 3

• ❌ Skipping the model re-evaluation after major releases

• ✅ Every major model update is an opportunity to make SkillOverflow leaner