Archon 工作流按节点 Skills 指南：为每个 DAG 节点注入专属专业技能

Archon 工作流按节点 Skills 指南为每个 DAG 节点注入专属专业技能【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/ArchonArchon 的 DAG 工作流节点支持skills字段允许你为单个节点选择加载的专业知识代码评审规范、Remotion 实践、测试约定等而无需把这些技能广播给所有节点。本文将以官方 Per-Node Skills 文档 为主体结合仓库源码Claude 提供器实现、跨提供器技能解析器、Codex 提供器详解安装、声明、作用域隔离与各提供器的行为差异帮助你写出真正按节点精确注入的工作流。什么是 Per-Node Skills在 Archon 的 DAG 工作流里每个 AI 节点都可以携带一个skills列表。只有声明了该列表的节点才会把对应技能的上下文注入自己的提示词体系其他节点既看不到、也不会加载这些技能。这样你可以让review节点只加载代码评审技能让implement节点只加载编码规范技能避免把重量级技能塞进每个节点的上下文节省 token、提升速度把技能当作节点级的能力参数而不是全工作流共享的全局环境。技能的投放delivery是 provider 相关的Providerskills:字段行为Claude消费 per-node 列表走 Agent SDK 原生技能选择器Pi消费 per-node 列表跨.agents/skills/.claude/skills解析Copilot消费 per-node 列表同样走跨提供器解析Codex工作流节点上抑制自动技能目录必须用$skill-name显式调用OpenCode当前未实现顶层 YAML 字段在依赖跨提供器可移植行为之前务必先查阅 provider capability matrix。Quick Start从安装到节点引用以官方 Remotion 技能为例完整流程分两步。第一步安装技能npx skills add remotion-dev/skills该命令会把SKILL.md文件放到.claude/skills/remotion-best-practices/目录下这是npx skills的默认安装位置后面会详述全局与项目级区别。第二步在工作流中引用name: generate-video description: Generate a Remotion video nodes: - id: generate prompt: Create an animated countdown video skills: - remotion-best-practices节点 YAML 里的skills字段在 dag-node.ts 的节点 schema 中定义为z.array(z.string().min(1)).optional()——即字符串数组、每个技能名必须是非空字符串。工作流加载时节点规范化逻辑 还会对每个名字做trim()处理避免手误带入空白字符。Codex 需要额外一步显式调用。先安装到 Codex 的原生.agents/skills/根目录npx skills add remotion-dev/skills --agent codex --skill remotion-best-practices -y然后在工作流节点正文最好是命名命令文件中显式引用Use $remotion-best-practices to create the requested video.Codex 会加载原始的SKILL.md并相对安装目录解析其引用的脚本和资源。工作原理Claude 的原生技能选择链路在 Claude 提供器中节点声明的skills被直接透传给 Agent SDKYAML: skills: [remotion-best-practices] ↓ Claude SDK options: skills: [remotion-best-practices] strictMcpConfig: true ↓ SDK loads only the declared skill into the main-session system prompt对应的实现位于 Claude provider.tsoptions.skills nodeConfig.skills ?? []即省略字段与skills: []等价都不会选择任何技能非空列表则是该节点的精确允许列表exact allowlist只有列出的已安装技能会被注入主会话系统提示词。两条关键细节值得注意Skill工具自动保持启用当节点设置了allowed_tools时提供器会在工作流路径上把Skill重新加回工具列表见 provider.ts L569-L575 与 L638-L644因为 SDK 的原生技能选择要求Skill工具保持可用且其权限规则使用Skill(name)形式。你不需要手动在allowed_tools里补充它。settingSources默认保持[project, user]Archon 保留 Claude 正常的项目/用户设置来源CLAUDE.md与 agents 照常加载但不会因此把环境里的潜在技能ambient skills暴露给节点。声明在磁盘上的技能必须位于已启用的来源之下项目级技能要求启用project用户全局技能要求启用user。Archon 在启动 provider 之前就会做这项检查详见下文未解析名称的处理。安装技能的三种方式技能必须先安装到文件系统才能被节点引用。安装方式有三种。1. 通过 skills.sh市场# 安装到当前项目 npx skills add remotion-dev/skills # 全局安装所有项目可用 npx skills add remotion-dev/skills -g # 从多技能仓库安装指定技能 npx skills add anthropics/skills --skill skill-creator # 搜索技能 npx skills find database2. 通过 GitHub# 公开仓库 npx skills add owner/repo # 仓库内指定路径 npx skills add owner/repo/path/to/skill # 私有仓库使用 SSH 密钥或 GITHUB_TOKEN npx skills add gitgithub.com:org/private-skills.git3. 手动创建在.claude/skills/下创建目录内含SKILL.md文件.claude/skills/my-skill/ └── SKILL.mdSKILL.md使用 YAML frontmatter 声明技能名与描述正文是技能激活后注入给 Agent 的指令--- name: my-skill description: What this skill does and when to use it --- # Instructions Step-by-step content here. The agent loads this when the skill activates.技能发现目录与 settingSources技能从以下位置被发现这是ClaudeProvider中默认的settingSources: [project, user]契约LocationScope.claude/skills/当前工作目录下项目级~/.claude/skills/用户级所有项目这一契约在 shared/skills.ts 的claudeSkillSearchRoots中实现项目级根为cwd/.claude/skills用户级根为CLAUDE_CONFIG_DIR未设置时取~/.claude下的skills。Claude 的命令行并不发现跨提供器通用的.agents/skills约定因此 Archon 特意为 Claude 保留了这组更窄的搜索根。若希望同时排除用户级指令与 agents可在.archon/config.yaml中设置assistants: claude: settingSources: [project]此时技能选择在节点上仍然是精确的但用户全局技能在user来源被禁用后不再可用。顺带一提Pi 与 Copilot 走的是更宽的兼容解析器skillSearchRoots见 shared/skills.ts L55-L66查找顺序为cwd/.agents/skills/→cwd/.claude/skills/→~/.agents/skills/→~/.claude/skills/同名时首个命中者胜出。该解析器刻意不做祖先目录向上遍历与 Pi 的 cwd 边界语义保持一致。无论哪个提供器解析都遵循name-only 契约拒绝路径穿越、嵌套路径与绝对路径见 resolveSkillDirectories 实现。作用域Installed 与 Active 的区别Installed已安装技能存在于磁盘上某个 provider 原生目录下。Active激活技能被列在某个 DAG 节点的skills:中只有该节点会把技能内容注入其上下文。nodes: - id: classify prompt: Classify this task # No skills — fast, cheap, no extra context - id: implement prompt: Write the code skills: [code-conventions, testing-patterns] # Gets both skills injected — deeper domain knowledge - id: review prompt: Review the code skills: [code-review] # Gets a different skill — review-focused expertise三个技能都已安装在磁盘上但每个节点只加载自己声明的那部分。这正是 Stripe Minions 原则的体现agents perform best when given a smaller box with a tastefully curated set of tools——给 Agent 一个更小的盒子、一小组精心挑选的工具效果最佳。热门技能速查SkillInstallWhat It Teachesarchon-cli内置archon skill install通过 CLI 运行、管理、配置和编写 Archon 工作流remotion-best-practicesnpx skills add remotion-dev/skillsRemotion 动画模式、API 用法、常见坑35 条规则skill-creatornpx skills add anthropics/skills如何创建新的 SKILL.md 文件社区技能浏览 skills.sh 市场按领域检索海量社区技能每个节点多个技能一个节点可以声明多个技能它们会被全部注入- id: implement prompt: Build the feature skills: - code-conventions - testing-patterns - api-design保持列表精简。Claude 会把每个选中的技能都加载进主会话系统提示词未列出的已安装技能不会暴露给该工作流节点。从源码实现看跨提供器的解析会做去重duplicate names are de-duped见 shared/skills.ts重复声明不会造成重复注入。技能与 MCP 的组合技能与 MCP 在同一节点上自然组合- id: create-pr prompt: Create a PR with the changes skills: - pr-conventions # Teaches HOW to write good PRs mcp: .archon/mcp/github.json # Provides the GitHub tools技能教的是流程processMCP 提供的是能力capability。二者结合的效果优于单独使用任一方。更多 MCP 节点配置见 Per-Node MCP Servers 指南。Codex 兼容性显式调用优先Codex 支持通过原生文件系统发现已安装技能来源为project/.agents/skills/与用户级 Codex 根目录但它不会原生发现.claude/skills/。对每一个 Codex 支持的工作流 AI 节点Archon 都会禁用自动技能目录automatic skill catalog。在 Codex provider 实现 中工作流节点会通过skills: { include_instructions: false }抑制目录这防止了描述匹配机制自发选中某个无关的环境技能。直接使用 Codex 聊天及其他非工作流调用保持正常 Codex 行为。具体兼容性规则必须显式调用—— 在命令文件或提示词中写Use $skill-name to ...。Codex 会做渐进式披露progressive disclosure从其原始目录加载所选技能。YAMLskills:不是 Codex 的激活机制—— 非空列表不会重新启用自动目录、不会注入元数据、也不会创建排他允许列表它会被忽略并发出警告。若另一个选中的 provider 需要该列表可以保留但为了 Codex 的可移植性仍需写显式$skill-name调用。省略与skills: []—— 在 Codex 工作流节点上都保持自动目录关闭精确加载型 provider 会把[]视为空声明集合。SKILL.md 格式—— Codex 解析与 Claude Code 相同的name/descriptionfrontmatter。技能正文中 Claude 特有的!bash执行行在 Codex 中会被当作字面文本不报错、不执行。这是行为边界不是文件系统安全—— 显式请求某个环境技能$skill-name仍可能激活它。Archon 阻止的是自动宣传不会隐藏或移动文件。未来外部二进制—— 如果某个 Codex 版本拒绝目录抑制配置Archon 会警告并继续以原生发现方式运行而不会拒绝整个 run对应实现见 codex/provider.ts 的兼容性回退分支。需要说明的是普通仓库指令如AGENTS.md在目录关闭时依然生效。$skill-name的调用细节还可以参考 authoring-commands 指南 中的命令文件写法。限制与边界必须预先安装—— 磁盘上的技能必须在工作流运行前存在目前没有按需拉取on-demand fetching能力。provider 原生路径—— Claude 的声明只能从项目/用户的.claude/skills/解析Archon 不会把.agents/skills/复制进 Claude 的根目录。容器工作流—— 隔离运行器中只有项目本地.claude/skills/可见。宿主机上的用户全局技能必须先安装到项目里容器节点才能声明它否则 Archon 会在产生 provider 费用之前就失败。provider 语义不同—— 请查阅 capability matrixCodex 使用显式$skill-name调用而非 YAML 列表注入。未解析名称的处理Claude 如何区分两种情形Archon 区分两种情况因为 Claude 的技能命名空间大于文件系统声明的名称Archon 的响应已安装但不在某个已启用设置来源覆盖的.claude/skills/目录中——例如只存在于.agents/skills/或存在于user作用域但settingSources: [project]花费前报错Error before spend。Claude 显然无法加载它修复方式是调整路径。任何技能目录中都不存在警告run 继续。Claude 自带的内置技能和plugin 限定名plugin:skill存在于任何技能目录之外因此 Archon 让 SDK 自行解析。拼写错误也落在这里——会被报告而 Claude 会忽略未知名称而不是加载它。这一分支在 Claude provider.ts 的预检逻辑 中实现先用resolveClaudeSkillDirectories解析已安装但不可达unreachable的名称再通过findInstalledSkillNames区分装在了别处与磁盘上完全不存在分别对应claude.declared_skills_unreachable与claude.declared_skills_unresolved两类结果。内置技能与插件技能因此可以像已安装技能一样在 Claude 节点上直接声明。Troubleshooting 速查表ProblemCauseFixClaude skill not found报错已安装但在未启用的.claude/skills/根之外移动到.claude/skills/name/SKILL.md或启用持有它的设置来源Claude skill not found警告磁盘上不存在——内置技能与plugin:skill名称的正常状态对这些名称可忽略否则检查拼写或运行npx skills add sourceCodex 不使用某技能工作流节点自动目录已关闭在命令/提示词中用$skill-name显式调用并安装到 Codex 原生根如.agents/skills/Codex 对skills:发出警告Codex 未实现 YAML 列表仅为其他 provider 保留该列表对 Codex 使用$skill-name技能太多超出上下文预算每个节点精简到 2-3 个最相关技能技能没有效果描述过于含糊用具体、可操作的指令重写 SKILL.md结语Per-Node Skills 是 Archon 工作流作者精细化控制节点能力的关键机制安装一次、按节点声明、由 provider 各自投递。理解 Claude 的精确 allowlist 与Skill工具自动保留、Pi/Copilot 的跨提供器解析顺序以及 Codex 的显式$skill-name契约你就能写出既节省上下文预算、又具备跨提供器可移植性的高质量工作流。本文涉及的更多周边能力可继续阅读Inline sub-agentsagents:字段与原生 per-node 技能选择独立组合、Per-Node MCP Serversmcp:外部工具接入、Hookshooks:工具权限控制以及 provider capability matrix跨提供器能力对照。【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考