feat(skills): Add contextual-commit skill for structured commit reasoning#1281
feat(skills): Add contextual-commit skill for structured commit reasoning#1281
Conversation
…ning Add a Claude Code skill that extends Conventional Commits with structured action lines (intent, decision, rejected, constraint, learned) in the commit body. This preserves the WHY behind code changes — intent, alternatives considered, constraints discovered — that diffs alone cannot show. intent(skills): capture development reasoning in commits so future sessions don't lose context about why code was written decision(skills): action-line format in commit body over separate metadata files — works with all git workflows (merge, squash, rebase, cherry-pick) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
⚡ Performance Benchmark
Details
|
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces a new skill that significantly enhances the utility of Git commit messages. By integrating structured reasoning directly into the commit body, it ensures that the full context of code changes, including intentions, decisions, and constraints, is permanently recorded. This approach improves the long-term maintainability and understandability of the codebase by making the 'why' behind every change readily accessible to current and future developers. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. Footnotes
|
📝 WalkthroughWalkthroughIntroduced a new "contextual-commit" skill specification and updated commit body guidelines to enforce its use. The skill defines structured action-line formats for commit bodies, replacing previous unstructured context requirements, while maintaining Conventional Commits compliance for commit subjects. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
…ines intent(claude-md): avoid duplicating commit body rules between CLAUDE.md and the skill file decision(claude-md): single reference to skill file over inline duplication Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Deploying repomix with
|
| Latest commit: |
0e7601f
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://c404e285.repomix.pages.dev |
| Branch Preview URL: | https://feat-contextual-commit-skill.repomix.pages.dev |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a new contextual-commit skill for an AI agent, documented in a new SKILL.md file. The skill aims to capture the reasoning behind code changes by extending conventional commits with structured action lines. The documentation is comprehensive and well-structured. I have one suggestion to improve the consistency of the rules for the agent, specifically regarding how to handle changes for which it lacks conversation context. My feedback aims to prevent the agent from generating low-value commit messages that repeat information already present in the diff.
PR Review: feat(skills): Add contextual-commit skillOverall: Well-written skill that fills a real gap - preserving dev reasoning in git history. LGTM with minor suggestions. Feedback:
Strengths: Action type taxonomy is well-chosen. 'When You Lack Conversation Context' section prevents hallucinated context. Rule 8 keeps it pragmatic. Pre-commit checklist is practical. Premortem: Adoption friction with non-Claude contributors (not a blocker). Verbosity creep risk despite Rule 3. No risk to existing tooling - good design. Generated with Claude Code |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
.agents/rules/base.md (1)
64-79: Align subject-line wording rules with the new skill to avoid conflicting instructions.Now that commit-body rules are delegated to
contextual-commit, consider consolidating/clarifying subject-line constraints here (e.g., capitalization expectations) so assistants don’t get mixed signals across rule sources.Based on learnings: Consult and adhere to the project-specific rules documented in
.agents/rules/base.mdduring development and review.Also applies to: 82-82
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.agents/rules/base.md around lines 64 - 79, Update the subject-line rules in the commit guidance to remove conflicts with the new contextual-commit skill: clarify that the assistant must follow the existing format `type(scope): Description` and explicitly state the capitalization rule for the subject (e.g., "Description" must start with a capital letter and use present tense), and note that commit-body rules are handled by contextual-commit so only subject-line constraints belong here; update the bullets that currently state "The assistant shall always include a scope" and "The assistant shall write description in clear, concise present tense starting with a capital letter" to be the authoritative subject-line rules and add a short note referencing that commit-body conventions are delegated to contextual-commit to avoid mixed signals.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.claude/skills/contextual-commit/SKILL.md:
- Around line 24-29: Add explicit language identifiers to all fenced code blocks
in the SKILL.md commit examples so markdownlint MD040 is satisfied: locate each
triple-backtick block containing the example commit templates (e.g., the block
starting with "type(scope): subject line (standard conventional commit)", the
block with "fix(button): correct alignment on mobile viewport", the blocks for
"feat(notifications): …", "refactor(payments): …", and "refactor(auth): …") and
change the opening fence to include a language token such as ```text (or
```diff/```bash if more appropriate) for each block; ensure every fenced block
in the file has a language tag.
---
Nitpick comments:
In @.agents/rules/base.md:
- Around line 64-79: Update the subject-line rules in the commit guidance to
remove conflicts with the new contextual-commit skill: clarify that the
assistant must follow the existing format `type(scope): Description` and
explicitly state the capitalization rule for the subject (e.g., "Description"
must start with a capital letter and use present tense), and note that
commit-body rules are handled by contextual-commit so only subject-line
constraints belong here; update the bullets that currently state "The assistant
shall always include a scope" and "The assistant shall write description in
clear, concise present tense starting with a capital letter" to be the
authoritative subject-line rules and add a short note referencing that
commit-body conventions are delegated to contextual-commit to avoid mixed
signals.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 7dc0819a-6ba2-4db8-9f49-7b6b169b482f
📒 Files selected for processing (2)
.agents/rules/base.md.claude/skills/contextual-commit/SKILL.md
Code Review —
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1281 +/- ##
=======================================
Coverage 87.18% 87.18%
=======================================
Files 115 115
Lines 4324 4324
Branches 1002 1002
=======================================
Hits 3770 3770
Misses 554 554 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
1 participant
Add a Claude Code skill that extends Conventional Commits with structured action lines in the commit body, preserving the reasoning behind code changes.
What it does
The
contextual-commitskill adds 5 action line types to commit bodies:intent(scope)— what the user wanted and whydecision(scope)— chosen approach when alternatives existedrejected(scope)— what was considered and discarded, with reasonsconstraint(scope)— hard limits discovered during implementationlearned(scope)— discoveries that save future timeSubject lines remain standard Conventional Commits — no tooling breakage.
Why
Diffs preserve WHAT changed. The reasoning — why this approach, what was rejected, what constraints were discovered — evaporates when a session ends. This skill captures that context directly in git history, accessible to future sessions and other agents.
Checklist
npm run testnpm run lint🤖 Generated with Claude Code