build-first-prompt.md

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:

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

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

Output:

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

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

prompt.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

# 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 · Chain Authoring Example

---

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

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

# 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.