# Commit

> Stage relevant files and create a well-formed git commit for the docs-builder repo. Use this when the user asks to commit changes, save work, or create a commit.

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

---


# Commit Skill

Read [`.claude/skills/writing-style.md`](../writing-style.md) before writing the commit message.

Creates a clean, well-formed commit following the docs-builder project conventions.

## Steps

### 1. Install Husky hooks if missing

Skip this step if `.husky/_/husky.sh` already exists. That file is generated by `dotnet husky install` and is gitignored, so a fresh worktree will not have it.

```bash
if [ ! -f .husky/_/husky.sh ]; then
  dotnet tool restore
  dotnet husky install
fi
```

Do not run `git config` yourself. Do not use `--no-verify`.

### 2. Understand what changed

```bash
git status
git diff
git diff --staged
git log --oneline -5
```

### 3. Stage files

Stage specific files by name — never `git add -A` or `git add .` blindly. Exclude:
- `.env` files or anything with secrets/credentials
- Large binaries not already tracked
- Unrelated changes to the task at hand

### 4. Write the commit message

- **First line**: Imperative mood, ≤72 chars, no trailing period. Front-load the outcome — a reader scanning `git log` sees this line only.
- **Body** (optional): One short paragraph explaining *why*, not what. Skip if the title is self-explanatory. Follow the sentence mechanics in `writing-style.md`.
- **Trailer**: Add a `Co-Authored-By:` line that identifies the model that helped write this commit. Use whatever attribution feels accurate — the model name you know yourself to be running as, or simply `Claude` if you are uncertain. The address is always `noreply@anthropic.com`. The point is honest attribution, not a precise version string.

Always pass the message via HEREDOC to avoid shell escaping issues:

```bash
git commit -m "$(cat <<'EOF'
Title here

Optional body explaining why.

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"
```

### 5. Handle hook failures

This project uses **Husky.Net** git hooks:
- **pre-commit**: runs prettier, eslint, typescript-check
- **pre-push**: runs dotnet-lint

If a hook fails:
1. Read the error output carefully
2. Fix the underlying issue (run `/lint` if it's a formatting problem)
3. Re-stage the affected files
4. Create a **new commit** — never `git commit --amend` for a failed commit, and never use `--no-verify`

### 6. Verify success

```bash
git status
```

Confirm a clean working tree.

### 7. Refresh the PR description if one exists

```bash
gh pr view --json number,url,isDraft,baseRefName --jq '{number,url,isDraft,baseRefName}' 2>/dev/null
```

- **No PR** → done. Say nothing.
- **PR exists** → compare the current body against the current diff versus the PR's base branch. A PR description always describes the current diff against the base branch. It is never a log of the commits on the branch and never records the direction the work took. If any section (`## What`, `## Verify`, `**Affects:**`, label) no longer describes that diff, the description is stale.
- **Stale description** → read and follow [pr](../pr/SKILL.md)'s update path (step 7). Do not hand-edit the body inline from the commit skill. State plainly what was refreshed.
- **Still accurate** → state that the description is still accurate. No edit needed.