Per-Node Skills

DAG workflow nodes support a skills field that preloads named skills into the node’s agent context. Each node gets specialized procedural knowledge — code review patterns, Remotion best practices, testing conventions — without polluting other nodes.

Both Claude and Codex support skills. Claude injects per-node skills via the SDK’s AgentDefinition.skills field (only listed skills are loaded for that node). Codex auto-discovers skills from the filesystem (.agents/skills/), so every installed skill is available on every Codex node — the YAML skills: list is informational for Codex.

Quick Start

1. Install a skill (e.g., the official Remotion skill):

npx skills add remotion-dev/skills

This places SKILL.md files in .claude/skills/remotion-best-practices/.

2. Reference it in your workflow:

name: generate-video
description: Generate a Remotion video
nodes:
  - id: generate
    prompt: "Create an animated countdown video"
    skills:
      - remotion-best-practices

That’s it. The skill’s content is injected into the agent’s context when the node runs. The agent can reference the skill’s knowledge (animation patterns, API usage, gotchas) without the user having to paste instructions into the prompt.

How It Works

When a node has skills: [name, ...], the executor wraps it in an AgentDefinition — the Claude Agent SDK mechanism for scoping skills to subagents.

YAML: skills: [remotion-best-practices]
  ↓
Executor builds AgentDefinition:
  {
    description: "DAG node 'generate'",
    prompt: "You have preloaded skills: remotion-best-practices...",
    skills: ["remotion-best-practices"],
    tools: [...nodeTools, "Skill"]
  }
  ↓
SDK loads skill content into agent context at startup
  ↓
Agent executes with full skill knowledge available

The Skill tool is automatically added to allowedTools so the agent can invoke skills. You don’t need to add it manually.

Installing Skills

Skills must be installed on the filesystem before they can be referenced.

From skills.sh (marketplace)

# Install to current project
npx skills add remotion-dev/skills

# Install globally (all projects)
npx skills add remotion-dev/skills -g

# Install a specific skill from a multi-skill repo
npx skills add anthropics/skills --skill skill-creator

# Search for skills
npx skills find "database"

From GitHub

# Public repo
npx skills add owner/repo

# Specific path in repo
npx skills add owner/repo/path/to/skill

# Private repo (uses SSH keys or GITHUB_TOKEN)
npx skills add git@github.com:org/private-skills.git

Manual

Create a directory in .claude/skills/ with a SKILL.md file:

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

SKILL.md format:

---
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.

Skill Discovery

Skills are discovered from these locations (via the default settingSources: ['project', 'user'] set in ClaudeProvider):

Location	Scope
.claude/skills/ (in cwd)	Project-level
~/.claude/skills/	User-level (all projects)

Set assistants.claude.settingSources: ['project'] in .archon/config.yaml to scope a workflow to project-level skills only.

Skills installed via npx skills add land in .claude/skills/ by default. Use -g for global installation to ~/.claude/skills/.

Scoping: Installed vs Active

Installed = the skill exists on disk. It’s discoverable by the Claude subprocess.

Active = listed in skills: on a specific DAG node. Only THAT node gets the skill content injected into its context.

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

All three skills are installed on disk. But each node only loads what it needs. This follows the Stripe Minions principle: “agents perform best when given a smaller box with a tastefully curated set of tools.”

Popular Skills

Skill	Install	What It Teaches
archon (bundled)	archon skill install	Archon workflows, commands, and project conventions
manage-run (bundled)	archon skill install	Inspect and control workflow runs via the archon CLI (focused run-management skill)
remotion-best-practices	npx skills add remotion-dev/skills	Remotion animation patterns, API usage, gotchas (35 rules)
skill-creator	npx skills add anthropics/skills	How to create new SKILL.md files
Community skills	Browse skills.sh	Search 500K+ skills for any domain

Multiple Skills Per Node

A node can have multiple skills. All are injected:

  - id: implement
    prompt: "Build the feature"
    skills:
      - code-conventions
      - testing-patterns
      - api-design

Keep it concise — each skill’s full content is injected into context at startup (not progressive disclosure). The agentskills.io spec recommends keeping SKILL.md under 500 lines / 5000 tokens.

Combining Skills with MCP

Skills and MCP compose naturally on the same node:

  - 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

Skills teach the process. MCP provides the capability. Together they produce better results than either alone.

Codex Compatibility

Codex supports skills via filesystem auto-discovery from <project>/.agents/skills/ (its canonical project-level skill path). After running archon skill install — or archon setup, which installs them automatically — both Claude Code and Codex pick up the bundled archon and manage-run skills with no further setup.

Important differences vs Claude:

• Auto-discovery, not per-node injection — Codex loads every skill present under .agents/skills/. The skills: list in YAML is informational for Codex nodes; Codex does not scope skills per node.
• No SDK-level skill activation — Archon does not pass skills: to the Codex SDK. Skills work entirely through filesystem discovery.
• SKILL.md format — Codex parses the same name/description frontmatter as Claude Code. Any Claude-specific !bash execution lines in a skill body are treated as literal text by Codex (no error, no execution).

To opt out of a skill on Codex, remove it from .agents/skills/. To force per-node scoping, use provider: claude on the node — Claude honors the skills: list strictly.

Limitations

• Pre-installation required — skills must exist on disk before the workflow runs. There is no on-demand fetching (yet).
• Per-node scoping is Claude-only — Claude honors the YAML skills: list via the SDK’s AgentDefinition.skills field. Codex auto-discovers all installed skills from .agents/skills/; for Codex the skills: list is informational and every installed skill is available on every node.
• Full injection — skill content is fully injected at startup, not progressively disclosed. Keep skills concise.
• No validation — if a named skill doesn’t exist, the SDK may fail silently. Verify skills are installed with npx skills list.

Troubleshooting

Problem	Cause	Fix
Skill not found	Not installed	Run npx skills add <source> (or archon skill install for the bundled Archon skills)
Skill loads on wrong node	Codex auto-discovers all installed skills; the skills: list is informational for Codex	Use provider: claude to scope per-node, or remove the skill from .agents/skills/
Too many skills	Context budget exceeded	Reduce to 2-3 most relevant skills per node
Skill has no effect	Description too vague	Rewrite SKILL.md with specific, actionable instructions

Related

• Inline sub-agents — agents: field for workflow-scoped sub-agents (composes with skills: on the same node; user-defined agents win on ID collision with the internal dag-node-skills wrapper)
• Per-Node MCP Servers — mcp: field for external tool access
• Hooks — hooks: field for tool permission control
• skills.sh — marketplace for discovering skills
• agentskills.io — the open SKILL.md standard