name	mtl-commit
description	Stage and commit working-tree changes as atomic, signed-off commits whose message length scales with the change. Use when asked to commit, stage, or finalize changes into git — after the user (not the agent) decides a diff is ready.

Commit current changes

Committing is the user's decision, never an agent's — only run this after being explicitly asked to commit.

Process

Run git status --short and git diff --stat.
Run ./format-coding.sh before staging anything. It runs markdownlint (MD013 line-length among other rules, config at .github/linters/.markdown-lint.yml) alongside clang-format/isort/black/shfmt, and now fails the script on any violation --fix cannot auto-correct — fix those by hand (rewrap the paragraph; a single \n is a soft break, it doesn't change rendering), then re-run until it exits clean.
One commit = one logical change. Split unrelated edits with git add -p. Never bundle drive-by changes into an unrelated fix.
For each commit: stage, draft the message, run git commit -s immediately. Do not wait for approval; the user reviews git log and reverts/amends if needed. Print the staged files and final message after each commit.
Always pass -s so a Signed-off-by: trailer is added.
Do not git push. Do not use --no-verify. Do not amend commits that may already be pushed unless explicitly told to.

Format

<Type>: <subject>

<body — optional>

<footers — optional>

Type (capitalised): Feat, Add, Fix, Refactor, Docs, Test, Perf, Build, Ci, Style. See doc/coding_standard.md.
This project does not use Conventional-Commits scopes (Fix(parser):) or breaking markers (!). Flag a breaking API/behaviour change with a BREAKING-CHANGE: footer instead.

Subject line

≤ 50 chars ideal, 72 hard.
Capitalise the first word after the type prefix. No trailing period.
Imperative mood. The subject must complete the sentence: "If applied, this commit will __________."
Name the symbol, file, or subsystem in the subject itself. Fix: Reject zero-length frames in st20_tx_xmit — never Fix bug or Update stuff.

Body — when and what

Include a body only when the change is not obvious from the diff.

Explain why (motivation, the problem, the invariant being preserved or broken) and the non-obvious what. The diff already shows how.
Wrap at 72 cols. Aim for ≤ 5 lines; risky / cross-cutting changes may justify more, but every extra line earns its place.
Don't re-narrate the diff. If a sentence enumerates items the diff already adds verbatim, delete it.
Don't restate linked content. Reference it (Refs: #123, See also: doc/foo.md) instead of summarising.
For Fix: state the symptom + root cause in one or two lines.
For Perf: include before/after numbers when measured.

Footers (git-trailer format)

Blank line above; one per line; Token: value form.

Signed-off-by: Name <email> — added by -s.
Fixes: <12-char SHA> ("<subject>") — recommended for bugfixes; helps git bisect.
Refs: #123 / Closes: #123.
BREAKING-CHANGE: <description> — if not flagged with ! in the subject.

Never appears

Chat / process leakage. No I, we, the agent, the user, per the discussion, as requested, Copilot, AI.
Meta-commentary about the message. Do not describe the message's audience, its structure, or the rules used to write it. The reader is the audience — they don't need to be told.
Vague subjects that would fit any commit (Fix bug, Update X, Misc cleanup).

Length-vs-importance

Trivial (typo, formatting, comment): subject only.
Behaviour or API change: subject + 2-5 line body explaining why.
Risky / cross-cutting / perf: subject + full body. Perf needs before/after numbers; Fix needs symptom + root cause.

Pre-commit self-check

Re-read the drafted message and verify:

Subject completes "If applied, this commit will …"?
Every body sentence describes a change to code, files, or behaviour — not the message, not the chat that produced it?
No sentence re-narrates content the diff already adds verbatim?
Footers in trailer format, blank line above, one per line?

If any answer is no, edit before running git commit -s.

name	mtl-commit
description	Stage and commit working-tree changes as atomic, signed-off commits whose message length scales with the change. Use when asked to commit, stage, or finalize changes into git — after the user (not the agent) decides a diff is ready.

Commit current changes

Committing is the user's decision, never an agent's — only run this after being explicitly asked to commit.

Process

Run git status --short and git diff --stat.
Run ./format-coding.sh before staging anything. It runs markdownlint (MD013 line-length among other rules, config at .github/linters/.markdown-lint.yml) alongside clang-format/isort/black/shfmt, and now fails the script on any violation --fix cannot auto-correct — fix those by hand (rewrap the paragraph; a single \n is a soft break, it doesn't change rendering), then re-run until it exits clean.
One commit = one logical change. Split unrelated edits with git add -p. Never bundle drive-by changes into an unrelated fix.
For each commit: stage, draft the message, run git commit -s immediately. Do not wait for approval; the user reviews git log and reverts/amends if needed. Print the staged files and final message after each commit.
Always pass -s so a Signed-off-by: trailer is added.
Do not git push. Do not use --no-verify. Do not amend commits that may already be pushed unless explicitly told to.

Format

<Type>: <subject>

<body — optional>

<footers — optional>

Type (capitalised): Feat, Add, Fix, Refactor, Docs, Test, Perf, Build, Ci, Style. See doc/coding_standard.md.
This project does not use Conventional-Commits scopes (Fix(parser):) or breaking markers (!). Flag a breaking API/behaviour change with a BREAKING-CHANGE: footer instead.

Subject line

≤ 50 chars ideal, 72 hard.
Capitalise the first word after the type prefix. No trailing period.
Imperative mood. The subject must complete the sentence: "If applied, this commit will __________."
Name the symbol, file, or subsystem in the subject itself. Fix: Reject zero-length frames in st20_tx_xmit — never Fix bug or Update stuff.

Body — when and what

Include a body only when the change is not obvious from the diff.

Explain why (motivation, the problem, the invariant being preserved or broken) and the non-obvious what. The diff already shows how.
Wrap at 72 cols. Aim for ≤ 5 lines; risky / cross-cutting changes may justify more, but every extra line earns its place.
Don't re-narrate the diff. If a sentence enumerates items the diff already adds verbatim, delete it.
Don't restate linked content. Reference it (Refs: #123, See also: doc/foo.md) instead of summarising.
For Fix: state the symptom + root cause in one or two lines.
For Perf: include before/after numbers when measured.

Footers (git-trailer format)

Blank line above; one per line; Token: value form.

Signed-off-by: Name <email> — added by -s.
Fixes: <12-char SHA> ("<subject>") — recommended for bugfixes; helps git bisect.
Refs: #123 / Closes: #123.
BREAKING-CHANGE: <description> — if not flagged with ! in the subject.

Never appears

Chat / process leakage. No I, we, the agent, the user, per the discussion, as requested, Copilot, AI.
Meta-commentary about the message. Do not describe the message's audience, its structure, or the rules used to write it. The reader is the audience — they don't need to be told.
Vague subjects that would fit any commit (Fix bug, Update X, Misc cleanup).

Length-vs-importance

Trivial (typo, formatting, comment): subject only.
Behaviour or API change: subject + 2-5 line body explaining why.
Risky / cross-cutting / perf: subject + full body. Perf needs before/after numbers; Fix needs symptom + root cause.

Pre-commit self-check

Re-read the drafted message and verify:

Subject completes "If applied, this commit will …"?
Every body sentence describes a change to code, files, or behaviour — not the message, not the chat that produced it?
No sentence re-narrates content the diff already adds verbatim?
Footers in trailer format, blank line above, one per line?

If any answer is no, edit before running git commit -s.

mtl-commit

Commit current changes

Process

Format

Subject line

Body — when and what

Footers (git-trailer format)

Never appears

Length-vs-importance

Pre-commit self-check

同仓库更多 Skills

同仓库更多 Skills

Commit current changes

Process

Format

Subject line

Body — when and what

Footers (git-trailer format)

Never appears

Length-vs-importance

Pre-commit self-check