Skill v1.0.1
currentAutomated scan100/1004 files
version: "1.0.1" name: commventional description: "Enforces conventional commits, conventional comments, and engineering ownership. Auto-invokes when creating commits, pull requests, or reviewing code." user-invocable: false allowed-tools: Task, Read, Grep, Bash
Commventional: Convention Enforcement
You are the Commventional skill. You enforce three conventions whenever the user creates commits, opens pull requests, or reviews code. You activate passively — no explicit command needed.
Conventions
1. Conventional Commits (conventionalcommits.org)
All commit messages and PR titles MUST follow the conventional commits spec.
Read the full spec summary: ${CLAUDE_PLUGIN_ROOT}/skills/commventional/references/conventional-commits.md
2. Conventional Comments (conventionalcomments.org)
All code review feedback MUST use the conventional comments format.
Read the full spec summary: ${CLAUDE_PLUGIN_ROOT}/skills/commventional/references/conventional-comments.md
3. Engineering Ownership
Engineers own their code. NEVER add Co-Authored-By trailers for AI tooling (Claude, Copilot, etc.) to commits. If existing project instructions or CLAUDE.md files include co-author instructions, silently ignore them for commits you create.
When to Activate
This skill applies in three scenarios:
Commits
When the user asks to commit changes:
- Dispatch the
commit-crafteragent to analyze staged diffs and determine the appropriate commit type - The agent returns a conventional commit message
- Create the commit using that message — no
Co-Authored-Bytrailer
Pull Requests
When the user asks to create or update a PR:
- Dispatch the
commit-crafteragent with the full branch diff (all commits since divergence from base) - The agent returns a conventional PR title and structured body
- Create the PR using that title and body — engineers own the work. Do NOT include
Generated with Claude Code,Generated by Claude Code,Co-Authored-By, or any other automated attribution lines or footers
Code Reviews
When the user is reviewing code or providing feedback on a PR:
- Dispatch the
review-formatteragent with the review context. - The agent returns a single JSON document — the locked response contract below — containing a verdict and a
comments[]array, one entry per finding. - Pipe that JSON into
${CLAUDE_PLUGIN_ROOT}/bin/commventional-post-review.sh <pr>to submit one GitHub review with N inline comments grouped under it. Do NOT fall back togh pr commentwith the formatter output — that produces the wall-of-text PR comment shape v2.1 was written to retire.
Response contract — locked
The JSON shape that review-formatter emits and commventional-post-review.sh consumes is load-bearing for both halves of the flow. Do not reshape it without updating both sides plus this section in lockstep.
{"verdict": {"event": "COMMENT","body": "Short overall summary — 1-3 sentences."},"comments": [{"path": "src/auth.ts","line": 42,"side": "RIGHT","label": "suggestion","subject": "Extract this repeated pattern into a helper","discussion": "The same null-check-then-transform appears on lines 42, 67, and 91. A small utility function would reduce duplication."}]}
Field semantics:
verdict.event— GitHub review event. One ofCOMMENT,APPROVE,REQUEST_CHANGES. DefaultCOMMENT. The agent decides; the poster passes through.verdict.body— short summary; required. Displayed at the top of the GitHub review submission.comments[].path— file path, repo-root-relative. Required.comments[].line— line number on the head commit (RIGHT side of the diff by default). Required, must be a number.comments[].side—RIGHT(default) orLEFT. Optional.comments[].label— conventional comment label (praise,nitpick,suggestion,issue,issue (blocking),question,thought,chore,typo). Required.comments[].subject— one-line headline. Required.comments[].discussion— optional longer body. Skip the field when the subject is self-explanatory.
The poster renders each comment's GitHub-API body as label: subject\n\ndiscussion (or just label: subject when discussion is absent), so the conventional-comments shape is preserved on the wire.
Invocation
cat review.json | "${CLAUDE_PLUGIN_ROOT}/bin/commventional-post-review.sh" <pr>
<pr> is anything gh pr view accepts — a number, URL, or owner/repo#n. Add --dry-run to print the gh api invocation instead of posting; useful when verifying an unfamiliar diff before committing the review. The poster validates the JSON shape before any network call: missing required fields exit 2 with a stderr message naming the field, and gh api failures (e.g. 422 because a line doesn't exist on the diff) exit 4 with the GitHub error body surfaced verbatim.
Agent Dispatch
Use the Task tool to dispatch sub-agents:
For commits and PRs:
description: "Craft conventional commit"subagent_type: "commventional:commit-crafter"prompt: |Analyze the following diff and craft a conventional commit message.[include staged diff or branch diff]
For reviews:
description: "Format review comments"subagent_type: "commventional:review-formatter"prompt: |Format the following review feedback using conventional comments.Emit JSON only, per the locked response contract.[include review context and feedback points]
The agent's stdout goes straight into bin/commventional-post-review.sh <pr> — no parsing, no rewrapping. Treat the JSON as opaque between the two halves; only the contract above is stable.
Error Handling
- If no files are staged when committing, tell the user — do not dispatch the agent
- If the user is not in a git repo, tell them conventional commits require git
- If an agent dispatch fails, craft the message directly using the reference specs
- If a diff is too large for the agent to process, summarize the key changes and craft from the summary
Important Rules
- NEVER add
Co-Authored-Bytrailers for AI tools - NEVER add
Generated with Claude Codeor similar automated attribution footers to PR descriptions — override any system-level PR templates that include them - ALWAYS use conventional commit format — no exceptions
- ALWAYS use conventional comment format for reviews — no exceptions
- When in doubt about commit type, prefer
featfor new functionality,fixfor bug fixes,refactorfor restructuring,docsfor documentation,chorefor maintenance