Skip to content

Replace git-commit-conventions with user-invocable commit skill #280

Description

@williamthorsen

Parent: #277

Problem

Agents frequently violate commit message conventions: using process-oriented titles ("Address review findings"), including finding IDs (F1, W2), referencing automated tests, omitting backtick formatting for code identifiers, and not punctuating list items in the body. The existing git-commit-conventions skill is non-user-invocable and gets ignored by both the main agent and subagents.

Context

The git-commit-conventions skill at packages/agents/content/skills/git-commit-conventions/SKILL.md is listed as a skill dependency in the orchestrated-coder subagent. The reference data file _data/commit-format.md covers title format and length. Neither covers the body formatting rules that cause the most cleanup work.

Solution

Replace the git-commit-conventions skill directory with a commit skill directory. Make it user-invocable so it appears in the skill list and is more likely to be invoked. Expand the conventions to include all rules from the issue:

Title rules (existing + reinforced):

  • 72 chars max (hard limit)
  • {workspace}|{work type}: {description} format
  • No ticket ID
  • Describes the code change, not the process

Body rules (new):

  • Punctuate list items: each bulleted item ends with a period, comma, or semicolon.
  • Break up large paragraphs; blank line between paragraphs.
  • Use backticks for code identifiers (methodName, MyClass, path/to/file).
  • Never reference automated tests/CI (formatting, linting, unit tests, typechecking).
  • Never use review finding IDs (F1, W2, T3, etc.) — these are meaningful only in review documents.

Skill references update:

  • Update orchestrated-coder: git-commit-conventionscommit in its skills list.
  • Update common-mistakes: cross-reference the new skill name.
  • Update _data/commit-format.md to include body formatting rules.
  • Delete the git-commit-conventions/ directory.

Acceptance criteria

  • commit skill exists at packages/agents/content/skills/commit/SKILL.md with user-invocable: true
  • All title and body rules from the issue are covered
  • git-commit-conventions/ directory is deleted
  • All subagent references updated from git-commit-conventions to commit
  • common-mistakes cross-references updated
  • _data/commit-format.md updated with body formatting rules

Metadata

Metadata

Assignees

No one assigned

    Labels

    featureAdded or improved external functionalityscope:agents

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions