diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md
index 9e1e0db..86543ef 100644
--- a/.claude/skills/release/SKILL.md
+++ b/.claude/skills/release/SKILL.md
@@ -66,9 +66,10 @@ Example: `/release minor`
 
 7. **Commit changes**:
 
-   **CRITICAL**: The commit message MUST start with `release: v` (no other words before the version).
-   The `tag-release.yml` workflow matches `startsWith(message, 'release: v')` on the merge commit.
-   When GitHub squash-merges a single-commit PR, the commit message becomes the merge commit message.
+   **CRITICAL**: The commit message MUST start with `release: v`.
+   When merging this PR to main, **you must squash-merge** so the merge commit message starts with `release: v`.
+   This is required for `tag-release.yml` to detect and trigger the release automation.
+   See CLAUDE.md for details on the release convention and why squash merge is required.
 
    ```bash
    git add Cargo.toml CHANGELOG.md
@@ -107,12 +108,16 @@ Example: `/release minor`
 
 ## After PR Merge
 
-When the PR is merged to main, the `tag-release.yml` workflow will:
+**⚠️ IMPORTANT: Squash-merge this PR when merging to main.** See CLAUDE.md for why this is required.
+
+When the PR is squash-merged to main, the `tag-release.yml` workflow will:
 1. Detect the version from `Cargo.toml`
 2. Create and push the git tag `vX.Y.Z`
 3. The `release.yml` workflow then runs CI and publishes to crates.io
 4. Create a commit bumping to next dev version (e.g., `0.0.2-alpha.0`)
 
+If you accidentally use a default merge commit, the automation won't trigger. See CLAUDE.md for the manual recovery steps.
+
 ## Troubleshooting
 
 - **gh CLI not installed**: `brew install gh` or see https://cli.github.com/
diff --git a/.github/workflows/tag-release.yml b/.github/workflows/tag-release.yml
index b271b7b..1cad456 100644
--- a/.github/workflows/tag-release.yml
+++ b/.github/workflows/tag-release.yml
@@ -14,8 +14,13 @@ jobs:
     permissions:
       contents: write
       pull-requests: write
-    # Only run if the commit message starts with "release: v" (matches merge commit titles)
-    if: "startsWith(github.event.head_commit.message, 'release: v')"
+    # Run when a release PR lands on main. Use `contains` rather than
+    # `startsWith` so it matches both merge strategies:
+    #   - squash merge: message starts with "release: v1.0.1 (#5)"
+    #   - merge commit: message is "Merge pull request #5 ...\n\nrelease: v1.0.1"
+    # Dev-version bump commits ("chore: bump ...") don't contain "release: v",
+    # so they won't trigger this job.
+    if: "contains(github.event.head_commit.message, 'release: v')"
 
     steps:
       - uses: actions/checkout@v4
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..4ffd0e8
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,46 @@
+# Clocksource Development Guide
+
+## Release Process
+
+The release workflow in this repo requires **squash-merging** release PRs to trigger the automated tagging and publishing pipeline.
+
+### Why squash merge?
+
+The `tag-release.yml` workflow checks if the merge commit message contains `release: v`. With a **squash merge** of a PR titled `release: v1.0.1`, the merge commit message becomes:
+```
+release: v1.0.1 (#5)
+```
+
+With a **default merge commit**, the message is:
+```
+Merge pull request #5 from owner/branch
+
+release: v1.0.1
+```
+
+The workflow guard `if: contains(github.event.head_commit.message, 'release: v')` matches squash-merge messages immediately but fails on merge-commit messages (where the title is on a later line).
+
+### Release convention
+
+1. Create a release PR with:
+   - Title: `release: vX.Y.Z`
+   - Single commit message: `release: vX.Y.Z`
+   - Version bump in `Cargo.toml`
+   - Updated `CHANGELOG.md`
+
+2. **Always squash-merge** when merging to `main`
+   - GitHub's merge button: select "Squash and merge"
+   - Command line: ensure the merge commit message starts with `release: v`
+
+3. After merge, `tag-release.yml` automatically:
+   - Creates and pushes git tag `vX.Y.Z`
+   - Triggers `release.yml` → CI + `cargo publish` → GitHub Release
+   - Opens PR bumping to next dev version (`vX.Y.(Z+1)-alpha.0`)
+
+If you accidentally merge without squashing, manually push the tag:
+```bash
+git tag -a vX.Y.Z -m "Release vX.Y.Z" <merge-commit-sha>
+git push origin vX.Y.Z
+```
+
+Then open a PR to bump the version to the next dev release.