跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

ring:committing-changes

Commit changes with scope allowlist enforcement, atomic grouping, GPG-signed conventional commits, and trailer management. Detects the repo's PR-validation scope policy before proposing any message. Use when the user asks to commit or has changes ready to record. Skip when the working tree is clean or the user wants raw git commands without grouping.

LerianStudio · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add LerianStudio/ring --skill ring:committing-changes

技能说明


name: ring:committing-changes description: >- Commit changes with scope allowlist enforcement, atomic grouping, GPG-signed conventional commits, and trailer management. Detects the repo's PR-validation scope policy before proposing any message. Use when the user asks to commit or has changes ready to record. Skip when the working tree is clean or the user wants raw git commands without grouping. allowed-tools:

  • Bash
  • Read
  • Glob
  • Grep
  • AskUserQuestion

Analyze changes, enforce scope policy, group them into coherent atomic commits, and create signed commits following repository conventions. This skill transforms a messy working directory into a clean, logical commit history — with a scope that will actually pass PR validation.

⛔ HARD STOP — READ SCOPE POLICY BEFORE ANYTHING ELSE

The scope is REQUIRED in every commit message. It MUST come from the repo's allowlist.

MUST detect the allowlist in Step 0 before analyzing or drafting any commit message. A commit with an invented or omitted scope will fail PR validation and block the PR.


Step 0 — Detect Scope Policy

Many repos enforce an allowlist of valid scope values via a GitHub Actions workflow. Failing this check blocks the PR, so MUST detect it before proposing any commit message.

0.1 — Locate the policy file

Check in this order:

  1. .github/workflows/pr-validation.yml (primary)
  2. .github/workflows/pr-title.yml
  3. .github/workflows/commitlint.yml
  4. .github/workflows/semantic-pull-request.yml
  5. Root configs: commitlint.config.{js,cjs,mjs,ts}, .commitlintrc*

0.2 — Extract the allowed scope list

Common forms to look for:

FormExample
scopes: block (one per line)Under amannn/action-semantic-pull-request
scopes: a,b,c inlineComma-separated on one line
scope-enum ruleIn commitlint config arrays

Also note any type restrictions — some repos limit types beyond the default Conventional Commits set.

0.3 — Apply the policy

SituationRequired Action
Policy found, scope is clearUse only scopes from the allowlist
Policy found, scope is ambiguousSTOP and ask the user which allowed scope to use
No policy file foundMUST still include a scope — ask the user what scope to use

NEVER omit the scope. NEVER invent a scope not in the allowlist. A bare type: description is FORBIDDEN.

State the policy source and chosen scope to the user before proceeding.


Step 1 — Gather Context

Run in parallel:

git status
git diff
git diff --cached
git log --oneline -10

Step 2 — Analyze and Group Changes

For each changed file determine:

  1. Type: feat, fix, chore, docs, refactor, test, style, perf, ci, build
  2. Scope: from the allowlist resolved in Step 0
  3. Logical group: what other files belong with this change?

Grouping Principles

PrincipleDescription
Feature + TestsImplementation and its tests go together
Config Changespackage.json, tsconfig, etc. grouped separately
DocumentationREADME, docs/ changes grouped together
RefactoringPure refactors (no behavior change) separate
Bug FixesEach fix is atomic with its test

Single vs Multiple Commits

Single commit when:

  • All changes belong to one coherent feature/fix
  • User provides a specific message via argument
  • Changes are minimal and related

Multiple commits when:

  • Changes span different concerns (feature + docs + deps)
  • Mix of features, fixes, and chores
  • Better git history benefits future archaeology

Step 3 — Determine Commit Order

Order matters for bisectability:

  1. Dependencies first — so subsequent commits can use them
  2. Core changes — implementation before consumers
  3. Tests with implementation — keep them atomic
  4. Documentation last — documents the final state

Step 4 — Present Plan and Confirm

MUST get user confirmation before executing.

Proposed Commit Plan:
─────────────────────
Scope policy: .github/workflows/pr-validation.yml → allowed scopes: [api, auth, docs, ci]
Chosen scope: auth

1. feat(auth): add OAuth2 refresh token support
   - src/auth/oauth.ts (modified)
   - src/auth/oauth.test.ts (modified)

2. chore(deps): update authentication dependencies
   - package.json (modified)
   - package-lock.json (modified)

3. docs(docs): update OAuth2 setup guide
   - docs/auth/oauth-setup.md (modified)

Proceed with this plan? [Execute plan / Single commit / Let me review]

Use AskUserQuestion to confirm before proceeding.


Step 5 — Draft Commit Messages

Every commit message MUST follow:

<type>(<scope>): <subject>

<body — optional>
  • Subject: max 50 characters, imperative mood ("add" not "added")
  • Body: wrap at 72 characters, explain motivation/context
  • Scope: REQUIRED, from the allowlist — NEVER omit, NEVER invent

Step 6 — Execute Commits

⛔ HARD STOP — TRAILER RULES

THE MOST COMMON MISTAKE: Putting trailer text INSIDE the -m quotes.

# ❌ WRONG — trailer text is INSIDE the -m quotes
git commit -m "feat(auth): add feature

X-Lerian-Ref: 0x1"

# ✅ CORRECT — --trailer is a SEPARATE argument OUTSIDE quotes
git commit -m "feat(auth): add feature" --trailer "X-Lerian-Ref: 0x1"

Before writing ANY git commit command, verify:

  • -m "..." contains ONLY the commit message (no trailer text inside)
  • --trailer flags are OUTSIDE and AFTER the -m parameter
  • Command is structured as: git commit -S -m "msg" --trailer "key: value"

Required Command Structure

git commit -S \
  -m "<type>(<scope>): <subject>" \
  -m "<body if needed>" \
  --trailer "X-Lerian-Ref: 0x1"

For each commit group, in order:

  1. Stage only the files for this commit:

    git add <file1> <file2> ...
    
  2. Create si

阅读完整来源 ↗