Working with Prompts

Prompts in Magma are specialized Markdown files where you "engineer" your instructions before sending them to an LLM.

1. Creating a Prompt

You can create a new prompt document in two ways:

• CLI: magma prompt.gen "Refactor function"
• Obsidian: Use the hotkey Cmd-Ctrl-P (QuickAdd: Custom Magma prompt).

This creates a file in your prompts/ folder using the standard template.

2. Anatomy of a Prompt Document

A standard Magma prompt document is divided into three functional areas:

Prologue (Buttons)

At the top, you'll see buttons like "Copy to clipboard". These use Obsidian plugins to trigger the Magma CLI.

Context Section

This is where you gather the knowledge required for the task.

• Use transclusions (![[...]]) to include project docs.
• Use links ([[...]]) for minor references.
• LLM Tip: When using an API integration, this section is sent as the System Prompt.

Task Section

This is where you write your actual request (e.g., "Please refactor the following Elixir code for better performance...").

3. The "Copy-Paste" Workflow

This is the most reliable and common way to use Magma:

1. Draft: Prepare your prompt in Obsidian using transclusions for context.
2. Compile & Copy: Click the "Copy to clipboard" button (or run magma copy-prompt "Prompt Name").
   • Magma resolves all transclusions and converts links to plain text.
3. Paste: Go to your favorite AI (ChatGPT, Claude.ai, etc.) and paste the result.

4. The "Manual Execution" Workflow

If you want to keep a record of the AI's response inside your vault:

1. Click "Execute manually" in Obsidian.
2. Magma copies the prompt to your clipboard and creates a new Prompt Result file in prompts/__prompt_results__/.
3. Paste the prompt into your AI and get the response.
4. Copy the AI's response and paste it back into the result file in Obsidian.

This workflow is excellent for maintaining a history of "prompt experiments" and their outcomes.