OpenMontage Three-Layer Knowledge Architecture: Tools, Skills, and Agent Skills Explained

The OpenMontage three-layer knowledge architecture separates Tool definitions (Layer 1), orchestration Skills (Layer 2), and vendor-specific Agent Skills (Layer 3), requiring agents to read them in that strict sequence before invoking any generation capability.

OpenMontage is an open-source generative media orchestration framework that structures its operational knowledge into a hierarchical three-layer system. This design ensures agents possess complete contextual awareness—from high-level pipeline workflows down to specific model parameters—before invoking any API call. The architecture is formally documented in AGENT_GUIDE.md and implemented across the tools/, skills/, and .agents/skills/ directories.

The Three Knowledge Layers

OpenMontage partitions its instruction set into distinct layers that separate what exists from how to use it and how to optimize specific vendor implementations. This separation keeps the system modular and makes it easy to add new tools or providers without disrupting existing orchestration logic.

Layer 1 – Tools (The Registry)

The Tools layer serves as the source of truth for available capabilities on the machine. Located in the tools/ directory, this layer describes every concrete tool that can be called, including its cost, runtime characteristics, fallback options, and related skills.

According to the source code in tools/tool_registry.py, the registry exposes methods like discover(), get_by_capability(), and provider_menu_summary() that agents use to enumerate available tools. Each tool definition includes an agent_skills field that points to its corresponding Layer 3 vendor skill, ensuring the agent knows exactly which low-level instructions to load before execution.

Layer 2 – Skills (Orchestration Logic)

The Skills layer encodes how OpenMontage wants tools orchestrated inside pipelines. Located in skills/, this layer contains director skills for each pipeline stage that specify workflow requirements, quality bars, and artifact contracts.

For example, the talking-head pipeline references skills/pipelines/talking-head/script-director.md to define the script generation stage. These director skills operate at the orchestration level, determining when to invoke specific tools and what quality standards to enforce, without delving into specific API parameters or vendor quirks.

Layer 3 – Vendor Skills (Implementation Details)

The Vendor Skills layer holds low-level, provider-specific prompting guidance and parameter tuning. Located in .agents/skills/, these files contain the exact prompt formats, model-specific parameters, and quality-enhancement techniques required for actual API calls.

Every generation tool lists an agent_skills field pointing to one of these vendor skills. As implemented in the OpenMontage source code, this field must be read before any API call is made, ensuring the agent applies the correct temperature settings, token limits, and vendor-specific prompt engineering.

The Mandatory Reading Order

Agents must follow a strict three-step reading sequence defined in AGENT_GUIDE.md【AGENT_GUIDE.md†L60-L66】. This ensures no tool is called "blindly" without proper contextual preparation.

1. Discover the tool contract – Query the Layer 1 registry to identify available tools and capabilities using registry.get_by_capability().
2. Load the director skill – Read the relevant Layer 2 pipeline skill to understand workflow requirements and quality bars.
3. Load the vendor skill – Access the Layer 3 .agents/skills/ file referenced by the tool's agent_skills field to obtain vendor-specific parameters.

The following Python implementation illustrates this pattern using the actual OpenMontage registry structure:

# Step 1: Discover available tools (Layer 1)

from tools.tool_registry import registry

registry.discover()
video_tool_info = registry.get_by_capability("video_generation")[0]
print(f"Selected provider: {video_tool_info['provider']}")

# Step 2: Load pipeline director skill (Layer 2)

# Example: talking-head pipeline script director

with open("skills/pipelines/talking-head/script-director.md") as f:
    script_director = f.read()
print(f"Stage guidance loaded: {len(script_director)} characters")

# Step 3: Read vendor-specific skill (Layer 3)

vendor_skill_path = video_tool_info["agent_skills"]
with open(vendor_skill_path) as f:
    vendor_skill = f.read()
print(f"Vendor parameters loaded: {vendor_skill.splitlines()[0]}")

This sequence guarantees that agents possess the high-level intent (Layer 2) and low-level vendor instructions (Layer 3) before executing any generation task.

Key Files and References

The three-layer architecture is implemented across these critical source files:

• AGENT_GUIDE.md – Documents the Layer Map【AGENT_GUIDE.md†L49-L58】 and defines the mandatory reading order for all agents.
• tools/tool_registry.py – Implements Layer 1 with discover(), get_by_capability(), and provider_menu_summary() methods.
• skills/pipelines/<pipeline>/<stage>-director.md – Contains Layer 2 director skills (e.g., skills/pipelines/talking-head/script-director.md).
• .agents/skills/<vendor>/<skill>.md – Houses Layer 3 vendor-specific instructions referenced via the tool agent_skills field.

Summary

• OpenMontage structures operational knowledge into three hierarchical layers: Tools (Layer 1), Skills (Layer 2), and Agent/Vendor Skills (Layer 3).
• Layer 1 (tools/) provides the registry of available capabilities via tool_registry.py, including agent_skills pointers to Layer 3.
• Layer 2 (skills/) contains orchestration logic and pipeline director skills defining workflow requirements and quality standards.
• Layer 3 (.agents/skills/) holds vendor-specific implementation details including prompt templates and model parameters.
• Reading order is strictly enforced: Tools → Skills → Vendor Skills, ensuring agents never execute API calls without proper contextual preparation as specified in AGENT_GUIDE.md.

Frequently Asked Questions

What happens if an agent skips Layer 3 and calls the tool directly?

Skipping Layer 3 violates the OpenMontage safety contract. Without reading the vendor skill in .agents/skills/, the agent lacks critical model-specific parameters, prompt templates, and quality optimizations required for successful generation. The AGENT_GUIDE.md explicitly prohibits blind tool invocation and mandates reading the vendor skill before any API call【AGENT_GUIDE.md†L60-L66】.

How does the tool registry connect Layer 1 to Layer 3?

The tool_registry.py implementation includes an agent_skills field in every tool definition returned by get_by_capability(). This field contains the file path to the corresponding Layer 3 vendor skill, creating a strict linkage between discovery and implementation details that agents must resolve before execution.

Can developers add new tools without modifying Layer 2 or Layer 3?

Yes. Developers can register new tools in Layer 1 by updating the registry, provided they either reference existing vendor skills via agent_skills or create new files in .agents/skills/ (Layer 3). Layer 2 skills only need modification if the new tool requires changes to existing pipeline workflows or if creating entirely new pipeline stages that demand new director skills.

Where is the three-layer architecture formally documented?

The architecture is formally defined in AGENT_GUIDE.md, specifically in the Layer Map section【AGENT_GUIDE.md†L49-L58】 and the Reading Order section【AGENT_GUIDE.md†L60-L66】. Additional context appears in PROJECT_CONTEXT.md, which describes how these layers interconnect to form the complete OpenMontage knowledge hierarchy.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}