Remotion 的 Issue 协作规范用 SKILL.md 规范 AI Agent 创建 GitHub Issue 的标题命名与多行 Markdown 处理【免费下载链接】remotion Make videos programmatically with React项目地址: https://gitcode.com/GitHub_Trending/re/remotionRemotion 在.agents/skills/目录下维护了一套供 AI Agent 使用的技能Skill文档其中 issue 技能 专门规定了如何以正确的命名格式创建和更新 GitHub Issue以及如何在ghCLI 中安全地处理多行 Markdown 正文。本文基于该技能文档逐节展开先讲清 Issue 标题的命名约定再讲绝不内联传递多行 Markdown这一核心原则及其在创建、编辑、评论 Issue 三种场景下的完整操作命令最后给出操作后的验证清单帮助你在类似的大型 monorepo 中建立可复制的 Issue 协作流程。技能文档在 Remotion 仓库中的定位Remotion 把内部协作流程沉淀为一个个SKILL.md文件放置在.agents/skills/目录下每个技能对应一个子目录。按 skill-locations 技能 的约定仅供内部 Agent 使用的技能放在.agents/skills/skill-name/SKILL.md而可对外分发的公开技能放在packages/skills/skills/下。issue 技能 属于典型的内部技能其 frontmatter 声明了适用场景name: issue description: Create or update GitHub issues with correct Remotion naming and safe multiline Markdown handling即使用正确的 Remotion 命名规范创建或更新 GitHub Issue并安全地处理多行 Markdown。文档同时划定了与姊妹技能 issue-management 的边界涉及父 Issue、子 Issue、blocked-by、blocking 等 GitHub Issues 2.0 关系操作时应转用issue-management技能而不是在本技能内处理。这种按职责拆分技能的做法让每个SKILL.md都保持短小、可被 Agent 一次性读入执行。Issue 标题格式规范技能文档要求标题简洁、行动导向concise, action-oriented并按 Issue 影响面选择前缀包级 Issue以包名为前缀当 Issue 主要影响某个包时标题以包名开头格式为remotion/package: 变更描述文档给出的三个示例分别是remotion/player: Support keyboard shortcuts for fullscreen remotion/lambda: Improve retry message for failed renders remotion/docs: Add examples contribution guide这些前缀对应仓库中真实存在的包packages/player 的 npm 包名是remotion/playerpackages/lambda 是remotion/lambda两者可在各自的package.json中确认。值得注意的是第三个示例remotion/docs——packages/docs 的package.json中包名实际是docs它并不是以remotion/作用域发布的 npm 包。这说明标题前缀约定的是读者能一眼识别的包标识而不强制与 npm 包名逐字一致写标题时以该包在仓库社区中的通用称呼为准即可。平台级 Issue使用固定前缀当 Issue 影响面超出单个包时按影响范围使用不同的固定前缀影响范围标题前缀网站 / 文档整体Docs: 变更描述Studio 整体Studio: 变更描述Monorepo 构建Build: 变更描述CI 流水线CI: 变更描述仓库级基础设施Repo: 变更描述这些前缀与 Remotion 仓库的实际结构对应得上Studio:对应 packages/studioDocs:对应 packages/docsDocusaurus 站点Build:/CI:对应根目录的 turbo.json、bunfig.toml 等 monorepo 基础设施。必须避免的模糊标题文档明确列出了反例Bug Fix issue Examples follow-up并给出对应的好标题示例Docs: Add a skill for creating examples核心逻辑是标题本身应包含领域前缀 动词 对象让只看标题不打开正文的人也能判断该 Issue 属于哪个模块、要做哪件事。核心原则绝不通过 shell 参数内联多行 Markdown这是整个技能文档中最关键的一条工程约束不要把 Issue 正文、PR 正文或长评论以字符串形式直接内联在 shell 命令参数里传递。为什么内联会出问题文档给出的错误示例gh issue create --title Docs: Add examples skill --body Line one\n\nLine two问题在于在gh这类工具中--body参数里的\n是字面转义序列而不是真正的换行符。命令执行后GitHub 上收到的正文会包含字面的反斜杠加n字符渲染出来的是一条挤在一起的长文本而不是预期的分段 Markdown。这类错误在 Agent 自动化场景下尤其常见——模型生成的字符串里普遍带\n一旦直接拼进命令行污染就不可见地进入了 Issue 正文。正确做法写入临时文件用 --body-file 传递文档要求始终把 Markdown 写入临时文件再用--body-file传入。临时文件建议放在/tmp/remotion-issue-body.mdRemotion 的命名习惯正文示例cat /tmp/remotion-issue-body.md EOF Summary of the issue. ## Tasks - [ ] First task - [ ] Second task ## Context Related to #1234. EOF注意 heredoc 使用了带引号的定界符EOF这会禁止 shell 对文件内容做任何变量展开或转义解析保证 Markdown 原样落盘。然后创建 Issuegh issue create \ --title Docs: Add a skill for creating examples \ --body-file /tmp/remotion-issue-body.md文档还补充了一条 Agent 专属建议当以 AI Agent 身份操作时优先使用 Agent 的文件写入工具write tool创建临时 Markdown 文件而不是在 shell 里拼 heredoc因为前者不经过 shell 转义层更不容易引入二次转义问题。同一原则在仓库其他技能中也被反复引用可见它是跨技能共享的约定pr 技能、flake 技能、update-remotion-rust-ffmpeg 技能 和 issue-management 技能 都出现了--body-file的用法其中 issue-management 在其安全工作流第 1 步再次强调用--body-file创建新 Issue 正文而不是内联多行 shell 字符串。编辑 Issue 正文编辑已有 Issue 遵循同样的两步流程把完整的替换正文不是补丁、不是增量写入临时 Markdown 文件用--body-file提交修改gh issue edit 1234 --body-file /tmp/remotion-issue-body.mdgh issue edit的--body-file语义是整体替换正文所以第 1 步必须先取回或重新整理出完整版本。编辑完成后必须做渲染验证gh issue view 1234 --json body --jq .body检查要点在文档中写得很具体输出中必须包含真正的空行而不是字面的\n转义序列。如果--jq .body打印出的内容里出现\n字符对就说明第 1 步写入的临时文件本身就是坏的多半是 heredoc 未加引号定界符或字符串被二次转义需要重新生成文件再编辑一次。添加 Issue 评论多行评论同样走文件通道只是命令换成了gh issue commentgh issue comment 1234 --body-file /tmp/remotion-issue-comment.md这里可以留意文档的细节示例中评论临时文件命名为/tmp/remotion-issue-comment.md与正文文件/tmp/remotion-issue-body.md区分开避免一次会话中连续操作时正文与评论文件互相覆盖。关联 Issue 的处理边界与引用格式issue 技能 自身不做 Issue 关系管理但给出两条协作规则关系操作交给issue-management技能。涉及 parent / sub-issue / blocked-by / blocking 时参照 issue-management 技能 执行优先使用gh issue create/gh issue edit的关系标志位如--parent、--blocked-by、--blocking而不是手写 GraphQL mutation。issue-management文档说明这些标志位来自 GitHub CLI 新增的 Issues 2.0 支持并在操作前要求先用gh issue create --help | grep -E -- --parent|--blocked-by|--blocking验证本地gh版本是否已支持防止对旧版 CLI 臆造命令。把模糊的 checklist 项替换为具体 Issue 编号文档还规定了关联 Issue 之后的正文更新策略如果一个 PR 或 Issue 提到后续工作且该工作已经被一个关联 Issue 跟踪就应当把模糊的 checkbox 项替换为具体编号。推荐写法The Remotion skill for creating examples is tracked separately in sub-issue #8158, not in this PR.避免写法- [ ] Add a Remotion skill for creating an example前提是该项工作并不属于当前 PR 的交付范围。这样做的收益是PR 的 checklist 始终只反映本 PR 内的完成度跨 PR 的工作通过#编号在 GitHub 侧形成可追踪的链接避免两个地方各维护一份会漂移的待办列表。操作完成后的验证清单技能文档末尾附有一份最终验证清单要求创建或编辑 Issue 后逐项确认用gh issue view number --json body --jq .body查看 Issue 正文确认 Markdown 中是真正的换行而非字面\n确认标题符合 包名 / Docs / Studio / Build / CI / Repo 的命名约定确认#1234这类 Issue 引用指向了正确的编号若添加了 Issue 关系按issue-management技能确认链接符合预期。这份清单把前文的三个核心约束命名规范、文件通道传递正文、关系操作边界收敛为一次可执行的检查流程适合作为 Agent 每次操作 Issue 后的收尾步骤。小结这套规范可迁移的关键点从 issue 技能 的完整内容可以提炼出三条对其他 monorepo 团队同样成立的实践标题即路由用包名:/Docs:/Studio:/Build:前缀让 Issue 在列表里自分类模糊标题Bug、Fix issue被显式列为反例多行内容永远走--body-filegh issue create、gh issue edit、gh issue comment三个入口统一使用临时文件规避 shell 参数中\n变成字面字符的经典坑并且编辑后要回读验证换行真实存在技能按职责拆分并交叉引用本技能只负责命名 正文安全Issue 2.0 关系管理交由 issue-management且要求先用--help探测 CLI 能力再执行从文档层面杜绝 Agent 对旧版工具臆造命令。配合根目录 AGENTS.md 中对开发环境的总体约定这套.agents/skills/技能文档构成了 Remotion 仓库人机协作尤其是 AI Agent 自动化的流程基线。【免费下载链接】remotion Make videos programmatically with React项目地址: https://gitcode.com/GitHub_Trending/re/remotion创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Remotion 的 Issue 协作规范：用 SKILL.md 规范 AI Agent 创建 GitHub Issue 的标题命名与多行 Markdown 处理
Remotion 的 Issue 协作规范用 SKILL.md 规范 AI Agent 创建 GitHub Issue 的标题命名与多行 Markdown 处理【免费下载链接】remotion Make videos programmatically with React项目地址: https://gitcode.com/GitHub_Trending/re/remotionRemotion 在.agents/skills/目录下维护了一套供 AI Agent 使用的技能Skill文档其中 issue 技能 专门规定了如何以正确的命名格式创建和更新 GitHub Issue以及如何在ghCLI 中安全地处理多行 Markdown 正文。本文基于该技能文档逐节展开先讲清 Issue 标题的命名约定再讲绝不内联传递多行 Markdown这一核心原则及其在创建、编辑、评论 Issue 三种场景下的完整操作命令最后给出操作后的验证清单帮助你在类似的大型 monorepo 中建立可复制的 Issue 协作流程。技能文档在 Remotion 仓库中的定位Remotion 把内部协作流程沉淀为一个个SKILL.md文件放置在.agents/skills/目录下每个技能对应一个子目录。按 skill-locations 技能 的约定仅供内部 Agent 使用的技能放在.agents/skills/skill-name/SKILL.md而可对外分发的公开技能放在packages/skills/skills/下。issue 技能 属于典型的内部技能其 frontmatter 声明了适用场景name: issue description: Create or update GitHub issues with correct Remotion naming and safe multiline Markdown handling即使用正确的 Remotion 命名规范创建或更新 GitHub Issue并安全地处理多行 Markdown。文档同时划定了与姊妹技能 issue-management 的边界涉及父 Issue、子 Issue、blocked-by、blocking 等 GitHub Issues 2.0 关系操作时应转用issue-management技能而不是在本技能内处理。这种按职责拆分技能的做法让每个SKILL.md都保持短小、可被 Agent 一次性读入执行。Issue 标题格式规范技能文档要求标题简洁、行动导向concise, action-oriented并按 Issue 影响面选择前缀包级 Issue以包名为前缀当 Issue 主要影响某个包时标题以包名开头格式为remotion/package: 变更描述文档给出的三个示例分别是remotion/player: Support keyboard shortcuts for fullscreen remotion/lambda: Improve retry message for failed renders remotion/docs: Add examples contribution guide这些前缀对应仓库中真实存在的包packages/player 的 npm 包名是remotion/playerpackages/lambda 是remotion/lambda两者可在各自的package.json中确认。值得注意的是第三个示例remotion/docs——packages/docs 的package.json中包名实际是docs它并不是以remotion/作用域发布的 npm 包。这说明标题前缀约定的是读者能一眼识别的包标识而不强制与 npm 包名逐字一致写标题时以该包在仓库社区中的通用称呼为准即可。平台级 Issue使用固定前缀当 Issue 影响面超出单个包时按影响范围使用不同的固定前缀影响范围标题前缀网站 / 文档整体Docs: 变更描述Studio 整体Studio: 变更描述Monorepo 构建Build: 变更描述CI 流水线CI: 变更描述仓库级基础设施Repo: 变更描述这些前缀与 Remotion 仓库的实际结构对应得上Studio:对应 packages/studioDocs:对应 packages/docsDocusaurus 站点Build:/CI:对应根目录的 turbo.json、bunfig.toml 等 monorepo 基础设施。必须避免的模糊标题文档明确列出了反例Bug Fix issue Examples follow-up并给出对应的好标题示例Docs: Add a skill for creating examples核心逻辑是标题本身应包含领域前缀 动词 对象让只看标题不打开正文的人也能判断该 Issue 属于哪个模块、要做哪件事。核心原则绝不通过 shell 参数内联多行 Markdown这是整个技能文档中最关键的一条工程约束不要把 Issue 正文、PR 正文或长评论以字符串形式直接内联在 shell 命令参数里传递。为什么内联会出问题文档给出的错误示例gh issue create --title Docs: Add examples skill --body Line one\n\nLine two问题在于在gh这类工具中--body参数里的\n是字面转义序列而不是真正的换行符。命令执行后GitHub 上收到的正文会包含字面的反斜杠加n字符渲染出来的是一条挤在一起的长文本而不是预期的分段 Markdown。这类错误在 Agent 自动化场景下尤其常见——模型生成的字符串里普遍带\n一旦直接拼进命令行污染就不可见地进入了 Issue 正文。正确做法写入临时文件用 --body-file 传递文档要求始终把 Markdown 写入临时文件再用--body-file传入。临时文件建议放在/tmp/remotion-issue-body.mdRemotion 的命名习惯正文示例cat /tmp/remotion-issue-body.md EOF Summary of the issue. ## Tasks - [ ] First task - [ ] Second task ## Context Related to #1234. EOF注意 heredoc 使用了带引号的定界符EOF这会禁止 shell 对文件内容做任何变量展开或转义解析保证 Markdown 原样落盘。然后创建 Issuegh issue create \ --title Docs: Add a skill for creating examples \ --body-file /tmp/remotion-issue-body.md文档还补充了一条 Agent 专属建议当以 AI Agent 身份操作时优先使用 Agent 的文件写入工具write tool创建临时 Markdown 文件而不是在 shell 里拼 heredoc因为前者不经过 shell 转义层更不容易引入二次转义问题。同一原则在仓库其他技能中也被反复引用可见它是跨技能共享的约定pr 技能、flake 技能、update-remotion-rust-ffmpeg 技能 和 issue-management 技能 都出现了--body-file的用法其中 issue-management 在其安全工作流第 1 步再次强调用--body-file创建新 Issue 正文而不是内联多行 shell 字符串。编辑 Issue 正文编辑已有 Issue 遵循同样的两步流程把完整的替换正文不是补丁、不是增量写入临时 Markdown 文件用--body-file提交修改gh issue edit 1234 --body-file /tmp/remotion-issue-body.mdgh issue edit的--body-file语义是整体替换正文所以第 1 步必须先取回或重新整理出完整版本。编辑完成后必须做渲染验证gh issue view 1234 --json body --jq .body检查要点在文档中写得很具体输出中必须包含真正的空行而不是字面的\n转义序列。如果--jq .body打印出的内容里出现\n字符对就说明第 1 步写入的临时文件本身就是坏的多半是 heredoc 未加引号定界符或字符串被二次转义需要重新生成文件再编辑一次。添加 Issue 评论多行评论同样走文件通道只是命令换成了gh issue commentgh issue comment 1234 --body-file /tmp/remotion-issue-comment.md这里可以留意文档的细节示例中评论临时文件命名为/tmp/remotion-issue-comment.md与正文文件/tmp/remotion-issue-body.md区分开避免一次会话中连续操作时正文与评论文件互相覆盖。关联 Issue 的处理边界与引用格式issue 技能 自身不做 Issue 关系管理但给出两条协作规则关系操作交给issue-management技能。涉及 parent / sub-issue / blocked-by / blocking 时参照 issue-management 技能 执行优先使用gh issue create/gh issue edit的关系标志位如--parent、--blocked-by、--blocking而不是手写 GraphQL mutation。issue-management文档说明这些标志位来自 GitHub CLI 新增的 Issues 2.0 支持并在操作前要求先用gh issue create --help | grep -E -- --parent|--blocked-by|--blocking验证本地gh版本是否已支持防止对旧版 CLI 臆造命令。把模糊的 checklist 项替换为具体 Issue 编号文档还规定了关联 Issue 之后的正文更新策略如果一个 PR 或 Issue 提到后续工作且该工作已经被一个关联 Issue 跟踪就应当把模糊的 checkbox 项替换为具体编号。推荐写法The Remotion skill for creating examples is tracked separately in sub-issue #8158, not in this PR.避免写法- [ ] Add a Remotion skill for creating an example前提是该项工作并不属于当前 PR 的交付范围。这样做的收益是PR 的 checklist 始终只反映本 PR 内的完成度跨 PR 的工作通过#编号在 GitHub 侧形成可追踪的链接避免两个地方各维护一份会漂移的待办列表。操作完成后的验证清单技能文档末尾附有一份最终验证清单要求创建或编辑 Issue 后逐项确认用gh issue view number --json body --jq .body查看 Issue 正文确认 Markdown 中是真正的换行而非字面\n确认标题符合 包名 / Docs / Studio / Build / CI / Repo 的命名约定确认#1234这类 Issue 引用指向了正确的编号若添加了 Issue 关系按issue-management技能确认链接符合预期。这份清单把前文的三个核心约束命名规范、文件通道传递正文、关系操作边界收敛为一次可执行的检查流程适合作为 Agent 每次操作 Issue 后的收尾步骤。小结这套规范可迁移的关键点从 issue 技能 的完整内容可以提炼出三条对其他 monorepo 团队同样成立的实践标题即路由用包名:/Docs:/Studio:/Build:前缀让 Issue 在列表里自分类模糊标题Bug、Fix issue被显式列为反例多行内容永远走--body-filegh issue create、gh issue edit、gh issue comment三个入口统一使用临时文件规避 shell 参数中\n变成字面字符的经典坑并且编辑后要回读验证换行真实存在技能按职责拆分并交叉引用本技能只负责命名 正文安全Issue 2.0 关系管理交由 issue-management且要求先用--help探测 CLI 能力再执行从文档层面杜绝 Agent 对旧版工具臆造命令。配合根目录 AGENTS.md 中对开发环境的总体约定这套.agents/skills/技能文档构成了 Remotion 仓库人机协作尤其是 AI Agent 自动化的流程基线。【免费下载链接】remotion Make videos programmatically with React项目地址: https://gitcode.com/GitHub_Trending/re/remotion创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考