diff --git a/.codex/AGENTS.md b/.codex/AGENTS.md
index 3830f87..b35113d 100644
--- a/.codex/AGENTS.md
+++ b/.codex/AGENTS.md
@@ -1,3 +1,2 @@
 after you finish work, commit with a conventional message. only commit the files you edited.
-run `make check` and fix any errors before committing.
-
+run `just check` and fix any errors before committing.
diff --git a/.codex/skills/takopi-release/SKILL.md b/.codex/skills/takopi-release/SKILL.md
new file mode 100644
index 0000000..ba5bd2d
--- /dev/null
+++ b/.codex/skills/takopi-release/SKILL.md
@@ -0,0 +1,67 @@
+---
+name: takopi-release
+description: Prepare and ship a Takopi release. Use when asked to cut a release, bump release versions, update changelog/spec/readme, tag v<major.minor.patch>, or trigger the GitHub release workflow.
+---
+
+# Takopi Release
+
+## Overview
+
+Prepare a tagged release that matches the GitHub Actions release workflow. The workflow requires the tag version to match both `pyproject.toml` and `src/takopi/__init__.py`.
+
+## Workflow
+
+### 1) Choose version + date
+
+Pick the release version (major.minor.patch) and the release date (YYYY-MM-DD) for changelog/spec headers.
+If the current version has a `.dev` suffix, assume the target release version is the same version without the suffix, as long as that tag does not already exist.
+
+### 2) Update changelog
+
+Update `changelog.md` by adding a new top section. Before writing it, study the diff between the previous tag and the new release to rank changes; put user-facing changes first.
+
+- `## v<major.minor.patch> (YYYY-MM-DD)`
+- Include subsections like `changes`, `fixes`, `breaking`, `docs` as needed.
+- Keep entries short and include PR links when available (match existing style).
+
+### 3) Bump versions
+
+Update version strings to match the release tag:
+
+- `pyproject.toml`: `project.version = "<major.minor.patch>"`
+- `src/takopi/__init__.py`: `__version__ = "<major.minor.patch>"`
+- `uv.lock`: refresh so the root package version matches (run `uv lock` or `uv sync`).
+
+### 4) Update spec + docs
+
+Update `docs/specification.md` to match the release:
+
+- Header: `# Takopi Specification v<major.minor.patch> [YYYY-MM-DD]`
+- Replace `Takopi v<old>` and `Out of scope for v<old>` lines with the new version.
+- Add a changelog entry like `- No normative changes; align spec version with the v<major.minor.patch> release.` unless the spec itself changed.
+
+If the release highlights new features, update `readme.md` accordingly (see v0.9.0 release).
+
+### 5) Run checks
+
+Run the standard checks before committing:
+
+- `just check` (ruff/ty/pytest)
+
+### 6) Commit + tag
+
+Commit the release using conventional commits:
+
+- Commit message: `chore(release): v<major.minor.patch>`
+- Tag: `git tag v<major.minor.patch>`
+
+Push the tag to trigger `.github/workflows/release.yml` (build, PyPI publish, GitHub release).
+
+### 7) Optional post-release bump
+
+If you keep a dev version between releases, bump the minor version (reset patch to 0) and commit (`chore: bump version to ...`).
+
+## Notes
+
+- The release workflow checks that the tag matches `pyproject.toml` and `src/takopi/__init__.py`.
+- Keep dates consistent across `changelog.md` and `docs/specification.md`.