Using agent.md to Define Agent Personas

The agent.md file is what separates a generic AI chat from a customised, persistent agent. It defines the rules, personality, and standing instructions for the agent running inside a given folder.

What is agent.md?

agent.md is a Markdown file created by running cos init in any folder. Every time you start a session in that folder, the agent reads this file first — before doing anything else. Think of it as the agent’s briefing document.

It follows an established standard (sometimes called the AGENTS.md standard), which means Cosine applies whatever you put in there consistently across every session.

What You Can Put in agent.md

There are no strict rules for what goes in agent.md — you can put anything you want the agent to remember. Common things to include:

• A persona or role: “You are an expert social media content strategist.”
• Tone and style rules: “Always write in a clear, direct tone. No emojis. No filler phrases.”
• Workflow instructions: “Save all research as .md files in this folder before drafting anything.”
• Context about the project: “This folder is for drafting outreach emails to enterprise customers. Our product is Cosine, an AI software engineering agent.”
• Model or behaviour preferences: “When researching, always look at our Notion knowledge base first.”

Example agent.md Files

Social Media Agent

You are an expert social media content strategist and copywriter.

Voice and tone:
- Clear, confident, and conversational
- No emojis
- Avoid buzzwords and filler phrases
- Punchy sentences — maximum 2 lines per paragraph

Workflow:
- Before drafting any post, save research notes as `.md` files in this folder
- Always check previous posts in this folder to maintain consistency

Sales Outreach Agent

You are a world-class sales professional. Think Harvey Specter from Suits — confident, precise, and deeply persuasive without being pushy.

Context:
- Product: Cosine — an AI software engineering agent
- See `vision.md` in this folder for the full product vision and differentiators

Workflow:
- Prioritise leads by ARR potential
- Discard any contacts with invalid or generic email addresses
- Draft personalised emails that reference the customer's specific context

Evolving Your agent.md Over Time

A key habit for getting the most out of Cosine: whenever you find yourself typing the same instruction repeatedly in a session, add it to agent.md.

The agent will apply it automatically next time — you only ever have to say it once.

For example, if you keep reminding the agent to check a certain file before drafting anything, add that as a rule. If you keep asking it to avoid a certain phrase or format, add that too. Over time, your agent becomes increasingly tailored to exactly how you work.

agent.md is Folder-Level, Not Global

Each folder has its own agent.md. There is no system-level or global agent.md. This means you can have completely different agents for different projects — a research agent in one folder, a coding agent in another, a sales agent in a third — all running simultaneously with completely different personalities and rules.

Key Takeaways

• agent.md is the briefing document your agent reads at the start of every session.
• Use it to define persona, tone, workflow rules, and project context.
• Add new rules whenever you find yourself repeating the same instruction.
• Each folder has its own independent agent.md — agents don’t share system-level instructions.

---

Next: Working with Multiple Agents in Parallel