Skip to main content
command CX Codex

create-release-note — Claude Code command

create-release-note generates two versions of release documentation from recent commits: one for customers, one for engineers. Analyzes changes, groups them by theme, and traces each change back to specific commit hashes.

MIT ★ 2,744 updated 2026-10-08

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/create-release-note.md
Open on GitHub

What create-release-note does

The command offers two workflows. Mode 1 takes a commit count (default 10) and generates notes immediately. Mode 2 lists commits from the last 24 hours, lets you pick a starting point, and generates from there to HEAD.

Both modes produce customer-facing release notes (focused on benefits, features, user impact) and technical engineering notes (with commit SHAs, file paths, implementation details). It groups related commits by subsystem, extracts file changes, and traces every claim back to actual commits.

Requires a Git repository with accessible commit history. Each statement in the output references specific SHAs and changed files.

What it helps with

  • generate two distinct release documents from commit history
  • select a precise commit range by date or count
  • group related changes across multiple subsystems
  • link every claim to specific commits and files

Example prompts for the agent

  • /create-release-note 20
  • /create-release-note
  • generate release notes for the last 15 commits

How to install create-release-note

Manually: put the files in place

.claude/commands/create-release-note.md

Call it with /create-release-note. For all projects use ~/.claude/commands/

Questions about create-release-note

How do I install create-release-note in Claude Code?

Copy the file to .claude/commands/create-release-note.md. For other platforms: ~/.codex/prompts/create-release-note.md (Codex), .github/prompts/create-release-note.prompt.md (GitHub Copilot), .gemini/commands/create-release-note.toml (Gemini CLI).

What does create-release-note do?

It analyzes commits and produces two release notes: one for end users (highlighting benefits and features) and one for developers (with technical details, commit SHAs, and file paths). You choose how many commits to include or pick a time range from recent history.

Does the command require Git?

Yes, it needs a working Git repository with accessible commit history. Without it, the command cannot run.

Source text

create-release-note.md · MIT
# Release Note Generator

Generate comprehensive release documentation from recent commits, producing two distinct outputs: a customer-facing release note and a technical engineering note.

## Interactive Workflow

When this command is triggered, **DO NOT** immediately generate release notes. Instead, present the user with two options:

### Mode Selection Prompt

Present this to the user:

```text
I can generate release notes in two ways:

**Mode 1: By Commit Count**
Generate notes for the last N commits (specify number or use default 10)
→ Quick generation when you know the commit count

**Mode 2: By Commit Hash Range (i.e. Last 24/48/72 Hours)**
Show all commits from the last 24/48/72 hours, then you select a starting commit
→ Precise control when you want to review recent commits first

Which mode would you like?
1. Commit count (provide number or use default)
2. Commit hash selection (show last 24/48/72 hours)

You can also provide an argument directly: /create-release-note 20
```

---

## Mode 1: By Commit Count

### Usage

```bash
/create-release-note          # Triggers mode selection
/create-release-note 20       # Directly uses Mode 1 with 20 commits
/create-release-note 50       # Directly uses Mode 1 with 50 commits
```

### Process

1. If `$ARGUMENTS` is provided, use it as commit count
2. If no `$ARGUMENTS`, ask user for commit count or default to 10
3. Set: `COMMIT_COUNT="${ARGUMENTS:-10}"`
4. Generate release notes immediately

---

## Mode 2: By Commit Hash Range

### Workflow

When user selects Mode 2, follow this process:

### Step 1: Retrieve Last 24 Hours of Commits

```bash
git log --since="24 hours ago" --pretty=format:"%h|%ai|%an|%s" --reverse
```

### Step 2: Present Commits to User

Format the output as a numbered list for easy selection:

```text
Commits from the last 24 hours (oldest to newest):

 1. a3f7e821 | 2025-10-15 09:23:45 | Alice Smith | Add OAuth provider configuration
 2. b4c8f932 | 2025-10-15 10:15:22 | Bob Jones | Implement token refresh flow
 3. c5d9e043 | 2025-10-15 11:42:18 | Alice Smith | Add provider UI components
 4. d6e1f154 | 2025-10-15 13:08:33 | Carol White | Database connection pooling
 5. e7f2g265 | 2025-10-15 14:55:47 | Alice Smith | Query optimization middleware
 6. f8g3h376 | 2025-10-15 16:20:12 | Bob Jones | Dark mode CSS variables
 7. g9h4i487 | 2025-10-15 17:10:55 | Carol White | Theme switching logic
 8. h0i5j598 | 2025-10-16 08:45:29 | Alice Smith | Error boundary implementation

Please provide the starting commit hash (8 characters) or number.
Release notes will be generated from your selection to HEAD (most recent).

Example: "a3f7e821" or "1" will generate notes for commits 1-8
Example: "d6e1f154" or "4" will generate notes for commits 4-8
```

### Step 3: Generate Notes from Selected Commit

Once user provides a commit hash or number:

```bash
# If user provided a number, extract the corresponding hash
SELECTED_HASH="<hash from user input>"

# Generate notes from selected commit to HEAD
git log ${SELECTED_HASH}..HEAD --stat --oneline
git log ${SELECTED_HASH}..HEAD --pretty=format:"%H|%s|%an|%ad" --date=short
```

**Important:** The range `${SELECTED_HASH}..HEAD` means "from the commit AFTER the selected hash to HEAD". If you want to include the selected commit itself, use `${SELECTED_HASH}^..HEAD` or count commits with `--ancestry-path`.

### Step 4: Confirm Range

Before generating, confirm with user:

```text
Generating release notes for N commits:
From: <hash> - <commit message>
To:   <HEAD hash> - <commit message>

Proceeding with generation...
```

---

## Core Requirements

### 1. Commit Analysis

**Determine commit source:**

- **Mode 1**: `COMMIT_COUNT="${ARGUMENTS:-10}"` → Use `git log -${COMMIT_COUNT}`
- **Mode 2**: User-selected hash → Use `git log ${SELECTED_HASH}..HEAD`

**Retrieve commits:**

- Use `git log <range> --stat --oneline`
- Use `git log <range> --pretty=format:"%H|%s|%an|%ad" --date=short`
- Analyze file changes to understand scope and impact
- Group related commits by feature/subsystem
- Identify major themes and primary focus areas

### 2. Traceability

- Every claim MUST be traceable to specific commit SHAs
- Reference actual files changed (e.g., src/config.ts, lib/utils.py)
- Use 8-character SHA prefixes for engineering notes (e.g., 0ca46028)
- Verify all technical details against actual commit content

### 3. Length Constraints

- Each section: ≤500 words (strict maximum)
- Aim for 150-180 words for optimal readability
- Prioritize most impactful changes if space constrained

---

## Section 1: Release Note (Customer-Facing)

### Purpose

Communicate value to end users without requiring deep technical knowledge. Audience varies by project type (system administrators, developers, product users, etc.).

### Tone and Style

- **Friendly & Clear**: Write as if explaining to a competent user of the software
- **Value-Focused**: Emphasize benefits and capabilities, not implementation details
- **Confident**: Use active voice and definitive statements
- **Professional**: Avoid jargon, explain acronyms on first use
- **Contextual**: Adapt language to the project type (infrastructure, web app, library, tool, etc.)

### Content Guidelines

**Include:**

- Major new features or functionality
- User-visible improvements
- Performance enhancements
- Security updates
- Dependency/component version upgrades
- Compatibility improvements
- Bug fixes affecting user experience

**Exclude:**

- Internal refactoring (unless it improves performance)
- Code organization changes
- Developer-only tooling
- Commit SHAs or file paths
- Implementation details
- Internal API changes (unless user-facing library)

### Structure Template

```markdown
## Release Note (Customer-Facing)

**[Project Name] [Version] - [Descriptive Title]**

[Opening paragraph: 1-2 sentences describing the primary focus/theme]

**Key improvements:**
- [Feature/improvement 1: benefit-focused description]
- [Feature/improvement 2: benefit-focused description]
- [Feature/improvement 3: benefit-focused description]
- [Feature/improvement 4: benefit-focused description]
- [etc.]

[Closing paragraph: 1-2 sentences about overall impact and use cases]
```

### Style Examples

✅ **Good (Customer-Facing):**
> "Enhanced authentication system with support for OAuth 2.0 and SAML providers"

❌ **Bad (Too Technical):**
> "Refactored src/auth/oauth.ts to implement RFC 6749 token refresh flow"

✅ **Good (Value-Focused):**
> "Improved database query performance, reducing page load times by 40%"

❌ **Bad (Implementation Details):**
> "Added connection pooling in db/connection.ts with configurable pool size"

✅ **Good (User Benefit):**
> "Added dark mode support with automatic system theme detection"

❌ **Bad (Technical Detail):**
> "Implemented CSS variables in styles/theme.css for runtime theme switching"

---

## Section 2: Engineering Note (Technical)

### Purpose

Provide developers/maintainers with precise technical details for code review, debugging, and future reference.

### Tone and Style

- **Precise & Technical**: Use exact terminology and technical language
- **Reference-Heavy**: Include SHAs, file paths, function names
- **Concise**: Information density over narrative
- **Structured**: Group by subsystem or feature area

### Content Guidelines

**Include:**

- 8-character SHA prefixes for every commit or commit group
- Exact file paths (src/components/App.tsx, lib/db/connection.py)
- Specific technical changes (version numbers, configuration changes)
- Module/function names when relevant
- Code organization changes
- All commits (even minor refactoring)
- Breaking changes or API modifications

**Structure:**

- Group related commits by subsystem
- List most significant changes first
- Use single-sentence summaries per commit/group
- Format: `SHA: description (file references)`

### Structure Template

```markdown
## Engineering Note (Technical)

**[Primary Focus/Theme]**

[Opening sentence: describe the main technical objective]

**[Subsystem/Feature Area 1]:**
- SHA1: brief technical description (file1, file2)
- SHA2: brief technical description (file3)
- SHA3, SHA4: grouped description (file4, file5, file6)

**[Subsystem/Feature Area 2]:**
- SHA5: brief technical description (file7, file8)
- SHA6: brief technical description (file9)

**[Subsystem/Feature Area 3]:**
- SHA7, SHA8, SHA9: grouped description (files10-15)
- SHA10: brief technical description (file16)

[Optional: List number of files affected if significant]
```

### Style Examples

✅ **Good (Technical):**
> "a3f7e821: OAuth 2.0 token refresh implementation in src/auth/oauth.ts, src/auth/tokens.ts"

❌ **Bad (Too Vague):**
> "Updated authentication system for better token handling"

✅ **Good (Grouped):**
> "c4d8a123, e5f9b234, a1c2d345: Database connection pooling (src/db/pool.ts, src/db/config.ts)"

❌ **Bad (No References):**
> "Fixed database connection issues"

✅ **Good (Precise):**
> "7b8c9d01: Upgrade react from 18.2.0 to 18.3.1 (package.json)"

❌ **Bad (Missing Context):**
> "Updated React dependency"

---

## Formatting Standards

### Markdown Requirements

- Use `##` for main section headers
- Use `**bold**` for subsection headers and project titles
- Use `-` for bullet lists
- Use `` `backticks` `` for file paths, commands, version numbers
- Use 8-character SHA prefixes: `0ca46028` not `0ca46028b9fa62bb995e41133036c9f0d6ac9fef`

### Horizontal Separator

Use `---` (three hyphens) to separate the two sections for visual clarity.

### Version Numbers

Format as: `version X.Y` or `version X.Y.Z` (e.g., "React 18.3", "Python 3.12.1")

### File Paths

- Use actual paths from repository: `src/components/App.tsx` not "main component"
- Multiple files: `(file1, file2, file3)` or `(files1-10)` for ranges
- Use project-appropriate path conventions (src/, lib/, app/, pkg/, etc.)

---

## Commit Grouping Strategy

### Group When

- Multiple commits modify the same file/subsystem
- Commits represent incremental work on same feature
- Space constraints require consolidation
- Related bug fixes or improvements

### Example Grouping

```text
Individual:
- c4d8a123: Add connection pool configuration
- e5f9b234: Implement pool lifecycle management
- a1c2d345: Add connection pool metrics

Grouped:
- c4d8a123, e5f9b234, a1c2d345: Database connection pooling (src/db/pool.ts, src/db/config.ts, src/db/metrics.ts)
```

### Don't Group

- Unrelated commits (different subsystems)
- Major features (deserve individual mention)
- Commits with significantly different file scopes
- Breaking changes (always call out separately)

---

## Quality Checklist

Before finalizing, verify:

- [ ] Mode selection presented (unless $ARGUMENTS provided)
- [ ] Commit range correctly determined (Mode 1: count, Mode 2: hash range)
- [ ] User confirmed commit range before generation
- [ ] Both sections ≤500 words
- [ ] Every claim traceable to specific commit(s)
- [ ] Customer note has no SHAs or file paths
- [ ] Engineering note has SHAs for all commits/groups
- [ ] File paths are accurate and complete
- [ ] Tone appropriate for each audience
- [ ] Markdown formatting consistent
- [ ] Version numbers accurate
- [ ] No typos or grammatical errors
- [ ] Primary focus clearly communicated in both sections
- [ ] Most significant changes prioritized first
- [ ] Language adapted to project type (not overly specific to one domain)

---

## Edge Cases

### If Fewer Commits Than Requested

- Generate notes for all available commits
- Note this at the beginning: "Release covering [N] commits"
- Example: "Release covering 7 commits (requested 10)"

### If No Commits in Last 24 Hours (Mode 2)

- Inform user: "No commits found in the last 24 hours"
- Offer alternatives:
  - Extend time range (48 hours, 7 days)
  - Switch to Mode 1 (commit count)
  - Manual hash range specification

### If Mostly Minor Changes

- Group aggressively by subsystem
- Lead with most significant changes
- Note: "Maintenance release with incremental improvements"

### If Single Major Feature Dominates

- Lead with that feature in both sections
- Group supporting commits under that theme
- Structure engineering note by feature components

### If Merge Commits Present

- Skip merge commits themselves
- Include the actual changes from merged branches
- Focus on functional changes, not merge mechanics

### If No Version Tag Available

- Use branch name or generic title: "Development Updates" or "Recent Improvements"
- Focus on change summary rather than version-specific language

### If User Provides Invalid Commit Hash

- Validate hash exists: `git cat-file -t ${HASH} 2>/dev/null`
- If invalid, show error and re-present commit list
- Suggest checking the hash or selecting by number instead

---

## Adapting to Project Types

### Infrastructure/DevOps Projects

- Focus on: deployment improvements, configuration management, monitoring, reliability
- Audience: sysadmins, DevOps engineers, SREs

### Web Applications

- Focus on: features, UX improvements, performance, security
- Audience: product users, stakeholders, QA teams

### Libraries/Frameworks

- Focus on: API changes, new capabilities, breaking changes, migration guides
- Audience: developers using the library

### CLI Tools

- Focus on: command changes, new options, output improvements, bug fixes
- Audience: command-line users, automation engineers

### Internal Tools

- Focus on: workflow improvements, bug fixes, integration updates
- Audience: team members, internal stakeholders

---

## Example Output Structure

```markdown
## Release Note (Customer-Facing)

**MyProject v2.4.0 - Authentication & Performance Update**

This release introduces comprehensive OAuth 2.0 support and significant performance improvements across the application.

**Key improvements:**
- OAuth 2.0 authentication with support for Google, GitHub, and Microsoft providers
- Improved database query performance with connection pooling, reducing response times by 40%
- Added dark mode support with automatic system theme detection
- Enhanced error handling and user feedback throughout the interface
- Security updates for dependency vulnerabilities

These enhancements provide a more secure, performant, and user-friendly experience across all application features.

---

## Engineering Note (Technical)

**OAuth 2.0 Integration and Performance Optimization**

Primary focus: authentication modernization and database performance improvements.

**Authentication System:**
- a3f7e821: OAuth 2.0 provider implementation (src/auth/oauth.ts, src/auth/providers/)
- b4c8f932: Token refresh flow and session management (src/auth/tokens.ts)
- c5d9e043: Provider registration UI components (src/components/auth/OAuthProviders.tsx)

**Performance Optimization:**
- d6e1f154: Database connection pooling (src/db/pool.ts, src/db/config.ts)
- e7f2g265: Query optimization middleware (src/db/middleware.ts)

**UI/UX Improvements:**
- f8g3h376, g9h4i487: Dark mode CSS variables and theme switching (src/styles/theme.css, src/components/ThemeProvider.tsx)
- h0i5j598: Error boundary implementation (src/components/ErrorBoundary.tsx)

**Security:**
- i1j6k609: Dependency updates for security patches (package.json, yarn.lock)
```

---

## Implementation Workflow

When executing this command, Claude should:

### If $ARGUMENTS Provided

1. Use `COMMIT_COUNT="${ARGUMENTS}"`
2. Run git commands with the determined count
3. Generate both sections immediately

### If No $ARGUMENTS

1. Present mode selection prompt to user
2. Wait for user response

**If user selects Mode 1:**
3. Ask for commit count or use default 10
4. Generate notes immediately

**If user selects Mode 2:**
3. Retrieve commits from last 24 hours
4. Present formatted list with numbers and hashes
5. Wait for user to provide hash or number
6. Validate selection
7. Confirm commit range
8. Generate notes from selected commit to HEAD

### Final Steps (Both Modes)

1. Analyze commits thoroughly
2. Generate both sections following all guidelines
3. Verify against quality checklist
4. Present both notes in the specified format

© centminmod · MIT · centminmod/my-claude-code-setup

Similar slash commands

All slash commands for Git and GitHub →

From the same set35

The whole set →
cleanup-context cleanup-context — a Claude Code command that audits project documentation files (CLAUDE-*.md, CLAUDE.md, README.md) to identify redundant content, obsolete materials, and overlapping coverage. CX Codex +1 ★ 2,744repo stars audit-session-metrics Reads a session-metrics JSON export and reports on token-usage waste. Invoke it with /audit-session-metrics quick or detailed against a finished export file. CX Codex +1 ★ 2,744repo stars task-breakdown task-breakdown groups turns from a Claude Code session into semantic tasks and generates an audit report with waste verdicts. CX Codex +1 ★ 2,744repo stars apply-thinking-to The apply-thinking-to command reshapes a prompt file with Anthropic-style extended-thinking patterns. Use it when an analysis needs clearer stages, checks, and trade-off review. CX Codex +1 ★ 2,744repo stars consult-zai consult-zai pairs z.ai GLM 5.2 with Claude code-searcher for two-model code reviews. Delivers a second opinion on bugs and architecture questions. CX Codex +1 ★ 2,744repo stars consult-codex The consult-codex skill sends code questions to OpenAI Codex and Claude code-searcher, then combines their cited findings. Use it for difficult debugging, design questions, or code review. CX Codex +1 ★ 2,744repo stars convert-to-todowrite-tasklist-prompt convert-to-todowrite-tasklist-prompt transforms verbose slash commands with heavy context into TodoWrite tasks that run in parallel via subagents. Speed gain: 60–70%. CX Codex +1 ★ 2,744repo stars refactor-code refactor-code audits code and generates a step-by-step refactoring blueprint without modifying repository files. Useful before breaking up legacy monolithic modules. CX Codex +1 ★ 2,744repo stars

Project sponsors

Companies that keep this analytics open