1. Home
2. Docs
3. Agent Prompts

Agent Prompts

Agent prompts are selectable workflow profiles for CodeAlta sessions. They tell the agent how to work: implement directly, plan first, review only, coordinate child sessions, keep visible notes, or follow a project-specific release workflow.

CodeAlta separates prompt-related instructions into a few layers:

Layer	Files	Use it for
Agent prompt	prompts/agents/<id>.prompt.md	Session workflow, mode behavior, delegation style, review rules, and when to ask the user.
System prompt	prompts/system/<id>.system-prompt.md	Stable host/agent invariants shared by one or more agent prompts.

The active agent prompt is included when a session starts or resumes. Its optional system property chooses which system prompt id to use; when omitted, CodeAlta uses default. Optional composition fields in the agent prompt frontmatter can also turn generated context sections on or off for that workflow.

Prompt composition at a glance

The selected agent prompt is the entry point for composition: its body becomes developer instructions, and its frontmatter chooses the system prompt plus the generated context sections CodeAlta adds around it.

In the model request, the system prompt is sent as the system message. The agent prompt body and enabled generated sections are combined as developer instructions, while the user's actual request and attachments remain the user message.

Built-in modes

CodeAlta ships two built-in agent prompts:

Mode	Prompt id	Best for	What it does
Default	default	Normal implementation/build work	Inspects relevant files, edits when implementation is feasible, verifies, self-reviews diffs, reports concrete outcomes, and executes approved plan files.
Plan	plan	Larger or riskier tasks where you want a plan before edits	Researches read-only, writes an implementation-ready Markdown plan under .alta/plans/, asks for review, and can hand off to Default when approved.

Typical prompts:

Use Plan mode for this task. Inspect the relevant docs and code,
then write an implementation-ready plan before any source edits.

Execute the approved plan at .alta/plans/2026-06-04-workflow-docs.md.

If git is active and .alta/plans/ is not ignored, the built-in prompts treat plan files as repository artifacts: Plan keeps the saved plan current, and Default keeps it synchronized with implementation progress.

Source locations and precedence

Prompt resources are layered in this order:

1. Built-in resources shipped with CodeAlta.
2. User-global resources under ~/.alta/prompts/.
3. Project-local resources under <project>/.alta/prompts/.

Each root has the same layout:

prompts/
  system/
    default.system-prompt.md
    my-custom-system.system-prompt.md
  agents/
    default.prompt.md
    plan.prompt.md
    reviewer.prompt.md

If multiple roots contain the same prompt or system id, the later source replaces the earlier one by default: project replaces global, and global replaces built-in. This lets you keep a global reviewer prompt while giving one repository a stricter project-local reviewer.prompt.md.

When you only want to add local instructions to an existing prompt, set mode: append (or append: true) in frontmatter. CodeAlta then appends that file's body after the nearest lower-precedence replacement chain instead of replacing it. Multiple append files stack in precedence order.

Create a custom agent prompt

Use a custom prompt when you repeat the same workflow often enough that it deserves a named mode.

1. Open the prompt manager with Ctrl+G Ctrl+H or /prompt.
2. Choose Agent Prompts.
3. Create a Global prompt for all projects or a Project prompt for the current project.
4. Pick a short lowercase id such as reviewer, triage, or release.
5. Fill in a concise name, description, optional system prompt id, optional composition overrides, and Markdown body.
6. Select the agent prompt from the footer Agent: selector or cycle prompts with Ctrl+T / /next_prompt.

Creating a system prompt does not activate it by itself. In normal use, a system prompt becomes active only when the selected agent prompt references its id in the System Prompt field (the system frontmatter property).

A minimal prompt file looks like this:

---
name: Reviewer
description: Review-only workflow that reports risks before code changes.
---
You are the active CodeAlta review agent for this session.

Review the requested change without editing files. Inspect relevant code,
tests, and docs. Report findings first, ordered by severity, with file and
line references when possible. If no issues are found, say so and mention any
verification gaps.

description is optional but should be decision-useful: CodeAlta surfaces effective agent prompt descriptions in generated model context so agents can discover available workflows and switch or delegate appropriately.

Agent prompt frontmatter and composition

Agent prompt frontmatter is the user-facing entry point for prompt composition. The file name selects the agent prompt id, the prompt's system field selects the system prompt id, mode controls replacement versus append behavior, and optional boolean fields override which generated context sections CodeAlta includes. In other words, you normally activate a custom system prompt by editing or creating an agent prompt that points at it, then selecting that agent prompt for the session.

Field	Required?	Use it for
name	Yes for replace; inherited for append	Display name in the prompt selector.
description	No	Short decision-useful summary shown to agents and users.
system	No	System prompt id from prompts/system/<id>.system-prompt.md; defaults to default when omitted.
mode	No	append to add this prompt body to the lower-precedence prompt with the same id; omit or use replace for the default replacement behavior.
append	No	Boolean alias for mode: append; prefer mode for new prompt files.
skills	No	Include available/active skill guidance.
project_context	No	Include repository instruction files such as AGENTS.md.
runtime_context	No	Include current date, platform, working directory, project root, and session kind.
tool_guidance	No	Include generated host-tool guidance and available agent-prompt discovery.

Do not restate defaults in every prompt. When generated-section boolean fields are omitted, CodeAlta uses its normal defaults, which currently include all generated sections when content is available. Add one of those booleans only when a workflow intentionally needs a different composition.

For example, a project can add repository-specific rules to the built-in default agent prompt without copying the whole file:

---
mode: append
---
For this repository, run `dotnet test -c Release` before reporting success
when C# runtime code changes.

Appended agent prompts inherit lower-precedence metadata such as name, description, system, and generated-section settings unless the appended file sets those fields. For example, an appended prompt can still set tool_guidance: false if the local addition intentionally changes composition.

For example, if you create prompts/system/team-release.system-prompt.md, reference it from an agent prompt with system: team-release:

---
name: Release Coordinator
description: Release workflow using the team release system prompt.
system: team-release
---
Coordinate the release checklist, verify packaging steps, and ask before
publishing.

Selecting Release Coordinator as the active agent prompt is what activates team-release for that session. If the system field is omitted, CodeAlta uses default.

For example, a narrow review prompt can keep the normal system prompt while disabling skill and tool-discovery guidance:

---
name: Minimal Reviewer
description: Review-only workflow with a smaller generated context.
skills: false
tool_guidance: false
---
Review the requested change without editing files. Report findings first,
ordered by severity, with file and line references when possible.

What to put in a prompt body

Good agent prompt bodies are concrete enough to shape behavior but small enough to stay understandable:

• state the role and scope of the workflow;
• define when the agent should inspect, implement, verify, or stop;
• say when it should ask for structured approval;
• explain whether it may delegate to child sessions;
• describe progress-note expectations when the task is long-running;
• name the smallest meaningful verification for the workflow;
• call out non-goals and safety boundaries.

For advanced workflows, the body can mention CodeAlta live-tool capabilities the model may use, such as session delegation, sticky notes, reminders, or structured asks. Users still prompt for the outcome; the model invokes live-tool commands internally when the selected provider/session supports them. See Advanced Agent Workflows for recipes and command-group coverage.

Selecting, switching, and editing prompts

Use the Agent: selector below the prompt editor to choose the prompt for the current draft/session. Built-in prompts appear first, followed by global prompts and project prompts.

The prompt manager lists built-in, global, and project prompts, shows shadowed replacements, and lets you create, edit, save, or delete global/project prompt files. Built-in prompt and system prompt files are visible for inspection but read-only; create a global or project file with the same id to replace or append to one.

Agents can also use the prompt and session live-tool command groups internally when you ask for prompt automation. For example, you can ask:

List the available agent prompts for this project and recommend which
one fits a read-only security review.

Create a project agent prompt named release-checklist that plans release
steps, keeps notes visible, and asks before publishing.

Switch this session to the reviewer prompt for the next turn.

Those are user prompts, not terminal commands. CodeAlta-managed agents translate them into the appropriate prompt/session operations when available.

Default and project-specific overrides or extensions

A project prompt can specialize a global workflow without changing other repositories. Common examples:

• plan.prompt.md that adds repository-specific plan-file sections;
• reviewer.prompt.md that includes local test commands and review gates;
• release.prompt.md that knows the repository's packaging and publishing checklist;
• triage.prompt.md that asks child sessions to inspect logs, issues, and recent session history.

System prompts and composition

System prompt files carry host-level behavior and should be short, stable, and explicit. Agent prompts are better for workflow-specific session behavior.

System prompts support the same mode: append / append: true frontmatter as agent prompts. This is useful for global or project-local additions to default.system-prompt.md without copying CodeAlta's full built-in system prompt:

---
mode: append
---
Always mention this team's release freeze window before proposing publish steps.

Use the agent prompt system frontmatter field when a workflow needs a custom system prompt. The value is the system prompt id, not the full path: for prompts/system/team-release.system-prompt.md, write system: team-release in the agent prompt frontmatter, then select that agent prompt for the session.

The activation flow is:

1. Create, replace, or append a system prompt, for example prompts/system/team-release.system-prompt.md.
2. Create or edit an agent prompt and set its System Prompt field (the system frontmatter property) to team-release.
3. Select that agent prompt from the Agent: selector before sending the prompt.

Keep composition overrides close to the agent prompt that needs them. Disabling generated context such as tool guidance can make advanced prompt workflows less discoverable to the agent, so prefer the default generated sections unless a specific workflow has a clear reason to remove them.

If you want a custom system prompt to affect the built-in Default or Plan modes, create a global or project agent prompt with the same agent prompt id (default.prompt.md or plan.prompt.md) and add the system field there. Review these replacements or append extensions carefully because they change every session that uses that mode in the matching scope.