Ruflo 的 $agent-docs-api-openapi面向 Codex CLI 的 OpenAPI 文档智能体技能深度解析【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo在 RufloClaude Flow 系多智能体编排平台仓库中.agents/目录承载了面向 OpenAI Codex CLI 的完整技能Skill体系其中 agent-docs-api-openapi 技能 是一个专职负责创建与维护 OpenAPI 3.0 / Swagger 文档的专家型智能体技能。本文以该技能的 SKILL.md 为骨架逐字段解析它的触发条件、能力边界、沙箱约束、生命周期钩子与协作关系并结合 Codex 模板源码 与 SKILL.md 生成器 说明该技能在 Ruflo 技能体系中的分发机制读完后可完整理解如何用一个声明式 YAML 定义一个受控的文档智能体并用$agent-docs-api-openapi语法在 Codex CLI 中调用它。1. 技能在 Ruflo 仓库中的定位Ruflo 支持跨智能体运行Claude Code、Codex、Copilot 等其 根 SKILL.md 说明项目以npx ruflo command的形式运行技能目录则按目标智能体分派Codex CLI 使用.agents/目录。.agents/README.md 给出了标准目录结构.agents/ config.toml # Main configuration file skills/ # Skill definitions skill-name/ SKILL.md # Skill instructions scripts/ # Optional scripts docs/ # Optional documentation关键规则是技能通过$skill-name语法调用每个技能由一段带 YAML frontmatter 元数据的 SKILL.md组成并声明触发条件、跳过条件、命令与示例。而项目级配置 config.toml 控制模型选择、审批策略、沙箱模式、MCP 连接与技能开关。在 Ruflo 中agent-docs-api-openapi只是.agents/skills/下约 140 个技能目录之一同级的还有agent-coder、agent-reviewer、agent-dev-backend-api等它属于模板常量中被标注为 Agent skills (converted from Claude Code agents) 的一类——即从 Claude Code 的 agent 定义转写而来的技能。1.1 技能如何进入 Codex 初始化流程模板源码 v3/claude-flow/codex/src/templates/index.ts 中的ALL_AVAILABLE_SKILLS数组列出了初始化时可分发的全部技能agent-docs-api-openapi位于其中第 152 行。该文件同时定义了四档模板模板说明技能数量minimal仅核心技能2default常用技能4full全量技能137137enterprise全量 治理137其中只有full与enterprise模板会带上agent-docs-api-openapiDEFAULT_SKILLS_BY_TEMPLATE中full: ALL_AVAILABLE_SKILLS。同一文件里的PLATFORM_MAPPING还明确了两大平台的差异Claude Code 的技能调用语法是/skill-name而 Codex 是$skill-nameClaude Code 的配置载体是CLAUDE.mdJSON settingsCodex 是AGENTS.mdTOML config。因此在 Codex CLI 中本文主题技能的调用形式就是$agent-docs-api-openapi1.2 文件布局与本地覆盖DIRECTORY_STRUCTURE常量描述了完整的落盘结构.agents/config.toml项目级 Codex 配置、.agents/skills/技能定义、.codex/config.toml用户级本地覆盖gitignored、.claude-flow/运行时数据。这解释了为何 config.toml 里既有sandbox_mode、approval_policy等全局策略又能在[profiles.dev]、[profiles.safe]、[profiles.ci]中按场景切换审批与沙箱强度——文档智能体的受控行为正是叠加在这一层平台配置之上生效的。2. SKILL.md 的文件结构frontmatter 与legacy YAML块SKILL.md 整体分为三部分YAML frontmatter技能元数据--- name: agent-docs-api-openapi description: Agent skill for docs-api-openapi - invoke with $agent-docs-api-openapi ---frontmatter 极简name是技能 ID即.agents/skills/下的目录名与调用语法$name一致description直接提示了调用方式。这种目录名 技能 ID 调用名的约定在 skill-md.ts 生成器 中得到印证generateSkillMd()渲染的 frontmatter 首字段就是name正文标题由formatSkillName(name)按连字符拆分并首字母大写生成。legacy agent-definition YAML 块第 6127 行这是技能最核心的机器可读定义。文件里有一段注释解释它为何被包在yaml代码栅栏中——历史上它是第二个---围栏块但渲染器skills.sh、GitHub web 视图把第二个---当成水平分割线导致原始 YAML 被直接倾倒进页面正文仓库标注为 issue #2469。因此现在用 yaml 代码块包裹既按代码渲染又保持机器可读。Markdown 正文第 129 行起面向执行者的系统提示system prompt包含职责、最佳实践、OpenAPI 结构模板与文档要素清单。这种元数据 机器定义 执行提示的三段式结构是 Ruflo 全部 agent 技能的通用形态。3. 智能体定义逐字段解析下面把 legacy YAML 块按逻辑分组完整拆解这是该技能真正的配置面。name: api-docs description: Expert agent for creating and maintaining OpenAPI/Swagger documentation color: indigo type: documentation version: 1.0.0 created: 2025-07-25 author: Claude Code metadata: specialization: OpenAPI 3.0 specification, API documentation, interactive docs complexity: moderate autonomous: truename: api-docs是智能体身份名供can_spawn/can_delegate_to引用的短名与技能 IDagent-docs-api-openapi不同二者分属调度层与文件系统层两套命名type: documentation与color: indigo用于编排 UI 的展示与分类autonomous: true声明该智能体可自主推进任务但自主边界由后文的constraints与behavior收紧。3.1 triggers三类触发条件triggers: keywords: - api documentation - openapi - swagger - api docs - endpoint documentation file_patterns: - **$openapi.yaml - **$swagger.yaml - **$api-docs/** - **$api.yaml task_patterns: - document * api - create openapi spec - update api documentation domains: - documentation - api触发分四个维度关键词命中用户意图含 openapi、swagger 等、文件模式命中工作区出现openapi.yaml、swagger.yaml、api.yaml或api-docs/目录、任务模式命中create openapi spec 之类的任务短语以及领域归属。需要说明本仓库技能文件中的$是特殊字符转义写法同目录 agent-dev-backend-api 技能 的钩子脚本里同样以2$dev$null形式出现还原后file_patterns的意图是匹配任意深度下的*openapi.yaml、*swagger.yaml、*api-docs/**、*api.yamltask_patterns中的*是通配词。阅读此类技能时按通配/转义理解即可不必当作字面文件名。3.2 capabilities工具白名单与资源配额capabilities: allowed_tools: - Read - Write - Edit - MultiEdit - Grep - Glob restricted_tools: - Bash # No need for execution - Task # Focused on documentation - WebSearch max_file_operations: 50 max_execution_time: 300 memory_access: read这是一套最小权限设计白名单只保留文件读写与搜索类工具Read/Write/Edit/MultiEdit/Grep/Glob——文档智能体需要读代码、写 YAML但不需要别的禁用 BashNo need for execution、禁用Task专注文档、不派生子任务、禁用 WebSearch不依赖外部资料配额单次任务最多 50 次文件操作、300 秒执行时限memory_access: read表示对记忆库只读——它可以检索既有的 API 模式但不能写入学习记录。对比同族的 agent-dev-backend-api 技能它允许 Bash 与 Task、配额放大到 100 次操作 / 600 秒、memory_access: both因为后端开发需要跑测试并沉淀模式。文档智能体与开发智能体在同一 schema 下呈现出清晰的职责—权限梯度这也是从源码结构看 Ruflo 智能体体系的典型设计能力与副作用正相关地递增。3.3 constraints路径与文件类型围栏constraints: allowed_paths: - docs/** - api/** - openapi/** - swagger/** - *.yaml - *.yml - *.json forbidden_paths: - node_modules/** - .git/** - secrets/** max_file_size: 2097152 # 2MB allowed_file_types: - .yaml - .yml - .json - .md围栏含义写入只能发生在docs/、api/、openapi/、swagger/目录及仓库任意位置的*.yaml/*.yml/*.json显式禁止触碰node_modules/、.git/和secrets/注意.agents/config.toml的[security]段也独立配置了blocked_patterns拦截.env、credentials.json、.pem、.key两层防护叠加。单文件上限 2MB可操作扩展名收敛到 yaml/yml/json/md 四种——正好覆盖 OpenAPI 生态的全部载体格式。3.4 behavior 与 communication交互行为约定behavior: error_handling: lenient confirmation_required: - deleting API documentation - changing API versions auto_rollback: false logging_level: info communication: style: technical update_frequency: summary include_code_snippets: true emoji_usage: minimalerror_handling: lenient遇到个别端点解析失败时继续生成其余文档而非整体中止对比 backend 技能的strict仅两类操作需人工确认删除 API 文档、变更 API 版本——其余文档生成可自动完成auto_rollback: false不回滚因为文档是增量产物回滚意义有限通信风格为技术性、按摘要频率汇报、必须附代码片段、emoji 克制——与hooks段里大量 emoji 提示形成对照hooks 输出面向运维日志communication 面向用户交互。3.5 integration 与 optimization协作与性能参数integration: can_spawn: [] can_delegate_to: - analyze-api requires_approval_from: [] shares_context_with: - dev-backend-api - test-integration optimization: parallel_operations: true batch_size: 10 cache_results: false memory_limit: 256MB这段定义了该智能体在 Ruflo 智能体图agent graph中的位置不能 spawn 任何子智能体can_spawn: []也不需要上级审批requires_approval_from: []——它是叶子节点可把子问题委派给analyze-api端点分析智能体与dev-backend-api、test-integration共享上下文。这与 agent-dev-backend-api 技能 中can_spawn: [test-unit, test-integration, docs-api]互为镜像后端开发智能体可以 spawn 出docs-api即本智能体二者组成实现 → 测试 → 文档的标准流水线性能参数允许并行操作、批大小 10、不缓存结果cache_results: false文档输出通常是一次性的、内存上限 256MB。3.6 hooks执行前后的自动化脚本hooks: pre_execution: | echo OpenAPI Documentation Specialist starting... echo Analyzing API endpoints... # Look for existing API routes find . -name *.route.js -o -name *.controller.js -o -name routes.js | grep -v node_modules | head -10 # Check for existing OpenAPI docs find . -name openapi.yaml -o -name swagger.yaml -o -name api.yaml | grep -v node_modules post_execution: | echo ✅ API documentation completed echo Validating OpenAPI specification... # Check if the spec exists and show basic info if [ -f openapi.yaml ]; then echo OpenAPI spec found at openapi.yaml grep -E ^(openapi:|info:|paths:) openapi.yaml | head -5 fi on_error: | echo ⚠️ Documentation error: {{error_message}} echo Check OpenAPI specification syntax三段钩子的工程意图pre_execution侦察先find出路由/控制器文件*.route.js、*.controller.js、routes.js确定待文档化的端点范围再探测是否已存在openapi.yaml/swagger.yaml/api.yaml——决定新建还是增量更新post_execution验收确认openapi.yaml存在后用grep -E ^(openapi:|info:|paths:)抽查三大顶层键是否齐备作为文档完整性的快速自检on_error诊断{{error_message}}模板占位符由运行期填充提示方向直接指向OpenAPI 规范语法。值得注意的细节该技能restricted_tools禁用了 Bash但这些钩子是平台侧生命周期脚本由 Codex 运行时按 config.toml 的[hooks]段执行pre_task true、post_task true与智能体自身可交互的工具白名单是两套机制——钩子提供确定性脚手架智能体在白名单内做判断性工作。3.7 examples触发示例与预期应答examples: - trigger: create OpenAPI documentation for user API response: Ill create comprehensive OpenAPI 3.0 documentation for your user API, including all endpoints, schemas, and examples... - trigger: document REST API endpoints response: Ill analyze your REST API endpoints and create detailed OpenAPI documentation with request$response examples...examples 是 few-shot 锚点用于让宿主智能体在路由阶段识别这句话应该命中该技能。再次提示request$response中的$为转义字符原文意图是 request/response examples。4. 执行提示正文职责、最佳实践与 OpenAPI 骨架SKILL.md 的 Markdown 正文第 129 行起是给智能体的系统提示结构为角色 → 职责 → 最佳实践 → 规范骨架 → 要素清单You are an OpenAPI Documentation Specialist focused on creating comprehensive API documentation.五大核心职责Key responsibilities创建符合 OpenAPI 3.0 的规范specification为所有端点撰写描述与示例准确定义请求/响应 schema包含认证与安全方案security schemes为所有操作operation提供清晰示例。六条最佳实践Best practices使用描述性的 summary 与 description附请求与响应示例文档化所有可能的错误响应用$ref即 OpenAPI 标准$ref引用可复用组件严格遵循 OpenAPI 3.0 规范用 tags 对端点做逻辑分组。OpenAPI 结构骨架原文档给出的最小可运行模板$ 为转义字符还原后如下openapi: 3.0.0 info: title: API Title version: 1.0.0 description: API Description servers: - url: https://api.example.com paths: /endpoint: get: summary: Brief description description: Detailed description parameters: [] responses: 200: description: Success response content: application/json: schema: type: object example: key: value components: schemas: Model: type: object properties: id: type: string这个骨架体现了职责与最佳实践的落地形态servers声明环境paths下每个方法带 summary/description 双层描述响应同时给出schema与example可复用模型集中放入components.schemas以便$ref引用。**文档要素清单Documentation elements**收尾清晰的 operation ID、请求/响应示例、错误响应文档、安全要求security requirements、限流信息rate limiting——其中限流与安全正是API 契约区别于普通接口清单的关键部分。5. SKILL.md 的生成与校验机制源码级佐证技能文件是手写还是生成v3/claude-flow/codex/src/generators/skill-md.ts 给出两种路径可帮助理解该文件的来源与约束generateSkillMd(options)从类型化选项name、description、version、tags、triggers、skipWhen、commands 等渲染一个全新 SKILL.md。frontmatter 格式与本技能一致namedescription: 折叠块并自动并入 Use when: ... 触发句正文固定为 Purpose / When to Trigger / When to Skip / Commands / Scripts / References / Best Practices 七节——agent-docs-api-openapi这类由 Claude Code agent 转写而来的技能内容更丰富超出了该模板的骨架属于以模板为起点的手工增强。generateBuiltInSkill(skillName)对内置技能BUILT_IN_SKILL_NAMES中的 6 个核心技能swarm-orchestration、memory-management、sparc-methodology、security-audit、performance-analysis、github-automation直接从包内.agents/skills树读取规范定义canonical definition使直接生成、项目初始化与 npm 产物三者不产生漂移源码注释原话。该模块还内置了安全校验readPayloadTree()拒绝技能目录中的符号链接与越界相对路径../或绝对路径直接抛错validateBuiltInSkillPayload()则用正则抽取 SKILL.md 中所有scripts/.../references/...本地引用逐一核对文件确实随技能树分发。这意味着技能文件的自包含性是被代码强制的——对agent-docs-api-openapi这类仅含单个 SKILL.md 的轻量技能校验天然通过而携带scripts/、docs/的技能则受同等约束。6. 实际使用方式与适用边界结合.agents/的文档与 config.toml在 Codex CLI 中使用该技能的完整链条是技能落位技能文件位于.agents/skills/agent-docs-api-openapi/SKILL.md。若项目经 Ruflo 初始化full/enterprise模板会把ALL_AVAILABLE_SKILLS中的技能含本技能拷贝进项目的.agents/skills/default模板则只装 4 个核心技能需要手动补充该目录。触发在 Codex CLI 会话中直接使用$agent-docs-api-openapi显式调用或在任务文本中命中 openapi、swagger、api documentation 等关键词或在openapi.yaml等文件存在时由触发器路由命中。平台约束叠加技能自身的 capabilities/constraints 之外config.toml 的sandbox_mode workspace-write、approval_policy on-request、[security]段的input_validation、path_traversal_prevention、secret_scanning、blocked_patterns会继续生效CI 场景可切到[profiles.ci]approval_policy never workspace-write。行为预期技能会先侦察路由文件与既有 specpre hook在docs/**、api/**、openapi/**、swagger/**或仓库级*.yaml/*.json内生成/更新 OpenAPI 3.0 文档写后抽查openapi:/info:/paths:顶层键post hook执行中删除文档或变更 API 版本前必须向用户确认。适用边界该技能面向OpenAPI 3.0文档max_file_size为 2MB不适合超大型拆分规范multi-file spec的跨文件重构它不生成代码、不执行测试Bash/Task 被禁验证手段仅限于钩子里的文本级抽查。若需要端点级语义分析按can_delegate_to: [analyze-api]的设计应由编排层委派专门的 API 分析智能体完成。7. 小结agent-docs-api-openapi是 Ruflo 智能体技能体系的一个标准样本一个 SKILL.md 同时承担了技能注册信息frontmatter、机器可读的智能体契约legacy YAML 块触发、工具白名单、路径围栏、确认点、钩子、协作关系、性能配额与执行提示OpenAPI 3.0 职责与最佳实践三重角色。它通过 templates/index.ts 的技能清单随full/enterprise模板分发通过 skill-md.ts 的 payload 校验保证自包含性并通过与dev-backend-api、test-integration的上下文共享嵌入实现—测试—文档流水线。对维护者而言理解这套字段语义尤其是triggers的四维触发、capabilities的工具白名单与constraints的路径围栏就能照着同一 schema 写出新的领域专家技能对使用者而言记住$agent-docs-api-openapi的调用语法与它的两条确认红线删文档、改版本即可在 Codex CLI 中安全地用它产出可交互的 API 文档。【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Ruflo 的 $agent-docs-api-openapi：面向 Codex CLI 的 OpenAPI 文档智能体技能深度解析
Ruflo 的 $agent-docs-api-openapi面向 Codex CLI 的 OpenAPI 文档智能体技能深度解析【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo在 RufloClaude Flow 系多智能体编排平台仓库中.agents/目录承载了面向 OpenAI Codex CLI 的完整技能Skill体系其中 agent-docs-api-openapi 技能 是一个专职负责创建与维护 OpenAPI 3.0 / Swagger 文档的专家型智能体技能。本文以该技能的 SKILL.md 为骨架逐字段解析它的触发条件、能力边界、沙箱约束、生命周期钩子与协作关系并结合 Codex 模板源码 与 SKILL.md 生成器 说明该技能在 Ruflo 技能体系中的分发机制读完后可完整理解如何用一个声明式 YAML 定义一个受控的文档智能体并用$agent-docs-api-openapi语法在 Codex CLI 中调用它。1. 技能在 Ruflo 仓库中的定位Ruflo 支持跨智能体运行Claude Code、Codex、Copilot 等其 根 SKILL.md 说明项目以npx ruflo command的形式运行技能目录则按目标智能体分派Codex CLI 使用.agents/目录。.agents/README.md 给出了标准目录结构.agents/ config.toml # Main configuration file skills/ # Skill definitions skill-name/ SKILL.md # Skill instructions scripts/ # Optional scripts docs/ # Optional documentation关键规则是技能通过$skill-name语法调用每个技能由一段带 YAML frontmatter 元数据的 SKILL.md组成并声明触发条件、跳过条件、命令与示例。而项目级配置 config.toml 控制模型选择、审批策略、沙箱模式、MCP 连接与技能开关。在 Ruflo 中agent-docs-api-openapi只是.agents/skills/下约 140 个技能目录之一同级的还有agent-coder、agent-reviewer、agent-dev-backend-api等它属于模板常量中被标注为 Agent skills (converted from Claude Code agents) 的一类——即从 Claude Code 的 agent 定义转写而来的技能。1.1 技能如何进入 Codex 初始化流程模板源码 v3/claude-flow/codex/src/templates/index.ts 中的ALL_AVAILABLE_SKILLS数组列出了初始化时可分发的全部技能agent-docs-api-openapi位于其中第 152 行。该文件同时定义了四档模板模板说明技能数量minimal仅核心技能2default常用技能4full全量技能137137enterprise全量 治理137其中只有full与enterprise模板会带上agent-docs-api-openapiDEFAULT_SKILLS_BY_TEMPLATE中full: ALL_AVAILABLE_SKILLS。同一文件里的PLATFORM_MAPPING还明确了两大平台的差异Claude Code 的技能调用语法是/skill-name而 Codex 是$skill-nameClaude Code 的配置载体是CLAUDE.mdJSON settingsCodex 是AGENTS.mdTOML config。因此在 Codex CLI 中本文主题技能的调用形式就是$agent-docs-api-openapi1.2 文件布局与本地覆盖DIRECTORY_STRUCTURE常量描述了完整的落盘结构.agents/config.toml项目级 Codex 配置、.agents/skills/技能定义、.codex/config.toml用户级本地覆盖gitignored、.claude-flow/运行时数据。这解释了为何 config.toml 里既有sandbox_mode、approval_policy等全局策略又能在[profiles.dev]、[profiles.safe]、[profiles.ci]中按场景切换审批与沙箱强度——文档智能体的受控行为正是叠加在这一层平台配置之上生效的。2. SKILL.md 的文件结构frontmatter 与legacy YAML块SKILL.md 整体分为三部分YAML frontmatter技能元数据--- name: agent-docs-api-openapi description: Agent skill for docs-api-openapi - invoke with $agent-docs-api-openapi ---frontmatter 极简name是技能 ID即.agents/skills/下的目录名与调用语法$name一致description直接提示了调用方式。这种目录名 技能 ID 调用名的约定在 skill-md.ts 生成器 中得到印证generateSkillMd()渲染的 frontmatter 首字段就是name正文标题由formatSkillName(name)按连字符拆分并首字母大写生成。legacy agent-definition YAML 块第 6127 行这是技能最核心的机器可读定义。文件里有一段注释解释它为何被包在yaml代码栅栏中——历史上它是第二个---围栏块但渲染器skills.sh、GitHub web 视图把第二个---当成水平分割线导致原始 YAML 被直接倾倒进页面正文仓库标注为 issue #2469。因此现在用 yaml 代码块包裹既按代码渲染又保持机器可读。Markdown 正文第 129 行起面向执行者的系统提示system prompt包含职责、最佳实践、OpenAPI 结构模板与文档要素清单。这种元数据 机器定义 执行提示的三段式结构是 Ruflo 全部 agent 技能的通用形态。3. 智能体定义逐字段解析下面把 legacy YAML 块按逻辑分组完整拆解这是该技能真正的配置面。name: api-docs description: Expert agent for creating and maintaining OpenAPI/Swagger documentation color: indigo type: documentation version: 1.0.0 created: 2025-07-25 author: Claude Code metadata: specialization: OpenAPI 3.0 specification, API documentation, interactive docs complexity: moderate autonomous: truename: api-docs是智能体身份名供can_spawn/can_delegate_to引用的短名与技能 IDagent-docs-api-openapi不同二者分属调度层与文件系统层两套命名type: documentation与color: indigo用于编排 UI 的展示与分类autonomous: true声明该智能体可自主推进任务但自主边界由后文的constraints与behavior收紧。3.1 triggers三类触发条件triggers: keywords: - api documentation - openapi - swagger - api docs - endpoint documentation file_patterns: - **$openapi.yaml - **$swagger.yaml - **$api-docs/** - **$api.yaml task_patterns: - document * api - create openapi spec - update api documentation domains: - documentation - api触发分四个维度关键词命中用户意图含 openapi、swagger 等、文件模式命中工作区出现openapi.yaml、swagger.yaml、api.yaml或api-docs/目录、任务模式命中create openapi spec 之类的任务短语以及领域归属。需要说明本仓库技能文件中的$是特殊字符转义写法同目录 agent-dev-backend-api 技能 的钩子脚本里同样以2$dev$null形式出现还原后file_patterns的意图是匹配任意深度下的*openapi.yaml、*swagger.yaml、*api-docs/**、*api.yamltask_patterns中的*是通配词。阅读此类技能时按通配/转义理解即可不必当作字面文件名。3.2 capabilities工具白名单与资源配额capabilities: allowed_tools: - Read - Write - Edit - MultiEdit - Grep - Glob restricted_tools: - Bash # No need for execution - Task # Focused on documentation - WebSearch max_file_operations: 50 max_execution_time: 300 memory_access: read这是一套最小权限设计白名单只保留文件读写与搜索类工具Read/Write/Edit/MultiEdit/Grep/Glob——文档智能体需要读代码、写 YAML但不需要别的禁用 BashNo need for execution、禁用Task专注文档、不派生子任务、禁用 WebSearch不依赖外部资料配额单次任务最多 50 次文件操作、300 秒执行时限memory_access: read表示对记忆库只读——它可以检索既有的 API 模式但不能写入学习记录。对比同族的 agent-dev-backend-api 技能它允许 Bash 与 Task、配额放大到 100 次操作 / 600 秒、memory_access: both因为后端开发需要跑测试并沉淀模式。文档智能体与开发智能体在同一 schema 下呈现出清晰的职责—权限梯度这也是从源码结构看 Ruflo 智能体体系的典型设计能力与副作用正相关地递增。3.3 constraints路径与文件类型围栏constraints: allowed_paths: - docs/** - api/** - openapi/** - swagger/** - *.yaml - *.yml - *.json forbidden_paths: - node_modules/** - .git/** - secrets/** max_file_size: 2097152 # 2MB allowed_file_types: - .yaml - .yml - .json - .md围栏含义写入只能发生在docs/、api/、openapi/、swagger/目录及仓库任意位置的*.yaml/*.yml/*.json显式禁止触碰node_modules/、.git/和secrets/注意.agents/config.toml的[security]段也独立配置了blocked_patterns拦截.env、credentials.json、.pem、.key两层防护叠加。单文件上限 2MB可操作扩展名收敛到 yaml/yml/json/md 四种——正好覆盖 OpenAPI 生态的全部载体格式。3.4 behavior 与 communication交互行为约定behavior: error_handling: lenient confirmation_required: - deleting API documentation - changing API versions auto_rollback: false logging_level: info communication: style: technical update_frequency: summary include_code_snippets: true emoji_usage: minimalerror_handling: lenient遇到个别端点解析失败时继续生成其余文档而非整体中止对比 backend 技能的strict仅两类操作需人工确认删除 API 文档、变更 API 版本——其余文档生成可自动完成auto_rollback: false不回滚因为文档是增量产物回滚意义有限通信风格为技术性、按摘要频率汇报、必须附代码片段、emoji 克制——与hooks段里大量 emoji 提示形成对照hooks 输出面向运维日志communication 面向用户交互。3.5 integration 与 optimization协作与性能参数integration: can_spawn: [] can_delegate_to: - analyze-api requires_approval_from: [] shares_context_with: - dev-backend-api - test-integration optimization: parallel_operations: true batch_size: 10 cache_results: false memory_limit: 256MB这段定义了该智能体在 Ruflo 智能体图agent graph中的位置不能 spawn 任何子智能体can_spawn: []也不需要上级审批requires_approval_from: []——它是叶子节点可把子问题委派给analyze-api端点分析智能体与dev-backend-api、test-integration共享上下文。这与 agent-dev-backend-api 技能 中can_spawn: [test-unit, test-integration, docs-api]互为镜像后端开发智能体可以 spawn 出docs-api即本智能体二者组成实现 → 测试 → 文档的标准流水线性能参数允许并行操作、批大小 10、不缓存结果cache_results: false文档输出通常是一次性的、内存上限 256MB。3.6 hooks执行前后的自动化脚本hooks: pre_execution: | echo OpenAPI Documentation Specialist starting... echo Analyzing API endpoints... # Look for existing API routes find . -name *.route.js -o -name *.controller.js -o -name routes.js | grep -v node_modules | head -10 # Check for existing OpenAPI docs find . -name openapi.yaml -o -name swagger.yaml -o -name api.yaml | grep -v node_modules post_execution: | echo ✅ API documentation completed echo Validating OpenAPI specification... # Check if the spec exists and show basic info if [ -f openapi.yaml ]; then echo OpenAPI spec found at openapi.yaml grep -E ^(openapi:|info:|paths:) openapi.yaml | head -5 fi on_error: | echo ⚠️ Documentation error: {{error_message}} echo Check OpenAPI specification syntax三段钩子的工程意图pre_execution侦察先find出路由/控制器文件*.route.js、*.controller.js、routes.js确定待文档化的端点范围再探测是否已存在openapi.yaml/swagger.yaml/api.yaml——决定新建还是增量更新post_execution验收确认openapi.yaml存在后用grep -E ^(openapi:|info:|paths:)抽查三大顶层键是否齐备作为文档完整性的快速自检on_error诊断{{error_message}}模板占位符由运行期填充提示方向直接指向OpenAPI 规范语法。值得注意的细节该技能restricted_tools禁用了 Bash但这些钩子是平台侧生命周期脚本由 Codex 运行时按 config.toml 的[hooks]段执行pre_task true、post_task true与智能体自身可交互的工具白名单是两套机制——钩子提供确定性脚手架智能体在白名单内做判断性工作。3.7 examples触发示例与预期应答examples: - trigger: create OpenAPI documentation for user API response: Ill create comprehensive OpenAPI 3.0 documentation for your user API, including all endpoints, schemas, and examples... - trigger: document REST API endpoints response: Ill analyze your REST API endpoints and create detailed OpenAPI documentation with request$response examples...examples 是 few-shot 锚点用于让宿主智能体在路由阶段识别这句话应该命中该技能。再次提示request$response中的$为转义字符原文意图是 request/response examples。4. 执行提示正文职责、最佳实践与 OpenAPI 骨架SKILL.md 的 Markdown 正文第 129 行起是给智能体的系统提示结构为角色 → 职责 → 最佳实践 → 规范骨架 → 要素清单You are an OpenAPI Documentation Specialist focused on creating comprehensive API documentation.五大核心职责Key responsibilities创建符合 OpenAPI 3.0 的规范specification为所有端点撰写描述与示例准确定义请求/响应 schema包含认证与安全方案security schemes为所有操作operation提供清晰示例。六条最佳实践Best practices使用描述性的 summary 与 description附请求与响应示例文档化所有可能的错误响应用$ref即 OpenAPI 标准$ref引用可复用组件严格遵循 OpenAPI 3.0 规范用 tags 对端点做逻辑分组。OpenAPI 结构骨架原文档给出的最小可运行模板$ 为转义字符还原后如下openapi: 3.0.0 info: title: API Title version: 1.0.0 description: API Description servers: - url: https://api.example.com paths: /endpoint: get: summary: Brief description description: Detailed description parameters: [] responses: 200: description: Success response content: application/json: schema: type: object example: key: value components: schemas: Model: type: object properties: id: type: string这个骨架体现了职责与最佳实践的落地形态servers声明环境paths下每个方法带 summary/description 双层描述响应同时给出schema与example可复用模型集中放入components.schemas以便$ref引用。**文档要素清单Documentation elements**收尾清晰的 operation ID、请求/响应示例、错误响应文档、安全要求security requirements、限流信息rate limiting——其中限流与安全正是API 契约区别于普通接口清单的关键部分。5. SKILL.md 的生成与校验机制源码级佐证技能文件是手写还是生成v3/claude-flow/codex/src/generators/skill-md.ts 给出两种路径可帮助理解该文件的来源与约束generateSkillMd(options)从类型化选项name、description、version、tags、triggers、skipWhen、commands 等渲染一个全新 SKILL.md。frontmatter 格式与本技能一致namedescription: 折叠块并自动并入 Use when: ... 触发句正文固定为 Purpose / When to Trigger / When to Skip / Commands / Scripts / References / Best Practices 七节——agent-docs-api-openapi这类由 Claude Code agent 转写而来的技能内容更丰富超出了该模板的骨架属于以模板为起点的手工增强。generateBuiltInSkill(skillName)对内置技能BUILT_IN_SKILL_NAMES中的 6 个核心技能swarm-orchestration、memory-management、sparc-methodology、security-audit、performance-analysis、github-automation直接从包内.agents/skills树读取规范定义canonical definition使直接生成、项目初始化与 npm 产物三者不产生漂移源码注释原话。该模块还内置了安全校验readPayloadTree()拒绝技能目录中的符号链接与越界相对路径../或绝对路径直接抛错validateBuiltInSkillPayload()则用正则抽取 SKILL.md 中所有scripts/.../references/...本地引用逐一核对文件确实随技能树分发。这意味着技能文件的自包含性是被代码强制的——对agent-docs-api-openapi这类仅含单个 SKILL.md 的轻量技能校验天然通过而携带scripts/、docs/的技能则受同等约束。6. 实际使用方式与适用边界结合.agents/的文档与 config.toml在 Codex CLI 中使用该技能的完整链条是技能落位技能文件位于.agents/skills/agent-docs-api-openapi/SKILL.md。若项目经 Ruflo 初始化full/enterprise模板会把ALL_AVAILABLE_SKILLS中的技能含本技能拷贝进项目的.agents/skills/default模板则只装 4 个核心技能需要手动补充该目录。触发在 Codex CLI 会话中直接使用$agent-docs-api-openapi显式调用或在任务文本中命中 openapi、swagger、api documentation 等关键词或在openapi.yaml等文件存在时由触发器路由命中。平台约束叠加技能自身的 capabilities/constraints 之外config.toml 的sandbox_mode workspace-write、approval_policy on-request、[security]段的input_validation、path_traversal_prevention、secret_scanning、blocked_patterns会继续生效CI 场景可切到[profiles.ci]approval_policy never workspace-write。行为预期技能会先侦察路由文件与既有 specpre hook在docs/**、api/**、openapi/**、swagger/**或仓库级*.yaml/*.json内生成/更新 OpenAPI 3.0 文档写后抽查openapi:/info:/paths:顶层键post hook执行中删除文档或变更 API 版本前必须向用户确认。适用边界该技能面向OpenAPI 3.0文档max_file_size为 2MB不适合超大型拆分规范multi-file spec的跨文件重构它不生成代码、不执行测试Bash/Task 被禁验证手段仅限于钩子里的文本级抽查。若需要端点级语义分析按can_delegate_to: [analyze-api]的设计应由编排层委派专门的 API 分析智能体完成。7. 小结agent-docs-api-openapi是 Ruflo 智能体技能体系的一个标准样本一个 SKILL.md 同时承担了技能注册信息frontmatter、机器可读的智能体契约legacy YAML 块触发、工具白名单、路径围栏、确认点、钩子、协作关系、性能配额与执行提示OpenAPI 3.0 职责与最佳实践三重角色。它通过 templates/index.ts 的技能清单随full/enterprise模板分发通过 skill-md.ts 的 payload 校验保证自包含性并通过与dev-backend-api、test-integration的上下文共享嵌入实现—测试—文档流水线。对维护者而言理解这套字段语义尤其是triggers的四维触发、capabilities的工具白名单与constraints的路径围栏就能照着同一 schema 写出新的领域专家技能对使用者而言记住$agent-docs-api-openapi的调用语法与它的两条确认红线删文档、改版本即可在 Codex CLI 中安全地用它产出可交互的 API 文档。【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考