Core categories

Core gives content six roles, called categories. Each category answers one question. To place something, pick the category whose question it answers. The table shows the loading rules when a category is present. Installation lets you select the built-in routes you need.

This illustrative Directive requires behavior. It is not a shipped testing policy. Use your workspace's selected frontmatter form when copying:

.agents/directives/testing.md (illustrative)

---
description: Run tests before finishing a code change
tags: [Directive, LoadNow]
---

# Test code changes

## Instructions

- Run the project's tests before calling a code change done.

This is a Directive because it requires behavior. A Pattern would show a reusable shape instead, such as an API response. The table below helps you choose the role.

Category	Question it answers	At startup
Directives	What behavior is required in this scope?	Entrypoint at startup, plus its Directive files
Guidance	What approach is recommended, and when does it fit?	Entrypoint at startup
Patterns	What reusable shape makes related work easy to create and inspect?	Entrypoint at startup
Skills	Which specialized capability would help with this work?	Entrypoint and CLI usage Skill at startup
Templates	What starting content can be copied, adapted, and maintained independently?	Entrypoint on demand
Maps	Where is a useful local or external source, and when should it be used?	Entrypoint at startup

"Entrypoint at startup" means the agent reads the category's purpose, rules, and one line per item. Linked items open when selected, tagged to load, or required by a loaded rule. Directives directly in directives/ must carry #LoadNow, and the Skills rules require the CLI usage guide. "Entrypoint on demand" means the entrypoint itself waits until selected. Loading and tags lists every startup file.

In a fresh install, each selected category entrypoint lists no items except Skills, which lists open-forge-cli. You or an Extension add the rest.

Directives

Required behavior. A Directive is a rule the agent must follow within its scope.

State the required action, its conditions, and meaningful exceptions in the instructions. Examples can clarify a rule, but the obligation remains understandable from the instructions themselves.

• Every Directive file directly in a Directives folder must carry #LoadNow, because it's mandatory there. Without the tag, it stays on demand.
• Each Directive file keeps its required Instructions under a non-empty ## Instructions heading.
• Files in the root directives/ folder apply to the whole workspace. A scoped folder like directives/frontend/ loads only when selected, and its Directives then add to the root ones. A narrower Directive never cancels a broader one.

Use a Directive when behavior is mandatory in a scope, such as a correction you keep repeating. If the right approach depends on the situation, use Guidance instead.

Guidance

Recommended approaches. Guidance explains a recurring situation, the recommended approach, why it works, and its tradeoffs. Unlike a Directive, it can be adapted when another approach fits better, and the agent explains the difference when it matters.

Patterns

Reusable shapes. A Pattern defines a concrete, inspectable shape: how an API response looks, how a test file is organized, where a component's files live. Each Pattern covers one shape.

Show the expected result as the main content through a concrete example, folder tree, table, diagram, or annotated outline. A reviewer given the Pattern and real code or files should be able to compare their structure. Brief notes explain when it applies, label required, optional and repeatable parts and their nesting and relationships, and say which names, values and orders are fixed or only illustrative.

Shared shapes make related work consistent and easier to inspect. In review, work that departs from the local Pattern stands out.

Link related sources for required rules, advice, maps, procedures, and starting files, and say which of them bind the shape. Sources that use a shape should link back to its Pattern, so readers can find the shape from either direction. Required behavior and procedures stay in their defining sources.

A Pattern is the default shape in its scope. A justified departure is allowed, and the agent explains material departures before other work depends on them. A justified adaptation is still a departure, so a review reports it separately from conformance. When a Directive makes a shape mandatory, the agent follows the Directive.

Skills

Specialized capabilities. A Skill is a native capability package entered through a SKILL.md file. The SKILL.md defines how to use the Skill and its resources. Your agent runtime controls how Skills are installed, activated, invoked, and executed.

Open Forge routes to Skills so agents can find them. It doesn't replace your harness's own Skill mechanism. The base ships one Skill, open-forge-cli, which teaches an agent when and how to use the CLI. The Skills entrypoint explicitly requires reading that usage guide at startup. Other Skills stay on demand. Repeatable methods live behind use-workflow, supplied by the Workflow Support Extension.

Templates

Copy-ready starting files. Copy a Template, adapt it, then maintain the result independently. Later changes to the Template never update copies made from it.

Keep only useful sections and detail while preserving the destination's required structure. Optional prompts help you choose what belongs in the result. They do not require you to fill every section.

The Templates entrypoint stays on demand, and a fresh install ships no Templates. Core Templates adds one starter per Core category, plus one for Memory. Other Extensions add Templates for their own records, and you can write your own.

Maps

Pointers to important sources. A Map links to local or external sources and says what they contain and when to use them: the architecture document, the API reference, a sibling repository. Maps stay broad. They point to the source and don't replace it.

Telling them apart

• Required or recommended? Required is a Directive. Recommended is Guidance.
• A shape or a procedure? A shape is a Pattern. A step-by-step procedure is a workflow recipe behind the use-workflow Skill from Workflow Support.
• Ongoing or one-time? A Directive or Pattern keeps guiding related work. A Template is starting content you copy once.
• Content or a pointer? Content lives in its own file. A pointer to where content lives is a Map.
• Something to remember? That's Memory, not a Core category. Writing an instruction into Memory doesn't make it a Directive.

Next: Memory.