docs: add prompt-writing guidance for AI assistants - #662
Conversation
Adds a "Writing effective instructions" section with a reusable prompt template, a filled-in example, and tips for iterating (using AI Evaluations, keeping a consistent fallback phrase). Cross-linked from the Filesearch doc's existing prompt-engineering pointer, which previously only linked out to an external blog post. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
📝 WalkthroughWalkthroughUpdated two assistant integration documents with July 2026 metadata. Expanded guidance for writing effective assistant instructions, including system-prompt coverage, templates, examples, evaluation practices, and fallback phrasing. Added an additional prompt-engineering reference to the file-search setup instructions. 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
🚀 Deployed on https://deploy-preview-662--glific-docs.netlify.app |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with 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.
Inline comments:
In `@docs/5`. Integrations/Creating and modifying assistants in Glific.md:
- Around line 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.
In `@docs/5`. Integrations/Filesearch Using OpenAI Assistants.md:
- 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.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 3baff521-0053-4418-a0dd-4eec7efbf651
📒 Files selected for processing (2)
docs/5. Integrations/Creating and modifying assistants in Glific.mddocs/5. Integrations/Filesearch Using OpenAI Assistants.md
| ``` | ||
| 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)]. | ||
| ``` |
There was a problem hiding this comment.
📐 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
...
-```
+```textAlso 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
|
|
||
| - 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.* |
There was a problem hiding this comment.
📐 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.
| *[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
2 participants
Summary
Fixes #540
The issue's Discord link wasn't accessible to me, and the issue body itself has no specifics beyond "some prompt suggestions to be included in the documentation" - so per discussion, this adds general prompt-writing guidance to the AI Assistant docs rather than guessing at the specific examples from that Discord thread. If the actual thread has more specific suggestions, happy to fold those in as a follow-up.
Adds a "Writing effective instructions" section to "Creating and modifying AI assistants in Glific" covering:
Instructionsfield (system prompt) should cover: role/audience, source of truth, tone/format, and fallback behaviorAlso updates the Filesearch doc's existing prompt-engineering pointer (previously only an external blog link) to also point to this new in-house section.
Test plan
Summary by CodeRabbit