Best Ways To Write Instructions For Software Use

Writing forces clarity. 🗣️ When someone comes up with an idea, we first talk about it at a high-level. ✍️ But then I ask them to write it out. You can miss a lot of the details in an hour-long conversation. But writing is like code... it demands clarity of thought. Without even realizing it, you’re building software… in a sense. 1️⃣ Write the high-level general idea down (the interface) 2️⃣ Break it down into smaller independent pieces or steps (helper functions) 3️⃣ List out example inputs and outputs for these building blocks (unit testing) 4️⃣ Glue the steps together (interfaces) 5️⃣ Loop in more people, get feedback, and identify inputs and desired outputs of the whole idea and see if they work (integration testing) 6️⃣ Things are going to break. Iterate until the idea’s implementation “works”. If someone asks a question, point them to the document. To add features to the idea later, iterate the document. Writing is unbelievably powerful. It gets everyone on the same page. It saves time. And it makes for rock solid ideas. Clearer. Sharper. Stronger. ✍️

Building with AI = Failing A Lot Take writing custom GPT instructions. I've probably written 50+ at this point and for the most part they have all followed a similar markdown pattern I learned over a year ago from Rachel Woods. But models evolve and what worked yesterday might not work as well today. When GPT-4o came out a few weeks ago, I definitely noticed some of my custom GPTs acting weird. Some got better. Some got worse. Some straight up broke. So I went back to the lab again and started to rebuild. Lots of failures later, I now have a new custom GPT prompt structure that still has the bones of my older markdown method, but incorporates a lot of OpenAI's recent guidelines. And now I have GPTs performing better than ever. You can check out the full article, but here are some good guidelines for any prompt writing: ✔ Simplify Complex Instructions -break larger steps down ✔Structure for clarity - use delimiters and examples ✔Promote Attention to Detail - encourage the model to focus on certain areas of the prompt ✔Avoid Negative Instructions - frame instructions positively ✔Granular Steps - break down steps as granularly as possible ✔Consistency and Clarity - be explicit with terms and be sure to define what you want with examples.

With actions coming soon, Declarative agents are an easy way to build and operationalize agents in a no-code way. Even with no code, #citizendevelopers and agent makers should follow best practices. One key step is providing comprehensive instructions for your agent. Instructions in agents are probably the most important part since they determine the agent's behavior. Instructions includes defining agent's purpose, clearly listing its skills (tasks that an agent supposed to complete), how it will handle with the errors and more. I’ve never had perfect luck setting up my instructions on the first try when building agents. It often takes multiple iterations and feedback from end users to refine and improve them. Instructions also has its own set of best practices and some of them are below: 🔹 Be clear and specific - start with your use case where you define your problem statement, an opportunity statement, goals, and scope. Then, baed on these details, outline your agent's purpose and provide general guidelines. 🔹 Break down large tasks into smaller steps - just like humans complete tasks step-by-step, agents also perform better with clear sequences. This helps with reasoning and planning. 🔹 Use structured syntax - add clear headings and delimiters to separate instructions from examples. I often write my instructions in plain language and then use Copilot to format them into Markdown or XML for better readability. 🔹 Provide examples - show your agent how you expect tasks to be completed. You can list concrete examples for your agent. 🔹 Set a positive tone: Rather than saying "don't do this," focus on what the agent should do. Positive tone helps agent overcome ambiguity. 🔹 Connect to a knowledge source - link the agent to relevant knowledge bases. This enables it to evolve from a general-purpose tool into a specialized, context-aware assistant (I mean this why we build agets in the first place, right?). If you're looking for inspiration, click on "Create an Agent" in Microsoft 365 Copilot, select Prompt Coach, and see the "Configuration" section for instruction examples. Even with these best practices, remember that refining agent instructions is an ongoing process. My advice is that build your agent, test it by yourself, and have your users test and provide feedback. 👉 See the best practices for writing effective instructions for declarative agents here: https://lnkd.in/eDDzEyUx 👉 If you are building agents in #CopilotStudio or #AzureAIFoundry, see the best practices for prompting here: https://lnkd.in/evtcSbeb Image source: Microsoft #agents #prompting #copilotagents #declarativeagents