# Commit

> Create git commits following STAR conventions with safety protocols. Use when user asks to commit changes, create a commit, or save work to git. Use when this capability is needed.

- Skill: `tomevault-io/commit-13` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/commit-13`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/commit-13/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/commit-13

---


# Git Commit Skill

Create commits following STAR project conventions with proper safety checks and commit message formatting.

## Git Safety Protocol

**NEVER**:
- Update git config without user permission
- Run destructive commands (`push --force`, `reset --hard`, `checkout .`, `restore .`, `clean -f`, `branch -D`) unless explicitly requested
- Skip hooks (`--no-verify`, `--no-gpg-sign`) unless explicitly requested
- Force push to main/master (warn user if requested)
- **CRITICAL**: Amend commits when pre-commit hooks fail - the commit did NOT happen, so `--amend` would modify the PREVIOUS commit!
- Commit changes unless explicitly asked (only commit when user requests it)
- Use `git add -A` or `git add .` (prefer adding specific files by name to avoid accidentally staging sensitive files)

**ALWAYS**:
- Create NEW commits rather than amending (unless user explicitly requests `git commit --amend`)
- When pre-commit hook fails: fix the issue, re-stage, and create a NEW commit
- Add specific files by name rather than using `git add -A`
- Avoid committing sensitive files (`.env`, `credentials.json`, etc.)

## Commit Workflow

When the user asks to create a commit, follow these steps:

### Step 1: Analyze Current State [PASS] READ-ONLY (Safe to run immediately)

Run these commands in parallel to understand the repository state:

```bash
# See all untracked files (NEVER use -uall flag)
git status

# See both staged and unstaged changes
git diff HEAD

# See recent commit messages to match style
git log --oneline -n 10
```

### Step 2: Draft Commit Message [PASS] READ-ONLY (Safe to draft)

Analyze all changes (both previously staged and newly added) and draft a message that:
- Summarizes the nature of changes (new feature, enhancement, bug fix, refactoring, test, docs)
- Is concise (1-2 sentences)
- Focuses on "why" rather than "what"
- Follows the project's commit message style (check recent commits)
- Uses accurate verbs:
  - "add" = wholly new feature
  - "update" = enhancement to existing feature
  - "fix" = bug fix
  - "refactor" = code restructuring

**IMPORTANT**: Do NOT add AI attribution. Never include "Co-Authored-By: Claude" or "Generated by Claude Code" footers. Write natural, human-style commit messages.

---

### Step 3: Stage and Commit

Run sequentially:

```bash
# Add relevant files by name (NOT git add -A or git add .)
git add path/to/file1.c path/to/file2.h

# Create commit with proper message formatting
git commit -m "$(cat <<'EOF'
Your commit message here.

Additional details if needed (optional).
EOF
)"

# Verify commit succeeded
git status
```

**Note**: Use HEREDOC format for commit messages to ensure proper formatting and avoid shell escaping issues.

### Step 4: Handle Pre-commit Hook Failures

If pre-commit hook fails:
1. **DO NOT use `--amend`** - the commit did NOT happen yet!
2. Fix the issue identified by the hook
3. Re-stage the fixed files: `git add path/to/fixed/file`
4. Create a NEW commit (not amend)

## Examples

### Example 1: Simple Feature Addition

```bash
# Step 1: Check status (READ-ONLY)
git status
git diff HEAD
git log --oneline -n 10

# Step 2: Draft message (READ-ONLY)
# Message: "Add PID controller implementation"
# Details: "Implements discrete-time PID algorithm with anti-windup and derivative filtering for motor velocity control."

# Step 3: Stage and commit
git add src/rx_pid.c src/rx_pid.h

git commit -m "$(cat <<'EOF'
Add PID controller implementation

Implements discrete-time PID algorithm with anti-windup and
derivative filtering for motor velocity control.
EOF
)"

# Step 4: Verify
git status
```

### Example 2: Bug Fix

```bash
git add src/rx_spi.c

git commit -m "$(cat <<'EOF'
Fix SPI timeout handling

Corrects timeout calculation to use milliseconds instead of
microseconds, preventing premature timeouts.
EOF
)"

git status
```

### Example 3: Documentation Update

```bash
git add CLAUDE.md
git commit -m "Update CLAUDE.md with LSP configuration instructions"
```

## Common Mistakes to Avoid

[FAIL] **Wrong**: Using `git add .` (might stage sensitive files)
[PASS] **Correct**: `git add src/module.c include/module.h`

[FAIL] **Wrong**: Amending after hook failure
[PASS] **Correct**: Fix issue, re-stage, create NEW commit

[FAIL] **Wrong**: Adding AI attribution to commit message
[PASS] **Correct**: Write natural, human-style commit messages

[FAIL] **Wrong**: Vague messages like "fix bug" or "update code"
[PASS] **Correct**: "Fix SPI timeout calculation in rx_spi.c"

## Important Notes

- **No `-uall` flag**: Never use `git status -uall` (can cause memory issues on large repos)
- **Sensitive files**: Never commit `.env`, `credentials.json`, API keys, or similar
- **Commit when asked**: Only create commits when user explicitly requests them
- **Natural messages**: No AI attribution, no "Generated by..." footers
- **Specific staging**: Prefer `git add <specific files>` over `git add .`

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/locked-inc) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-14 -->