LiorCohen/sdd / .claude/skills/commit
commit
VerifiedCreate a commit following repository guidelines with proper versioning and changelog updates.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.5 KB |
SKILL.md
View on GitHub---
name: commit
description: Create 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/` or `plugin/fullstack-typescript/system/`
- Changes are only to `.md` files, `.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`
- `.claudeignore`
- `plugin/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`:
1. Use the `manifest-validation` skill to validate both manifests
2. Fix any errors before proceeding
**Quick validation:**
```bash
# 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:
```markdown
## [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 features
- `Changed` - Changes to existing functionality
- `Enhanced` - Improvements to existing features
- `Fixed` - Bug fixes
- `Removed` - 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:**
1. Invoke the `docs-standards` agent to audit documentation against current plugin state
2. Review any inconsistencies found
3. Fix documentation issues before proceeding to commit
**Documentation files to verify:**
- `README.md` - Quick start, project structure, permissions
- `docs/getting-started.md` - Tutorial and structure diagrams
- `docs/commands.md` - Command references and examples
- `docs/workflows.md` - Workflow examples
- `docs/agents.md` - Agent descriptions
- `docs/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):
1. Stage all related files (code + version files + CHANGELOG)
2. Create the commit with the generated message
3. 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
1. **Forgetting version bump** - Always bump version for plugin file changes
2. **Mismatched versions** - plugin.json and marketplace.json must match
3. **Missing CHANGELOG** - Every change needs a CHANGELOG entry (versioned or Infrastructure)
4. **Wrong entry format** - Plugin changes use `## [x.y.z] - YYYY-MM-DD`, infrastructure uses `## Infrastructure - YYYY-MM-DD`
5. **Wrong commit format** - Must include Co-Authored-By
6. **Staging incomplete** - Must include all version files in same commit
7. **Wrong date in CHANGELOG** - Use today's date
8. **Wrong changelog file** - Update only `changelog/v{N}.md` (no root CHANGELOG.md)
9. **Amending pushed commits** - NEVER amend commits that have been pushed to remote
10. **Multiple changelog entries per commit** - Each commit = one changelog entry. Split if needed
11. **Incorrect task status** - Use the `tasks` skill for all task status changes; don't manually edit task files
12. **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:
```bash
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:**
1. Do NOT use `git commit --amend`
2. Create a new commit with a clear message explaining it fixes the previous commit
3. Example: `Fix: Correct typo in previous commit (a3614c1)`
## Verification Commands
Run these before committing:
```bash
# 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:
1. Identify the major version (e.g., `5.1.0` → major version `5`)
2. Add entry to `changelog/v5.md` after the header section
When creating a **new major version**:
1. Create `changelog/v{N}.md`
2. 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: 471k | 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: 198k | 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: 198k | 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: 198k | Updated | Claude CodeCodex | Verified | Install |