commit-coauthor

name	commit-coauthor
description	Create git commit with co-author attribution and comprehensive safety checks
context	fork
allowed-tools	["Bash","Read","Grep"]

Commit with Co-Author

Creates git commits with proper co-author attribution, following repository conventions and safety protocols.

Token Efficiency: Automates git safety checks and commit message generation (40% savings: 1,000 → 600 tokens)

Usage

Invoke with: /commit-coauthor [optional-message]

Examples:

• /commit-coauthor - Auto-generate commit message from staged changes
• /commit-coauthor "Fix authentication bug" - Use provided message
• /commit-coauthor "feat: Add user profile page" - Follow conventional commits

Prerequisites

• Git repository initialized
• Changes staged for commit (git add already executed)
• Git user.name and user.email configured
• No pre-commit hooks that would block commit (or hooks pass)

Workflow

Step 1: Safety Checks

Run git status to verify staged changes:

git status --porcelain

Check for:

• At least 1 file staged (M, A, D in column 1)
• No unresolved merge conflicts (UU status)
• Working directory state is clean enough to commit

If no staged changes:

• Return error: "No changes staged for commit. Use git add first."
• Exit Skill

If merge conflicts exist:

• Return error: "Unresolved merge conflicts detected. Resolve conflicts first."
• Exit Skill

Step 2: Sensitive File Detection

Check staged files for sensitive patterns:

# Get list of staged files
git diff --cached --name-only

Scan for sensitive file patterns:

• .env files (environment variables)
• credentials.json, secrets.yaml (credential files)
• *.pem, *.key (private keys)
• id_rsa, *.p12 (SSH/certificate files)
• Files containing password, secret, token in name

If sensitive files detected:

• Warn user: "⚠️ Sensitive file detected: [filename]. Are you sure you want to commit this?"
• List all detected sensitive files
• Ask user to confirm or exclude files

Grep staged files for sensitive content patterns:

# Check for hardcoded secrets in staged changes
git diff --cached | grep -iE "(api_key|secret_key|password|access_token|private_key)" || true

If sensitive content found:

• Warn user with context (line numbers, file names)
• Recommend using environment variables or git-crypt
• Ask for confirmation before proceeding

Step 3: Analyze Staged Changes

Get comprehensive diff of staged changes:

# Show staged changes with file names and line counts
git diff --cached --stat
git diff --cached

Analyze changes to determine:

• Change type: New feature, bug fix, refactor, docs, test, chore
• Scope: Which files/modules affected (frontend, backend, database, config)
• Impact: Breaking change, enhancement, minor fix
• File count: Single file or multiple files

Read recent commits for style:

# Get last 5 commit messages to match repo style
git log -5 --pretty=format:"%s"

Identify commit message conventions:

• Conventional Commits format: feat:, fix:, docs:, refactor:, test:, chore:
• Imperative mood: "Add feature" vs "Added feature"
• Scope usage: feat(auth):, fix(api):
• Length: Short (50 chars) vs detailed

Step 4: Generate Commit Message (if not provided)

Only if user didn't provide message

Message structure:

[type]([scope]): [short summary]

[optional body - detailed explanation]

Co-Authored-By: Claude Sonnet 4.5 <[e-mail]>

Type classification logic:

Files Changed	Patterns Found	Type
src/**/*.tsx, components/**	New component created	feat
*.tsx, *.ts	Bug fix in existing code	fix
README.md, docs/**	Documentation only	docs
*.test.ts, *.spec.ts	Test files only	test
Code structure changes, no new behavior	Refactoring	refactor
Build config, dependencies	Configuration	chore

Scope extraction:

• Auth files (auth/**, *Auth*): auth
• API files (api/**, *api*): api
• Database (db/**, *.drizzle.*): db
• UI components (components/**): ui
• Multiple areas: Omit scope or use general scope

Summary guidelines:

• Start with verb in imperative mood: "Add", "Fix", "Update", "Remove"
• Keep under 50 characters
• Focus on "what" and "why", not "how"
• No period at end

Example auto-generated messages:

feat(auth): Add password reset functionality

Implements password reset flow with email verification.
Adds /api/auth/reset-password endpoint and email templates.

Co-Authored-By: Claude Sonnet 4.5 <[e-mail]>

fix(api): Resolve null pointer in user profile endpoint

Adds null check before accessing user.shifts property.
Fixes TypeError that prevented profile page from loading.

Co-Authored-By: Claude Sonnet 4.5 <[e-mail]>

Step 5: Create Commit

Format commit message with co-author trailer:

If user provided message:

[user-message]

Co-Authored-By: Claude Sonnet 4.5 <[e-mail]>

If auto-generated:

[generated-message-with-body]

Co-Authored-By: Claude Sonnet 4.5 <[e-mail]>

Execute commit with HEREDOC for proper formatting:

git commit -m "$(cat <<'EOF'
[commit-message-here]

Co-Authored-By: Claude Sonnet 4.5 <[e-mail]>
EOF
)"

CRITICAL Git Safety Rules:

• ✅ Use co-author trailer (required)
• ❌ NEVER use --no-verify (skip hooks)
• ❌ NEVER use --amend unless:
  • User explicitly requested amend, AND
  • HEAD commit was created by Claude in this conversation, AND
  • Commit has NOT been pushed to remote
• ❌ NEVER use --force or --force-with-lease
• ❌ NEVER commit without user awareness

Step 6: Verify Commit Success

Check git status after commit:

git status
git log -1 --pretty=format:"%h %s%n%b"

Success indicators:

• Working tree clean or only unstaged files remain
• Latest commit matches expected message
• Co-author trailer present in commit body
• Commit hash generated

If commit failed:

• Extract error message from git output
• Identify failure cause (pre-commit hook, invalid message, etc.)
• Provide fix recommendation
• DO NOT retry automatically

If commit succeeded:

• Display commit hash and message
• Show files committed
• Note if there are remaining unstaged changes
• Ask if user wants to push to remote (don't push automatically)

Step 7: Return Commit Summary

Return structured result:

{
  "success": true,
  "commit_hash": "a1b2c3d",
  "commit_message": "[full commit message]",
  "files_committed": ["src/components/Auth.tsx", "src/api/auth.ts"],
  "files_count": 2,
  "insertions": 45,
  "deletions": 12,
  "unstaged_changes": 0,
  "co_author_added": true
}

If commit failed:

{
  "success": false,
  "error": "Pre-commit hook failed: ESLint errors",
  "recommendation": "Fix ESLint errors and retry commit"
}

Success Criteria

• Safety checks completed (staged changes verified)
• Sensitive files/content detected and warned
• Commit message follows repository conventions
• Co-author trailer added to commit body
• Git Safety Protocol followed (no --no-verify, no --amend without checks)
• Commit success verified
• Structured result returned

Git Safety Protocol

Never Skip Hooks

CRITICAL: Never use --no-verify or -n flag

# ❌ WRONG - Skips pre-commit hooks
git commit --no-verify -m "message"

# ✅ CORRECT - Respects hooks
git commit -m "message"

If pre-commit hook fails:

• Show error message from hook
• Fix the issue (lint errors, format issues, etc.)
• Create NEW commit after fixing
• Do NOT use --no-verify to bypass

Amend Rules

Only use --amend when ALL conditions met:

1. User explicitly requested amend, OR
2. Commit SUCCEEDED but pre-commit hook auto-modified files
3. HEAD commit was created by Claude in this conversation:

   git log -1 --format='%an %ae' | grep -q "Claude"
   

4. Commit has NOT been pushed to remote:

   git status | grep -q "Your branch is ahead"
   

NEVER amend if:

• ❌ Commit failed or was rejected by hook
• ❌ HEAD commit was created by user or other tool
• ❌ Commit already pushed to remote (requires force push)
• ❌ User didn't explicitly request amend

If commit FAILED or REJECTED:

• Fix the issue
• Create NEW commit (do NOT amend)

Force Push Protection

NEVER run force push unless:

• User explicitly requested: "force push to main"
• Even then, warn if branch is main/master

# ❌ NEVER run automatically
git push --force
git push --force-with-lease

# ✅ Only if user explicitly requests and confirms
# Show warning: "⚠️ Force push to main can overwrite team's work. Are you sure?"

Sensitive Content Rules

NEVER commit without warning:

• .env files (recommend .env.example instead)
• credentials.json, secrets.yaml
• Private keys (.pem, .key)
• Files with password, secret, token in content

If user requests committing sensitive file:

• Show warning with explanation
• Recommend alternatives (environment variables, git-crypt, secrets manager)
• Require explicit confirmation: "Type 'yes' to commit anyway"

Error Handling

Error 1: No Staged Changes

Symptom: git status shows no files in staging area Cause: User forgot to git add files Solution:

# Show what files can be staged
git status --short

# Return error
echo "No changes staged for commit. Use 'git add <file>' first."

Error 2: Pre-Commit Hook Failed

Symptom: Commit rejected with hook error message Cause: Code doesn't pass lint, format, or test checks Solution:

• Display full hook error message
• Identify issue (ESLint errors, Prettier format, failing tests)
• Recommend fix: "Run npm run lint:fix to auto-fix errors"
• Create NEW commit after fixing (do NOT use --no-verify)

Error 3: Invalid Commit Message Format

Symptom: Commit rejected due to commit message validation hook Cause: Message doesn't follow Conventional Commits or repo standards Solution:

• Show expected format from hook error
• Regenerate message following correct format
• Retry commit with corrected message

Error 4: Merge Conflict Detected

Symptom: git status shows UU (unmerged) files Cause: User in middle of merge with conflicts Solution:

echo "Unresolved merge conflicts detected in:"
git diff --name-only --diff-filter=U

echo "Resolve conflicts first using 'git mergetool' or manually edit files."

Error 5: Detached HEAD State

Symptom: git status shows "HEAD detached at [commit]" Cause: User checked out specific commit instead of branch Solution:

echo "⚠️ In detached HEAD state. Commit will not be on any branch."
echo "Checkout a branch first: 'git checkout main'"

Examples

Example 1: Auto-Generated Message

User: /commit-coauthor

Git status:

M  src/components/Settings.tsx
M  src/api/settings.ts
A  src/types/settings.d.ts

Auto-generated commit:

feat(settings): Add user notification preferences

Implements email and SMS notification toggles.
Adds Settings API endpoint and TypeScript types.

Co-Authored-By: Claude Sonnet 4.5 <[e-mail]>

Output:

{
  "success": true,
  "commit_hash": "7f3a8c2",
  "commit_message": "feat(settings): Add user notification preferences\n\nImplements email and SMS notification toggles.\nAdds Settings API endpoint and TypeScript types.\n\nCo-Authored-By: Claude Sonnet 4.5 <[e-mail]>",
  "files_committed": ["src/components/Settings.tsx", "src/api/settings.ts", "src/types/settings.d.ts"],
  "files_count": 3,
  "insertions": 87,
  "deletions": 5,
  "co_author_added": true
}

Console log: "✅ Commit created: 7f3a8c2 'feat(settings): Add user notification preferences'"

Example 2: User-Provided Message

User: /commit-coauthor "Fix null pointer in scheduler view"

Commit:

Fix null pointer in scheduler view

Co-Authored-By: Claude Sonnet 4.5 <[e-mail]>

Output:

{
  "success": true,
  "commit_hash": "b4c8d1e",
  "commit_message": "Fix null pointer in scheduler view\n\nCo-Authored-By: Claude Sonnet 4.5 <[e-mail]>",
  "files_committed": ["src/components/SchedulerView.tsx"],
  "files_count": 1,
  "insertions": 3,
  "deletions": 1,
  "co_author_added": true
}

Example 3: Sensitive File Warning

User: /commit-coauthor

Staged files: .env, src/config/database.ts

Output:

⚠️ Sensitive file detected: .env

This file may contain secrets or credentials.

Recommendations:
1. Create .env.example with placeholder values instead
2. Add .env to .gitignore
3. Use environment variables for sensitive data

Detected patterns in .env:
- DATABASE_URL (contains connection string)
- JWT_SECRET (contains secret key)

Do you want to proceed with committing .env? (Type 'yes' to confirm)

If user confirms 'yes':

• Create commit with warning in commit body
• Log sensitive file commit for audit

If user cancels:

• Exit Skill
• Suggest: git reset HEAD .env to unstage

Example 4: Pre-Commit Hook Failure

User: /commit-coauthor

Pre-commit hook output:

ESLint found 3 errors:
  src/components/Settings.tsx
    42:15  error  'user' is not defined  no-undef
    58:22  error  Missing semicolon      semi

Skill output:

{
  "success": false,
  "error": "Pre-commit hook failed: ESLint errors",
  "details": "3 errors in src/components/Settings.tsx",
  "recommendation": "Fix ESLint errors:\n1. Line 42: Define 'user' variable\n2. Line 58: Add missing semicolon\n\nRun 'npm run lint:fix' to auto-fix, then retry commit."
}

Console log: "❌ Commit failed: ESLint errors detected. Fix errors and retry."

Example 5: Conventional Commits Format

User: /commit-coauthor

Staged files: Multiple test files added

Auto-detected type: test

Commit:

test(auth): Add unit tests for password reset flow

Tests email verification and token expiration.
Achieves 95% coverage for auth module.

Co-Authored-By: Claude Sonnet 4.5 <[e-mail]>

Integration with Development Workflow

Use this Skill:

• ✅ After implementing feature (stage changes, commit with co-author)
• ✅ After fixing bugs (proper commit message with fix type)
• ✅ Before creating pull request (commit all work)
• ✅ During code review fixes (commit review changes)

Combine with other Skills:

1. Implement feature
2. Run /debug-console (verify no console errors)
3. Run /visual-test-figma (verify design matches)
4. Run /commit-coauthor (commit changes with co-author)
5. Run /create-pr (create pull request) - P2 Skill

Integration with Git Workflow:

# Feature development workflow
git checkout -b feature/user-settings
# ... make changes ...
git add .
/commit-coauthor  # ← This Skill
git push -u origin feature/user-settings
/create-pr  # ← P2 Skill (next phase)

Conventional Commits Reference

Type prefixes:

• feat: New feature
• fix: Bug fix
• docs: Documentation only
• style: Code style (formatting, missing semicolons)
• refactor: Code restructuring without behavior change
• perf: Performance improvement
• test: Adding/updating tests
• chore: Build process, dependencies, tooling

Scope examples:

• (auth): Authentication/authorization
• (api): API endpoints
• (db): Database schema/queries
• (ui): UI components
• (build): Build system
• (deps): Dependencies

Breaking changes:

feat(api)!: Change user endpoint response format

BREAKING CHANGE: User endpoint now returns 'id' instead of 'userId'

Token Efficiency

Baseline (manual git commit):

• Read git commit guidelines: 200 tokens
• Check staged files: 100 tokens
• Analyze changes: 200 tokens
• Write commit message: 200 tokens
• Execute commit: 100 tokens
• Verify success: 200 tokens
• Total: ~1,000 tokens

With commit-coauthor Skill:

• Skill invocation: 150 tokens
• Safety checks: 100 tokens
• Auto-generate message: 200 tokens
• Execute commit: 50 tokens
• Verify success: 100 tokens
• Total: ~600 tokens

Savings: 400 tokens (40% reduction)

Projected usage: 20x per week Weekly savings: 8,000 tokens Annual savings: 416,000 tokens (~$1.04/year)

Related Documentation

• Git Safety Protocol - Git safety rules in system prompt
• Conventional Commits - Commit message standard
• TOKEN_EFFICIENCY.md - Token optimization patterns

---

Skill Version: 1.0 Created: 2026-01-09 Last Updated: 2026-01-09 Requires: Claude Code v2.1.0+, Git repository