Smart Commit Skill | Agent Skills

Smart Commit

Analyze the current Claude Code session history and split uncommitted changes into logical commit groups.

CRITICAL: Execution Rules

MUST DO:

Run python scripts/parse-session.py for session data extraction
Run python scripts/analyze-commits.py for commit group analysis
Wait for complete script output before proceeding
Use AskUserQuestion before executing each commit
Use TaskCreate for commit execution workflow

NEVER DO:

Parse ~/.claude/projects/ JSONL files directly with Bash/jq/Read
Commit without user confirmation
Modify or checkout files to split commits (only use git add for staging)
Reorder file history or manipulate working tree state

WHY: Session JSONL files have complex nested structures with tool calls, snapshots, and message threading. The Python scripts handle this reliably. Overlapping files are auto-merged by the analysis script, so no file manipulation is needed.

Workflow

Phase 1: Pre-flight Check

git status --porcelain

If output is empty → tell user "No uncommitted changes found" and stop
If changes exist → proceed to Phase 2
Also run git diff --stat to show a summary of changes

Phase 2: Session Data Extraction

Run the parse-session script from the plugin's skill directory:

python <plugin-skill-dir>/scripts/parse-session.py --project "$(pwd)"

The script outputs JSON to stdout with:

session_id: Current session identifier
project_path: Working project path
user_messages: List of user messages with timestamps
file_ops: List of file edit/write operations with timestamps and paths
snapshots: File history snapshot mappings

On error: Script prints [ERROR] and [HINT] to stderr. Show these to user.

Phase 3: Commit Group Analysis

Pipe or pass the session data to the analysis script:

python <plugin-skill-dir>/scripts/analyze-commits.py --session-data <temp-json-path>

Or via stdin:

python <plugin-skill-dir>/scripts/parse-session.py --project "$(pwd)" | \
  python <plugin-skill-dir>/scripts/analyze-commits.py

The script outputs JSON with:

commit_groups: Ordered list of commit groups, each with index, type, message, files, user_context
merged_groups: Info about groups that were merged due to overlapping files
summary: Total groups count and merge statistics

Important: Overlapping files (same file in multiple groups) are automatically merged into a single group by the script. This means every file appears in exactly one group → simple git add per group is safe.

Phase 4: Present Commit Plan

Show the user a formatted commit plan:

Commit Plan (N commits):

1. feat: Add user authentication
   Files: src/auth.ts (new), src/middleware.ts (modified)
   Context: "사용자 인증 기능 추가해줘"

2. fix: Fix validation error handling
   Files: src/validator.ts (modified)
   Context: "에러 처리 고쳐줘"

[Merged: Groups 2,3 combined due to shared file src/middleware.ts]

Then use AskUserQuestion:

"Execute all commits as planned" (Recommended)
"Let me review each commit individually"
"Cancel"

If cancelled → stop. Otherwise proceed to Phase 5.

Phase 5: Execute Commits via TaskCreate

Create a Task for each commit group and execute sequentially.

For detailed TaskCreate workflow, blocking dependencies, and per-commit confirmation logic, see: commit-execution.md

Quick summary:

Create all Tasks with blockedBy dependencies for ordering
For each Task: confirm with user → git add <files> → git commit
Last commit includes any remaining unstaged changes
Skipped commits' files roll into the next commit

Phase 6: Result Report

After all commits are done:

git log --oneline -N  # N = number of commits created
git status

Show:

List of commits created with their hashes
Any remaining uncommitted changes
Total commits: X created, Y skipped

Error Handling

| Issue | Cause | Solution | |-------|-------|----------| | "No session found" | No recent session for project | Use --session <id> to specify manually | | "No file operations" | Session has no edits | Nothing to commit, inform user | | Script not found | Wrong working directory | Ensure plugin is installed correctly | | Git conflicts | Staging issues | Run git status and show user | | Empty commit group | All files in group already committed | Skip and continue |

If a Python script fails:

Show the stderr output to the user
Verify ~/.claude/ directory exists and has session data
Check Python 3 is available
Suggest --verbose flag for detailed diagnostics

Script CLI Reference

parse-session.py

| Option | Description | |--------|-------------| | --project <path> | Project directory path (auto-detects latest session) | | --session <id> | Specific session ID to parse | | --verbose | Print detailed parsing log to stderr |

analyze-commits.py

| Option | Description | |--------|-------------| | --session-data <path> | Path to JSON from parse-session.py (or use stdin) | | --verbose | Print boundary decision reasoning to stderr |

Agent Skills: Smart Commit

Install this agent skill to your local

Skill Files