Authoring instructions
Building effective workflows is about giving Assistant clear direction. The more specific and structured your workflow design, the more consistent and reliable your results will be.
This guide covers proven practices for creating workflows that deliver high-quality, repeatable results.
Workflow Builder agent is trained on these practices and can help you apply them. Describe what you want to automate and the assistant will draft well-structured instructions, suggest requested files, and help you iterate on the design. You can also paste your existing instructions into the conversation and ask the assistant to review or improve them.
Core Principle: Self-Contained Instructions
Workflow logic belongs in the Instructions field, not in Linked Artifacts.
Don't split your workflow's behavior across artifacts and instructions. The Instructions field should be the complete, self-contained source of what the workflow does and how it does it.
When instructions live in artifacts, problems arise:
- The agent must read and interpret the artifact before starting, adding latency
- If the artifact is modified, behavior may change unexpectedly
- Workflow logic becomes harder to review and maintain
If you find yourself writing step-by-step procedures, checklists, or workflow phases in an artifact, move them to the Instructions field instead.
Structure Your Instructions
A well-structured Instructions field follows five sections:
1. Role Statement
Start with a brief identity statement (1–2 sentences) that tells Assistant what it does and what quality to prioritize:
"You are an assistant made by Nomic created to check drawings against an internal standards document. It is important that you are thorough and careful in your drawing check."
Avoid persona-only descriptions that say WHO the assistant is but not WHAT to do or HOW:
Avoid: "You are a senior principal architect/engineering assistant tasked with analyzing contractor submittals."
The second example describes a persona but provides no actionable workflow. Always pair the role with specific instructions.
2. Output Format
Define the exact format for results before the workflow steps. This ensures Assistant knows what it's building toward from the start.
- Specify table columns with headers
- Provide citation format with concrete examples
- Explain what each column should contain
For example:
"Present findings in a markdown table with these columns: Drawing Page Number, Standard Requirement, Observed Violation, Standard Citation. The Drawing Page Number should be a markdown link with a citationId to the page."
Defining the output format before the steps helps Assistant structure its work from the beginning, rather than reformatting at the end.
3. Numbered Steps with Clear Objectives
Break down the workflow into numbered steps, each with a stated objective:
## Step 1
Objective: Read and understand the submittal document.
## Step 2
Objective: Search specifications for relevant requirements.
## Step 3
Objective: Compare submittal against specifications and record findings.
For complex steps, include procedural sub-bullets describing specific actions to take.
4. Tool Instructions
Be explicit about which tools to use and how to use them. Name the specific tools — don't use generic descriptions like "use your tools to analyze the document."
Good tool instructions include:
- The exact tool name (e.g., "Use the drawing judge tool to verify violations")
- Tool capacity and limits (e.g., "You can ask the drawing judge up to twenty questions at a time")
- What to include in tool calls (e.g., "Quote the standard in each question so it is made aware of the context")
5. Verification Step
If accuracy and thoroughness matter, include a final step that double-checks completeness:
"Step 5: Verify that every drawing in the set has been checked. If any are missing, repeat the review for those drawings. Otherwise, write a brief summary alerting the user to the updated Results Table."
The clearer your instructions, the more consistent your results. If you find yourself explaining the workflow to colleagues, that explanation belongs in your instructions.
Use Sub-Agents for Parallel, Scoped Work
Workflows can dispatch multiple sub-agents in parallel—often one per issue class or scoped task. For drawing sets, those sub-agents hunt for issues across the set (cross-referencing sheets as needed); they are not a shortcut for handing each sheet to a separate sub-agent from start to finish.
When designing workflows that use sub-agents:
- Sub-agents are powerful but can be expensive. Cost scales with how much analysis runs—parallel hunts, large sets, or many dispatches add work. When testing a new workflow, start with a narrower scope to verify the right information is gathered before scaling up.
- Sub-agents are independent. Each dispatch should include everything that sub-agent needs—file paths, standards to check against, result format—without assuming shared memory with other sub-agents unless the main agent merges results.
- Use sub-agents for focused hunts across documents. They fit patterns like issue-class review on drawings, section-by-section compliance passes on specs, or parallel extractions—while the main agent handles preparation (reading standards, creating result tables) and consolidation.
- Be explicit about each sub-agent’s procedure. Write out the steps it should follow—which tools to use, what to look for, and how to record results—including how it should move across sheets or sections when the task spans the whole set.
- Results go to a shared table. Sub-agents record findings using
upsert_table_element. The instructions should tell the main agent to create the table before dispatching, and define the table columns in the output format section.
Use Artifacts Wisely
Artifacts are useful, but they work best when used for their intended purpose.
Good — reference data. Artifacts are most useful for static domain knowledge the agent needs during execution: legends, terminology tables, standards definitions, or other reference material. These are most valuable when based on content you or your team have written or entered directly.
Avoid — instruction documents. If you're writing "Phase 1", "Step 1", or "Actions:" in an artifact, those belong in the Instructions field instead. See Self-Contained Instructions.
Avoid — output containers. The agent can create its own tables and markdown documents as it works, so there is no need to pre-populate an artifact with output structure. If you want a specific output format, describe it in the Instructions field and the agent will create the appropriate documents at runtime.
| Do This | Avoid This |
|---|---|
| Store reference legends and terminology tables | Put workflow instructions in artifacts |
| Use artifacts for static domain knowledge | Pre-populate artifacts as empty output templates |
| Keep artifacts focused on a single purpose | Create many overlapping artifacts |
Request the Right Files
When your workflow requires users to provide files, make it easy for them to understand what's needed.
Write meaningful descriptions. Every requested file should have a description explaining what it's for and what type of file is expected:
"Drawing Set — Upload the architectural floor plan PDF you want to check for code compliance"
"Project Specifications — Upload the relevant spec sections for submittal review"
Distinguish requested files from context. Requested files are per-run inputs that change every time someone uses the workflow (e.g., "the submittal to review"). Context files are persistent reference material that stays the same across runs (e.g., "company standards document"). Use the Requested Files field for per-run inputs and the Context section for persistent references.
Good file descriptions save time for everyone. Users know exactly what to provide, and your workflow gets the inputs it needs.
Choose the Right Assistant Mode
The Assistant Mode setting controls how the workflow executes. Always choose a mode explicitly — leaving it unset can lead to unpredictable behavior.
- Standard — Best for simpler, interactive tasks where fast responses matter. Use when the workflow involves a focused review of a single document or a straightforward generation task.
- Deep Research — Best for complex analysis that benefits from extended reasoning. Use when the workflow needs to cross-reference multiple sources, apply detailed standards, or produce thorough reports.
- Background Agent — Best for long-running tasks that should run autonomously until complete. Use when the workflow dispatches sub-agents, reviews large document sets, or performs multi-step processes that don't require user interaction during execution. This is the preferred mode for most review and compliance workflows.
Set Up Inputs and Outputs
The Inputs and Outputs fields are short labels (up to 30 characters) that appear on the workflow card. They give users a quick sense of what the workflow expects and produces before they start it.
Write concise, descriptive labels:
- Inputs: "Drawing set, standards PDF" or "Submittal, project specs"
- Outputs: "Compliance table, summary" or "Review report"
These labels don't affect how the workflow executes — they are purely informational for users browsing workflows.
Common Pitfalls to Avoid
- Delegation to artifacts — Don't write instructions like "read the attached artifact for your workflow plan." Put all instructions directly in the Instructions field.
- Persona-only prompts — A role description without actionable steps produces unpredictable results. Always include numbered steps with clear objectives.
- Vague tool references — "Use your tools to analyze the document" is less effective than "Use the drawing judge tool to verify each potential violation."
- No output format specified — Without a defined format, results may vary each time the workflow runs.
- Missing verification steps — Always include a final review step to catch errors and confirm completeness.
- Empty file descriptions — Users shouldn't have to guess what files to provide. Every requested file needs a clear description.
- Wrong assistant mode — A long multi-document review on Standard mode may produce shallow results; a simple lookup on Background Agent wastes time. Always set the mode explicitly.
Putting It All Together
A well-designed workflow combines all these elements:
- Self-contained instructions with all workflow logic in one place
- Five-section structure — role, output format, steps, tool instructions, verification
- Explicit tool references naming specific tools and how to use them
- Sub-agents for parallel, scoped analysis across documents or issue classes when appropriate
- Focused artifacts for reference data only, not instructions or output templates
- Descriptive file requests that guide users on what to upload
- Clear input/output labels on the workflow card
- The right assistant mode for the task's complexity
- Built-in verification to ensure quality and completeness
When you follow these practices, your workflows will deliver consistent, high-quality results that your team can rely on.
Ready to build your first workflow? Open Workflow Builder, use Workflow Builder agent, or start from a Nomic template.