[Coding Agent] add claude skills for API Compatibility by zhwesky2010 · Pull Request #7899 · PaddlePaddle/docs

zhwesky2010 · 2026-04-27T17:09:54Z

《Paddle API 对齐 PyTorch 项目》完整 SKILL 体系

AI Agent 自动对齐 Paddle API 与 PyTorch API。包含 1 个总 skill 和 6 个分阶段 skill。

两种使用方式

方式一：一步到位（推荐）

使用总 skill /api-compatibility，传入待对齐的 PyTorch API 列表：

/api-compatibility torch.atan torch.asinh torch.abs_

总 skill 会自动执行完整流程（Step1→Step2→Step3→Step4→Step5），返回对齐结果统计表。

方式二：分步操作

针对具体任务，单独调用对应 skill：

阶段	Skill	用途
Step1	`/api-change-decider`	分析 API 差异，决策改动方案
Step2	`/python-decorator`	用 Python 装饰器修改 API
Step2	`/cpp-sink`	用 C++下沉修改 API（性能更优）
Step3	`/pytorch-alignment-validator`	验证 API 对齐
Step4	`/api-docs-updater`	更新中文文档
Step5	`/create-pr`	提交 PR 到三个仓库

工作流程

输入：待对齐 API 列表
  ↓
Step1：方案决策（api-change-decider）
  ├─ 分析 API 差异
  └─ 决策改动方案（方案 1-6）
  ↓
Step2：代码修改（python-decorator 或 cpp-sink）
  ├─ 方案 1：Python 装饰器
  ├─ 方案 2：C++下沉
  └─ 其他方案：跳过
  ↓
Step3：对齐验证（pytorch-alignment-validator）
  ├─ 更新 API 映射
  ├─ 补充测试用例
  └─ 运行单元测试
  ↓
Step4：文档更新（api-docs-updater）
  └─ 更新中文 API 文档
  ↓
Step5：代码提交（create-pr）
  └─ 提交 PR 到 Paddle/PaConvert/docs
  ↓
输出：对齐结果统计表

使用示例

完整对齐一个 API（推荐方式）：

/api-compatibility torch.atan            # 执行全部步骤

自动完成全流程，得到对齐结果。

调试单个 API（需要逐步修改）：

/api-change-decider torch.atan            # 确定方案
/cpp-sink torch.atan                      # 指定方案修改
/python-decorator torch.atan              # 指定方案修改
/pytorch-alignment-validator torch.atan   # 验证
/api-docs-updater torch.atan              # 更新文档
/create-pr torch.atan                     # 提交 PR

paddle-bot · 2026-04-27T17:10:02Z

感谢你贡献飞桨文档，文档预览构建中，Docs-New 跑完后即可预览，预览链接：http://preview-pr-7899.paddle-docs-preview.paddlepaddle.org.cn/documentation/docs/zh/api/index_cn.html
预览工具的更多说明，请参考：飞桨文档预览工具

github-actions · 2026-04-27T17:10:26Z

📚 本次 PR 文档预览链接（点击展开）

ℹ️ 预览提醒请等待 `Docs-NEW` 流水线运行完成后再点击预览链接，否则可能会看到旧版本内容或遇到链接无法访问的情况。

docs/dev_guides/coding_agent/api_compatibility/.claude/skills/README.md: 点击预览
docs/dev_guides/coding_agent/api_compatibility/.claude/skills/api-change-decider/SKILL.md: 点击预览
docs/dev_guides/coding_agent/api_compatibility/.claude/skills/api-compatibility/SKILL.md: 点击预览
docs/dev_guides/coding_agent/api_compatibility/.claude/skills/api-docs-updater/SKILL.md: 点击预览
docs/dev_guides/coding_agent/api_compatibility/.claude/skills/cpp-sink/SKILL.md: 点击预览
docs/dev_guides/coding_agent/api_compatibility/.claude/skills/create-pr/SKILL.md: 点击预览
docs/dev_guides/coding_agent/api_compatibility/.claude/skills/python-decorator/SKILL.md: 点击预览
docs/dev_guides/coding_agent/api_compatibility/.claude/skills/pytorch-alignment-validator/SKILL.md: 点击预览

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR adds a Claude skill-based workflow for “Paddle API 对齐 PyTorch” and refreshes the API compatibility guide to document the new end-to-end and step-by-step usage.

Changes:

Reworked the API compatibility README to describe the new skill体系, usage modes, and step workflow.
Added multiple .claude/skills/*/SKILL.md documents to define per-step skills (decision, implementation, validation, docs update, PR creation).
Added an orchestrator skill (api-compatibility) describing the full pipeline and constraints.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
docs/dev_guides/coding_agent/api_compatibility/README.md	Updates the guide to the new skill体系 and documents one-shot vs step-by-step usage.
docs/dev_guides/coding_agent/api_compatibility/.claude/skills/api-compatibility/SKILL.md	Adds the orchestrator skill spec (project goals,流程/约束、调用子技能).
docs/dev_guides/coding_agent/api_compatibility/.claude/skills/api-change-decider/SKILL.md	Adds Step1 decision skill spec (diff analysis + scheme selection).
docs/dev_guides/coding_agent/api_compatibility/.claude/skills/python-decorator/SKILL.md	Adds Step2 Python decorator implementation playbook.
docs/dev_guides/coding_agent/api_compatibility/.claude/skills/cpp-sink/SKILL.md	Adds Step2 C++ sinking implementation playbook.
docs/dev_guides/coding_agent/api_compatibility/.claude/skills/pytorch-alignment-validator/SKILL.md	Adds Step3 PaConvert-based alignment validation playbook.
docs/dev_guides/coding_agent/api_compatibility/.claude/skills/api-docs-updater/SKILL.md	Adds Step4 Chinese docs update playbook.
docs/dev_guides/coding_agent/api_compatibility/.claude/skills/create-pr/SKILL.md	Adds Step4 PR creation instructions across three repos.

Copilot · 2026-04-27T17:20:25Z

Markdown 表格行首使用了 ||，在 GitHub Flavored Markdown 下会多出一个空白列，导致渲染错位。建议统一改为单个 | 起始（如 | 阶段 | Skill | 用途 |），并在本 PR 新增的其他 SKILL 文档表格处保持一致。

Copilot · 2026-04-27T17:20:26Z

分步示例里同时执行了 /cpp-sink 和 /python-decorator 两种 Step2 实现方式，但实际应根据 Step1 的方案二选一；按当前文案会误导读者把两种修改叠加。建议改成条件分支说明（例如“若方案=cpp-sink 则运行 /cpp-sink，否则运行 /python-decorator”），或给出两个互斥的示例流程。

Suggested change

/api-change-decider torch.atan # 先确定方案

# 若 Step1 判定为“方案 2：C++下沉”，则执行：

/cpp-sink torch.atan

# 若 Step1 判定为“方案 1：Python 装饰器”，则执行：

/python-decorator torch.atan

Copilot · 2026-04-27T17:20:26Z

+---
+name: pytorch-alignment-validator
+description: 仅用于《Paddle API 对齐 PyTorch 项目》，负责 Step3：Pytorch 对齐验证，基于 PaConvert 工具验证 Paddle API 与 PyTorch API 是否用法完全对齐一致
+allowed-tools: Read Grep‌ Glob‌ Write‌ Edit Bash(python *)


allowed-tools 这一行在 Grep/Glob/Write/Edit 之间疑似包含零宽字符（不可见分隔符），可能导致工具白名单解析失败或在不同环境下行为不一致。建议删除这些特殊字符并用普通空格分隔，保证 frontmatter 为纯 ASCII/UTF-8 可见字符。

Suggested change

allowed-tools: Read Grep‌ Glob‌ Write‌ Edit Bash(python *)

allowed-tools: Read Grep Glob Write Edit Bash(python *)

Copilot · 2026-04-27T17:20:26Z

+## Step 3：推送代码到 upstream claude 分支
+
+```bash
+# Paddle 仓库
+cd /path/to/Paddle
+git push upstream HEAD:claude -f
+
+# docs 仓库
+cd /path/to/docs
+git push upstream HEAD:claude -f
+
+# PaConvert 仓库
+cd /path/to/PaConvert
+git push upstream HEAD:claude -f


这里把 remote（upstream）、分支名（claude）以及 GitHub 用户名（zhwesky2010）写死，会导致他人按文档执行时大概率失败（remote 名称不同、分支策略不同、fork 用户名不同）。建议将这些改为占位符/变量（例如 <GITHUB_USER>、<BRANCH>、<REMOTE>），或加入获取当前用户/remote 的命令指引（如用 gh api user -q .login 获取 login），避免流程不可复用。

Suggested change

## Step 3：推送代码到 upstream claude 分支

```bash

# Paddle 仓库

cd /path/to/Paddle

git push upstream HEAD:claude -f

# docs 仓库

cd /path/to/docs

git push upstream HEAD:claude -f

# PaConvert 仓库

cd /path/to/PaConvert

git push upstream HEAD:claude -f

## Step 3：推送代码到指定 remote 和分支

请先根据本地仓库实际配置确认用于推送的 remote 名称和目标分支名，并将下面命令中的 `<REMOTE>`、`<BRANCH>` 替换为对应值。

```bash

# Paddle 仓库

cd /path/to/Paddle

git push <REMOTE> HEAD:<BRANCH>

# docs 仓库

cd /path/to/docs

git push <REMOTE> HEAD:<BRANCH>

# PaConvert 仓库

cd /path/to/PaConvert

git push <REMOTE> HEAD:<BRANCH>

Copilot · 2026-04-27T17:20:27Z

+## Step 3：推送代码到 upstream claude 分支
+
+```bash
+# Paddle 仓库
+cd /path/to/Paddle
+git push upstream HEAD:claude -f
+
+# docs 仓库
+cd /path/to/docs
+git push upstream HEAD:claude -f
+
+# PaConvert 仓库
+cd /path/to/PaConvert
+git push upstream HEAD:claude -f


这里把 remote（upstream）、分支名（claude）以及 GitHub 用户名（zhwesky2010）写死，会导致他人按文档执行时大概率失败（remote 名称不同、分支策略不同、fork 用户名不同）。建议将这些改为占位符/变量（例如 <GITHUB_USER>、<BRANCH>、<REMOTE>），或加入获取当前用户/remote 的命令指引（如用 gh api user -q .login 获取 login），避免流程不可复用。

Suggested change

## Step 3：推送代码到 upstream claude 分支

```bash

# Paddle 仓库

cd /path/to/Paddle

git push upstream HEAD:claude -f

# docs 仓库

cd /path/to/docs

git push upstream HEAD:claude -f

# PaConvert 仓库

cd /path/to/PaConvert

git push upstream HEAD:claude -f

## Step 3：推送代码到指定 remote 的目标分支

将下面命令中的 `<REMOTE>` 和 `<BRANCH>` 替换为当前仓库实际使用的 remote 名称和目标分支名后再执行。

```bash

# Paddle 仓库

cd /path/to/Paddle

git push <REMOTE> HEAD:<BRANCH>

# docs 仓库

cd /path/to/docs

git push <REMOTE> HEAD:<BRANCH>

# PaConvert 仓库

cd /path/to/PaConvert

git push <REMOTE> HEAD:<BRANCH>

Copilot · 2026-04-27T17:20:28Z

+)"
+
+# Docs PR
+gh pr create --repo PaddlePaddle/docs --base develop --head zhwesky2010:claude \


这里把 remote（upstream）、分支名（claude）以及 GitHub 用户名（zhwesky2010）写死，会导致他人按文档执行时大概率失败（remote 名称不同、分支策略不同、fork 用户名不同）。建议将这些改为占位符/变量（例如 <GITHUB_USER>、<BRANCH>、<REMOTE>），或加入获取当前用户/remote 的命令指引（如用 gh api user -q .login 获取 login），避免流程不可复用。

Copilot · 2026-04-27T17:20:28Z

+)"
+
+# PaConvert PR
+gh pr create --repo PaddlePaddle/PaConvert --base master --head zhwesky2010:claude \


这里把 remote（upstream）、分支名（claude）以及 GitHub 用户名（zhwesky2010）写死，会导致他人按文档执行时大概率失败（remote 名称不同、分支策略不同、fork 用户名不同）。建议将这些改为占位符/变量（例如 <GITHUB_USER>、<BRANCH>、<REMOTE>），或加入获取当前用户/remote 的命令指引（如用 gh api user -q .login 获取 login），避免流程不可复用。

Copilot · 2026-04-27T17:20:28Z

+3. 输出结果序号需要保持连贯，每一个输出结果均需要检验，尽可能循环检验减少行数。
+3. 比对测试项，对于内容相同的测试项，不要重复添加。


列表编号重复（两条都是 3.），会影响阅读和引用。建议把后一条改为 4.（或使用无序列表）以保持编号一致。

Copilot · 2026-04-27T17:20:28Z

+|-|-|-|-|-|
+|API 中文文档|`{api_name}_cn.rst`|docs/docs/api/paddle/|tan_cn.rst||
+|API 差异文档|`torch.{api_name}.md`|docs/docs/guides/model_convert/convert_from_pytorch/api_difference/|torch.tan.md||
+|C++下沉使用|`python_api_info.yaml`、`ops.yaml`|Paddle/paddle/phi/ops/yaml/|python_api_info.yamlops.yaml||


示例列里 python_api_info.yamlops.yaml 缺少分隔，读者无法直观看出是两个文件名。建议改为 python_api_info.yaml / ops.yaml 或 python_api_info.yaml, ops.yaml（与同表其他行的示例风格一致）。

Suggested change

|C++下沉使用|`python_api_info.yaml`、`ops.yaml`|Paddle/paddle/phi/ops/yaml/|python_api_info.yamlops.yaml||

|C++下沉使用|`python_api_info.yaml`、`ops.yaml`|Paddle/paddle/phi/ops/yaml/|python_api_info.yaml / ops.yaml||

Copilot · 2026-04-27T17:20:29Z

+1. 接收待对齐的 Pytorch API 列表：$ARGUMENTS
+2. 为对应的 Paddle API 决策改动方案
+3. 执行具体的 Paddle API 修改
+4. 验证修改后的 Paddle API 是否对齐 Pytorch
+5. 更新修改后的 Paddle API 中文文档
+6. 给出 Pytorch API 列表的对齐结果统计


专有名词大小写不一致：文档中多处使用了 Pytorch，建议统一为官方写法 PyTorch（同一文件内已同时出现 PyTorch/Pytorch 时更容易造成检索与引用混乱）。

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

sunzhongkai588

LGTM

Copilot AI review requested due to automatic review settings April 27, 2026 17:09

Copilot started reviewing on behalf of zhwesky2010 April 27, 2026 17:10 View session

zhwesky2010 changed the title ~~add claude agent skills for API Compatibility~~ [Code Agent] add claude agent skills for API Compatibility Apr 27, 2026

zhwesky2010 force-pushed the claude branch 2 times, most recently from 7e492b2 to b3d561c Compare April 27, 2026 17:15

zhwesky2010 changed the title ~~[Code Agent] add claude agent skills for API Compatibility~~ [Code Agent] add claude skills for API Compatibility Apr 27, 2026

Copilot AI reviewed Apr 27, 2026

View reviewed changes

zhwesky2010 force-pushed the claude branch 2 times, most recently from 9cd1814 to aed0e96 Compare April 27, 2026 17:27

add claude agent skills for API Compatibility

943dda6

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

zhwesky2010 force-pushed the claude branch from aed0e96 to 943dda6 Compare April 27, 2026 17:30

sunzhongkai588 approved these changes Apr 30, 2026

View reviewed changes

sunzhongkai588 merged commit 49f5a0c into PaddlePaddle:develop Apr 30, 2026
5 checks passed

zhwesky2010 changed the title ~~[Code Agent] add claude skills for API Compatibility~~ [Coding Agent] add claude skills for API Compatibility Apr 30, 2026

+/api-change-decider torch.atan  # 先确定方案
+# 若 Step1 判定为“方案 2：C++下沉”，则执行：
+/cpp-sink torch.atan
+# 若 Step1 判定为“方案 1：Python 装饰器”，则执行：
+/python-decorator torch.atan

	allowed-tools: Read Grep‌ Glob‌ Write‌ Edit Bash(python *)
	allowed-tools: Read Grep Glob Write Edit Bash(python *)

		3. 输出结果序号需要保持连贯，每一个输出结果均需要检验，尽可能循环检验减少行数。
		3. 比对测试项，对于内容相同的测试项，不要重复添加。

	\|C++下沉使用\|`python_api_info.yaml`、`ops.yaml`\|Paddle/paddle/phi/ops/yaml/\|python_api_info.yamlops.yaml\|\|
	\|C++下沉使用\|`python_api_info.yaml`、`ops.yaml`\|Paddle/paddle/phi/ops/yaml/\|python_api_info.yaml / ops.yaml\|\|

Conversation

zhwesky2010 commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

《Paddle API 对齐 PyTorch 项目》完整 SKILL 体系

两种使用方式

方式一：一步到位（推荐）

方式二：分步操作

工作流程

使用示例

Uh oh!

paddle-bot Bot commented Apr 27, 2026

Uh oh!

github-actions Bot commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

sunzhongkai588 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

zhwesky2010 commented Apr 27, 2026 •

edited

Loading

github-actions Bot commented Apr 27, 2026 •

edited

Loading