PR-Agent Agent Skills 实战指南用 SKILL.md 构建组织级代码评审知识库【免费下载链接】pr-agent PR Agent: The Original Open-Source PR Reviewer. This project is not the Qodo free tier.项目地址: https://gitcode.com/gh_mirrors/pr/pr-agentAgent Skills 是 PR-Agent 提供的可复用评审知识注入机制将团队沉淀的评审标准以SKILL.md格式统一托管在宿主部署层由 PR-Agent 自动发现、解析并注入到/review、/improve、/describe以及顶层/ask的提示词中实现一套知识库多仓库复用。读完本文你将掌握 SKILL.md 的书写格式、[skills]配置项的全部语义、宿主级与仓库级配置的安全边界、资源打包规则以及底层发现、解析、预算裁剪与请求级缓存的具体实现。概述什么是 Agent SkillsAgent Skills 允许你把经过整理的、可复用的评审指导分发给 PR-Agent其载体是 agent-skills 标准定义的SKILL.md格式。一个 skill 就是一个目录目录内含一个SKILL.md文件文件以 YAML frontmatter必须包含name和description两个字段开头随后是 Markdown 正文。PR-Agent 支持该功能的四个工具为Review、Improve、Describe、Ask。一个典型的 skill 目录结构如下--- name: terraform-standards description: Use when reviewing Terraform code — checks state safety and risky deletions. --- # Terraform Review Guidance - Flag any resource deletion that is not explicitly called out in the PR description. - Require prevent_destroy on stateful resources. - ...启用后PR-Agent 会在配置的路径下递归发现每一个SKILL.md解析其内容并把每个 skill 的name、description和正文注入到/review、/improve、/describe以及顶层/ask的提示词中与extra_instructions并列存在。模型根据各 skill 的description作为何时适用的信号自行判断并应用与当前 PR 或问题相关的指导。核心价值主张是组织级org-wide、宿主级host-level的 skill 库在 PR-Agent 部署处安装一套精挑细选的 skills即可跨多个仓库复用而无需把评审指导逐一检入每个仓库。配置[skills]段与三个配置项Skills默认关闭配置写在configuration.toml或任意宿主级配置源如环境变量、secrets 文件等中。默认配置段位于 pr_agent/settings/configuration.toml[skills] enabled false paths [] # directories scanned recursively for */SKILL.md; supports ~ and $VAR max_skills_tokens 8000 # token budget for the combined skills block三个配置项的语义如下配置项类型默认值作用enabledboolfalse开关。关闭时get_skills_context()直接返回空串不执行任何文件系统扫描。pathslist[str][]发现路径列表。每一项可以是目录递归扫描其中所有*/SKILL.md也可以是直接指向某个SKILL.md文件的路径。路径中的~与$VAR/${VAR}会被展开。max_skills_tokensint8000合并后的 skills 注入块的 token 预算上限。超出预算的 skill 会从末尾被丢弃并记录 warning若第一个 skill 单独就超出预算它会被裁剪并在末尾追加[truncated]标记。从源码 pr_agent/algo/skills_loader.py 可以看到路径展开通过os.path.expanduser(os.path.expandvars(...))完成即同时支持~和$VAR/${VAR}两种写法且空串、非字符串条目会被静默忽略。max_skills_tokens若配置成非法值如not-a-number加载器会记录 warning 并回退到默认值8000常量_DEFAULT_MAX_SKILLS_TOKENS见 skills_loader.py。安全边界skills.paths仅限宿主级配置!!! warning skills.pathsis host-level onlyskills.paths不能在仓库的.pr_agent.toml中设置它只能在部署被管理的层级配置。原因很直接该配置项会从PR-Agent 宿主机的文件系统读取文件如果允许仓库设置它恶意仓库就可以把 PR-Agent 指向宿主机上的敏感文件例如~/.ssh/*并将其内容泄露进模型提示词。仓库提供的skills.paths会被忽略并给出 warning。仓库则可以在自己的.pr_agent.toml中设置两个安全的按仓库偏好项skills.enabled—— 例如让某个仓库选择加入opt in宿主管控的 skill 库skills.max_skills_tokens—— 为该仓库调整注入块的大小上限。仓库永远无法重定向文件系统扫描目录。该安全边界有对应的单元测试守护见 tests/unittest/test_skills_loader.py测试构造了一个恶意的仓库.pr_agent.tomlpaths [/etc/pwned]验证其无法注入同时验证enabled与max_skills_tokens这两个安全键可以被仓库设置覆盖。资源打包规则PR-Agent 支持纯文本text-onlyskillsagent-skills 标准允许在SKILL.md旁边捆绑额外文件PR-Agent 会内联其中的文本资源skill 目录树中的所有*.md文件包括references/子目录会被追加到SKILL.md正文之后。单个资源文件超过 256 KB 会被跳过并给出 warning常量_MAX_RESOURCE_FILE_BYTES 256 * 1024见 skills_loader.py。scripts/与assets/子目录会被整体跳过PR-Agent 执行的是单次single-shot模型调用、没有工具使用循环tool-use loop无法按需执行脚本或加载二进制资源。某个嵌套目录若包含自己的SKILL.md它会被视为独立的 skill不会内联进父 skill。简言之PR-Agent 只支持纯文本的 agent skills。此外/ask_line不在 skills 注入范围内因为它的提示词围绕选中的 diff hunk 和可选的线程历史单独做预算。上述规则的源码实现位于 skills_loader.py 的_gather_resources通过os.walk遍历 skill 目录剪枝scripts/assets子目录常量_EXCLUDED_RESOURCE_DIRS见 skills_loader.py遇到嵌套SKILL.md时停止继续下钻按os.path.getsize过滤超限文件读取时捕获OSError/UnicodeDecodeError非 UTF-8 文件被跳过而不至于让整个 skill 加载崩溃。对应测试覆盖了 references 递归内联、scripts/assets 排除、嵌套 skill 独立性、超限文件跳过、非 UTF-8 文件跳过等场景见 tests/unittest/test_skills_loader.py。工作流程从磁盘到提示词的完整链路整个功能的核心入口是 skills_loader.py 中的get_skills_context()其执行链路可拆解为五步读取配置从全局设置读取skills.enabled、skills.paths、skills.max_skills_tokens关闭或未配置路径时直接返回空串。发现discoverydiscover_skills()见 skills_loader.py遍历每个路径——目录则递归找*/SKILL.md文件则校验文件名必须是SKILL.md不存在的路径跳过并 warning用os.path.realpath去重避免重叠路径重复加载最后按 skill 名称排序。解析parse_parse_skill_file()见 skills_loader.py以首行---定位 frontmatter 起止用yaml.safe_load解析元数据缺少name或description或为空串、frontmatter 不是 YAML 映射、缺少开/闭分隔符、YAML 非法时该文件被跳过并 warning。解析通过后继续收集资源。格式化format_format_skill()见 skills_loader.py把每个 skill 渲染成### Skill: {name}When to use: {description} 正文 各资源以#### {relative_path}小标题分隔的提示词块。预算裁剪budgetformat_skills_context()见 skills_loader.py按max_skills_tokens依次累积每个 skill 的 token 数超出预算时丢弃剩余 skill若第一个 skill 就超预算则用clip_tokens裁剪并追加[truncated]标记同时保证裁剪后 标记仍不超预算。关于 frontmatter 解析有一个细节值得注意正文中即使再出现---行例如正文里有 Markdown 水平线或嵌套代码块也只有第一个闭合分隔符之后的全部内容视为正文解析不会误判对应测试test_body_with_inner_dashes_preserved。提示词注入点skills 上下文通过 Jinja2 模板的受保护块注入四个工具的提示词/review注入点位于 pr_agent/settings/pr_reviewer_prompts.toml以 Organizational standards and review skills (apply the ones relevant to this PR) 引导语出现调用发生在 pr_agent/tools/pr_reviewer.py。/improve代码建议同样注入skills_context见 pr_agent/settings/code_suggestions/pr_code_suggestions_prompts.toml调用在 pr_agent/tools/pr_code_suggestions.py。/describe见 pr_agent/settings/pr_description_prompts.toml 与 pr_agent/tools/pr_description.py。/ask顶层提问见 pr_agent/settings/pr_questions_prompts.toml调用在 pr_agent/tools/pr_questions.py。模板统一使用{%- if skills_context %}守卫未启用 skills 或未发现任何 skill 时整个注入块完全不会出现在提示词中不影响其余提示内容。请求级缓存request-scoped memoization同一请求内三个工具review、improve、describe都会调用get_skills_context()。为避免重复的文件扫描、解析与格式化加载器借助starlette_context实现了按请求 按生效配置的缓存见 skills_loader.py缓存键由(enabled, 展开后的 paths, max_skills_tokens)三元组构成任何一项变化都会导致缓存失效并重新计算。CLI 场景下不存在请求上下文则每次调用都重新计算对单条 CLI 命令无害。对 skill 正文中可能出现的 Jinja2 语法如 Helm/Ansible/Terraform 模板的{{ }}或{% %}模板渲染是单遍的注入的变量内容不会被再次解析为模板而是原样呈现为字面字符见测试TestJinjaSafetytests/unittest/test_skills_loader.py。这意味着你可以放心地把带模板语法的评审示例写进 skill 正文。限制与未来方向PR-Agent 采用的是单次模型调用分发架构因此 agent-skills 标准中的**渐进式披露progressive disclosure**模型——模型先根据description选定SKILL.md再读取references/*.md仅在需要时才加载——在当前架构下无法实现。当前实现把每个启用 skill 的全文都加载进每个 PR 的提示词中并用max_skills_tokens限制总量。依赖脚本执行或二进制资产的 skills 不会生效。文档明确说明为支持渐进式披露的架构变更已列入未来计划。测试验证与实战建议围绕该功能有两组专项测试tests/unittest/test_skills_loader.py覆盖 frontmatter 解析合法性、发现逻辑嵌套、去重、缺失路径、直接文件路径、畸形文件跳过、格式化输出结构、预算超限时的丢弃与裁剪、配置缓存、路径展开、资源收集规则、仓库配置安全边界与 Jinja 安全性。tests/unittest/test_skills_context_budget.py参数化验证在任意预算下20/50/200/1000 token裁剪后的注入块 token 数严格不超过预算且始终保留[truncated]标记与 skill 正文——即使预算极小也不会退化到空内容。实战落地建议按职责拆分 skill每个 skill 聚焦一类评审主题如terraform-standards、security-hardening、sql-migration-safety用description精确描述适用场景这是模型选择应用哪个 skill 的唯一信号。知识库放宿主层把 skill 库安装在 PR-Agent 部署主机上通过宿主级配置指定paths在仓库级.pr_agent.toml中按需enabled true并调整max_skills_tokens。控制总预算skills 会注入每一次 PR 请求的提示词过多的 skill 会挤占上下文建议保持max_skills_tokens在合理范围并观察日志中 dropping N skill(s) 的 warning 来校准库的规模。只放文本把需要随 skill 附带的背景材料写成references/*.md避免依赖脚本或二进制资源。【免费下载链接】pr-agent PR Agent: The Original Open-Source PR Reviewer. This project is not the Qodo free tier.项目地址: https://gitcode.com/gh_mirrors/pr/pr-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PR-Agent Agent Skills 实战指南：用 SKILL.md 构建组织级代码评审知识库
PR-Agent Agent Skills 实战指南用 SKILL.md 构建组织级代码评审知识库【免费下载链接】pr-agent PR Agent: The Original Open-Source PR Reviewer. This project is not the Qodo free tier.项目地址: https://gitcode.com/gh_mirrors/pr/pr-agentAgent Skills 是 PR-Agent 提供的可复用评审知识注入机制将团队沉淀的评审标准以SKILL.md格式统一托管在宿主部署层由 PR-Agent 自动发现、解析并注入到/review、/improve、/describe以及顶层/ask的提示词中实现一套知识库多仓库复用。读完本文你将掌握 SKILL.md 的书写格式、[skills]配置项的全部语义、宿主级与仓库级配置的安全边界、资源打包规则以及底层发现、解析、预算裁剪与请求级缓存的具体实现。概述什么是 Agent SkillsAgent Skills 允许你把经过整理的、可复用的评审指导分发给 PR-Agent其载体是 agent-skills 标准定义的SKILL.md格式。一个 skill 就是一个目录目录内含一个SKILL.md文件文件以 YAML frontmatter必须包含name和description两个字段开头随后是 Markdown 正文。PR-Agent 支持该功能的四个工具为Review、Improve、Describe、Ask。一个典型的 skill 目录结构如下--- name: terraform-standards description: Use when reviewing Terraform code — checks state safety and risky deletions. --- # Terraform Review Guidance - Flag any resource deletion that is not explicitly called out in the PR description. - Require prevent_destroy on stateful resources. - ...启用后PR-Agent 会在配置的路径下递归发现每一个SKILL.md解析其内容并把每个 skill 的name、description和正文注入到/review、/improve、/describe以及顶层/ask的提示词中与extra_instructions并列存在。模型根据各 skill 的description作为何时适用的信号自行判断并应用与当前 PR 或问题相关的指导。核心价值主张是组织级org-wide、宿主级host-level的 skill 库在 PR-Agent 部署处安装一套精挑细选的 skills即可跨多个仓库复用而无需把评审指导逐一检入每个仓库。配置[skills]段与三个配置项Skills默认关闭配置写在configuration.toml或任意宿主级配置源如环境变量、secrets 文件等中。默认配置段位于 pr_agent/settings/configuration.toml[skills] enabled false paths [] # directories scanned recursively for */SKILL.md; supports ~ and $VAR max_skills_tokens 8000 # token budget for the combined skills block三个配置项的语义如下配置项类型默认值作用enabledboolfalse开关。关闭时get_skills_context()直接返回空串不执行任何文件系统扫描。pathslist[str][]发现路径列表。每一项可以是目录递归扫描其中所有*/SKILL.md也可以是直接指向某个SKILL.md文件的路径。路径中的~与$VAR/${VAR}会被展开。max_skills_tokensint8000合并后的 skills 注入块的 token 预算上限。超出预算的 skill 会从末尾被丢弃并记录 warning若第一个 skill 单独就超出预算它会被裁剪并在末尾追加[truncated]标记。从源码 pr_agent/algo/skills_loader.py 可以看到路径展开通过os.path.expanduser(os.path.expandvars(...))完成即同时支持~和$VAR/${VAR}两种写法且空串、非字符串条目会被静默忽略。max_skills_tokens若配置成非法值如not-a-number加载器会记录 warning 并回退到默认值8000常量_DEFAULT_MAX_SKILLS_TOKENS见 skills_loader.py。安全边界skills.paths仅限宿主级配置!!! warning skills.pathsis host-level onlyskills.paths不能在仓库的.pr_agent.toml中设置它只能在部署被管理的层级配置。原因很直接该配置项会从PR-Agent 宿主机的文件系统读取文件如果允许仓库设置它恶意仓库就可以把 PR-Agent 指向宿主机上的敏感文件例如~/.ssh/*并将其内容泄露进模型提示词。仓库提供的skills.paths会被忽略并给出 warning。仓库则可以在自己的.pr_agent.toml中设置两个安全的按仓库偏好项skills.enabled—— 例如让某个仓库选择加入opt in宿主管控的 skill 库skills.max_skills_tokens—— 为该仓库调整注入块的大小上限。仓库永远无法重定向文件系统扫描目录。该安全边界有对应的单元测试守护见 tests/unittest/test_skills_loader.py测试构造了一个恶意的仓库.pr_agent.tomlpaths [/etc/pwned]验证其无法注入同时验证enabled与max_skills_tokens这两个安全键可以被仓库设置覆盖。资源打包规则PR-Agent 支持纯文本text-onlyskillsagent-skills 标准允许在SKILL.md旁边捆绑额外文件PR-Agent 会内联其中的文本资源skill 目录树中的所有*.md文件包括references/子目录会被追加到SKILL.md正文之后。单个资源文件超过 256 KB 会被跳过并给出 warning常量_MAX_RESOURCE_FILE_BYTES 256 * 1024见 skills_loader.py。scripts/与assets/子目录会被整体跳过PR-Agent 执行的是单次single-shot模型调用、没有工具使用循环tool-use loop无法按需执行脚本或加载二进制资源。某个嵌套目录若包含自己的SKILL.md它会被视为独立的 skill不会内联进父 skill。简言之PR-Agent 只支持纯文本的 agent skills。此外/ask_line不在 skills 注入范围内因为它的提示词围绕选中的 diff hunk 和可选的线程历史单独做预算。上述规则的源码实现位于 skills_loader.py 的_gather_resources通过os.walk遍历 skill 目录剪枝scripts/assets子目录常量_EXCLUDED_RESOURCE_DIRS见 skills_loader.py遇到嵌套SKILL.md时停止继续下钻按os.path.getsize过滤超限文件读取时捕获OSError/UnicodeDecodeError非 UTF-8 文件被跳过而不至于让整个 skill 加载崩溃。对应测试覆盖了 references 递归内联、scripts/assets 排除、嵌套 skill 独立性、超限文件跳过、非 UTF-8 文件跳过等场景见 tests/unittest/test_skills_loader.py。工作流程从磁盘到提示词的完整链路整个功能的核心入口是 skills_loader.py 中的get_skills_context()其执行链路可拆解为五步读取配置从全局设置读取skills.enabled、skills.paths、skills.max_skills_tokens关闭或未配置路径时直接返回空串。发现discoverydiscover_skills()见 skills_loader.py遍历每个路径——目录则递归找*/SKILL.md文件则校验文件名必须是SKILL.md不存在的路径跳过并 warning用os.path.realpath去重避免重叠路径重复加载最后按 skill 名称排序。解析parse_parse_skill_file()见 skills_loader.py以首行---定位 frontmatter 起止用yaml.safe_load解析元数据缺少name或description或为空串、frontmatter 不是 YAML 映射、缺少开/闭分隔符、YAML 非法时该文件被跳过并 warning。解析通过后继续收集资源。格式化format_format_skill()见 skills_loader.py把每个 skill 渲染成### Skill: {name}When to use: {description} 正文 各资源以#### {relative_path}小标题分隔的提示词块。预算裁剪budgetformat_skills_context()见 skills_loader.py按max_skills_tokens依次累积每个 skill 的 token 数超出预算时丢弃剩余 skill若第一个 skill 就超预算则用clip_tokens裁剪并追加[truncated]标记同时保证裁剪后 标记仍不超预算。关于 frontmatter 解析有一个细节值得注意正文中即使再出现---行例如正文里有 Markdown 水平线或嵌套代码块也只有第一个闭合分隔符之后的全部内容视为正文解析不会误判对应测试test_body_with_inner_dashes_preserved。提示词注入点skills 上下文通过 Jinja2 模板的受保护块注入四个工具的提示词/review注入点位于 pr_agent/settings/pr_reviewer_prompts.toml以 Organizational standards and review skills (apply the ones relevant to this PR) 引导语出现调用发生在 pr_agent/tools/pr_reviewer.py。/improve代码建议同样注入skills_context见 pr_agent/settings/code_suggestions/pr_code_suggestions_prompts.toml调用在 pr_agent/tools/pr_code_suggestions.py。/describe见 pr_agent/settings/pr_description_prompts.toml 与 pr_agent/tools/pr_description.py。/ask顶层提问见 pr_agent/settings/pr_questions_prompts.toml调用在 pr_agent/tools/pr_questions.py。模板统一使用{%- if skills_context %}守卫未启用 skills 或未发现任何 skill 时整个注入块完全不会出现在提示词中不影响其余提示内容。请求级缓存request-scoped memoization同一请求内三个工具review、improve、describe都会调用get_skills_context()。为避免重复的文件扫描、解析与格式化加载器借助starlette_context实现了按请求 按生效配置的缓存见 skills_loader.py缓存键由(enabled, 展开后的 paths, max_skills_tokens)三元组构成任何一项变化都会导致缓存失效并重新计算。CLI 场景下不存在请求上下文则每次调用都重新计算对单条 CLI 命令无害。对 skill 正文中可能出现的 Jinja2 语法如 Helm/Ansible/Terraform 模板的{{ }}或{% %}模板渲染是单遍的注入的变量内容不会被再次解析为模板而是原样呈现为字面字符见测试TestJinjaSafetytests/unittest/test_skills_loader.py。这意味着你可以放心地把带模板语法的评审示例写进 skill 正文。限制与未来方向PR-Agent 采用的是单次模型调用分发架构因此 agent-skills 标准中的**渐进式披露progressive disclosure**模型——模型先根据description选定SKILL.md再读取references/*.md仅在需要时才加载——在当前架构下无法实现。当前实现把每个启用 skill 的全文都加载进每个 PR 的提示词中并用max_skills_tokens限制总量。依赖脚本执行或二进制资产的 skills 不会生效。文档明确说明为支持渐进式披露的架构变更已列入未来计划。测试验证与实战建议围绕该功能有两组专项测试tests/unittest/test_skills_loader.py覆盖 frontmatter 解析合法性、发现逻辑嵌套、去重、缺失路径、直接文件路径、畸形文件跳过、格式化输出结构、预算超限时的丢弃与裁剪、配置缓存、路径展开、资源收集规则、仓库配置安全边界与 Jinja 安全性。tests/unittest/test_skills_context_budget.py参数化验证在任意预算下20/50/200/1000 token裁剪后的注入块 token 数严格不超过预算且始终保留[truncated]标记与 skill 正文——即使预算极小也不会退化到空内容。实战落地建议按职责拆分 skill每个 skill 聚焦一类评审主题如terraform-standards、security-hardening、sql-migration-safety用description精确描述适用场景这是模型选择应用哪个 skill 的唯一信号。知识库放宿主层把 skill 库安装在 PR-Agent 部署主机上通过宿主级配置指定paths在仓库级.pr_agent.toml中按需enabled true并调整max_skills_tokens。控制总预算skills 会注入每一次 PR 请求的提示词过多的 skill 会挤占上下文建议保持max_skills_tokens在合理范围并观察日志中 dropping N skill(s) 的 warning 来校准库的规模。只放文本把需要随 skill 附带的背景材料写成references/*.md避免依赖脚本或二进制资源。【免费下载链接】pr-agent PR Agent: The Original Open-Source PR Reviewer. This project is not the Qodo free tier.项目地址: https://gitcode.com/gh_mirrors/pr/pr-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考