# Commit Staged

> Generates and commits conventional-commits messages by analyzing staged git diffs — fast and fork-context safe. Use when the user asks to commit staged changes, needs a type-scope-description message generated from the current diff, or wants scope selection guidance and pre-commit hook handling.

- **Type:** Skill
- **Install:** `agentstack add skill-jamie-bitflight-claude-skills-commit-staged`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Jamie-BitFlight](https://agentstack.voostack.com/s/jamie-bitflight)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Jamie-BitFlight](https://github.com/Jamie-BitFlight)
- **Source:** https://github.com/Jamie-BitFlight/claude_skills/tree/main/.claude/skills/commit-staged

## Install

```sh
agentstack add skill-jamie-bitflight-claude-skills-commit-staged
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

Analyze these staged changes and generate commit message, then commit the changes:
!`uv run prek run >/dev/null 2>&1 || git add -u`
!`git --no-pager status || true`
!`git --no-pager diff --cached || true`
!`git --no-pager diff --cached --stat || true`

$ARGUMENTS

## Commit message format

Follow conventional commits format (no footer, except for breaking change footer):

```text
(): 

[optional body]
```

### Types

- **feat**: New feature
- **fix**: Bug fix
- **docs**: Documentation changes
- **style**: Code style changes (formatting, missing semicolons)
- **refactor**: Code refactoring
- **test**: Adding or updating tests
- **chore**: Maintenance tasks

### Examples

**Feature commit:**

```text
feat(auth): add JWT authentication

Implement JWT-based authentication system with:
- Login endpoint with token generation
- Token validation middleware
- Refresh token support
```

**Bug fix:**

```text
fix(api): handle null values in user profile

Prevent crashes when user profile fields are null.
Add null checks before accessing nested properties.
```

**Refactor:**

```text
refactor(database): simplify query builder

Extract common query patterns into reusable functions.
Reduce code duplication in database layer.
```

## Commit message guidelines

**DO:**

- Use imperative mood ("add feature" not "added feature")
- Keep first line under 50 characters
- Capitalize first letter
- No period at end of summary
- Explain WHY not just WHAT in body

**DON'T:**

- Use vague messages like "update" or "fix stuff"
- Include technical implementation details in summary
- Write paragraphs in summary line
- Use past tense

## Multi-file commits

When committing multiple related changes:

```text
refactor(core): restructure authentication module

- Move auth logic from controllers to service layer
- Extract validation into separate validators
- Update tests to use new structure
- Add integration tests for auth flow

Breaking change: Auth service now requires config object
```

## Scope Rules

**Scope MUST identify WHERE in the codebase, NOT what type of change.**

The scope is a module, component, or directory name - never a description of the change itself.

### Determining Scope

1. **Single module/directory**: Use that module name

   - Changes to `src/auth/*.py` → `auth`
   - Changes to `plugins/gitlab-skill/` → `gitlab-skill`

2. **Multiple files in same area**: Use the common parent

   - Changes to `skills/python3-dev/assets/*.py` → `assets` or `python3-dev`

3. **Cross-cutting changes**: Use the primary affected area OR omit scope

   - Config + code changes → use primary area: `feat(auth): add OAuth support`
   - Truly scattered changes → omit: `chore: update dependencies across modules`

4. **Root config files**: Use the config type
   - `pyproject.toml` linting rules → `lint` or `ruff`
   - `pyproject.toml` dependencies → `deps`
   - `.github/workflows/` → `ci`

### Scope Anti-Patterns

**NEVER use these as scopes** - they describe WHAT, not WHERE:

| ❌ Wrong   | ✅ Correct                     | Why                                     |
| ---------- | ------------------------------ | --------------------------------------- |
| `docs`     | `readme`, `api-docs`, `skills` | "docs" is a change type, not a location |
| `tests`    | `auth-tests`, `api`            | Be specific about what's being tested   |
| `types`    | `models`, `api`                | Types belong to a module                |
| `refactor` | (use as type, not scope)       | "refactor" is a type, not a location    |
| `bugfix`   | (use `fix` as type)            | "bugfix" is a type, not a location      |

### Scope Examples

**By domain:**

- `feat(auth): add JWT authentication`
- `fix(payments): handle currency conversion`
- `refactor(users): extract validation logic`

**By layer:**

- `feat(api): add user profile endpoint`
- `fix(db): resolve connection pool leak`
- `chore(ci): update Node version to 20`

**By plugin/skill:**

- `feat(gitlab-skill): add MR approval support`
- `fix(python3-dev): correct shebang detection`
- `docs(commit-staged): clarify scope selection`

## Breaking changes

Indicate breaking changes clearly:

```text
feat(api)!: restructure API response format

BREAKING CHANGE: All API responses now follow JSON:API spec

Previous format:
{ "data": {...}, "status": "ok" }

New format:
{ "data": {...}, "meta": {...} }

Migration guide: Update client code to handle new response structure
```

## Template workflow

1. **Review changes**: `git diff --staged`
2. **Identify type**: Is it feat, fix, refactor, etc.?
3. **Determine scope**: What part of the codebase?
4. **Write summary**: Brief, imperative description
5. **Add body**: Explain why and what impact
6. **Note breaking changes**: If applicable

## Interactive commit helper

Use `git add -p` for selective staging:

```bash
# Stage changes interactively
git add -p

# Review what's staged
git diff --staged

# Commit with message
git commit -m "type(scope): description"
```

## Amending commits

Fix the last commit message:

```bash
# Amend commit message only
git commit --amend

# Amend and add more changes
git add forgotten-file.js
git commit --amend --no-edit
```

## Best practices

1. **Atomic commits** - One logical change per commit
2. **Test before commit** - Ensure code works
3. **Reference issues** - Include issue numbers if applicable
4. **Keep it focused** - Don't mix unrelated changes
5. **Write for humans** - Future you will read this

## Commit message checklist

- [ ] Type is appropriate (feat/fix/docs/etc.)
- [ ] Scope identifies WHERE (module/directory), NOT what type of change
- [ ] Scope is NOT a banned word: `docs`, `tests`, `types`, `refactor`, `bugfix`
- [ ] Summary is under 50 characters
- [ ] Summary uses imperative mood
- [ ] Body explains WHY not just WHAT
- [ ] Breaking changes are clearly marked
- [ ] Related issue numbers are included

Finally, you will commit the changes with the generated commit message, without using `--no-verify`:

```sh
git commit -m ""
```

If you are blocked by a pre-commit or prek hook, you should stop, and announce your intended commit message, and that it was blocked, and requires a linting-agent to be run against the issues found.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Jamie-BitFlight](https://github.com/Jamie-BitFlight)
- **Source:** [Jamie-BitFlight/claude_skills](https://github.com/Jamie-BitFlight/claude_skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jamie-bitflight-claude-skills-commit-staged
- Seller: https://agentstack.voostack.com/s/jamie-bitflight
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.