improve committing changes skill

[quexten]

🎟️ Tracking

📔 Objective

Currently, the committing changes skill may result in hard to review changesets. We want the change sets to be easily reviewable. To do this, they have to be structured by intent, with one intent captured per commit. This makes PR's easy to review commit-by-commit instead of as one big diff.

Example: bitwarden/sdk-internal@406cfdc

[github-actions]

Plugin Validation Summary — bitwarden-delivery-tools

Result: ✅ PASS — All checks passed. No blocking issues. Two cosmetic minor suggestions (non-blocking).

Changed files reviewed

• plugins/bitwarden-delivery-tools/.claude-plugin/plugin.json
• plugins/bitwarden-delivery-tools/CHANGELOG.md
• plugins/bitwarden-delivery-tools/skills/committing-changes/SKILL.md

---

1. Plugin Structure Validation (plugin-validator)

PASS — no critical, major, or minor issues.

• Manifest (plugin.json): valid JSON; name: bitwarden-delivery-tools (kebab-case); version: 2.1.0 valid semver; author, homepage, repository, keywords all well-formed.
• Version consistency: plugin.json 2.1.0 ↔ CHANGELOG.md:8 [2.1.0] - 2026-07-09 ↔ .claude-plugin/marketplace.json:81 2.1.0. Descriptions match across manifest and marketplace.
• Semantic bump correctness: doc-only additions → MINOR bump 2.0.0 → 2.1.0 is appropriate.
• CHANGELOG: Keep a Changelog compliant; new 2.1.0 entry under ### Changed accurately describes the two added sections.
• Directory / auto-discovery: skill at canonical skills/committing-changes/SKILL.md; README.md and plugin-level references/ present.
• ${CLAUDE_PLUGIN_ROOT} usage: SKILL.md:21 references ${CLAUDE_PLUGIN_ROOT}/references/change-type-labels.md — file exists at the plugin references/ dir. No broken references.
• Components: 10 skills; no commands/agents/hooks/MCP servers (nothing else to validate).

2. Skill Review — committing-changes (skill-reviewer)

PASS — no critical or major issues.

• Frontmatter: valid; name matches directory; description is third-person with concrete trigger phrases ("commit", "git commit", "commit message", "prepare commit", "stage changes"). Strong triggering.
• Word count: ~383 words — below the 1,000–3,000 target, but appropriate: heavy content (the change-type/label table and preflight checklist) is correctly externalized to references/change-type-labels.md and the perform-preflight skill. Padding would be an anti-pattern.
• Writing style: imperative/infinitive throughout. Clear logical flow.
• Progressive disclosure: correctly implemented — lean core, heavy tables in references/, examples inline.
• Reference integrity: references/change-type-labels.md and perform-preflight skill both exist.
• New sections: "Structure Commits by Intent" and "Follow-up Fixes on an Open PR" cross-reference each other coherently and match the CHANGELOG entries.

Minor (warnings — should fix, non-blocking):

• SKILL.md:45 — heading "Followup Commits" is inconsistent with SKILL.md:61 "Follow-up Fixes on an Open PR". Standardize hyphenation to "Follow-up". Cosmetic.
• SKILL.md:15 — trailer guidance is embedded inside the fenced <optional trailers, ...> placeholder line; a short prose sentence above the code block (e.g. "Add trailers such as Jira-Ticket: and GitHub-Issue: to link tracking items.") would read more cleanly. Optional polish.

3. Security Validation (reviewing-claude-config)

PASS — no security issues.

• No committed secrets, API keys, tokens, or passwords in any changed file.
• No settings.local.json or settings files in the diff; no permission scoping or command auto-approval concerns.
• The PM-12345 / #6789 strings in SKILL.md are illustrative commit-message placeholders, not credentials.
• All three changed files are documentation/metadata only — no executable code or broad file-access grants.

---

Verdict

APPROVE. The version bump (2.1.0), CHANGELOG entry, and skill content changes are consistent, structurally sound, and free of security issues. The two minor items above are cosmetic and do not block merge.

[SaintPatrck]

@quexten we spoke briefly in Slack about these changes possibly not being needed now that we have Stacked PR's enabled. Are you still interested in exploring this, or should it be closed for now?

❓ Is bitwarden/sdk-internal@406cfdc meant to be an example of a good or bad commit?

[SaintPatrck]

💭 I feel like restructuring-git-history warrants its own skill that can be triggered by users when/if they want to cleanup their work history. That skill would reference committing-changes to format a specific commit correctly. As a separate skill, it also becomes flexible enough to incorporate into other things like this "Storybook" concept I was experimenting with to improve the code review experience.

It's also important to consider the description and expected triggers for this skill. They're intentionally broad enough to trigger on any allusion to committing changes which increases chances of unintentionally and silently rewriting someone's history.

[SaintPatrck]

⚠️ This example now repeats the Jira ticket already included in the commit title. Is this meant to be an example of a commit addressing multiple tickets?