# Semantic Commit

> Commit a staged or deliberately selected change set using Semantic Commit format.

- **Type:** Skill
- **Install:** `agentstack add skill-graysurf-agent-kit-semantic-commit`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [graysurf](https://agentstack.voostack.com/s/graysurf)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [graysurf](https://github.com/graysurf)
- **Source:** https://github.com/graysurf/agent-kit/tree/main/skills/tools/git/semantic-commit

## Install

```sh
agentstack add skill-graysurf-agent-kit-semantic-commit
```

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

## About

# Semantic Commit

## Contract

Prereqs:

- Run inside a git work tree (or pass `--repo ` to target one explicitly).
- `git` available on `PATH`.
- `semantic-commit` available on `PATH` (install via `brew install nils-cli`).
- `git-scope` is optional; default summary mode falls back to `git show` when unavailable.

Inputs:

- Staged changes (`git add ...`) for `semantic-commit staged-context`; the staged set may come from the user, an existing index state, or
  agent-selected pre-skill staging.
- Prepared commit message via stdin (preferred), `--message`, or `--message-file` for `semantic-commit commit`.
- Optional target repository via `--repo `.

Outputs:

- `semantic-commit staged-context`: prints staged change context in `bundle|json|patch` format.
- `semantic-commit commit`: validates message, optionally commits staged changes, and prints commit summary unless disabled.
- Optional recovery file from `--message-out `.

Exit codes:

- `0`: success (including `--validate-only`, `--dry-run`, and help output).
- `1`: usage or operational failure (invalid args, git command failure, hooks/conflicts, bad repo path).
- `2`: no staged changes for commands that require staged input.
- `3`: commit message missing/empty.
- `4`: commit message validation failed.
- `5`: required dependency missing (for example, `git`).

Failure modes:

- Not in a git repo and no valid `--repo` supplied.
- No staged changes (`exit 2`).
- No message provided in automation mode (`exit 3`).
- Message format invalid (`exit 4`).
- `git commit` failure (hooks/conflicts/signing/repo state) (`exit 1`).
- Summary helper unavailable (`git-scope` missing): warning emitted, fallback to `git show`.

## Setup

- Run inside the target git repo, or use `--repo ` to avoid shell `cwd` switching.
- Use only the entrypoints below; they are the stable interface for agents.

Use this skill for:

- User-staged or pre-existing staged changes.
- Agent-selected task changes after the agent has inspected the working tree and staged only the intended paths.

Use `semantic-commit-autostage` instead when the full working tree delta is intentionally in scope.

## Commands (only entrypoints)

- Get staged context:
  - `semantic-commit staged-context [--format ] [--json] [--repo ]`
- Commit / validate prepared message:
  - `semantic-commit commit [--message |--message-file ] [options]`
  - Useful options: `--message-out`, `--summary `, `--no-summary`, `--validate-only`, `--dry-run`, `--auto-fix`,
    `--automation`, `--repo`, `--no-progress`, `--quiet`
  - `--auto-fix` (opt-in) normalizes machine-fixable issues before validation: wraps body lines at 100 chars (whitespace break preferred,
    codepoint hard-break for CJK / unbreakable runs), lowercases the header type / `(scope)`, uppercases the first char of `-` bullets,
    inserts a missing blank line between header and body, and drops empty lines inside the body. Does **not** truncate over-length headers
    or repair structural header errors; those still exit `4`.
- Do not call internal helpers directly; treat these commands as the only contract surface.

## Workflow

Rules:

- Never run `git add` in this skill; commit only what the user has already staged.
- If the agent must select this task's changes, inspect `git status`/diff and complete selective staging before entering this skill.
- Build message intent from `semantic-commit staged-context` output only.
- Prefer explicit `--repo ` when operating from another working directory.

Recommended flow:

1. Run `semantic-commit staged-context --format bundle` (or `--json` if your parser expects JSON only).
2. Draft the semantic message (`type(scope): subject` + optional bullet body).
3. Run `semantic-commit commit --validate-only ...` before committing to catch formatting errors early.
4. Optionally run `semantic-commit commit --dry-run ...` for staged/message sanity checks without creating a commit.
5. Run `semantic-commit commit ...` to finalize.
6. Capture and report `exit_code`, `stdout`, and `stderr`.

## Follow Semantic Commit format

Use one of:

- `type(scope): subject`
- `type: subject`

Rules:

- Type must be lowercase.
- Header length must be `<= 100` characters.
- If body exists: line 2 must be blank, and every body line must start with `-` followed by an uppercase letter.
- Each body line must be `<= 100` characters.

## Error handling matrix

- `exit 2` (`no staged changes`): stop and ask for staging.
- `exit 3` (`message missing/empty`): provide/repair `--message` or `--message-file`.
- `exit 4` (`validation failed`): fix header/body format first; do not commit. For body line-length, bullet casing, header type/scope casing,
  blank-separator, or empty-body-line failures, retrying with `--auto-fix` normalizes the message in-place. Over-length headers and structural
  header errors are not auto-fixable and must be rewritten by hand.
- `exit 1` from commit: treat as operational failure and report stderr verbatim.
- `git-scope` warning only: not fatal unless summary is explicitly required to be `git-scope`.

## Example

```bash
semantic-commit staged-context --format json

semantic-commit commit \
  --message-file /tmp/commit-msg.txt \
  --validate-only

semantic-commit commit \
  --message-file /tmp/commit-msg.txt \
  --summary git-show
```

## Output and clarification rules

- On failure: include command, exit code, and stderr; do not claim success.
- On success: include command output (commit summary) in a code block.
- If staged context cannot disambiguate type/scope/subject, ask one concise clarification question before committing.

## Source & license

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

- **Author:** [graysurf](https://github.com/graysurf)
- **Source:** [graysurf/agent-kit](https://github.com/graysurf/agent-kit)
- **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-graysurf-agent-kit-semantic-commit
- Seller: https://agentstack.voostack.com/s/graysurf
- 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%.