Prompt Append

prompt_append is the simplest customization mechanism in Weave. It appends text to an agent's built-in prompt without modifying or replacing that prompt. The agent's core behavior is preserved and your instructions are layered on top.

Basic Usage

Add prompt_append under any agent block in your .weave config:

agent shuttle {
  models ["anthropic/claude-sonnet-4-5"]
  mode subagent
  prompt_append "Always verify work by running the full test suite before marking a task complete."
}

You can append to multiple agents at once:

agent shuttle {
  models ["anthropic/claude-sonnet-4-5"]
  mode subagent
  prompt_append "Always verify work by running the full test suite before completion."
}

agent tapestry {
  prompt_append "Format all todos as [N/M: task title]. Always mark in_progress before starting."
}

agent pattern {
  prompt_append "Create detailed acceptance criteria for every plan."
}

How It Works

Your prompt_append text is concatenated to the end of the agent's built-in prompt. The base prompt is never modified; your text simply follows it.

TIP

prompt_append is the right tool when you want to add project-specific rules, verification steps, or formatting conventions on top of an agent's existing behavior. For reusable domain knowledge that you want to share across projects or teams, use Skills instead.

Prompt Append File

For longer instructions, use prompt_append_file to reference a Markdown file. The path is resolved relative to the config scope's prompts/ directory:

agent shuttle {
  prompt_append_file "shuttle-extra.md"
}

prompt_append and prompt_append_file are mutually exclusive. Use one or the other per agent block.

Use Cases

Enforce verification before completion:

agent shuttle {
  prompt_append "Always run `npm test` and verify all tests pass before marking any task complete."
}

Add formatting conventions:

agent tapestry {
  prompt_append "Format all todo items as [N/M: short title] where N is the current task number and M is the total. Keep titles under 35 characters."
}

Inject domain rules:

agent shuttle {
  prompt_append "This project uses Python 3.12. Always use async/await for I/O. Use Pydantic v2 models. Follow PEP 8."
}

Remind agents of project conventions:

agent pattern {
  prompt_append "Every plan must include a Verification section with at least 3 acceptance criteria per task."
}

Full Prompt Replacement

If you need to completely replace an agent's prompt (not just append), use the prompt field on the agent block. Use this sparingly. Replacing the full prompt removes the agent's built-in behavior. prompt_append is almost always the better choice.