# Writing Better Instructions ### About this export | Field | Value | | --- | --- | | **content_type** | lesson | | **platform** | contentstack-academy | | **source_url** | https://www.contentstack.com/academy/courses/building-your-first-agent-in-agentos/writing-better-instructions | | **course_slug** | building-your-first-agent-in-agentos | | **lesson_slug** | writing-better-instructions | | **markdown_file_url** | /academy/md/courses/building-your-first-agent-in-agentos/writing-better-instructions.md | | **generated_at** | 2026-06-08T14:32:06.204Z | > Part of **[Building Your First Agent in AgentOS](https://www.contentstack.com/academy/courses/building-your-first-agent-in-agentos)** on Contentstack Academy. **Academy MD v3** — structured for retrieval; no quiz or assessment keys. #### Lesson text By the end of this lesson, you will be able to: * Explain the role instructions play in agent behavior * Understand how instruction quality impacts output quality * Write clearer, more effective instructions for common agent tasks * Identify opportunities to refine instructions and improve results * Apply instruction-writing best practices when building agents ### **Why Instructions Matter** If triggers determine when work begins and tools determine what capabilities are available, instructions determine what outcome the agent is trying to achieve. Instructions are how we communicate our expectations to the agent. They provide direction. They define objectives. They establish constraints. Without instructions, an agent has no clear understanding of what success looks like. Consider the difference between these two requests: **Generate tags for this article.** and **Generate 3-5 specific tags that accurately represent the primary themes of the article. Avoid generic tags unless they are central to the content.** Both requests ask the agent to generate tags. One provides significantly more guidance. As a result, the quality of the output is often very different. ### **Instructions Are Not Procedures** One of the most important ideas to understand is that instructions are not the same thing as traditional programming. When writing instructions, you are usually defining outcomes rather than individual steps. For example, a traditional workflow might specify: * Read the article * Identify key themes * Generate a teaser * Create SEO metadata * Save the results An agent is often capable of determining many of those steps on its own. Instead of focusing exclusively on procedure, focus on the desired result. For example: **Generate a teaser, SEO title, SEO description, and tags that accurately represent the content of the article.** This gives the agent a goal while allowing it to determine how best to achieve that outcome using the available tools. ### **Good Instructions Provide Context** Agents generally perform better when they understand the purpose behind a task. Instead of simply saying: **Generate a teaser.** Consider providing additional context: **Generate a teaser that summarizes the article while encouraging readers to continue reading.** Now the agent understands not only what to generate, but why it is generating it. This additional context often improves quality significantly. ### **Good Instructions Define Constraints** Constraints help establish expectations. For example: #### **Weak Instruction** Generate an SEO description. #### **Better Instruction** Generate an SEO description between 140 and 160 characters. The second version provides a measurable target. Similarly: #### **Weak Instruction** Generate tags. #### **Better Instruction** Generate 3-5 specific tags that improve content discovery. Avoid generic tags unless they are central to the article. The additional guidance reduces ambiguity and improves consistency. ### **Refinement Is Part of the Process** One of the most common misconceptions about agents is that the first output should always be perfect. In reality, building agents is often an iterative process. You review the output. You identify opportunities for improvement. You adjust the instructions. Then you test again. For example, imagine our Content Enrichment Agent generates these tags: * Technology * AI * Content These tags aren't incorrect. But they're not particularly useful. We might refine our instructions by adding: **Generate tags that are specific, reusable across multiple articles, and useful for content discovery. Avoid overly broad categories unless they are central to the article.** The result is often a much stronger set of tags. Notice what changed. We didn't modify the trigger. We didn't change the tools. We simply improved the instructions. ### **A Simple Framework for Writing Instructions** When creating instructions, consider the following framework: #### **Outcome** What should the agent accomplish? Example: Generate a teaser and SEO metadata. #### **Context** Why is the agent performing this task? Example: The metadata should improve discoverability and help readers understand the article. #### **Constraints** What rules should the agent follow? Example: Generate an SEO description between 140 and 160 characters. When all three elements are present, the agent has a much clearer understanding of what success looks like. ### **The Instructions We'll Use** For our Content Enrichment Agent, we'll ask the agent to: * Retrieve the article that triggered the workflow * Analyze the content * Generate a teaser * Generate an SEO title * Generate an SEO description * Generate tags * Update the content entry * Notify the team when enrichment is complete As we continue building, we'll refine these instructions and observe how those refinements influence the final output. ### **Key Takeaways** * Instructions define the outcome an agent should achieve. * Better instructions generally produce better results. * Focus on outcomes rather than detailed procedures whenever possible. * Context helps agents understand why a task is being performed. * Constraints help improve consistency and quality. * Refinement is a normal part of agent development. ### **Next Lesson** Next, we'll apply these principles as we transform our article summary workflow into a complete Content Enrichment Agent that generates metadata, updates content entries, and prepares content for review. #### Key takeaways - Connect **Writing Better Instructions** back to your stack configuration before moving to the next module. - Capture one concrete artifact (screenshot, Postman call, or code snippet) that proves the step works in your environment. - Re-read the delivery versus management boundary for anything you changed in the entry model. ## Supplement for indexing ### Content summary Writing Better Instructions. By the end of this lesson, you will be able to: Explain the role instructions play in agent behavior Understand how instruction quality impacts output quality Write clearer, more effective instructions for common agent tasks Identify opportunities to refine instructions and improve results Apply instruction-writing best practices when building agents Why Instructions Matter If triggers determine when work begins and tools determine what capabilities are available, instructions determine what outcome the agent is trying to achieve. Instructions are how we communicate our expectations to the agent. They provide direction. They define objectives. They establish constraints. Without instructions ### Retrieval tags - Writing - Better - Instructions - building-your-first-agent-in-agentos - lesson 06 - Writing Better Instructions - building-your-first-agent-in-agentos lesson ### Indexing notes Index this lesson as a primary chunk tagged with lesson_id "06" and topics: [Writing, Better, Instructions]. Parent course slug: building-your-first-agent-in-agentos. Use asset_references URLs as thumbnail hints in search results when present. Never surface LMS quiz content or assessment answers from this file. ### Asset references _No image or video thumbnail URLs were extracted._ ### External links | Label | URL | | --- | --- | | Contentstack Academy home | `https://www.contentstack.com/academy/` | | Training instance setup | `https://www.contentstack.com/academy/training-instance` | | Academy playground (GitHub) | `https://github.com/contentstack/contentstack-academy-playground` | | Contentstack documentation | `https://www.contentstack.com/docs/` |