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

> Understand OpenMontage's three-layer knowledge architecture: Tool definitions, orchestration Skills, and Agent Skills. Learn the reading order for efficient agent invocation.

- Repository: [Calesthio/OpenMontage](https://github.com/calesthio/OpenMontage)
- Tags: architecture
- Published: 2026-08-30

---

**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`](https://github.com/calesthio/OpenMontage/blob/main/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`](https://github.com/calesthio/OpenMontage/blob/main/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`](https://github.com/calesthio/OpenMontage/blob/main/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`](https://github.com/calesthio/OpenMontage/blob/main/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:

```python

# 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`](https://github.com/calesthio/OpenMontage/blob/main/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`](https://github.com/calesthio/OpenMontage/blob/main/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`](https://github.com/calesthio/OpenMontage/blob/main/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`](https://github.com/calesthio/OpenMontage/blob/main/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`](https://github.com/calesthio/OpenMontage/blob/main/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`](https://github.com/calesthio/OpenMontage/blob/main/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`](https://github.com/calesthio/OpenMontage/blob/main/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`](https://github.com/calesthio/OpenMontage/blob/main/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`](https://github.com/calesthio/OpenMontage/blob/main/PROJECT_CONTEXT.md), which describes how these layers interconnect to form the complete OpenMontage knowledge hierarchy.