Skip to main content

Macros

There is no macros: block in the canonical schema. AppDefinition (extra: forbid) declares exactly 8 top-level blocks: app, runtime, agents, tools, security, ui, dev, flow. Any other top-level key is rejected by Pydantic at compile time. This page is a redirect: it points at the existing blocks that cover the use cases the term "macros" suggests.

Earlier drafts of this page described a macros: block with parameters, action steps, branching, and nested macros. That feature was never implemented and is not part of the schema_version: 2 language.

What you probably want​

Three Digitorn features cover the use cases that "macros" suggested:

Reusable commands → Skills​

For commands the user can invoke (/commit, /review, /audit), declare them under dev.skills. Each skill is a markdown file in the bundle's skills/ directory; the agent reads the file when the command is called.

dev:
  skills:
    - command: /commit
      description: "Stage + commit + push the current diff"
      path: skills/commit.md
    - command: /review
      description: "Adversarial code review with focus on security"
      path: skills/review.md

Full reference: Skills System.

Reusable orchestration → Flows​

For deterministic graphs (triage → specialist → approval → output), use the flow: block. Flow nodes (agent, tool, parallel, approval, decision, terminal) compose the same way macros were intended to - but with a fully implemented runtime, schema validation, and reachability checks.

Reusable prompt fragments → Bundle namespaces​

For sharing prompt content across agents, use the filesystem-backed namespaces ({{prompt.X}}, {{skill.X}}, {{behavior.X}}, {{include:path}}) - verified in App Configuration → Variables and documented further in Bundle namespaces.

agents:
  - id: assistant
    system_prompt: |
      You are an assistant.
      {{prompt.guidelines}}        # inlines prompts/guidelines.md
      {{include:./shared/header.md}}  # explicit path import

Multi-step workflows → Sub-agents​

For composable multi-step flows where each step is itself an agent turn, use the multi-agent pattern via Agent(...) - coordinator spawns specialists. See Multi-Agent.

Cross-references​