LiorCohen/sdd / .claude/skills/commit
commit
VerifiedCreate a commit following repository guidelines with proper versioning and changelog updates.
Commit Skill
Create commits that follow the repository's guidelines with proper versioning and changelog updates.
Workflow
Step 1: Analyze Changes
Run git status and git diff to understand:
- Which files have been modified
- Which plugins are affected
- Whether version files need updating
- Whether CHANGELOG needs updating
Step 1.5: Build Verification
When to run: If any changed files are under plugin/core/system/ or plugin/fullstack-typescript/system/ (TypeScript source).
Run npm run typecheck:plugin and verify it passes. If there are type errors, fix them before proceeding — never commit code that doesn't compile.
Skip conditions:
- No changes under
plugin/core/system/orplugin/fullstack-typescript/system/ - Changes are only to
.mdfiles,.tasks/, or non-TypeScript files
Step 2: Version Check
For each affected plugin, check if version bump is needed:
Files That REQUIRE Version Bump:
| Directory/File | Description |
|---|---|
plugin/core/commands/ | All command .md files |
plugin/core/skills/ | All core skill .md files |
plugin/core/system/ | Core CLI system source files |
plugin/core/permissions/ | Permission configuration |
plugin/fullstack-typescript/agents/ | All agent .md files |
plugin/fullstack-typescript/skills/ | All tech pack skill .md files |
plugin/fullstack-typescript/system/ | Tech pack CLI system source files |
plugin/fullstack-typescript/templates/ | All template files |
plugin/.claude-plugin/ | Plugin manifest |
Files That Do NOT Require Version Bump (Marketplace-Level):
- Root
README.md - Root
CLAUDE.md - Root
CONTRIBUTING.md changelog/directory (changelog entries go in version-specific files).claude/skills/(marketplace-level skills).gitignore.claudeignoreplugin/tests/(test files)
If version bump is needed, prompt for type:
- PATCH (x.x.Z): Bug fixes, small improvements
- MINOR (x.Y.0): New features, backwards compatible
- MAJOR (X.0.0): Breaking changes
Update BOTH files:
plugin/.claude-plugin/plugin.json.claude-plugin/marketplace.json
Step 2.5: Manifest Validation
When to run: After updating version files, before proceeding to changelog.
If changes affect plugin/.claude-plugin/plugin.json or .claude-plugin/marketplace.json:
- Use the
manifest-validationskill to validate both manifests - Fix any errors before proceeding
Quick validation:
# Verify versions match
jq -r '.version' plugin/.claude-plugin/plugin.json
jq -r '.plugins[0].version' .claude-plugin/marketplace.json
Skip conditions:
- No changes to manifest files
- Version-only changes (version match is checked above)
Step 3: Changelog Check
Changelog structure:
changelog/v{N}.md- Per-major-version files (v1.md, v2.md, v3.md, v4.md, v5.md)
Plugin changes: Format ## [x.y.z] - YYYY-MM-DD (versioned releases)
Infrastructure changes: Format ## Infrastructure - YYYY-MM-DD (date-based)
Update the version-specific file (changelog/v{major}.md): Add entry at the top (after the header)
Entry format:
## [x.y.z] - YYYY-MM-DD
### [Category]
- **[component]**: Description of change
- Detail 1
- Detail 2
### Rationale
Why this change was made (for significant changes).
Categories:
Added- New featuresChanged- Changes to existing functionalityEnhanced- Improvements to existing featuresFixed- Bug fixesRemoved- Removed features
Determining the version file:
- Extract major version from new version (e.g.,
5.0.2→v5.md) - File path:
changelog/v{major}.md
Step 4: Documentation Check
When to run: If changes affect plugin functionality (commands, agents, skills, directory structure, workflows).
What to check:
- Invoke the
docs-standardsagent to audit documentation against current plugin state - Review any inconsistencies found
- Fix documentation issues before proceeding to commit
Documentation files to verify:
README.md- Quick start, project structure, permissionsdocs/getting-started.md- Tutorial and structure diagramsdocs/commands.md- Command references and examplesdocs/workflows.md- Workflow examplesdocs/agents.md- Agent descriptionsdocs/components.md- Component types
Skip conditions:
- Changes only affect test files
- Changes only affect marketplace-level skills (
.claude/skills/) - Changes only affect task management (
.tasks/) - Trivial changes (typos, formatting)
Step 5: Task Status Check
If changes involve .tasks/ or are related to a tracked task:
Use the tasks skill to ensure proper task status management. The tasks skill is authoritative for:
- Task lifecycle (inbox → speccing → planning → plan-review → implementing → reviewing → complete)
- Plan creation and approval workflows
- Automatic status transitions based on user actions
Common scenarios:
| Scenario | Action |
|---|---|
| Plan created and approved | Use /tasks plan-review N to move task to plan-review |
| Starting implementation | Use /tasks implement N to move task to implementing |
| Implementation complete | Use /tasks review N to move task to reviewing |
| Work fully done | Use /tasks complete N to mark task complete |
Skip conditions:
- Trivial changes (typos, formatting) don't need task tracking
- Changes already have correct task status
Step 6: Generate Commit Message
Task-context detection: Before generating the message, check if the current branch is a feature branch for a task (e.g., feature/task-19-*). If so, and the task is in 4-implementing/ or 5-reviewing/, prefix the commit message with the task reference:
Task #19: [Action] [Component]: [Description]
Version bumps on feature branches:
- During implementation: The final commit before moving to review must include the version bump and changelog entry (run Steps 2–3). Earlier implementation commits skip Steps 2–3.
- During reviewing: If the previous commit has NOT been pushed, amend it and update the changelog entry. If it HAS been pushed, create a new commit but amend the existing changelog entry in-place (update the version entry, do not create a new one). Never create a second version bump — only update the one created during implementation.
Default format (when not on a task feature branch):
[Action] [Component]: [Description], bump to [version]
[Optional detailed explanation]
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Actions:
- Add: New feature or file
- Fix: Bug fix
- Update: Enhancement to existing feature
- Remove: Deletion
- Refactor: Code restructuring without behavior change
- Docs: Documentation only
- Tasks: Task management changes (adding, completing, updating tasks in
.tasks/)
Step 7: Review and Confirm
Task-only commits (all changed files are under .tasks/): Skip confirmation — proceed directly to Step 8.
All other commits: Present to the user:
- Summary of files to be committed
- Proposed commit message
- Version changes (if any)
- Changelog additions (if any)
Wait for user confirmation before proceeding.
Step 8: Execute Commit
After confirmation (or immediately for task-only commits):
- Stage all related files (code + version files + CHANGELOG)
- Create the commit with the generated message
- Display commit result
Example
User: /commit
Agent: Analyzing changes...
Found changes in:
- plugin/fullstack-typescript/agents/backend-dev.md
Detected plugin: plugin (current version: 1.10.19)
Version files need updating:
- plugin/.claude-plugin/plugin.json
- .claude-plugin/marketplace.json
What type of version bump?
1. PATCH (1.10.19 → 1.10.20) - Bug fixes, small improvements
2. MINOR (1.10.19 → 1.11.0) - New features
3. MAJOR (1.10.19 → 2.0.0) - Breaking changes
User: 1
Agent: Updating versions to 1.10.20...
✓ Updated plugin.json
✓ Updated marketplace.json
changelog/v1.md needs an entry for 1.10.20.
Proposed entry:
## [1.10.20] - 2026-01-17
### Fixed
- Updated backend-dev agent with improved error handling
Should I add this entry? (yes/edit/no)
User: yes
Agent: ✓ Updated changelog/v1.md
Proposed commit message:
---
Fix backend-dev agent: Improve error handling, bump to 1.10.20
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
Files to commit:
- plugin/fullstack-typescript/agents/backend-dev.md
- plugin/.claude-plugin/plugin.json
- changelog/v1.md
- .claude-plugin/marketplace.json
Proceed with commit? (yes/edit/no)
User: yes
Agent: ✓ Committed: abc1234 "Fix backend-dev agent: Improve error handling, bump to 1.10.20"
Quick Reference
Plugin TS changed? → Typecheck → Bump version → CHANGELOG → Check docs → Stage all → Commit
Plugin non-TS changed? → Bump version → CHANGELOG → Check docs → Stage all → Commit
Infrastructure file changed? → CHANGELOG → Stage all → Commit
Task-only changes? → Stage all → Commit (no confirmation needed)
Common Mistakes to Avoid
- Forgetting version bump - Always bump version for plugin file changes
- Mismatched versions - plugin.json and marketplace.json must match
- Missing CHANGELOG - Every change needs a CHANGELOG entry (versioned or Infrastructure)
- Wrong entry format - Plugin changes use
## [x.y.z] - YYYY-MM-DD, infrastructure uses## Infrastructure - YYYY-MM-DD - Wrong commit format - Must include Co-Authored-By
- Staging incomplete - Must include all version files in same commit
- Wrong date in CHANGELOG - Use today's date
- Wrong changelog file - Update only
changelog/v{N}.md(no root CHANGELOG.md) - Amending pushed commits - NEVER amend commits that have been pushed to remote
- Multiple changelog entries per commit - Each commit = one changelog entry. Split if needed
- Incorrect task status - Use the
tasksskill for all task status changes; don't manually edit task files - Outdated documentation - Plugin changes may require docs updates; run docs-standards agent to check
One Commit = One Changelog Entry
CRITICAL: If your changes would result in multiple changelog entries, split them into separate commits.
Example - Wrong:
git add file1.md file2.md file3.md
git commit -m "Add feature A, fix bug B, refactor C"
# Results in 3 changelog entries in one commit - BAD
Example - Correct:
git add file1.md && git commit -m "Add feature A"
git add file2.md && git commit -m "Fix bug B"
git add file3.md && git commit -m "Refactor C"
# Each commit has one changelog entry - GOOD
Why: Clean git history, easier rollbacks, clearer blame, simpler code review.
Amending vs New Commit
CRITICAL: Before amending, check if the commit has been pushed:
git log origin/main..HEAD --oneline
- If the commit appears in this list → Safe to amend (not pushed yet)
- If the commit does NOT appear → It's been pushed, create a NEW commit instead
When a pushed commit needs fixing:
- Do NOT use
git commit --amend - Create a new commit with a clear message explaining it fixes the previous commit
- Example:
Fix: Correct typo in previous commit (a3614c1)
Verification Commands
Run these before committing:
# Check versions match
echo "Plugin version:"
cat plugin/.claude-plugin/plugin.json | grep version
echo "Marketplace version:"
cat .claude-plugin/marketplace.json | grep version
# Check changelog has entry for new version
head -20 changelog/v5.md # Adjust version number as needed
# Check staged files
git status
Changelog File Structure
The changelog is split by major version to stay within Claude's file size limits:
changelog/
├── README.md # Compelling summary of all major versions (for evaluators)
├── v1.md # All 1.x releases
├── v2.md # All 2.x releases
├── v3.md # All 3.x releases
├── v4.md # All 4.x releases
├── v5.md # All 5.x releases
└── v6.md # All 6.x releases (current)
When adding a new entry:
- Identify the major version (e.g.,
5.1.0→ major version5) - Add entry to
changelog/v5.mdafter the header section
When creating a new major version:
- Create
changelog/v{N}.md - Add a summary paragraph and table row to
changelog/README.md
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 196k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |