> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pfrankov/obsidian-local-gpt/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating Custom Actions

> Learn how to create custom AI actions with specific prompts and configurations

## Overview

Custom actions allow you to create reusable AI workflows tailored to your specific needs. Each action can have its own prompt, system prompt, temperature settings, and behavior.

## The LocalGPTAction Interface

Actions are defined using the `LocalGPTAction` interface:

```typescript theme={null}
// From src/interfaces.ts:28-36
export interface LocalGPTAction {
  name: string;
  prompt: string;
  temperature?: number;
  system?: string;
  replace?: boolean;
  separator?: boolean;
  community?: CommunityActionRef;
}
```

### Field Descriptions

<ParamField path="name" type="string" required>
  The display name of the action that appears in the context menu and Action Palette.
</ParamField>

<ParamField path="prompt" type="string" required>
  The main instruction sent to the AI. Can include template keywords like `{{=SELECTION=}}` and `{{=CONTEXT=}}`.
</ParamField>

<ParamField path="temperature" type="number">
  Controls randomness/creativity (0-2). If not set, uses the default creativity setting. Lower values are more deterministic.
</ParamField>

<ParamField path="system" type="string">
  The system prompt that defines the AI's role and behavior. This is sent as the system message to guide the AI's overall approach.
</ParamField>

<ParamField path="replace" type="boolean">
  When `true`, the AI's response replaces the selected text. When `false` (default), the response is appended after the selection.
</ParamField>

<ParamField path="separator" type="boolean">
  When `true`, creates a visual separator in the actions list instead of an executable action.
</ParamField>

<ParamField path="community" type="CommunityActionRef">
  Metadata for community actions. Automatically managed when installing actions from the community library.
</ParamField>

## Creating Actions in Settings

### Method 1: Manual Creation

1. Open **Settings** → **Local GPT**
2. Scroll to the **Actions** section
3. Click **Add Action**
4. Fill in the action fields:
   * **Name:** A descriptive name for your action
   * **System Prompt:** (Optional) Define the AI's role
   * **Prompt:** The main instruction
   * **Replace selected text:** Toggle on to replace instead of append
5. Click **Save**

<Note>
  Action names must be unique. If you try to save an action with a duplicate name, you'll see an error message.
</Note>

### Method 2: Quick Add

Use the Quick Add field for faster action creation using a special format:

**Format:**

```
Name: [action name] ✂️ System: [system prompt] ✂️ Prompt: [main prompt] ✂️ Replace: [true/false]
```

**Example:**

```
Name: Expand Ideas ✂️ System: You are a creative brainstorming assistant ✂️ Prompt: Generate 3 creative ways to expand on this idea
```

<Tip>
  The scissor emoji (✂️) is used as a separator. You can copy it from the settings page or use the keyboard shortcut.
</Tip>

### Method 3: Community Actions

1. Click **Community Actions** button
2. Browse available actions
3. Click **Install** on any action you want to use
4. The action is automatically added to your list

<Info>
  Community actions are automatically updated to the latest version. To prevent auto-updates, modify the Prompt or System Prompt fields.
</Info>

## Action Field Examples

### Example 1: Code Documentation Generator

```yaml theme={null}
Name: 📝 Document Code
System: You are an expert technical writer specializing in code documentation. Write clear, comprehensive documentation following best practices.
Prompt: |
  Analyze the following code and generate:
  1. A clear description of what it does
  2. Parameter documentation
  3. Return value documentation
  4. Usage examples
  
  Code:
  {{=SELECTION=}}
Replace: false
```

### Example 2: Grammar Fixer with Context

```yaml theme={null}
Name: ✍️ Fix Grammar
System: You are a professional editor. Correct grammar and spelling while preserving the author's voice and style.
Prompt: |
  Proofread and correct the following text for grammar, spelling, and punctuation errors.
  Maintain the original tone and meaning.
  
  {{=SELECTION=}}
Replace: true
```

### Example 3: Meeting Notes Summarizer

```yaml theme={null}
Name: 📋 Summarize Meeting
System: You are an executive assistant skilled at summarizing meeting notes into actionable insights.
Prompt: |
  Summarize the following meeting notes into:
  - Key discussion points
  - Decisions made
  - Action items with owners
  - Next steps
  
  Format as a structured list.
  
  {{=SELECTION=}}
Replace: false
```

### Example 4: Enhanced Context Action

```yaml theme={null}
Name: 🧠 Answer with Context
System: You are a knowledgeable assistant with access to relevant context from the user's vault.
Prompt: |
  # Question
  {{=SELECTION=}}
  
  {{=CONTEXT_START=}}
  # Relevant Context from Vault
  {{=CONTEXT=}}
  {{=CONTEXT_END=}}
  
  # Instructions
  Answer the question using the provided context when relevant. If the context doesn't contain relevant information, provide a general answer.
Replace: false
```

<Tip>
  Use `{{=CONTEXT_START=}}` and `{{=CONTEXT_END=}}` to conditionally include context only when available. See the [Prompt Templating guide](/guides/prompt-templating) for more details.
</Tip>

### Example 5: Creative Rewriter

```yaml theme={null}
Name: 🎨 Make Creative
System: You are a creative writer with a flair for making text more engaging and vivid.
Prompt: Rewrite the following text to be more creative, engaging, and vivid while keeping the core message intact.
Temperature: 0.8
Replace: true
```

## Default Actions

Local GPT comes with these default actions:

```typescript theme={null}
// From src/defaultSettings.ts:13-45
actions: [
  {
    name: "🪄 General help",
    prompt: "",
    system: "You are an assistant helping a user write more content in a document based on a prompt. Output in markdown format. Do not use links. Do not include literal content from the original document.",
  },
  {
    name: "✍️ Continue writing",
    prompt: "Act as a professional editor with many years of experience as a writer. Carefully finalize the following text, add details, use facts and make sure that the meaning and original style are preserved. Purposely write in detail, with examples, so that your reader is comfortable, even if they don't understand the specifics. Don't use clericalisms, evaluations without proof with facts, passive voice. Use Markdown markup language for formatting. Answer only content and nothing else, no introductory words, only substance.",
    system: "You are an AI assistant that follows instruction extremely well. Help as much as you can.",
  },
  {
    name: "🍭 Summarize",
    prompt: "Make a concise summary of the key points of the following text.",
    system: "You are an AI assistant that follows instruction extremely well. Help as much as you can.",
  },
  {
    name: "📖 Fix spelling and grammar",
    prompt: "Proofread the below for spelling and grammar.",
    system: "You are an AI assistant that follows instruction extremely well. Help as much as you can.",
    replace: true,
  },
  {
    name: "✅ Find action items",
    prompt: 'Act as an assistant helping find action items inside a document. An action item is an extracted task or to-do found inside of an unstructured document. Use Markdown checkbox format: each line starts with "- [ ] "',
    system: "You are an AI assistant that follows instruction extremely well. Help as much as you can.",
  },
]
```

## Temperature Settings

The `temperature` field controls the creativity/randomness of responses:

<CardGroup cols={2}>
  <Card title="0.0 - 0.3" icon="lock">
    **Deterministic**: Consistent, factual outputs. Best for grammar fixes, code documentation, data extraction.
  </Card>

  <Card title="0.4 - 0.6" icon="scale-balanced">
    **Balanced**: Good mix of consistency and variety. Best for summarization, rewriting, Q\&A.
  </Card>

  <Card title="0.7 - 1.0" icon="wand-sparkles">
    **Creative**: More varied, creative outputs. Best for brainstorming, creative writing, idea generation.
  </Card>

  <Card title="1.0+" icon="rocket">
    **Highly Creative**: Maximum randomness. Use sparingly for experimental or highly creative tasks.
  </Card>
</CardGroup>

<Warning>
  If you don't specify a temperature, the action will use the default creativity setting from **Settings** → **Local GPT** → **Creativity**.
</Warning>

## Replace Mode

The `replace` field determines how the AI's response is inserted:

### Replace: false (default)

```markdown theme={null}
Selected text: "Write about climate change"

After action:
"Write about climate change"

[AI response appears here]
```

### Replace: true

```markdown theme={null}
Selected text: "This is writen badly"

After action:
"This is written badly"
```

<Tip>
  Use `replace: true` for actions like:

  * Grammar/spelling correction
  * Text simplification
  * Format conversion
  * Rewriting/rephrasing
</Tip>

## Managing Actions

### Editing Actions

1. Click **Edit** next to any action in the settings
2. Modify the fields as needed
3. Click **Save**

<Info>
  If you edit a community action, it will stop receiving automatic updates. This allows you to customize it without losing your changes.
</Info>

### Deleting Actions

1. Click **Edit** on the action you want to delete
2. Click **Remove**
3. Click **Remove** again to confirm (button turns red)

### Reordering Actions

**Desktop:**

* Drag and drop actions using the grip handle (⋮⋮) on the left

**Mobile:**

* Use the chevron up/down buttons to move actions

### Creating Separators

1. Click **Add Separator**
2. A visual separator is added to organize your actions list
3. Drag to position it where needed

<Tip>
  Use separators to group related actions together, like "Writing Aids", "Code Tools", "Research", etc.
</Tip>

## Sharing Actions

Every action has a copy button that generates a shareable string:

1. Click the **Copy** icon next to any action
2. Share the copied text with others
3. Recipients can paste it into the **Quick Add** field

**Shareable format:**

```
Name: Action Name ✂️ System: System prompt here ✂️ Prompt: Main prompt here ✂️ Replace: true ✂️ Language: en
```

## Best Practices

### Action Naming

* Use emojis to make actions visually distinct (🪄, ✍️, 📝, 🧠)
* Keep names short and descriptive
* Group related actions with similar emoji/prefix

### System Prompts

* Define the AI's role clearly ("You are a...")
* Set expectations for output format
* Include constraints or guidelines
* Keep it focused and specific

### Main Prompts

* Be clear and specific about what you want
* Use template keywords for flexibility
* Provide examples when helpful
* Structure complex prompts with headers

### Performance Tips

* Shorter prompts = faster responses
* Use `replace: true` when you don't need to keep the original
* Avoid overly complex system prompts that might confuse the model
* Test actions with different models to find the best fit

## Troubleshooting

### Action Not Appearing in Menu

* Check that the action name is not empty
* Ensure the action was saved successfully
* Try reloading Obsidian

### Unexpected Output

* Review your system prompt for clarity
* Check template keyword placement
* Adjust temperature for more/less variation
* Try a different AI model

### Performance Issues

* Simplify overly complex prompts
* Use a faster model for the action
* Reduce context limit if using Enhanced Actions
* Check your AI provider connection

## Related Resources

<CardGroup cols={2}>
  <Card title="Prompt Templating" icon="code" href="/guides/prompt-templating">
    Master template keywords for dynamic prompts
  </Card>

  <Card title="AI Providers Setup" icon="plug" href="/guides/ai-providers-setup">
    Configure AI models and providers
  </Card>
</CardGroup>