4/5 AGENTS.md: Teaching AI How You Work

December 24, 2025 · 6 min read

#AGENTS.md #GitHub Copilot #AI #VSCode #ai-augmented-workflow

Previous: GitHub Copilot Beyond Code: Your AI Writing Partner

Post 3 ended with a problem: Copilot forgets your rules between sessions. You tell it “keep the voice whimsical” and it does — once. Next time you open the project, it defaults to generic.

AGENTS.md fixes this. It’s a file in your project root that AI tools read automatically. Your rules persist because they’re in a file, not in a conversation.

README vs AGENTS.md

You already know README files — they tell humans what a project is about.

AGENTS.md does the same thing for AI:

	README.md	AGENTS.md
Audience	Humans	AI assistants
Purpose	”What is this project?"	"How should you behave in this project?”
Content	Description, setup, usage	Role, style, constraints, boundaries
Read by	Developers, users	Copilot, Claude, ChatGPT

40,000+ projects on GitHub already use AGENTS.md. It’s backed by OpenAI and Google as a standard way to give AI context about a project.

Anatomy of AGENTS.md

A good AGENTS.md has five sections:

1. Role

Who is the AI in this project?

## Your Role

You are a **creative storyteller and educator** who transforms
dry computer science concepts into enchanting fairy tales.

Think: Brothers Grimm meets Donald Knuth.

This isn’t just flavor text. It changes how Copilot generates content. “Creative storyteller” produces different output than “technical writer” or “documentation assistant.”

2. Project Structure

Where things live. AI tools use this to navigate your project:

## Project Structure

algorithm-fairy-tales/
├── AGENTS.md              # This file
├── tales/                 # Individual fairy tale stories
│   ├── sorting/           # Sorting algorithm tales
│   ├── searching/         # Search algorithm tales
│   └── graphs/            # Graph algorithm tales
├── presentations/         # Marp slide decks
└── assets/                # Images and diagrams

3. Style Guide

The voice, structure, and conventions:

## Writing Style

### Voice & Tone
- Whimsical but not childish
- Educational but not lecturing
- Use fairy tale conventions (Once upon a time, kingdoms, quests)
- Include subtle technical accuracy beneath the metaphor

### Story Structure
Every tale follows this pattern:
1. **The Kingdom** — Introduce the problem domain as a setting
2. **The Challenge** — Present the computational problem as a quest
3. **The Hero's Method** — The algorithm as a character's approach
4. **The Journey** — Step-by-step walkthrough as narrative
5. **The Moral** — Time/space complexity as wisdom gained

4. Character Archetypes

Domain-specific mappings that ensure consistency:

### Character Archetypes
| Algorithm Concept | Fairy Tale Character |
|-------------------|---------------------|
| Array | A row of cottages in a village |
| Pointer | A magical compass or guide |
| Recursion | A mirror that shows smaller mirrors |
| Stack | A tower of plates in a giant's kitchen |
| Queue | Villagers waiting at the bakery |
| Tree | An actual enchanted tree with branches |
| Hash table | A magical librarian who knows every book's location |

Without this table, Copilot invents new metaphors every time. With it, arrays are always cottages, stacks are always plate towers. Your fairy tale world stays consistent.

5. Boundaries

The three-tier pattern that prevents AI from going off-script:

## Boundaries

### Always Do
- Maintain technical accuracy beneath the metaphor
- Include time complexity as "the moral of the story"
- Add speaker notes with storytelling guidance
- Use Mermaid diagrams for algorithm visualization
- Keep language accessible to non-programmers

### Ask First
- Before introducing new character archetypes not in the table
- Before changing the established story structure
- Before adding code snippets (storytelling, not coding)

### Never Do
- Never use actual code syntax in the tales
- Never break the fourth wall or mention "algorithms" directly
- Never use jargon without a fairy tale equivalent
- Never create tales longer than 1500 words
- Never skip the "moral" (complexity analysis)

Always / Ask First / Never is the key pattern. It gives AI clear lanes:

Always: do this without asking
Ask First: check with me before doing this
Never: hard boundaries, no exceptions

The Before/After Test

Here’s the same prompt, without and with AGENTS.md:

Prompt: “Write the opening paragraph for a story about breadth-first search.”

Without AGENTS.md (generic Copilot):

Breadth-First Search (BFS) is a graph traversal algorithm that explores all vertices at the current depth before moving to vertices at the next depth level. In this story, we’ll explore how BFS works through a practical example…

With AGENTS.md (fairy tale Copilot):

Once upon a time, in the Enchanted Forest of Connected Clearings, there lived a young cartographer named Bree. Unlike the wanderers who ventured deep into one path until they were hopelessly lost, Bree had a peculiar habit: she visited every clearing one step away before taking a second step. “First, meet all your neighbors,” she would say. “Only then should you meet their neighbors.”

Same AI. Same prompt. Completely different output. The AGENTS.md transformed Copilot from a documentation bot into a fairy tale author.

Hands-On: Write Your AGENTS.md

Create AGENTS.md in the root of your algorithm-fairy-tales/ project. Use the five sections above as your template.

Your project now looks like:

algorithm-fairy-tales/
├── AGENTS.md                    ← NEW: AI instructions
├── tales/
│   └── lady-binary.md           ← expanded in Post 3
├── presentations/
└── assets/

Open Copilot Chat. Ask it to write a new fairy tale — “The Bubble Kingdom” about Bubble Sort. Watch how it follows the five-part structure, uses the character archetypes table, and stays within the word limit.

Then try the same prompt in a project without AGENTS.md. The difference is immediate.

Templates for Other Content Types

The fairy tale AGENTS.md is creative. The pattern works for any content:

Blog posts:

## Your Role
Technical writer for an engineering blog.

## Style
- Direct, experience-first. No filler.
- Lead with what happened, not what you expected.
- Code examples must be runnable.

## Boundaries
### Never Do
- Never use "in this blog post we will..."
- Never add disclaimers about AI limitations

Business specifications:

## Your Role
Business analyst writing functional specifications.

## Style
- User stories in Given/When/Then format
- Acceptance criteria as checkboxes
- Diagrams in Mermaid, never screenshots

## Boundaries
### Always Do
- Include non-functional requirements
- Reference the data model
### Never Do
- Never assume implementation details

The structure is always the same: role, style, boundaries. The content changes per project.

What You’ve Built

Your fairy tale project now has:

A Markdown outline (Post 1)
A VSCode workspace with Git (Post 2)
A Copilot-expanded story with Mermaid diagrams (Post 3)
An AGENTS.md that keeps the AI on-brand (this post)

One thing remains: turning this story into a presentation. That’s Post 5 — where Marp converts your fairy tale into slides without ever opening PowerPoint.

Next: From Story to Stage: Creating Presentations with Marp

Back to Blog

Posts