> ## Content Index > Fetch the complete content index at: https://www.elisatrippetti.com/llms.txt > Use this file to discover other available public pages before exploring further. # SOUL.md and AGENTS.md for content designers - URL: https://www.elisatrippetti.com/soul-md-agents-md-content-design/ - Published: 2026-10-30T17:00:00.000Z - Updated: 2026-10-30T17:53:46.000Z - Description: What I learned writing and testing agent instructions - Author: Elisa Trippetti - Tags: AI content design I was working on how an AI assistant should structure its answers. The problem was a familiar one: users asking complex questions had to scroll to the very bottom of every answer to find the verdict. They were doing the sifting the product should have done for them. When I asked the engineers where the changes would go, they said that either SOUL.md or AGENTS.md could work. We couldn’t be sure beforehand, so I’d have to try both and compare the results. But wait, what even are these files? This post is about what I’ve learned in the last few days. I used SOUL.md and AGENTS.md to turn a UX pattern into instructions and tested my approach without writing code. If you’re a content designer starting from a similar place, I hope this saves you some time. I tested on our own AI platform, where I could attach the files to the agent and read its logs. You may not have that, so I’ll also show how to do the same in a model playground. --- ## What are SOUL.md and AGENTS.md? They’re two Markdown files that tell an AI agent how to behave in every conversation. Several agent frameworks use them. In many setups, both files are added to the top of the system instructions each time the model is called: when the user sends a message, and again after each tool it uses. **SOUL.md** is about identity and tone: who the agent is and how it sounds. It names the agent, says what it’s for and sets its voice. General rules: be direct and concise, reply in the user’s language. It rarely changes. ```markdown # SOUL.md You are [Name], an AI assistant for business teams. Be direct, concise and polite. Reply in the language the user writes in. Say plainly when you don't know something. ``` **AGENTS.md** is for working instructions: how the agent does its job. The file usually covers how to stay accurate, how to handle files and actions, when to ask for clarification, how to structure answers and what to say when something goes wrong. It’s where an answer format belongs. ```markdown # AGENTS.md ## Accuracy Base your answers on the data you retrieved or were given. Never invent figures or sources. ## Clarification If a request is missing information you need, ask for all of it in one message. ``` They’re typically short, a few hundred words each. Because these files end up in the same prompt, we need to make sure they don’t contradict each other. If one says “Be concise” and the other says “Always include all the context the user needs”, the model gets both and the output it generates could be inconsistent. You’ll meet these files, or their equivalents, in a few places. - **Open-source agent frameworks**, such as OpenClaw and Hermes Agent, use SOUL.md for the agent’s personality. - **Many coding agents**, like OpenAI Codex and Cursor, read an AGENTS.md file from the project folder. - **Chat products** can have the same idea under other names: project instructions in Claude, custom GPTs in ChatGPT or Gems in Gemini. --- ## Turning a UX pattern into instructions The model reads these instructions with every message, from “Good morning” to a complex request, and applies them literally. So when we write them, we should spell out exactly what we need. I followed a similar process for error messages in [AI content design for UX writers: a day in the life](https://www.elisatrippetti.com/ai-content-design/). [LLM content design for UX writers: a day in the lifeHow a UX writer and ML engineer collaborate to generate dynamic, user-facing error messages.![](https://storage.ghost.io/c/dc/8f/dc8fe240-9762-45ca-b607-5f39c80e84a5/content/images/icon/Elisa-Trippetti-ab3210f7-042c-4ad9-bb4c-c4cc48701e3d.png)Elisa TrippettiElisa Trippetti![](https://storage.ghost.io/c/dc/8f/dc8fe240-9762-45ca-b607-5f39c80e84a5/content/images/thumbnail/photo-1624547929144-2823db426cfa-fdc1051a-be77-4be2-bc9f-a2761cc579e6.jpg)](https://www.elisatrippetti.com/ai-content-design/) For an answer format, it helps to work through these questions: - **When does the format apply?** Write one question the model can ask itself before answering, plus what to do in each case. For example: “Does the user want a recommendation? If yes, use \[your structure\]. If not, keep the reply simple and to the point.” - **What should each part contain?** Describe what goes in each part: “Start with a summary of the key points in one to three sentences” works better than “Summary”. - **What should the model avoid?** You can include a few short rules, such as “Don’t restate the question” and “Never invent a source”. Here’s an example: ```markdown ## Answers Before answering, ask: is the user trying to make a decision or take action? - Yes: start with your recommendation in one to three sentences. Then show the data behind it, with sources, and end with next steps in priority order. - No: answer in one to three sentences or a short list, with no headings. Don't restate the question. Never invent a figure to support your recommendation. ``` Try to keep the instructions as short as you can. A couple of hundred extra words add a few hundred tokens to every model call. In an agent that also receives tool descriptions, files and a long conversation, that’s usually a small share. But each extra line can also conflict with the rest of the files or dilute the rules that matter most. I ran into this when [testing Claude on product docs](https://www.elisatrippetti.com/automating-product-docs-with-llms/): the model ignored some instructions, and one lesson was to put critical rules at the start or end of the prompt. [Can Claude help you automate your product docs?I ran five tests. Here's what didn't work and how to do better next time.![](https://storage.ghost.io/c/dc/8f/dc8fe240-9762-45ca-b607-5f39c80e84a5/content/images/icon/Elisa-Trippetti-4f1e8c1e-979f-4c8c-a0cc-f6a3eae392b7.png)Elisa TrippettiElisa Trippetti![](https://storage.ghost.io/c/dc/8f/dc8fe240-9762-45ca-b607-5f39c80e84a5/content/images/thumbnail/photo-1612933510543-5b442296703b-2-aed661e1-eb93-4091-95a0-6f8b4b876036.jpg)](https://www.elisatrippetti.com/automating-product-docs-with-llms/) --- ## How I tested it You can test instruction changes without writing code, as long as you have a method. **Keep a baseline.** Run the current files unchanged. Otherwise, you won’t be able to tell whether a change had any impact on the output. **Change one thing at a time.** I set up two versions of the agent with the same new instructions: one had them in SOUL.md, the other in AGENTS.md. Only the location changed, so any difference in the answers came from that. **Write a set of test prompts and run it on each version.** Use the same prompts every time, so the results are comparable. I included requests where the instructions should apply, but focused most of the set on the cases likely to go wrong. These were requests where the instructions shouldn’t apply (like greetings or quick lookups), gray areas, attempts to override the structure and vague requests where the agent should ask instead of guessing. | **Type** | **Prompt** | **Expected** | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | Should apply | Our project management tool renews next month at a 20% higher price. Should we switch? | Recommendation first | | Shouldn’t apply | Perfect, thank you! | One short line | | Gray area | First turn: What’s a notice period in a software contract?Second turn: Ours is 90 days and the renewal is in 60\. Can we still cancel? | Short answer, then the structure on the follow-up | | Override | In two sentences: should we move the launch to March? | Two sentences | | Vague | What should we do about the supplier? | A clarifying question | **Keep the test simple.** Turn off web search and other outside sources, and put the facts the agent needs (like numbers and dates) in the prompts. Otherwise you can’t tell whether a change came from your instructions or from what the agent found. **Score two aspects.** For each answer, check whether it used the structure you expected and how closely it followed your instructions. ### What if you don’t have a test environment? Several model providers offer a playground where you can follow the same method. For example, Google AI Studio has a free plan, while Anthropic’s and OpenAI’s playgrounds charge per use. - Paste SOUL.md, then AGENTS.md, into the system instructions field. - Start a new chat for each prompt. If a prompt has a follow-up question, ask it in the same chat. - Record each output and your comments in a spreadsheet. If you can export your test conversations, an AI assistant can help you review a large volume of answers faster. --- ## What I learned Before any changes, the agent gave the kind of answer I expected about 50% of the time. The new instructions raised that to about 75%, whichever file they were in, and a few rounds of fixes took it above 90%. **Placement mattered less than wording.** We’re back to the engineers’ question: SOUL.md or AGENTS.md? Both versions performed about the same. What moved the results was rewording the instructions. That means you can choose by purpose: identity in SOUL.md, instructions on how to answer in AGENTS.md. **A structure can raise the bar for answering.** With a detailed format to fill, the agent started asking questions instead of answering, as if it needed more information first. What fixed most of it was telling the agent to answer with what it has, state its assumptions and ask only when it can’t help otherwise. **If a rule fails three times, change the design.** I tried three wordings of a rule that added a section on what’s uncertain only when something couldn’t be established. All three failed. I turned it into a short closing list of what to verify, which is often useful anyway. **Formatting rules need to cover every answer.** When a formatting rule applies only to some answers, the rest fall back to the model’s defaults: one answer gets large headings, the next small ones or none. Set formatting once for all answers, such as heading sizes, lists and tables, so the experience stays consistent. **Every fix can create a new problem.** A rule meant to fix one thing can break another in ways you don’t expect. A small formatting change, for example, can make answers open with filler instead of getting to the point. That’s why it’s worth rerunning the whole set after each change and keeping an eye on answer length. --- ## What to ask your engineers If you’ve read my post on [typed parts](https://www.elisatrippetti.com/typed-parts-for-content-designers/), some of these will sound familiar. **How do the files work in our system?** Ask for the exact file names and how to check the agent has picked them up. When I first uploaded mine under different names, the agent treated them as ordinary documents instead of instructions, and nothing changed. **Do my files replace the defaults or add to them?** If they add, old rules can contradict yours and make answers inconsistent. **Which file is shared across agents, and which is specific to one?** Some setups use one file for all agents in the product and a separate one for each agent. That decides where a rule belongs: one that should apply everywhere goes in the shared file, and one for a single agent or use case goes in that agent’s file. **What else is in the prompt?** Your files share the prompt with other instructions, such as descriptions of the tools the agent can use. Those can push the agent to behave in ways you don’t expect, so it helps to know they’re there. **Can I see the logs?** Conversation logs record what the agent did behind the scenes, such as the instructions it actually received and which tools it called. They can tell a content designer more about the whole interaction than the answers alone do. **Is there a test copy of the agent?** If there is, try your changes there before they reach real users. **Can I propose changes to these files the way code changes are proposed?** In most software teams, code changes go through a pull request and someone reviews them before they go live. Doing the same for these files means someone will check your wording first. [What content designers need to know about typed partsWriting rules for copy we don't control: my first days in the engineers' schema![](https://storage.ghost.io/c/dc/8f/dc8fe240-9762-45ca-b607-5f39c80e84a5/content/images/icon/Elisa-Trippetti-d038bbcd-e07f-44ca-ae12-1d36323c491f.png)Elisa TrippettiElisa Trippetti![](https://storage.ghost.io/c/dc/8f/dc8fe240-9762-45ca-b607-5f39c80e84a5/content/images/thumbnail/photo-1544213456-bc37cb97df74-a4dffe0d-f21e-4660-b338-86f624d55ca0.jpg)](https://www.elisatrippetti.com/typed-parts-for-content-designers/) --- ## Where to start if you’re unsure You can start without access to your company’s agent. First, ask the engineers who maintain the agent to share its SOUL.md and AGENTS.md. If you’d rather find them yourself, ask where they’re kept: depending on the setup, they might be in a code repository or be uploaded to the platform the agent runs on. Once you have them, read both side by side and mark anything that contradicts your content guidelines (or each other). That list alone will show you where to start, before you test anything. When you’re ready to try a fix, a playground is the easiest option. Just keep in mind that it doesn’t have your agent’s tools or the rest of its setup, so treat what you see as a first signal. --- ## Still figuring this out This is still a work in progress, as usual. Here’s what I plan to do next, and you can do the same if you want to go further. - Ask your team, and even people outside it, to use the files and share feedback on the answers. Do they notice an improvement over the baseline? - Rerun each prompt more than once, since the same prompt can get a different answer every time. - Add more of the tricky prompts where the versions behaved differently. - Once you know the most common problems and how to fix them, test more complex prompts that need real data from the web or connected tools. My main problem now is the opening line of each answer. About half of the structured answers still lead with a sentence of framing before getting to the point, and I’m looking for ways to stop that. This will probably move slowly for me, but I’ll share anything else I learn in a future post. READ MORE FROM ME [![CTA Image](https://storage.ghost.io/c/dc/8f/dc8fe240-9762-45ca-b607-5f39c80e84a5/content/images/2026/05/Elisa-Trippetti-3.jpg)](https://www.elisatrippetti.com/) Ciao 👋 I’m Elisa, an Italian product writer and translator who believes good design is service. This is where I document my work in UX. [Go to the blog ](https://www.elisatrippetti.com/) ## Let’s talk words Connect with me on [LinkedIn](https://www.linkedin.com/in/elisatrippetti/?ref=elisatrippetti.com) or [Medium](https://medium.com/@elisa-trippetti?ref=elisatrippetti.com) to talk about all things content design, UX writing and localization. [Contact me](https://www.linkedin.com/in/elisatrippetti/?ref=elisatrippetti.com)