AgentSkillsCN

git-best-practices

默认安全的 Git 工作流与传统提交规范。适用于 Git 操作（差异、暂存、提交、分支、合并、冲突解决、变基/拣选）、PR 审核及发布（打标签）。防止未经同意的破坏性操作。

SKILL.md
--- frontmatter
name: git-best-practices
description: Safe-by-default git workflow and Conventional Commits. Use for git operations (diffs, staging, commits, branches, merges, conflict resolution, rebase/cherry-pick), PR review, and releases (tagging). Prevent destructive operations without consent.

Git Best Practices

Safety Rules

  • •Read-only by default: Prefer git status, git diff, git log, git show, git blame before making changes
  • •Push requires explicit request: Never push unless user asks
  • •Checkout allowed for: PR review, explicit user request
  • •Branch changes require consent: Ask before creating/switching branches
  • •History rewriting requires consent: Ask before commit --amend, interactive rebase, or force push (especially if anything may be shared)
  • •Destructive ops require explicit user consent:
    • •Allow previews like git clean -n (no deletion); do not run git clean -fd without consent
    • •Do not discard worktree changes with git reset --hard or git restore . without consent
    • •Do not delete branches/tags or force push without consent

Preferred Commands

  • •Prefer modern porcelain: git switch (branches) and git restore (undo) when appropriate
  • •git restore --staged <path> is usually safe; discarding worktree changes (e.g., git restore .) requires explicit consent

Conventional Commits

Format: <type>[optional scope][optional !]: <description>

Subject Line

  • •Use imperative mood (“add”, “fix”, “remove”)
  • •Keep it short and specific; avoid trailing periods

Types

TypeUse for
featNew features
fixBug fixes
docsDocumentation only
styleFormatting, whitespace (no code change)
refactorCode change that neither fixes nor adds
perfPerformance improvements
testAdding or correcting tests
buildBuild system or dependencies
ciCI configuration
choreOther changes (tooling, config)
revertReverting a previous commit

Scope

  • •Use the smallest sensible scope
  • •Omit scope if unclear or too broad
  • •Examples: feat(auth):, fix(api):, docs(readme):

Breaking Changes

Mark with ! before the colon OR add a BREAKING CHANGE: footer:

code
feat(api)!: remove deprecated endpoints

BREAKING CHANGE: /v1/users endpoint removed, use /v2/users

Body and Footers

  • •Use body only when the subject line needs elaboration
  • •Footers follow git-trailer style: Token: value
  • •Common footers: BREAKING CHANGE:, Fixes:, Refs:, Co-authored-by:

Examples

code
feat(auth): add OAuth2 login flow

fix: prevent race condition in queue processing

docs: update API authentication examples

refactor(db)!: migrate from MySQL to PostgreSQL

BREAKING CHANGE: database connection config format changed

Pre-Commit Checklist

  • •Review git status
  • •Review git diff and git diff --staged
  • •Run the smallest relevant checks if known (or ask what to run)
  • •Scan for secrets (tokens, keys, credentials) and unintended debug logs
  • •Prefer small, logical commits; use git add -p when changes are mixed
  • •Propose a commit split and draft commit messages before staging/committing

Workflow

After reviewing changes, end with:

  1. •Short summary of proposed commits
  2. •Clear question for next steps (stage/commit/push)

If anything is ambiguous, ask short, direct questions with options.