Skip to content

docs: add prompt-writing guidance for AI assistants #662

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
SangeetaMishr wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add prompt-writing guidance for AI assistants #662

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 42 additions & 1 deletion docs/5. Integrations/Creating and modifying assistants in Glific.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
<tr>
<td><b>3 minutes read</b></td>
<td style={{ paddingLeft: '40px' }}><b>Level: Advanced</b></td>
<td style={{ paddingLeft: '40px' }}><b>Last Updated: April 2026</b></td>
<td style={{ paddingLeft: '40px' }}><b>Last Updated: July 2026</b></td>
</tr>
</table>
</h4>
Expand All @@ -29,6 +29,47 @@ This doc details how to create new assistants, modify the created assistants and

5. From here, copy the assistant id and use it in the flow.

## Writing effective instructions

The `Instructions` field you fill in when creating or editing an assistant is its system prompt - it tells the assistant how to behave, what it knows, and what to do when it doesn't know something. A clear, specific prompt makes a real difference in the quality of your assistant's answers.

A good prompt usually covers:

- Role and audience - who the assistant is for and what it should help with.
- Source of truth - tell it to answer only using the uploaded knowledge base, rather than general knowledge, if that's what you want.
- Tone and format - how formal or casual, how long the answers should be, and any language requirements.
- What to do when it doesn't know - a clear fallback instruction (for example, ask it to say so honestly instead of guessing). This also makes it possible to detect and route unanswered questions to a human agent - see [Open a ticket with a human agent](https://glific.github.io/docs/docs/Product%20Features/Flows/Flow%20Actions/Open%20a%20ticket%20with%20a%20human%20agent/).

### Example template

```
You are a helpful assistant for [organization name]. You help [describe your users, e.g. "farmers enrolled in our program"] with questions about [topic].

Answer only using the information in your knowledge base. Do not guess or make up information.

If you don't know the answer, reply exactly with: "[fallback phrase]"

Keep answers under [N] sentences unless the user asks for more detail. Respond in [language(s)].
```
Comment on lines +45 to +53

@coderabbitai coderabbitai Bot Jul 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Specify a language for both fenced prompt examples.

Add text (or markdown) after each opening fence so the documentation passes MD040 and renders consistently.

Proposed fix 
-```
+```text
...
-```
+```text

Also applies to: 57-65

🧰 Tools
🪛 markdownlint-cli2 (0.23.0)

[warning] 45-45: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/5`. Integrations/Creating and modifying assistants in Glific.md around
lines 45 - 53, Update both fenced prompt examples in the documentation,
including the additional example around the second referenced section, so each
opening code fence specifies the text or markdown language. Leave the prompt
content unchanged and ensure every corresponding closing fence remains valid.

Source: Linters/SAST tools


### Example filled in

```
You are a helpful assistant for Kaivalya Education. You help Panchayati Raj Institution (PRI) members with questions about local governance and Viksit Panchayat guidelines.

Answer only using the information in your knowledge base. Do not guess or make up information.

If you don't know the answer, reply exactly with: "I'm not able to help with that yet."

Keep answers under 3 sentences unless the user asks for more detail. Respond in Hindi.
```

### Tips for improving your prompt over time

- Add a couple of example question-and-answer pairs directly in the prompt if the assistant's responses don't match the format you want.
- Use [AI Evaluations](https://glific.github.io/docs/docs/Integrations/AI%20Evaluations%20in%20Glific/) to test your prompt against a Golden Set of questions, and refine it based on where it scores poorly.
- Keep the fallback phrase consistent - it's easier to track and route unanswered questions if the assistant always says the same thing when it doesn't know.

## Modifying an assistant
1. From the assistant list page, click on “edit” the assistant action.
<img width="1098" height="367" alt="Screenshot 2026-04-14 at 2 46 55 PM" src="https://github.com/user-attachments/assets/d08527ee-29d3-44bf-9a3d-ce15a45bea8c" />
Expand Down
4 changes: 2 additions & 2 deletions docs/5. Integrations/Filesearch Using OpenAI Assistants.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<tr>
<td><b>6 minutes read</b></td>
<td style={{ paddingLeft: 40 }}><b> Level: Advanced</b></td>
<td style={{ paddingLeft: 40 }}><b>Last Updated: April 2026</b></td>
<td style={{ paddingLeft: 40 }}><b>Last Updated: July 2026</b></td>
</tr>
</table>
</h3>
Expand Down Expand Up @@ -47,7 +47,7 @@ Define the following parameters:


- Provide a system prompt in the `Instructions` field.
*[Click Here](https://glific.org/a-simple-guide-to-using-large-language-models/#prompt) to read more on prompt engineering.*
*[Click Here](https://glific.org/a-simple-guide-to-using-large-language-models/#prompt) to read more on prompt engineering, or see [Writing effective instructions](https://glific.github.io/docs/docs/Integrations/Creating%20and%20modifying%20assistants%20in%20Glific/#writing-effective-instructions) for a prompt template and examples.*

@coderabbitai coderabbitai Bot Jul 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Replace “Click Here” with descriptive link text.

Use text such as “Read a simple guide to prompt engineering” so the link’s destination is clear without relying on surrounding context.

Proposed fix 
-*[Click Here](https://glific.org/a-simple-guide-to-using-large-language-models/#prompt)
+*[Read a simple guide to prompt engineering](https://glific.org/a-simple-guide-to-using-large-language-models/#prompt)
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
*[Click Here](https://glific.org/a-simple-guide-to-using-large-language-models/#prompt) to read more on prompt engineering, or see [Writing effective instructions](https://glific.github.io/docs/docs/Integrations/Creating%20and%20modifying%20assistants%20in%20Glific/#writing-effective-instructions) for a prompt template and examples.*
*[Read a simple guide to prompt engineering](https://glific.org/a-simple-guide-to-using-large-language-models/#prompt) to read more on prompt engineering, or see [Writing effective instructions](https://glific.github.io/docs/docs/Integrations/Creating%20and%20modifying%20assistants%20in%20Glific/#writing-effective-instructions) for a prompt template and examples.*
🧰 Tools
🪛 markdownlint-cli2 (0.23.0)

[warning] 50-50: Link text should be descriptive

(MD059, descriptive-link-text)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/5`. Integrations/Filesearch Using OpenAI Assistants.md at line 50,
Update the first Markdown link in the referenced paragraph by replacing “Click
Here” with descriptive text such as “Read a simple guide to prompt engineering,”
while preserving its existing destination and the separate “Writing effective
instructions” link.

Source: Linters/SAST tools

- Files (.csv, .doc, .docx, .html, .java, .md, .pdf, .pptx, .txt) can be uploaded by clicking on `Manage Files`.
These files will be utilized by the assistant to generate responses and each file will take approx 15 secs to upload.

Expand Down
Loading