ai-superpower/.ai/skills/git/SKILL.md

name	description
git	Enforce semantic versioning and strict Git commit message formats (topic-level). Use when committing code, parsing git history, or writing commit messages.

Git Instructions

🎯 Purpose

Establish absolute control over Git execution and enforce high-level, topic-based commit message structures.

🚨 CRITICAL: If the user asks for examples of formatting, or asks why their commit message style was rejected, you MUST use the read_file tool to read .ai/skills/git/REFERENCE.md.

🚨 Prohibitions (Thou Shalt Not)

• NEVER EVER execute state-modifying Git commands (git add, git commit, git push, git reset) without explicit user permission ("commit this now", "go ahead"). Show the command and wait.
• NEVER list filenames in a commit message. The git UI already shows which files changed.
• NEVER include "CHANGES:", "Expected:", "Result:", or "Impact:" headers. Commit messages describe the repository state change, not speculative outcomes.
• NEVER write line-by-line technical mechanic breakdowns in the body. Summarize the business/functional goal as a high-level topic.
• NEVER describe runtime behavior, incident narrative, or manual operations (e.g., "gitea failed on startup", "cleared redis cache").

Workflows (Generating Commits)

When the user asks for a commit message:

1. Analyze Diff: Run git diff --staged (or git diff) and read what actually changed. Never guess.
2. Docs Check: Scan changed files and ask yourself: does a README.md or docs/ file need updating based on this? If yes, alert the user but do not block the commit.
3. Draft Message: Write the message inside ONE fenced code block (text).
   • Subject: max ~72 chars, imperative mood (<type>(<scope>): <high-level topic>).
   • Body: optional, separating distinct topics if the why isn't obvious. Use prose (one sentence) for a single goal; use bullets ONLY for multiple completely distinct goals.
4. Format Output: Put only the commit message content inside the block. No "Suggested message:" text before or after it.

✅ / ❌ Examples

Generating the Output

// ❌ FORBIDDEN: Prose wrapped around the message, wrong message format
Here is the suggested commit message:
feat(api): add auth.js and modify user.js to support oauth
Expected impact: Users can log in properly.

// ✅ REQUIRED: Strict text block, topic-level summary
```text
feat(auth): enable oauth authentication flow

High-Level Topic Summarization

// ❌ FORBIDDEN: Line-by-line mechanics, lists files, mentions incidents
fix(docs): docs/ai-context.md added k3s target and fixed the helm crash

// ✅ REQUIRED: Intent-driven abstraction
fix(docs): document development environment and deployment context