♻️ refactor(skills): standardize first-party skill contracts

upgrade commit-message, style-cleanup, and bulk-refactor-workflow to use trigger-focused frontmatter and a shared contract structure. add a first-party skill quality test gate and register it in tests documentation.
2026-05-19 09:38:32 +08:00
parent 2c5050de09
commit e0b1c3ab1b
5 changed files with 335 additions and 136 deletions
@@ -1,94 +1,107 @@
 ---
 name: style-cleanup
-description:
-  "Clean up formatting and code style with the repo’s existing toolchain
-  (clang-format/black/isort/flake8/pre-commit/etc). Triggers: 整理代码风格,
-  格式化, format, fmt, lint fix, clang-format, black, isort."
+description: Use when the user asks to format code, fix lint issues, or align style with the repository's existing toolchain without changing behavior.
 ---

 # Style Cleanup Workflow（整理代码风格 / 格式化）

+## Overview
+
+Apply the repository's existing formatter and lint toolchain without changing
+behavior. Core principle: trust repo truth, keep scope tight, and verify with a
+rerun.
+
 ## When to Use

- “整理代码风格 / 格式化 / format / fmt / lint fix”
- 合并前做一次风格对齐（不做语义级重构）
- 批量改动后，希望把格式化与机械性风格问题收敛到可控 diff
+- The user asks for formatting, `fmt`, `format`, or lint cleanup
+- A code change is done and needs a final style pass before review or commit
+- A mechanical change produced noisy diff that should be normalized by the repo's
+  existing toolchain

-## Inputs（required）
+## When Not to Use

- Scope：仅本次改动文件（默认）｜全仓库｜指定目录/文件类型
- Languages：自动识别；如为多语言仓库请确认优先级
- Verification：至少一个可执行的验证命令（如未知，先问/再推断）
+- This is not for semantic refactors or behavior changes
+- This is not for introducing a new formatter or lint configuration
+- This is not for full-repo reformatting unless the user explicitly requests that
+  scope

-## Procedure（default）
+## Inputs

-1. **Baseline**
+- Target scope: staged files, unstaged files, explicit file list, or explicit
+  directory
+- Relevant languages in scope
+- Verification commands available in the repository

-   - 记录当前状态：`git status --porcelain`
-   - 明确范围（默认只处理变更文件）：
-     - staged：`git diff --name-only --cached`
-     - unstaged：`git diff --name-only`
-     - untracked：`git ls-files -o --exclude-standard`
+## Procedure

-2. **Detect Toolchain（prefer repo truth）**
+1. **Baseline the scope**

-   - 优先用仓库既有入口脚本 / 配置：
-     - JS/TS：`package.json`
-       scripts（`format`/`lint`/`lint:fix`）、prettier/biome/eslint 配置
-     - Python：`pyproject.toml` / `.flake8` / `.pylintrc` /
-       `.pre-commit-config.yaml`
-     - C/C++：`.clang-format`（唯一真相），可选 `.clang-tidy`
-     - Shell：`shfmt`/`shellcheck`（若仓库已使用）
-     - Markdown：prettier/markdownlint（仅在仓库已固定时使用）
-   - 禁止默认“引入新 formatter/linter 配置”；缺配置时只做最小手工调整，并先确认是否允许落地配置文件。
+   - Record `git status --short`.
+   - Default to changed files only unless the user requested broader scope.
+   - Resolve the target file set before running any formatter.

-3. **Apply（format first, then lint）**
+2. **Detect the repo toolchain**

-   - 先 formatter（会改文件），再 lint（检查），再 lint
-     --fix（如有），最后再跑一次 check 确认干净。
-   - 默认只处理目标文件集合；避免全仓库 reformat（除非用户明确要求）。
-   - 典型命令（按仓库实际替换）：
-     - C++：`clang-format -i <files...>`；CI 校验：`clang-format --dry-run --Werror <files...>`
-     - Python：`black <files...>` + `isort <files...>`；或
-       `pre-commit run --files <files...>`
-     - JS/TS：`npm run format -- <files...>` / `pnpm ...` /
-       `npx prettier -w <files...>`（以项目脚本为准）
+   - Prefer repository scripts and checked-in config over ad hoc commands.
+   - Use the repo's existing formatter/linter stack:
+     - JS/TS: `package.json`, prettier, biome, eslint
+     - Python: `pyproject.toml`, `isort`, `black`, `ruff`, `flake8`,
+       `pre-commit`
+     - C/C++: `.clang-format`, optional `.clang-tidy`
+     - Shell: `shfmt`, `shellcheck` if already present
+     - Markdown: prettier/markdownlint only if the repo already uses them

-4. **Guardrails**
+3. **Run cleanup in a fixed loop**

-   - 只做风格与格式：不改变行为、不改 public API、不做重构。
-   - 如格式化导致 diff 暴涨（文件数/行数过大）：先停下，给出原因与两种方案让用户选：
-     1. 仅格式化本次改动文件（推荐默认）
-     2. 全仓库统一格式（通常需要单独 PR/提交）
+   - Use `formatter -> lint/check -> lint --fix -> final check`.
+   - Prefer repository entrypoints over raw tool invocations.
+   - Keep execution scoped to the chosen files whenever the toolchain supports it.
+
+4. **Control blast radius**
+
+   - If the formatter expands the diff far beyond the requested scope, stop and
+     explain the tradeoff.
+   - Offer a scoped pass vs. a full-repo normalization pass instead of silently
+     widening scope.

 5. **Verify**
-   - 跑最小验证命令（仓库已有命令优先）。
-   - 若无法运行（缺环境/缺权限/缺依赖）：说明原因，并给出替代验证（例如 formatter 二次运行无 diff、lint 输出为 0）。

-## Playbook as Authority（如果项目 vendoring 了本 Playbook）
+   - Re-run the lightweight checks after fixes.
+   - Confirm that the second formatter run produces no additional diff.
+   - If the repo has a canonical lint or test command for style verification, run
+     that command and report the result.

-当目标仓库包含 `docs/standards/playbook/docs/`（或直接包含
-`docs/tsl|cpp|python/...`），风格决策参考：
+## Playbook as Authority

- TSL：`docs/tsl/code_style.md`、`docs/tsl/naming.md`、`docs/tsl/toolchain.md`
- C++：`docs/cpp/code_style.md`、`docs/cpp/naming.md`、`docs/cpp/toolchain.md`
- Python：`docs/python/style_guide.md`、`docs/python/tooling.md`、`docs/python/configuration.md`
+When the target repo vendors this playbook, prefer these references for style
+judgment:

-## Output Contract（stable）
+- TSL: `docs/tsl/code_style.md`, `docs/tsl/naming.md`, `docs/tsl/toolchain.md`
+- C++: `docs/cpp/code_style.md`, `docs/cpp/naming.md`, `docs/cpp/toolchain.md`
+- Python: `docs/python/style_guide.md`, `docs/python/tooling.md`,
+  `docs/python/configuration.md`

- Scope：实际处理范围（文件/目录/语言）
- Toolchain：使用了哪些工具与配置依据
- Commands：实际执行命令（按顺序）
- Changes：修改文件列表 + 改动规模概览
- Remaining：仍未修复的问题（分类：formatter / lint / style）+ 下一步建议
+## Output Contract
+
+- `Scope:` actual files/directories/languages processed
+- `Toolchain:` repo configs and commands used
+- `Commands:` execution order
+- `Changes:` modified files plus diff-size summary
+- `Remaining:` unresolved lint/style issues plus why they remain

 ## Success Criteria

- formatter 二次运行无新增 diff
- lint/检查命令通过（或仅剩已确认的例外）
- 未引入语义变更（仅格式/风格）
+- Style cleanup stays within the requested or agreed scope
+- The second formatter run produces no additional diff
+- Verification commands pass, or any remaining exception is explicitly explained
+- No semantic behavior change is introduced

 ## Failure Handling

- 工具缺失：优先提示安装方式或替代命令；无法解决则退回“最小手工风格修复 + 明确未覆盖项”
- 规则冲突（如 black vs flake8）：以仓库配置为准；必要时调整例外配置但需先确认
+- If the repo lacks a formatter/linter, say so and fall back to minimal manual
+  cleanup only with clear limits
+- If tools are missing locally, report the missing dependency and stop before
+  inventing a new toolchain
+- If two configured tools conflict, follow checked-in repo config and surface the
+  conflict instead of papering over it
+- If cleanup would require wider scope than requested, stop and ask for approval