# Tutorial: Build Your First Prompt


Stop copy-pasting the same instructions into Claude. Define them once, invoke them anywhere.

## Why This Matters

| Problem | Solution | Result |
|---------|----------|--------|
| **Repetitive Typing** | Defined Templates | Zero copy-pasting |
| **Inconsistent Output** | Structured Arguments | Reliable results every time |
| **Slow Iteration** | Hot Reload | Edit → Run instantly (no restart) |

---

## 1. The Single-File Pattern (Simple)

Best for short, simple prompts. Everything lives in one `.yaml` file.

### Create the file

`resources/prompts/general/hello/prompt.yaml`:

```yaml
id: hello
name: Hello World
description: A simple greeting prompt

# Inline template
userMessageTemplate: |
  Hello {{name}}! Welcome to the system.
  Current time: {{now}}

arguments:
  - name: name
    type: string
    required: true
```

### Run it

```bash
prompt_engine(command: ">>hello name='Developer'")
```

**Output**:
```text
Hello Developer! Welcome to the system.
Current time: ...
```

> [!NOTE]
> Single-file prompts are great for getting started. Once your template grows past ~20 lines, switch to the directory pattern below.

> [!TIP]
> **Prompt ID convention**: Use `snake_case` (lowercase with underscores). Hyphens are accepted as input but automatically normalized to underscores — `my-prompt` and `my_prompt` resolve to the same prompt.

---

## 2. The Directory Pattern (Scalable)

Best for complex prompts with long templates or system instructions. Splits config from content.

### Create the structure

```text
resources/prompts/general/code_review/
├── prompt.yaml          # Config only
└── user-message.md      # Content only
```

### `prompt.yaml`

```yaml
id: code_review
name: Code Review
description: Analyze code for quality issues
userMessageTemplateFile: user-message.md  # Points to file

arguments:
  - name: code
    required: true
  - name: language
    defaultValue: "typescript"
```

### `user-message.md`

```markdown
# Code Review: {{language}}

Please review the following code:

```{{language}}
{{code}}
```

Check for:
- Logic errors
- Performance bottlenecks
- Security risks
```

### Run it

```bash
prompt_engine(command: ">>code_review code='function x() {}'")
```

> [!TIP]
> **Ready for multi-step workflows?** Chains connect prompts into pipelines where each step feeds the next.
> [Chains Lifecycle](../concepts/chains-lifecycle.md) · [Chain Authoring Example](../guides/chain-authoring-example.md)

---

## 3. Mode Arguments with Auto-Discovery

When your prompt has arguments with discrete options (like `format`, `style`, or `doc_type`), use **equality conditionals** in templates. The server automatically extracts these options and surfaces them in hooks.

### Update `prompt.yaml`

```yaml
id: code_review
name: Code Review
description: Analyze code for quality issues
userMessageTemplateFile: user-message.md

arguments:
  - name: code
    required: true
  - name: language
    defaultValue: "typescript"
  - name: focus
    type: string
    description: "Review focus: security | performance | readability"
    required: false
```

### Update `user-message.md`

```markdown
# Code Review: {{language}}

{% if focus == "security" %}
**Focus: Security Analysis**
- Check for injection vulnerabilities
- Validate input handling
- Review authentication patterns
{% elif focus == "performance" %}
**Focus: Performance Analysis**
- Identify bottlenecks
- Check algorithmic complexity
- Review memory usage
{% elif focus == "readability" %}
**Focus: Readability Analysis**
- Check naming conventions
- Review code structure
- Assess documentation
{% else %}
**Focus: General Review**
{% endif %}

```{{language}}
{{code}}
```
```

### What happens

When you invoke `>>code_review`, hooks display:

```
focus: security | performance | readability (optional)
```

The options are **automatically extracted** from your template conditionals—no manual `options` array needed.

---

## 4. Hot Reload in Action

You don't need to restart the server to see changes.

1. Run `>>hello name='Dev'`
2. Edit `prompt.yaml`: Change "Hello" to "Greetings"
3. Run `>>hello name='Dev'` again
4. **Result**: "Greetings Dev!" appears instantly

This works for template content too—update your conditionals and see changes immediately.

> [!NOTE]
> Hot reload watches all files in your prompts directory. Changes to `prompt.yaml`, `user-message.md`, and `system-message.md` are picked up automatically — no server restart needed.

---

## Next Steps

> [!TIP]
> **Add quality checks to your prompts.** Gates validate output before it reaches the user — from simple word-count checks to full test suites.
> [Gates Guide](../guides/gates.md) · [Gate Configuration Reference](../reference/gate-configuration.md)

- **[Add Validation](../how-to/add-validation.md)**: Ensure arguments match patterns (e.g., valid URLs).
- **[Template Syntax](../reference/template-syntax.md)**: Use loops, conditionals, and script calls.
- **[Configuration](../reference/prompt-yaml-schema.md)**: Full reference for `prompt.yaml` options.
- **[Chains Lifecycle](../concepts/chains-lifecycle.md)**: Connect prompts into multi-step workflows.
- **[Skills Sync](../guides/skills-sync.md)**: Export prompts as native skills for Claude Code, Cursor, and more.
