What happens before every commit?

The workflow formats Markdown files with mdformat (excluding opensrc/), previews changes with git status and git diff, and helps decide single vs multiple commits.

How should I structure the commit messages?

Start with uppercase, use imperative mood, and reference skill/agent names in brackets when applicable. If AI made changes, add a Co-Authored-By line.

How are proposed commits shown?

The system outputs proposed commits and their affected files before you approve execution.

commit

npx machina-cli add skill guillempuche/ai-standards/commit --openclaw

Files (1)

SKILL.md

1.6 KB

Commit Workflow

Standard commit workflow for the ai-standards repository.

Before Every Commit

1. Run Markdown Formatter

Format project markdown files using mdformat (excludes opensrc/ which contains external source):

nix develop -c mdformat skills/ .claude/ agents/ templates/ *.md

2. Preview Changes

Show files involved and diff preview:

git status
git diff --stat
git diff

3. Analyze and Group Changes

Review the changes and determine:

Single commit: All changes are related to one feature/fix
Multiple commits: Changes are unrelated and should be separate

Examples:

Docs update + new skill → 2 commits
Rename agent + update references → 1 commit
Bug fix + unrelated refactor → 2 commits

4. Stage and Commit

For single commit:

git add -A
git commit -m "commit message"

For multiple commits, stage selectively:

git add <related-files>
git commit -m "first commit message"

git add <other-files>
git commit -m "second commit message"

Commit Message Guidelines

Start with uppercase, imperative mood
Reference skill/agent names in brackets when applicable: [powersync] Add sync pattern docs

If AI made the changes, include co-author:

Co-Authored-By: Claude <noreply@anthropic.com>

Output Format

Always show proposed commits with their files:

**Commit 1:** `commit message here`
- file1.md
- file2.ts

**Commit 2:** `another commit message`
- file3.md

Then wait for user approval before executing.

Source

git clone https://github.com/guillempuche/ai-standards/blob/main/.claude/skills/commit/SKILL.mdView on GitHub

Overview

This skill defines a standardized commit workflow for the ai-standards repository. It formats all Markdown files, previews changes, and guides staging and committing with clear messages, ensuring clean history and consistency across the project.

How This Skill Works

Before committing, the workflow formats Markdown files with mdformat (excluding opensrc/), then shows the working tree via git status and git diff. It helps decide whether changes belong to a single commit or multiple commits, then stages and commits accordingly, following a documented message format. If AI contributed changes, a Co-Authored-By line can be included.

When to Use It

Preparing a docs update for ai-standards and want consistent Markdown formatting
Renaming an agent or updating references within the repo
Bug fixes or small feature updates that are tightly related
Splitting unrelated changes into separate commits to keep history clear
When you want to preview the exact files affected before committing

Quick Start

Step 1: Run the Markdown formatter
Step 2: Preview changes with git status and git diff
Step 3: Stage and commit per guidelines; review proposed commits before executing

Best Practices

Always run the Markdown Formatter before committing
Preview affected files with git status and git diff
Group related changes into a single commit whenever feasible
Follow commit message guidelines: uppercase start, imperative mood, brackets for names
Use the Output Format to review proposed commits before executing

Example Use Cases

Docs update + new skill → 2 commits
Rename agent + update references → 1 commit
Bug fix + unrelated refactor → 2 commits
Format all Markdown in skills/ before release
Add new skill docs and tests in one batch

Frequently Asked Questions

Add this skill to your agents