# Pre Publish Checklist

> Use when about to tag, release, or push a repo for publication.

- Skill: `william-yeh/pre-publish-checklist` (Agent Skill)
- Install (CLI): `npx skillmds@latest add william-yeh/pre-publish-checklist`
- Raw SKILL.md: https://api.skillmd.com/api/skills/william-yeh/pre-publish-checklist/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: william-yeh (https://skillmd.com/u/william-yeh)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/william-yeh/pre-publish-checklist

---


# Pre-Publish Checklist

## Arguments

- `--skip <check>` — skip a specific check by name. Can be repeated.
  Valid values: `skill-lint`, `version-sync`, `code-review`, `tests`, `ci`, `docs`

## Process

### Step 1 — Detect repo types

Scan the repo root for the following signals. Collect **all** matches — a repo can be multiple types simultaneously.

| Signal | Repo Type | Notes |
|---|---|---|
| `SKILL.md` (at root) | Agent Skill | Skill dir = repo root |
| `skill/SKILL.md` | Agent Skill | Skill dir = `skill/` (subdir layout — recommended for `npx skills add`) |
| `.claude-plugin/plugin.json` | Agent Skill (plugin) | Plugin layout — one or more skills under `skills/<name>/` |
| `pyproject.toml` / `setup.py` / `setup.cfg` | Python program | |
| `package.json` | Node.js program | |
| `go.mod` | Go program | |
| `Cargo.toml` | Rust program | |
| `pom.xml` / `build.gradle` | Java program | |
| `build.gradle.kts` / `settings.gradle.kts` | Kotlin program | |
| `project.clj` / `deps.edn` / `build.clj` | Clojure program | |
| `*.sln` / `*.csproj` (any at root) | C# program | |
| `*.fsproj` (any at root) | F# program | |
| `CMakeLists.txt` / `meson.build` / `configure.ac` | C/C++ program | |

When an Agent Skill is detected, record the **skill target path** (repo root, `skill/`, or the plugin root) — later Agent Skill checks operate on this path, not the repo root.

If no signals match, report "unknown repo type — cannot determine which checks to run" and stop.

### Step 2 — Run checks

Run every applicable check. Skip any whose name matches a `--skip` argument.

#### Agent Skill checks (when an Agent Skill signal matched)

Use the **skill target path** recorded in Step 1 (repo root, `skill/`, or the plugin root) for both checks below.

1. **Skill lint** (`--skip skill-lint` to skip)
   - Invoke the `William-Yeh/agent-skill-linter` skill against the skill target path: `/skill-lint check <skill-target-path>`
   - The linter auto-detects single-skill vs. plugin mode from the target.
   - Linter errors → BLOCKING
   - Linter warnings only → WARNING

2. **Version sync** (`--skip version-sync` to skip)
   - Run: `git tag --list` to check if the repo has any existing git tags.
   - If no tags exist, skip this check (nothing to compare against).
   - If tags exist, get the latest tag: `git describe --tags --abbrev=0`
   - Parse the `version` field from the SKILL.md frontmatter at the skill target path. In plugin mode, read the version from `.claude-plugin/plugin.json` instead.
   - Strip any leading `v` prefix from the git tag before comparing (e.g. `v0.1.0` → `0.1.0`).
   - Compare the parsed version against the latest git tag:
     - If version == latest tag → BLOCKING: "Version not bumped — `<version>` matches existing tag `<tag>`. Increment the version before publishing."
     - If version < latest tag → BLOCKING: "Version `<version>` is older than existing tag `<tag>`."
     - If version > latest tag → PASS

#### Program source code checks (when any language build manifest detected)

3. **Code review** (`--skip code-review` to skip)
   - Invoke the `William-Yeh/common-code-reviewer` skill: `/common-code-reviewer`
   - Reviewer verdict "REQUEST CHANGES" → BLOCKING
   - Reviewer verdict "APPROVE WITH COMMENTS" → WARNING
   - Reviewer verdict "APPROVE" → pass

4. **Local tests** (`--skip tests` to skip)
   - Run the test command for each detected language:

     | Repo type | Test command |
     |---|---|
     | Python | `uv run pytest` |
     | Node.js | `npm test` |
     | Go | `go test ./...` |
     | Rust | `cargo test` |
     | Java | `./mvnw test` or `./gradlew test` |
     | Kotlin | `./gradlew test` |
     | Clojure | `lein test` or `clojure -T:build test` |
     | C# / F# | `dotnet test` |
     | C/C++ | `cmake --build . --target test` or `make test` |

   - Any test failure → BLOCKING

5. **CI status** (`--skip ci` to skip)
   - Run: `gh run list --branch $(git branch --show-current) --limit 1`
   - Latest run status is not `completed` with `success` conclusion → BLOCKING

### Step 3 — Report

Output a consolidated report:

```
## Pre-Publish Checklist

Detected types: <comma-separated list>

### <Type>
- [x] <check name>: PASSED
- [WARNING] <check name>: <reason>
- [BLOCKING] <check name>: <reason>

---

Verdict: BLOCKED — N blocking issue(s) must be resolved before publishing.

Blocking issues:
1. <description>

Warnings (non-blocking):
1. <description>
```

When all checks pass or only warnings remain, the verdict is:

```
Verdict: READY TO PUBLISH
```

### Step 4 — Document rationale (when READY TO PUBLISH) (`--skip docs` to skip)

Skip this step entirely if there are blocking issues or if `--skip docs` was passed.

Gather context from all available sources:
- The current coding-agent session dialog (decisions made, alternatives discussed, trade-offs considered)
- `git log` and diff since the last tag or branch point
- Issue/PR references mentioned in commit messages or the session

Then update or create the following documents as applicable.

#### 4a — ADR (Architecture Decision Record)

- First, check `README.md` for any project-specific documentation arrangement (e.g. the project may direct decision records to `DESIGN.md`, a wiki, or a custom path).
- If no project-specific arrangement is documented, look for a `docs/adr/` or `adr/` directory; if neither exists, create `docs/adr/`.
- Scan existing ADR files to determine the next sequential number (e.g. `0001`, `0002`).
- Write a new ADR **only** if the change involves a design or architecture decision (new dependency, changed interface contract, security trade-off, algorithm choice). Skip for pure bug fixes or trivial patches.
- Template:

  ```markdown
  # ADR-<NNNN>: <Short decision title>

  Date: <YYYY-MM-DD>

  ## Status

  Accepted

  ## Context

  <Why this change was needed — problem statement, constraints, background.>

  ## Decision

  <What was decided and why this option was chosen over alternatives.>

  ## Consequences

  <Trade-offs, follow-up work, risks introduced or mitigated.>
  ```

#### 4a-ii — ADR consolidation review

After writing any new ADR (or even if none was written), read all existing ADRs and assess whether consolidation is warranted:

- **Superseded decisions**: if a new ADR reverses or significantly changes an older one, update the older ADR's `## Status` to `Superseded by ADR-<NNNN>` and add a note explaining what changed.
- **Overlapping decisions**: if two or more ADRs cover the same concern from different angles and have drifted out of sync, merge their content into the most recent one, mark the older ones as `Merged into ADR-<NNNN>`, and update cross-references.
- **Stale assumptions**: if context or consequences described in an old ADR are now known to be incorrect (e.g. a dependency was replaced, a constraint was lifted), annotate that ADR with an `## Amendment` section rather than editing history in place.

Skip this sub-step if there are fewer than two existing ADRs (nothing to consolidate).

Include consolidation actions in the documentation summary:

```
- [ADR] docs/adr/0001-choose-httpx.md — status updated to "Superseded by ADR-0004"
- [ADR] docs/adr/0002-retry-strategy.md — Amendment section added
```

#### 4b — Usage / changelog notes

- Look for `CHANGELOG.md`, `USAGE.md`, or `README.md` at the repo root.
- Append or update the relevant section to reflect: what changed, how users invoke or benefit from it, and any breaking changes or migration steps.
- Keep it concise — one to three bullet points per item.

#### 4c — Other noteworthy items

- If the session dialog or code reveals performance characteristics, known limitations, or operational notes future maintainers should know, add a short note to the appropriate place (e.g. `NOTES.md`, inline comment block, or an existing developer guide).

After completing documentation, output a summary:

```
## Documentation updates

- [ADR] docs/adr/0003-use-uv-for-dependency-management.md — created
- [CHANGELOG] Added entry under "Unreleased" for <feature>
- (none) — no architecture decisions or notable items to record
```

### Step 5 — Handoff

- **No blocking issues**: Offer to invoke `commit-commands:commit-push-pr` to complete the publish step.
- **Blocking issues remain**: Display them clearly. Do not proceed.