deprecate-best-practice-skill
Deprecate Best Practice Skill
Mark an outdated grimoire skill for removal and, where possible, point users to the practice that supersedes it.
Why This Is Best Practice
Adopted by: Explicit deprecation with replacement pointers is standard across all
major knowledge systems — npm packages use deprecated metadata with migration notes,
MDN Web Docs marks obsolete APIs with explicit "Use X instead" banners, and the Python
Package Index surfaces deprecation notices prominently to prevent installation of
abandoned packages.
Impact: Without deprecation, outdated skills get served to users indefinitely.
Research on documentation debt (Aghajani et al., 2019, MSR) found 50–60% of surveyed
developers encountered bugs caused by stale documentation; explicit deprecation markers
reduce this by surfacing decay at the point of use.
Why best: Silent removal leaves users with broken install paths and no migration
guidance. Deprecation-with-pointer gives users a safe off-ramp and maintains trust in
the repo as a reliable source.