@fitlab-ai/agent-infra 0.5.4 → 0.5.6

package/README.md

@@ -341,6 +341,92 @@ agent-infra ships with **a rich set of built-in AI skills**. They are organized
 
 > Every skill works across supported AI TUIs. The command prefix changes, but the workflow semantics stay the same.
 
+<a id="custom-skills"></a>
+
+## Custom Skills
+
+Built-in skills cover the standard delivery lifecycle, but teams often need project-specific instructions such as coding standards, deployment checks, or internal review rules. agent-infra supports that through **custom skills**.
+
+### Create a custom skill in the project
+
+Create a directory under `.agents/skills/<name>/` and add a `SKILL.md` file:
+
+```text
+.agents/skills/
+  enforce-style/
+    SKILL.md
+    reference/
+      style-guide.md
+```
+
+Minimum frontmatter:
+
+```yaml
+---
+name: enforce-style
+description: "Apply team style checks before submitting code"
+args: "<task-id>"   # optional
+---
+```
+
+- `name`: user-facing skill name
+- `description`: used when generating editor command metadata
+- `args`: optional argument hint; agent-infra uses it when generating slash commands for supported AI TUIs
+
+After adding the skill, run `update-agent-infra` again:
+
+| TUI | Command |
+|-----|---------|
+| Claude Code | `/update-agent-infra` |
+| Codex | `$update-agent-infra` |
+| Gemini CLI | `/{{project}}:update-agent-infra` |
+| OpenCode | `/update-agent-infra` |
+
+That refresh detects non-built-in skill directories in `.agents/skills/` and generates matching commands for Claude Code, Gemini CLI, and OpenCode automatically.
+
+### Sync custom skills from shared sources
+
+If you maintain reusable team skills outside the repository, declare them in `.agents/.airc.json`:
+
+```json
+{
+  "skills": {
+    "sources": [
+      { "type": "local", "path": "~/company-skills" },
+      { "type": "local", "path": "~/team-skills" }
+    ]
+  }
+}
+```
+
+Expected source layout:
+
+```text
+~/company-skills/
+  enforce-style/
+    SKILL.md
+  release-check/
+    SKILL.md
+    reference/
+      checklist.md
+```
+
+Behavior:
+
+- Sources are applied in list order; later sources overwrite earlier custom sources when they define the same file
+- `type: "local"` is the only supported source type today; the structure leaves room for future source types
+- `~` in source paths is expanded to the current user's home directory
+
+### Sync behavior and conflict rules
+
+When `update-agent-infra` runs:
+
+- Manually created custom skills in `.agents/skills/` are protected from managed-file cleanup
+- Files synced from external custom sources are copied into `.agents/skills/`
+- For synced skills that still exist in a configured source, files removed from the source are also removed locally during the next sync
+- Built-in skills always win over custom sources; if a source defines a skill with the same name as a built-in skill, agent-infra skips that custom source skill instead of overriding the built-in one
+- If you truly need to replace a built-in skill or command, use the existing `ejected` mechanism and own that file in the project
+
 <a id="prebuilt-workflows"></a>
 
 ## Prebuilt Workflows
@@ -410,7 +496,12 @@ The generated `.agents/.airc.json` file is the central contract between the boot
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateVersion": "v0.5.4",
+  "templateVersion": "v0.5.6",
+  "skills": {
+    "sources": [
+      { "type": "local", "path": "~/company-skills" }
+    ]
+  },
   "files": {
     "managed": [
       ".agents/workspace/README.md",
@@ -439,6 +530,8 @@ The generated `.agents/.airc.json` file is the central contract between the boot
 | `org` | GitHub organization or owner used by generated metadata and links. |
 | `language` | Primary project language or locale used by rendered templates. |
 | `templateVersion` | Installed template version for future upgrades and drift tracking. |
+| `skills` | Optional custom skill sync configuration. |
+| `skills.sources` | Optional ordered list of external custom skill sources. Only `type: "local"` is supported today. |
 | `files` | Per-path update strategy configuration for managed, merged, and ejected files. |
 
 <a id="file-management-strategies"></a>

package/README.zh-CN.md

@@ -341,6 +341,92 @@ agent-infra 提供 **丰富的内置 AI skills**。它们按使用场景分组
 
 > 所有 skills 都可跨支持的 AI TUI 复用。变化的只是命令前缀，工作流语义保持一致。
 
+<a id="custom-skills"></a>
+
+## 自定义 Skills
+
+内置 skills 覆盖了标准交付生命周期，但很多团队还需要项目特有的指令，例如编码规范、发布检查或内部审查规则。agent-infra 通过**自定义 skill**支持这些场景。
+
+### 在项目中创建自定义 skill
+
+在 `.agents/skills/<name>/` 下创建目录，并添加 `SKILL.md`：
+
+```text
+.agents/skills/
+  enforce-style/
+    SKILL.md
+    reference/
+      style-guide.md
+```
+
+最小 frontmatter 示例：
+
+```yaml
+---
+name: enforce-style
+description: "在提交代码前执行团队风格检查"
+args: "<task-id>"   # 可选
+---
+```
+
+- `name`：对用户可见的 skill 名称
+- `description`：用于生成编辑器命令元数据
+- `args`：可选参数提示；agent-infra 会在生成支持的 AI TUI 命令时使用它
+
+添加 skill 后，再执行一次 `update-agent-infra`：
+
+| TUI | 命令 |
+|-----|------|
+| Claude Code | `/update-agent-infra` |
+| Codex | `$update-agent-infra` |
+| Gemini CLI | `/{{project}}:update-agent-infra` |
+| OpenCode | `/update-agent-infra` |
+
+同步时会自动检测 `.agents/skills/` 下的非内置 skill 目录，并为 Claude Code、Gemini CLI、OpenCode 生成对应命令。
+
+### 从共享源同步自定义 skills
+
+如果团队在仓库外统一维护可复用 skill，可以在 `.agents/.airc.json` 中声明：
+
+```json
+{
+  "skills": {
+    "sources": [
+      { "type": "local", "path": "~/company-skills" },
+      { "type": "local", "path": "~/team-skills" }
+    ]
+  }
+}
+```
+
+源目录结构示例：
+
+```text
+~/company-skills/
+  enforce-style/
+    SKILL.md
+  release-check/
+    SKILL.md
+    reference/
+      checklist.md
+```
+
+行为说明：
+
+- 多个 source 按数组顺序应用；后面的 source 如果定义了同名文件，会覆盖前面的自定义 source 文件
+- 当前只支持 `type: "local"`；配置结构已为未来扩展其他来源类型预留
+- source 路径中的 `~` 会自动展开为当前用户的 home 目录
+
+### 同步行为与冲突规则
+
+执行 `update-agent-infra` 时：
+
+- 手动放在 `.agents/skills/` 下的自定义 skill 不会被 managed 文件清理删除
+- 外部 source 中的 skill 会同步复制到 `.agents/skills/`
+- 对于仍存在于配置 source 中的 skill，如果源里删掉某个文件，下次同步时本地对应残留文件也会被删除
+- 内置 skill 始终优先于自定义 source；如果 source 里出现与内置 skill 同名的目录，agent-infra 会跳过该 source skill，而不是覆盖内置实现
+- 如果你确实需要替换内置 skill 或命令，请使用现有的 `ejected` 机制，让项目自己接管该文件
+
 <a id="prebuilt-workflows"></a>
 
 ## 预置工作流
@@ -410,7 +496,12 @@ import-issue #42                    从 GitHub Issue 导入任务
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateVersion": "v0.5.4",
+  "templateVersion": "v0.5.6",
+  "skills": {
+    "sources": [
+      { "type": "local", "path": "~/company-skills" }
+    ]
+  },
   "files": {
     "managed": [
       ".agents/workspace/README.md",
@@ -439,6 +530,8 @@ import-issue #42                    从 GitHub Issue 导入任务
 | `org` | 生成元数据和链接时使用的 GitHub 组织或拥有者。 |
 | `language` | 渲染模板时采用的项目主语言或区域设置。 |
 | `templateVersion` | 当前安装的模板版本，用于升级和差异追踪。 |
+| `skills` | 可选的自定义 skill 同步配置。 |
+| `skills.sources` | 可选的外部自定义 skill 源列表，按顺序应用。当前仅支持 `type: "local"`。 |
 | `files` | 针对具体路径配置 `managed`、`merged`、`ejected` 三类更新策略。 |
 
 <a id="file-management-strategies"></a>

package/lib/defaults.json

@@ -36,6 +36,7 @@
       ".claude/hooks/",
       ".gemini/commands/",
       ".github/hooks/check-version-format.sh",
+      ".github/scripts/",
       ".opencode/commands/"
     ],
     "merged": [

package/lib/sandbox/commands/create.js

@@ -63,6 +63,10 @@ function buildSignature(preparedDockerfile, tools) {
     .slice(0, 12);
 }
 
+function hostJoin(basePath, ...segments) {
+  return basePath.startsWith('/') ? path.posix.join(basePath, ...segments) : path.join(basePath, ...segments);
+}
+
 function resolveToolDirs(config, tools, branch) {
   return tools.map((tool) => {
     const candidates = toolConfigDirCandidates(tool, config.project, branch);
@@ -266,7 +270,7 @@ export function prepareHostShellConfig({ home, project, branch, repoRoot }) {
 }
 
 function gpgCacheDir(home, project) {
-  return path.join(home, '.agent-infra', 'gpg-cache', project);
+  return hostJoin(home, '.agent-infra', 'gpg-cache', project);
 }
 
 function normalizeSigningKey(signingKey) {
@@ -649,11 +653,11 @@ export function extractClaudeCredentialsBlob(home, execFn = execFileSync) {
 }
 
 export function claudeCredentialsDir(home, project) {
-  return path.join(home, '.agent-infra', 'credentials', project, 'claude-code');
+  return hostJoin(home, '.agent-infra', 'credentials', project, 'claude-code');
 }
 
 export function claudeCredentialsPath(home, project) {
-  return path.join(claudeCredentialsDir(home, project), '.credentials.json');
+  return hostJoin(claudeCredentialsDir(home, project), '.credentials.json');
 }
 
 export function writeClaudeCredentialsFile(home, project, blob) {

package/lib/sandbox/shell.js

@@ -1,4 +1,6 @@
 import { execFileSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
 
 const DEFAULT_TIMEOUT_MS = 60 * 60 * 1000;
 
@@ -11,25 +13,62 @@ function normalizeOptions(opts = {}, stdio) {
   };
 }
 
+function resolveCommand(cmd) {
+  if (process.platform !== 'win32' || path.extname(cmd)) {
+    return cmd;
+  }
+
+  const pathValue = process.env.Path || process.env.PATH || '';
+  const extensions = (process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD')
+    .split(';')
+    .filter(Boolean);
+
+  for (const dir of pathValue.split(path.delimiter).filter(Boolean)) {
+    for (const extension of extensions) {
+      const candidate = path.join(dir, `${cmd}${extension.toLowerCase()}`);
+      if (fs.existsSync(candidate)) {
+        return candidate;
+      }
+      const upperCandidate = path.join(dir, `${cmd}${extension.toUpperCase()}`);
+      if (fs.existsSync(upperCandidate)) {
+        return upperCandidate;
+      }
+    }
+  }
+
+  return cmd;
+}
+
+function commandOptions(cmd, opts) {
+  if (process.platform === 'win32' && /\.(?:bat|cmd)$/i.test(cmd)) {
+    return { ...opts, shell: true };
+  }
+  return opts;
+}
+
 export function run(cmd, args, opts = {}) {
-  return execFileSync(cmd, args, {
+  const resolved = resolveCommand(cmd);
+  return execFileSync(resolved, args, commandOptions(resolved, {
     ...normalizeOptions(opts, ['pipe', 'pipe', 'pipe']),
     encoding: 'utf8'
-  }).trim();
+  })).trim();
 }
 
 export function runOk(cmd, args, opts = {}) {
-  const result = spawnSync(cmd, args, normalizeOptions(opts, 'pipe'));
+  const resolved = resolveCommand(cmd);
+  const result = spawnSync(resolved, args, commandOptions(resolved, normalizeOptions(opts, 'pipe')));
   return result.status === 0;
 }
 
 export function runInteractive(cmd, args, opts = {}) {
-  const result = spawnSync(cmd, args, normalizeOptions(opts, 'inherit'));
+  const resolved = resolveCommand(cmd);
+  const result = spawnSync(resolved, args, commandOptions(resolved, normalizeOptions(opts, 'inherit')));
   return result.status ?? 1;
 }
 
 export function runVerbose(cmd, args, opts = {}) {
-  const result = spawnSync(cmd, args, normalizeOptions(opts, 'inherit'));
+  const resolved = resolveCommand(cmd);
+  const result = spawnSync(resolved, args, commandOptions(resolved, normalizeOptions(opts, 'inherit')));
 
   if (result.status !== 0) {
     if (result.signal === 'SIGTERM') {
@@ -40,9 +79,10 @@ export function runVerbose(cmd, args, opts = {}) {
 }
 
 export function runSafe(cmd, args, opts = {}) {
-  const result = spawnSync(cmd, args, {
+  const resolved = resolveCommand(cmd);
+  const result = spawnSync(resolved, args, commandOptions(resolved, {
     ...normalizeOptions(opts, ['pipe', 'pipe', 'pipe']),
     encoding: 'utf8',
-  });
+  }));
   return (result.stdout ?? '').trim();
 }

package/lib/sandbox/tools.js

@@ -18,6 +18,10 @@ import { safeNameCandidates, sanitizeBranchName } from './constants.js';
  * @property {string[]=} postSetupCmds
  */
 
+function hostJoin(basePath, ...segments) {
+  return basePath.startsWith('/') ? path.posix.join(basePath, ...segments) : path.join(basePath, ...segments);
+}
+
 function createBuiltinTools(home, project) {
   /** @type {Record<string, SandboxTool>} */
   return {
@@ -25,7 +29,7 @@ function createBuiltinTools(home, project) {
       id: 'claude-code',
       name: 'Claude Code',
       npmPackage: '@anthropic-ai/claude-code',
-      sandboxBase: path.join(home, '.agent-infra', 'sandboxes', 'claude-code'),
+      sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'claude-code'),
       containerMount: '/home/devuser/.claude',
       versionCmd: 'claude --version',
       setupHint: 'Authenticates via host credentials live-mounted at ~/.claude/.credentials.json',
@@ -38,7 +42,7 @@ function createBuiltinTools(home, project) {
       // letting ensureClaudeOnboarding actually take effect.
       envVars: { CLAUDE_CONFIG_DIR: '/home/devuser/.claude' },
       hostPreSeedDirs: [
-        { hostDir: path.join(home, '.claude', 'plugins'), sandboxSubdir: 'plugins' }
+        { hostDir: hostJoin(home, '.claude', 'plugins'), sandboxSubdir: 'plugins' }
       ],
       pathRewriteFiles: [
         'plugins/installed_plugins.json',
@@ -46,7 +50,7 @@ function createBuiltinTools(home, project) {
       ],
       hostLiveMounts: [
         {
-          hostPath: path.join(home, '.agent-infra', 'credentials', project, 'claude-code', '.credentials.json'),
+          hostPath: hostJoin(home, '.agent-infra', 'credentials', project, 'claude-code', '.credentials.json'),
           containerSubpath: '.credentials.json'
         }
       ]
@@ -55,12 +59,12 @@ function createBuiltinTools(home, project) {
       id: 'codex',
       name: 'Codex',
       npmPackage: '@openai/codex',
-      sandboxBase: path.join(home, '.agent-infra', 'sandboxes', 'codex'),
+      sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'codex'),
       containerMount: '/home/devuser/.codex',
       versionCmd: 'codex --version',
       setupHint: 'Run codex once inside the container and choose Device Code login if needed.',
       hostLiveMounts: [
-        { hostPath: path.join(home, '.codex', 'auth.json'), containerSubpath: 'auth.json' }
+        { hostPath: hostJoin(home, '.codex', 'auth.json'), containerSubpath: 'auth.json' }
       ],
       postSetupCmds: [
         'test -d /workspace/.codex/commands && ln -sfn /workspace/.codex/commands /home/devuser/.codex/prompts || true'
@@ -70,13 +74,13 @@ function createBuiltinTools(home, project) {
       id: 'opencode',
       name: 'OpenCode',
       npmPackage: 'opencode-ai',
-      sandboxBase: path.join(home, '.agent-infra', 'sandboxes', 'opencode'),
+      sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'opencode'),
       containerMount: '/home/devuser/.local/share/opencode',
       versionCmd: 'opencode version',
       setupHint: 'Configure OpenCode credentials inside the container before first use.',
       hostLiveMounts: [
         {
-          hostPath: path.join(home, '.local', 'share', 'opencode', 'auth.json'),
+          hostPath: hostJoin(home, '.local', 'share', 'opencode', 'auth.json'),
           containerSubpath: 'auth.json'
         }
       ]
@@ -85,16 +89,16 @@ function createBuiltinTools(home, project) {
       id: 'gemini-cli',
       name: 'Gemini CLI',
       npmPackage: '@google/gemini-cli',
-      sandboxBase: path.join(home, '.agent-infra', 'sandboxes', 'gemini-cli'),
+      sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'gemini-cli'),
       containerMount: '/home/devuser/.gemini',
       versionCmd: 'gemini --version',
       setupHint: 'Run gemini inside the container to finish authentication.',
       hostLiveMounts: [
-        { hostPath: path.join(home, '.gemini', 'oauth_creds.json'), containerSubpath: 'oauth_creds.json' }
+        { hostPath: hostJoin(home, '.gemini', 'oauth_creds.json'), containerSubpath: 'oauth_creds.json' }
       ],
       hostPreSeedFiles: [
-        { hostPath: path.join(home, '.gemini', 'settings.json'), sandboxName: 'settings.json' },
-        { hostPath: path.join(home, '.gemini', 'google_accounts.json'), sandboxName: 'google_accounts.json' }
+        { hostPath: hostJoin(home, '.gemini', 'settings.json'), sandboxName: 'settings.json' },
+        { hostPath: hostJoin(home, '.gemini', 'google_accounts.json'), sandboxName: 'google_accounts.json' }
       ]
     }
   };
@@ -119,15 +123,15 @@ export function resolveTools(config) {
 }
 
 export function toolConfigDir(tool, project, branch) {
-  return path.join(tool.sandboxBase, project, sanitizeBranchName(branch));
+  return hostJoin(tool.sandboxBase, project, sanitizeBranchName(branch));
 }
 
 export function toolConfigDirCandidates(tool, project, branch) {
-  return safeNameCandidates(branch).map((name) => path.join(tool.sandboxBase, project, name));
+  return safeNameCandidates(branch).map((name) => hostJoin(tool.sandboxBase, project, name));
 }
 
 export function toolProjectDirCandidates(tool, project) {
-  return [path.join(tool.sandboxBase, project)];
+  return [hostJoin(tool.sandboxBase, project)];
 }
 
 export function toolNpmPackagesArg(tools) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",

package/templates/.agents/README.en.md

@@ -120,6 +120,58 @@ To adapt agent-infra to a private code-hosting platform:
 4. If you maintain a fork of the template source, add matching `.{platform}.` template variants before adding that platform identifier to the sync logic.
 5. Validate the customized workflow on a test task before rolling it out broadly.
 
+## Custom Skills
+
+Projects can add their own skills alongside the built-in task workflow.
+
+### Local project skills
+
+Create a directory under `.agents/skills/<name>/` and add a `SKILL.md` file:
+
+```text
+.agents/skills/
+  enforce-style/
+    SKILL.md
+    reference/
+      style-guide.md
+```
+
+Recommended frontmatter:
+
+```yaml
+---
+name: enforce-style
+description: "Apply the team style guide before code review"
+args: "<task-id>"   # optional
+---
+```
+
+After adding or updating a custom skill, run `update-agent-infra` again. The sync step detects non-built-in skills and generates matching commands for Claude Code, Gemini CLI, and OpenCode automatically.
+
+### Shared skill sources
+
+To reuse centralized team skills, configure `.agents/.airc.json`:
+
+```json
+{
+  "skills": {
+    "sources": [
+      { "type": "local", "path": "~/company-skills" }
+    ]
+  }
+}
+```
+
+Each source should mirror the `.agents/skills/` layout and include `SKILL.md` at the root of every skill directory.
+
+### Sync behavior
+
+- Custom project skills in `.agents/skills/` are protected from managed-file cleanup
+- Source entries are applied in order; later custom sources overwrite earlier custom sources
+- Files deleted from an existing configured source are removed locally on the next sync for that sourced skill
+- Built-in skills are not overridable by custom sources; if a source skill name conflicts with a built-in skill, the source copy is skipped
+- Use `files.ejected` if the project must take ownership of a built-in skill or command
+
 ## Skill Authoring Conventions
 
 When writing or updating `.agents/skills/*/SKILL.md` files and their templates, keep step numbering consistent:

package/templates/.agents/README.zh-CN.md

@@ -120,6 +120,58 @@
 4. 如果你维护的是模板源码分支或私有 fork，需要先补齐对应的 `.{platform}.` 模板变体，再把该平台标识加入模板同步逻辑。
 5. 在正式推广前，先用一个测试任务完整验证工作流和 gate 校验。
 
+## 自定义 Skills
+
+项目可以在内置任务工作流之外增加自己的 skill。
+
+### 项目内本地 skill
+
+在 `.agents/skills/<name>/` 下创建目录，并添加 `SKILL.md`：
+
+```text
+.agents/skills/
+  enforce-style/
+    SKILL.md
+    reference/
+      style-guide.md
+```
+
+推荐 frontmatter：
+
+```yaml
+---
+name: enforce-style
+description: "在代码审查前应用团队风格规范"
+args: "<task-id>"   # 可选
+---
+```
+
+新增或修改自定义 skill 后，再执行一次 `update-agent-infra`。同步过程会自动检测非内置 skill，并为 Claude Code、Gemini CLI、OpenCode 生成对应命令。
+
+### 共享 skill 源
+
+如需复用团队集中维护的 skill，可在 `.agents/.airc.json` 中配置：
+
+```json
+{
+  "skills": {
+    "sources": [
+      { "type": "local", "path": "~/company-skills" }
+    ]
+  }
+}
+```
+
+每个 source 都应镜像 `.agents/skills/` 的目录结构，并在每个 skill 目录根部提供 `SKILL.md`。
+
+### 同步行为
+
+- `.agents/skills/` 中手动创建的项目自定义 skill 不会被 managed 文件清理删除
+- 多个 source 按声明顺序应用；后面的自定义 source 会覆盖前面的自定义 source 文件
+- 对于仍存在于配置 source 中的 skill，如果源里删掉文件，下次同步时会删除本地对应残留文件
+- 自定义 source 不能覆盖内置 skill；如果与内置 skill 同名，会跳过该 source skill
+- 如果项目必须接管某个内置 skill 或命令，请使用 `files.ejected`
+
 ## Skill 编写规范
 
 编写或维护 `.agents/skills/*/SKILL.md` 及其模板时，步骤编号遵循以下规则：

package/templates/.agents/rules/issue-pr-commands.github.en.md

@@ -99,12 +99,21 @@ gh pr list --state {state} --base {base-branch} --json number,title,url,headRefN
 Create a PR:
 
 ```bash
-gh pr create --base "{target-branch}" --title "{title}" --assignee @me --body "$(cat <<'EOF'
+gh pr create --base "{target-branch}" --title "{title}" --assignee @me \
+  {label-args} {milestone-arg} \
+  --body "$(cat <<'EOF'
 {pr-body}
 EOF
 )"
 ```
 
+- expand `{label-args}` into repeated `--label "{label}"` flags from the validated label list
+- pass `{label-args}` only when `has_triage=true`; otherwise omit it and continue
+- omit all `--label` flags when nothing valid remains
+- expand `{milestone-arg}` into `--milestone "{milestone}"`
+- pass `{milestone-arg}` only when `has_triage=true`; otherwise omit it and continue
+- omit `{milestone-arg}` entirely when no milestone should be set
+
 ## Update PRs
 
 Update PR titles, labels, or milestones with:

package/templates/.agents/rules/issue-pr-commands.github.zh-CN.md

@@ -99,12 +99,21 @@ gh pr list --state {state} --base {base-branch} --json number,title,url,headRefN
 创建 PR：
 
 ```bash
-gh pr create --base "{target-branch}" --title "{title}" --assignee @me --body "$(cat <<'EOF'
+gh pr create --base "{target-branch}" --title "{title}" --assignee @me \
+  {label-args} {milestone-arg} \
+  --body "$(cat <<'EOF'
 {pr-body}
 EOF
 )"
 ```
 
+- `{label-args}` 由调用方按有效 label 列表展开为多个 `--label "{label}"`
+- 仅当 `has_triage=true` 时传入 `{label-args}`；否则整体省略并继续
+- 没有有效 label 时省略全部 `--label`
+- `{milestone-arg}` 展开为 `--milestone "{milestone}"`
+- 仅当 `has_triage=true` 时传入 `{milestone-arg}`；否则整体省略并继续
+- `{milestone-arg}` 为空时整体省略
+
 ## PR 更新
 
 更新 PR 标题、label 或 milestone：