feat: Optimize PR workflow with on-demand skill loading and project-level skills management (#12943)

### What this PR does

Before this PR:
- CLAUDE.md contained detailed PR workflow instructions that were loaded
in every agent session, consuming unnecessary tokens
- No unified project-level skills management mechanism; adding public
skills lacked standardization
- No automated checks to prevent non-compliant skills from being merged
- Team members had no convenient way to share skills with each other

After this PR:
- Simplified PR instructions in CLAUDE.md, now loaded on-demand via the
`gh-create-pr` skill
- Introduced project-level skills management (`.agents/skills/`
directory + `public-skills.txt` whitelist)
- Added `scripts/skills-sync.ts` and `scripts/skills-check.ts` for
automated management
- Integrated skills validation into CI to prevent non-whitelisted skills
from being merged
- **Teams can now easily share skills through the project-level
mechanism**, with `skills-sync.ts` automatically syncing skills to all
team members' local environments, streamlining onboarding and avoiding
duplicated configuration efforts
- **Optimized PR creation workflow**: `gh-create-pr` skill enforces
English PR body writing and displays the draft to users for review
before creation, ensuring quality and compliance

Fixes #

### Why we need it and why it was done in this way

The following tradeoffs were made:
- Moved PR workflow from CLAUDE.md to a skill, sacrificing immediate
visibility for token efficiency
- **Introduced whitelist mechanism (`public-skills.txt`) instead of
auto-scanning all files**: Allows developers to freely use private
project-level skills in the `.agents/skills/` directory (e.g.,
team-internal skills, personal customizations). Only skills added to the
whitelist are tracked by git and submitted. This ensures standardization
for shared skills while preserving development flexibility
- Skills exist in both `.agents/skills/` (project-level, shareable) and
`.claude/skills/` (local, private)
- **Symlink only SKILL.md files instead of entire directories**: On some
Windows/restricted filesystems, symlinks may fail or be treated as
regular files. If an entire directory is symlinked, failure results in a
regular file instead of a directory, causing complete skill failure
that's hard to diagnose. Symlinking only SKILL.md allows quick detection
when symlinks fail (file content displays directly or errors), reducing
troubleshooting costs

The following alternatives were considered:
- Keeping PR instructions in CLAUDE.md with collapsible blocks, but this
still consumes context tokens
- Using git hooks for pre-commit checks, but CI checks are more reliable
and don't block local development

Links to places where the discussion took place: N/A

### Breaking changes

None

### Special notes for your reviewer

- `gh-create-pr` skill fully implements the project's PR workflow
requirements (read template → display body → confirm → create)
- `skills-check.ts` validates: 1) tracked skills are in the whitelist;
2) whitelist skills have corresponding files
- Process for adding new public skills: 1) create skill files; 2) add to
`public-skills.txt`; 3) CI auto-validation
- `.claude/skills/` added to `.gitignore` for private skills

### Checklist

This checklist is not enforcing, but it's a reminder of items that could
be relevant to every PR.
Approvers are expected to review this list.

- [x] PR: The PR description is expressive enough and will help future
contributors
- [x] Code: [Write code that humans can
understand](https://en.wikiquote.org/wiki/Martin_Fowler#code-for-humans)
and [Keep it simple](https://en.wikipedia.org/wiki/KISS_principle)
- [x] Refactor: You have [left the code cleaner than you found it (Boy
Scout
Rule)](https://learning.oreilly.com/library/view/97-things-every/9780596809515/ch08.html)
- [x] Upgrade: Impact of this change on upgrade flows was considered and
is present (link) or not required. You want a user-guide update if it's
a user facing feature.
- [ ] Documentation: A user-guide update was considered and is present
(link) or not required. You want a user-guide update if it's a user
facing feature.

### Release note

```release-note
Optimize PR workflow by moving instructions to on-demand skill; introduce project-level skills management with automated validation
```

Author: EurFelux

.agents/skills/.gitignore

@@ -0,0 +1,8 @@
+# AUTO-GENERATED by `pnpm skills:sync`.
+# Do not edit manually.
+*
+!.gitignore
+!README*.md
+!public-skills.txt
+!gh-create-pr/
+!gh-create-pr/**

.agents/skills/README.md

@@ -0,0 +1,56 @@
+# Skills Management
+
+This directory is the single source of truth for repository skills.
+
+## Add a New Skill
+
+1. Create a new folder under `.agents/skills/<skill-name>/`.
+2. Add a `SKILL.md` file with:
+   - `name` and `description` in YAML frontmatter
+   - concise workflow instructions in the body
+3. (Optional) Add `agents/openai.yaml` if Codex UI metadata is needed.
+4. If this skill should be shared in the repository, append `<skill-name>` to `.agents/skills/public-skills.txt`.
+
+## Naming Rules
+
+- Use lowercase letters, digits, and hyphens only.
+- Prefer short, action-oriented names (for example: `gh-create-pr`).
+
+## Claude Compatibility
+
+For each new public skill, run:
+
+```bash
+pnpm skills:sync
+```
+
+`skills:sync` will create/update `.claude/skills/<skill-name>/SKILL.md` as:
+
+- a copied file from `.agents/skills/<skill-name>/SKILL.md`.
+- symlinks are not allowed; check enforces regular files for compatibility.
+
+## White-list Tracking Rules
+
+The public white-list is defined in `.agents/skills/public-skills.txt`.
+
+- Skills listed there are synced to both `.agents/skills/.gitignore` and `.claude/skills/.gitignore`.
+- Private/local-only skills should stay out of `public-skills.txt`.
+- Use one skill name per line. Comment lines must start with `#` and cannot be appended inline.
+
+After updating `public-skills.txt`, run:
+
+```bash
+pnpm skills:sync
+```
+
+Then validate:
+
+```bash
+pnpm skills:check
+```
+
+The sync/check scripts manage and verify:
+
+- `.agents/skills/.gitignore`
+- `.claude/skills/.gitignore`
+- `.claude/skills/<skill-name>/SKILL.md` content matches `.agents/skills/<skill-name>/SKILL.md`

.agents/skills/README.zh.md

@@ -0,0 +1,56 @@
+# Skills 管理说明
+
+本目录是仓库内 skills 的唯一维护来源（single source of truth）。
+
+## 新增 Skill 流程
+
+1. 在 `.agents/skills/<skill-name>/` 下创建新目录。
+2. 添加 `SKILL.md`，包含：
+   - YAML frontmatter 中的 `name` 和 `description`
+   - 正文中的精简流程说明
+3. （可选）如需 Codex UI 元数据，添加 `agents/openai.yaml`。
+4. 若该 skill 需要作为仓库公共 skill 跟踪，请将 `<skill-name>` 追加到 `.agents/skills/public-skills.txt`。
+
+## 命名规则
+
+- 仅使用小写字母、数字和连字符（`-`）。
+- 优先使用简短、动作导向的名称（例如：`gh-create-pr`）。
+
+## Claude 兼容
+
+每个新增的公共 skill，请执行：
+
+```bash
+pnpm skills:sync
+```
+
+`skills:sync` 会自动创建/更新 `.claude/skills/<skill-name>/SKILL.md`：
+
+- 复制 `.agents/skills/<skill-name>/SKILL.md` 的内容。
+- 不允许使用符号链接；check 会强制要求为普通文件以保证兼容性。
+
+## 白名单跟踪规则
+
+公共白名单由 `.agents/skills/public-skills.txt` 定义。
+
+- 写入该文件的 skill 会同步到 `.agents/skills/.gitignore` 和 `.claude/skills/.gitignore`。
+- 私有/仅本地使用的 skill 不应写入 `public-skills.txt`。
+- 每行只写一个 skill 名称。注释行必须以 `#` 开头，不能写行尾注释。
+
+更新 `public-skills.txt` 后，请执行：
+
+```bash
+pnpm skills:sync
+```
+
+然后校验：
+
+```bash
+pnpm skills:check
+```
+
+上述脚本会自动维护并校验：
+
+- `.agents/skills/.gitignore`
+- `.claude/skills/.gitignore`
+- `.claude/skills/<skill-name>/SKILL.md` 与 `.agents/skills/<skill-name>/SKILL.md` 的内容一致性

.agents/skills/gh-create-pr/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: gh-create-pr
+description: Create or update GitHub pull requests using the repository-required workflow and template compliance. Use when asked to create/open/update a PR so the assistant reads `.github/pull_request_template.md`, fills every template section, preserves markdown structure exactly, and marks missing data as N/A or None instead of skipping sections.
+---
+
+# GitHub PR Creation
+
+## Workflow
+
+1. Read `.github/pull_request_template.md` before drafting the PR body.
+2. Collect PR context from the current branch (base/head, scope, linked issues, testing status, breaking changes, release note content).
+3. Draft the PR body using the template structure exactly:
+   - Keep section order and headings.
+   - Keep checkbox and code block formatting.
+   - Fill every section; if not applicable, write `N/A` or `None`.
+4. Present the full Markdown PR body in chat for review before creating the PR.
+5. Ask for explicit confirmation to create the PR with that body.
+6. After confirmation, create the PR with `gh pr create --body-file` using a unique temp file path.
+7. Report the created PR URL and summarize title/base/head and any required follow-up.
+
+## Constraints
+
+- Never skip template sections.
+- Never rewrite the template format.
+- Keep content concise and specific to the current change set.
+- PR title and body must be written in English.
+- Never create the PR before showing the full final body to the user.
+- Never rely on command permission prompts as PR body preview.
+
+## Command Pattern
+
+```bash
+# read template
+cat .github/pull_request_template.md
+
+# show this full Markdown body in chat first
+pr_body_file="$(mktemp /tmp/gh-pr-body-XXXXXX).md"
+cat > "$pr_body_file" <<'EOF'
+...filled template body...
+EOF
+
+# run only after explicit user confirmation
+gh pr create --base <base> --head <head> --title "<title>" --body-file "$pr_body_file"
+rm -f "$pr_body_file"
+```

.agents/skills/gh-create-pr/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Create GitHub PR"
+  short_description: "Create PRs with required template compliance"
+  default_prompt: "Create a pull request for my current branch using the repository template workflow."

.agents/skills/public-skills.txt

@@ -0,0 +1,3 @@
+# Public skills tracked by skills:sync and skills:check.
+# One skill name per line.
+gh-create-pr

.claude/skills/.gitignore

@@ -0,0 +1,7 @@
+# AUTO-GENERATED by `pnpm skills:sync`.
+# Do not edit manually.
+*
+!.gitignore
+!README*.md
+!gh-create-pr/
+!gh-create-pr/**

.claude/skills/README.md

@@ -0,0 +1,8 @@
+# Claude Skills Mirror
+
+This directory is a synced mirror for Claude-compatible skill files.
+
+- Do not create new skills directly under `.claude/skills`.
+- Create and maintain skills under `.agents/skills` only.
+- Update `.agents/skills/public-skills.txt`, then run `pnpm skills:sync`.
+- `pnpm skills:check` verifies `.claude/skills/<skill>/SKILL.md` matches `.agents/skills/<skill>/SKILL.md`.

.claude/skills/README.zh.md

@@ -0,0 +1,8 @@
+# Claude Skills 镜像说明
+
+本目录是面向 Claude 的 skill 文件镜像目录。
+
+- 不要直接在 `.claude/skills` 下创建新 skill。
+- 所有 skill 仅在 `.agents/skills` 中创建和维护。
+- 更新 `.agents/skills/public-skills.txt` 后，执行 `pnpm skills:sync`。
+- `pnpm skills:check` 会校验 `.claude/skills/<skill>/SKILL.md` 与 `.agents/skills/<skill>/SKILL.md` 内容一致。

.claude/skills/gh-create-pr/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: gh-create-pr
+description: Create or update GitHub pull requests using the repository-required workflow and template compliance. Use when asked to create/open/update a PR so the assistant reads `.github/pull_request_template.md`, fills every template section, preserves markdown structure exactly, and marks missing data as N/A or None instead of skipping sections.
+---
+
+# GitHub PR Creation
+
+## Workflow
+
+1. Read `.github/pull_request_template.md` before drafting the PR body.
+2. Collect PR context from the current branch (base/head, scope, linked issues, testing status, breaking changes, release note content).
+3. Draft the PR body using the template structure exactly:
+   - Keep section order and headings.
+   - Keep checkbox and code block formatting.
+   - Fill every section; if not applicable, write `N/A` or `None`.
+4. Present the full Markdown PR body in chat for review before creating the PR.
+5. Ask for explicit confirmation to create the PR with that body.
+6. After confirmation, create the PR with `gh pr create --body-file` using a unique temp file path.
+7. Report the created PR URL and summarize title/base/head and any required follow-up.
+
+## Constraints
+
+- Never skip template sections.
+- Never rewrite the template format.
+- Keep content concise and specific to the current change set.
+- PR title and body must be written in English.
+- Never create the PR before showing the full final body to the user.
+- Never rely on command permission prompts as PR body preview.
+
+## Command Pattern
+
+```bash
+# read template
+cat .github/pull_request_template.md
+
+# show this full Markdown body in chat first
+pr_body_file="$(mktemp /tmp/gh-pr-body-XXXXXX).md"
+cat > "$pr_body_file" <<'EOF'
+...filled template body...
+EOF
+
+# run only after explicit user confirmation
+gh pr create --base <base> --head <head> --title "<title>" --body-file "$pr_body_file"
+rm -f "$pr_body_file"
+```