Publish a lifecycle and compatibility policy, checked in CI

.github/workflows/ci.yml

@@ -19,7 +19,8 @@ jobs:
         with:
           persist-credentials: false
           # all branches and tags: the plugin release record is checked
-          # against the PR's base branch and any release tag
+          # against the PR's base branch and any release tag, and the
+          # lifecycle check reads the release tags
           fetch-depth: 0
       - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
@@ -40,6 +41,18 @@ jobs:
           else
             python scripts/check_release_consistency.py
           fi
+      - name: Lifecycle notes (removals, deprecations, breaking changes)
+        # docs/lifecycle.md: on a PR, compatibility changes since the target
+        # branch need CHANGELOG entries; always, the newest release's bump
+        # must be big enough for what it removes or deprecates
+        env:
+          BASE_REF: ${{ github.base_ref }}
+        run: |
+          if [ -n "$BASE_REF" ]; then
+            uv run --locked --extra dev python scripts/check_lifecycle.py --base "origin/$BASE_REF"
+          else
+            uv run --locked --extra dev python scripts/check_lifecycle.py
+          fi
 
   test:
     runs-on: ubuntu-latest

CLAUDE.md

@@ -77,7 +77,8 @@ by `--agent all`); `skilldeck migrate` moves old-format installs to `SKILL.md`.
   (`tests/test_eval_scoring.py`). See `evals/README.md`. New/changed skills
   should be run through them.
 - `docs/` — `authoring-skills.md`, `adapters.md`, `catalog.md`, `compatibility.md`
-  (the public agent compatibility matrix), `releasing.md`
+  (the public agent compatibility matrix), `lifecycle.md` (the versioning,
+  deprecation and compatibility policy), `releasing.md`
 - `tests/fixtures/adapter-contracts/` — each adapter's exact rendered file,
   paths and env-override behaviour for one synthetic skill; checked byte for
   byte by `tests/test_adapter_contracts.py`
@@ -140,6 +141,30 @@ by `--agent all`); `skilldeck migrate` moves old-format installs to `SKILL.md`.
   stay in sync — `scripts/check_release_consistency.py` enforces this in CI and
   `pytest`. A dated CHANGELOG section without a matching `v*` tag is prepared, not
   published.
+- Lifecycle: follow `docs/lifecycle.md` for what bumps package/skill versions
+  (skills from 1.0.0: removing a checklist area or changing output shape is
+  major, adding checks minor, wording/citations patch; while a skill is 0.x a
+  breaking change bumps its minor) and for deprecation → notice → removal (a
+  release tag must ship the deprecation ≥90 days before removal, 180 from 1.0).
+  `### Removed` is only for public-surface removals (skills, agents/adapters,
+  commands/options, stable output or `meta.yaml` fields); internal code
+  removals go under Changed. `scripts/check_lifecycle.py` (CI `lint` job,
+  `--base origin/<target>`; needs `uv run --locked --extra dev`) fails a PR
+  unless a section the PR adds (`[Unreleased]`, or a release it cuts) has a
+  bullet naming the thing **in its own backticks**: `### Removed` for a removed
+  skill (also deprecated at base, and if any tag contains it, a reachable
+  `v*` tag whose own meta.yaml + CHANGELOG deprecate it, ≥ the notice period
+  before, counted from max(section date, tag date)); `### Removed` of its own,
+  naming no skill, for a removed adapter; one `### Removed` bullet naming skill
+  and agent for an agent dropped from a skill; `### Deprecated` for a newly
+  deprecated skill; `### Changed` naming skill + new version when a skill's
+  major goes up; `**Breaking:**` + `schema_version` for a catalog schema bump.
+  Urgent security removals skip deprecation/notice only with a `### Removed`
+  bullet marked `**Security:**` plus a `### Security` entry naming the skill.
+  Without release tags it prints a note and skips notice rules. It also fails
+  (as does `prepare_release.py`) when the newest dated section is a patch
+  release with Removed/Deprecated/**Breaking** entries. Run it locally with
+  `--base origin/main` (after `git fetch --tags`) before pushing.
 - Release CI must build once, verify wheel/sdist/plugin identity (against the
   tagged commit's files), produce a runtime-only SPDX SBOM and exact
   checksums, attest those bytes, then publish the same bundle. The build job

CONTRIBUTING.md

@@ -53,6 +53,12 @@ once in an agent-neutral format — never hand-edit per-agent output. A skill's
 [docs/authoring-skills.md](docs/authoring-skills.md) for the full guide, and bump that
 skill's own `version` in `meta.yaml` whenever its content changes.
 
+Deprecating or removing a skill, dropping an agent, or making a major version change
+needs a `CHANGELOG.md` entry that names it, and CI checks for one. See
+[docs/lifecycle.md](docs/lifecycle.md) for the rules and the notice period, and run
+`uv run --locked --extra dev python scripts/check_lifecycle.py --base origin/main` to
+check.
+
 ## Opening the pull request
 
 - Make sure the checks above pass.

README.md

@@ -211,6 +211,10 @@ Each skill is a directory under `src/skilldeck/skills/` containing a `meta.yaml`
 and a `skill.md`. See [docs/authoring-skills.md](docs/authoring-skills.md), and
 follow the [contributor guide](CONTRIBUTING.md) for setup and validation.
 
-## Changelog
+## Changelog and support
 
 Notable changes are recorded in [CHANGELOG.md](CHANGELOG.md).
+[docs/lifecycle.md](docs/lifecycle.md) says what each kind of version bump
+means, how long deprecated skills, agents and formats stay supported (a
+deprecation ships in a release at least 90 days before the removal), and
+what happens to skills you have already installed when one is removed.

SECURITY.md

@@ -19,7 +19,9 @@ When you report, include as much of the following as you can:
 
 - We aim to acknowledge a report within **3 business days**.
 - We'll confirm the issue, keep you updated as we work on a fix, and let you know when
-  it ships.
+  it ships. For a confirmed high- or critical-severity issue, we aim to publish a fixed
+  release within 7 days of confirming it, as the
+  [lifecycle policy](docs/lifecycle.md#security-fixes) describes.
 - With your permission, we're happy to credit you once the fix is public.
 
 Please give us a reasonable window to release a fix before disclosing publicly. We're a

docs/authoring-skills.md

@@ -79,6 +79,16 @@ that agent would have nothing to move to). `skilldeck list` and
 they write one, and `skilldeck catalog --json` reports the record to tools
 (see [the skill catalog](catalog.md)).
 
+Deprecating a skill also needs a `### Deprecated` entry in `CHANGELOG.md`
+naming it in backticks, and CI checks for one. The skill can be removed only
+after a release has published the deprecation for the notice period (90
+days before 1.0). While a skill is 0.x, a breaking change bumps its minor
+version. A rename is a new skill plus a deprecation of the old name.
+See [Lifecycle and compatibility](lifecycle.md#deprecating-a-skill) for the
+full path, including what happens to installed copies, and
+[Skill versions](lifecycle.md#skill-versions) for which changes are major,
+minor or patch.
+
 ## `skill.md`
 
 The agent-neutral body of the skill — the actual instructions/prompt. Write it

docs/catalog.md

@@ -77,7 +77,9 @@ from it, rather than trusting a second file that could drift from it.
 - `deprecated` is `null`, or an object with `since` (the skill version that
   first carried the deprecation), `replacement` (the skill to use instead, or
   `null`) and `reason`. See
-  [Deprecating a skill](authoring-skills.md#deprecating-a-skill).
+  [Deprecating a skill](authoring-skills.md#deprecating-a-skill). A removed
+  skill is simply absent; [Lifecycle and compatibility](lifecycle.md#the-catalog)
+  covers each state and how long a deprecated skill stays.
 
 `catalog` runs the full `skilldeck provenance --verify` check first. If any
 installed skill no longer matches its recorded digest, is missing, or has a

docs/compatibility.md

@@ -294,3 +294,7 @@ handles a change like this:
    fix as soon as it merges, following [Releasing](releasing.md), instead of
    batching it with other changes. Have the changelog entry tell users to run
    `skilldeck migrate` or `skilldeck update`.
+
+When skilldeck itself drops an agent or a format that the vendor still
+supports, it deprecates it first and waits a notice period: see
+[Removing an agent or format](lifecycle.md#removing-an-agent-or-format).