# Clean Commit

> Create clean, atomic commits following project conventions. Use when committing code changes, staging files, or writing commit messages.

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

---


# Clean Commit

Create clean, atomic commits that follow the project's conventions. One logical change per commit.

Do not include references to Claude or AI in commit messages. Do not add Co-Authored-By lines or AI attribution signatures.

## Commit Format

Use the project's commit format if defined under `## Commit conventions` in CLAUDE.md.

If no project format is specified, use conventional commits:

```
<type>(<scope>): <short description>

<optional body explaining why>

<optional footer with ticket references>
```

Types: `feat`, `fix`, `ref`, `docs`, `test`, `chore`

- Title 50 characters or less
- Imperative mood ("Add feature" not "Added feature")
- Focus on the "why", not the "what" -- the diff shows the what
- Reference tickets when applicable (`Refs PROJ-1234`)

## Security Check

Before staging any file, check for potential secrets.

**File patterns to block:**

- `.env`, `.env.*`
- `credentials.*`, `secrets.*`
- `*_key.pem`, `*.p12`

**Content patterns to detect:**

- `API_KEY=`, `SECRET_KEY=`, `PASSWORD=`, `TOKEN=`
- `-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----`
- AWS access keys (`AKIA...`)
- GitHub tokens (`ghp_...`, `gho_...`)
- Stripe keys (`sk_live_...`)
- Database connection strings with embedded passwords
- High-entropy strings that look like credentials

**If potential secrets are found:**

1. **Do NOT stage the file**
2. Explain what was detected and why it's risky
3. Suggest adding the file or pattern to `.gitignore`
4. Ask the developer how to proceed

## Process

### 1. Review changes

- Run `git status` to see all changed files
- Run `git diff` to see staged and unstaged changes
- Understand what changed and why
- If changes span multiple unrelated concerns, ask the developer if they should be separate commits

### 2. Stage files

- `git add <specific files>` -- never `git add .`
- Group files by logical change
- Run the Security Check on every file before staging
- If changes span multiple logical units, split into multiple commits

### 3. Draft commit message

- Follow the Commit Format section above
- Reference tickets when applicable (e.g., `Refs PROJ-1234`)
- Keep the body concise -- avoid long paragraphs

### 4. Confirm with the developer

- Show the staged files and proposed commit message
- Wait for approval before executing
- Never commit without confirmation

### 5. Execute and verify

- Create the commit
- Run `git log -1` to confirm the commit was created
- Run `git status` to verify clean state

## Examples

### Feature Commit

```
feat(auth): add password reset flow

Implements forgot password functionality with email verification.
Users can now request a password reset link sent to their email.

Refs PROJ-1234
```

### Bug Fix Commit

```
fix(api): handle null response in user endpoint

The user endpoint could return null for soft-deleted accounts,
causing dashboard crashes when accessing user properties.

Fixes PROJ-5678
```

### Refactor Commit

```
ref: extract validation logic to shared module

Moves duplicate validation code into a shared validator class.
No behavior change.
```

## Key Principles

- **Atomic** -- one logical change per commit
- **Never commit secrets** -- check for .env, credentials, API keys
- **No AI references** -- do not mention Claude or AI in commit messages, no Co-Authored-By
- **Confirm first** -- always show the developer what you're about to commit
- **Message explains why** -- the diff shows what changed, the message explains the reason
- **Project conventions win** -- if CLAUDE.md specifies a format, use it