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/Archon

Archon 的 DAG 工作流节点支持skills字段，允许你为单个节点选择加载的专业知识（代码评审规范、Remotion 实践、测试约定等），而无需把这些技能广播给所有节点。本文将以官方 Per-Node Skills 文档 为主体，结合仓库源码（Claude 提供器实现、跨提供器技能解析器、Codex 提供器）详解安装、声明、作用域隔离与各提供器的行为差异，帮助你写出真正"按节点精确注入"的工作流。

什么是 Per-Node Skills

在 Archon 的 DAG 工作流里，每个 AI 节点都可以携带一个skills列表。只有声明了该列表的节点，才会把对应技能的上下文注入自己的提示词体系；其他节点既看不到、也不会加载这些技能。这样，你可以：

• 让review节点只加载代码评审技能，让implement节点只加载编码规范技能；
• 避免把重量级技能塞进每个节点的上下文，节省 token、提升速度；
• 把"技能"当作节点级的能力参数，而不是全工作流共享的全局环境。

技能的投放（delivery）是 provider 相关的：

在依赖跨提供器可移植行为之前，务必先查阅 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 SDK：

YAML: 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.ts：options.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 "database"

2. 通过 GitHub

# 公开仓库 npx skills add owner/repo # 仓库内指定路径 npx skills add owner/repo/path/to/skill # 私有仓库（使用 SSH 密钥或 GITHUB_TOKEN） npx skills add git@github.com:org/private-skills.git

3. 手动创建

在.claude/skills/下创建目录，内含SKILL.md文件：

.claude/skills/my-skill/ └── SKILL.md

SKILL.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']契约）：

这一契约在 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 一个更小的盒子、一小组精心挑选的工具，效果最佳。

热门技能速查

每个节点多个技能

一个节点可以声明多个技能，它们会被全部注入：

- 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

技能教的是流程（process），MCP 提供的是能力（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 matrix：Codex 使用显式$skill-name调用而非 YAML 列表注入。

未解析名称的处理：Claude 如何区分两种情形

Archon 区分两种情况，因为 Claude 的技能命名空间大于文件系统：

这一分支在 Claude provider.ts 的预检逻辑 中实现：先用resolveClaudeSkillDirectories解析已安装但"不可达（unreachable）"的名称，再通过findInstalledSkillNames区分"装在了别处"与"磁盘上完全不存在"，分别对应claude.declared_skills_unreachable与claude.declared_skills_unresolved两类结果。内置技能与插件技能因此可以像已安装技能一样在 Claude 节点上直接声明。

Troubleshooting 速查表

结语

Per-Node Skills 是 Archon 工作流作者精细化控制节点能力的关键机制：安装一次、按节点声明、由 provider 各自投递。理解 Claude 的精确 allowlist 与Skill工具自动保留、Pi/Copilot 的跨提供器解析顺序，以及 Codex 的显式$skill-name契约，你就能写出既节省上下文预算、又具备跨提供器可移植性的高质量工作流。本文涉及的更多周边能力可继续阅读：Inline sub-agents（agents:字段，与原生 per-node 技能选择独立组合）、Per-Node MCP Servers（mcp:外部工具接入）、Hooks（hooks:工具权限控制），以及 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