← Back to blog

AI systems and workflows

The operating manual behind an AI tool: What do .md files actually do?

Imagine that you have built a custom AI tool. The model is ready, its tools are connected, and the interface works. The model still does not automatically know which record your organization treats as authoritative, the order in which a job should run, or when it must return to the user. This is where .md files become useful. They are not secret files that make AI smarter; they hold the tool's operating manual, domain knowledge, and working rules in an explicit form.

Anıl MirapAugust 10, 20268 min read

The simplest answer first

.md is not an AI-specific file format.

Markdown is plain text. A few simple symbols can express headings, lists, links, tables, and code blocks. It opens in any text editor, remains easy for people to read, and is straightforward for software to process. That combination is exactly why it works well in AI systems: the content stays in natural language while its structure remains visible.

Headings communicate hierarchy, lists communicate sequence, and code blocks preserve examples that should not be rewritten. The model sees more than one uninterrupted paragraph; it receives clearer boundaries between topics and their relationships. The extension itself still carries no intelligence. If the surrounding system never discovers or loads the file, that .md file cannot influence behavior.

Markdown is therefore better understood not as 'a format AI likes,' but as a shared context layer that people can author and machines can consume in an orderly way.

A prompt is not yet a tool

A chat instruction is temporary; a custom tool needs persistent behavior.

For a one-off conversation, you can explain the task in a message. A tool used every day, shared by several people, or allowed to act on other systems needs something more durable. Requiring every user to repeat the same explanation makes behavior dependent on individual memory.

Consider an AI tool that evaluates requests arriving at an IT warehouse. It needs more than 'classify this request.' It must know which inventory record is authoritative, how urgency is determined, when an action may happen automatically, and when responsibility must return to a person. Those are not details the model can infer from general knowledge; they are organization- and process-specific requirements.

.md files move those requirements out of chat history and into the tool's lasting definition of work. They combine elements of an AI requirement specification, a work instruction, and an operating manual.

A modular structure

Use small files with clear jobs instead of one giant prompt.

Putting the role, all domain knowledge, every rule, and every example into one text looks simple at first. A healthier structure gives each file one responsibility.

custom-ai-tool/

  • AGENT.mdIdentity and behaviorPurpose, intended users, priorities, and work that is out of scope.
  • KNOWLEDGE.mdDomain knowledgeTerminology, business rules, authoritative sources, and internal meanings.
  • WORKFLOW.mdWorkflowSteps from input to result, decision points, and the definition of completion.
  • RULES.mdOperating boundariesWhich tool to use when, what is prohibited, and where the tool must stop.
  • EXAMPLES.mdBehavior examplesGood and bad outputs, expected tone and format, and error handling.
  • tools/Execution layerAPI calls, calculations, file processing, and other deterministic operations.

These names are illustrative. Some platforms expect specific conventions such as AGENTS.md or SKILL.md, so the discovery and loading rules of the chosen system must take priority.

The context budget

Not every file belongs in every task.

Modularity is useful for more than tidy folders. When a user asks for an email draft, inventory policy is irrelevant; when they request data analysis, corporate writing examples are unnecessary. Irrelevant content consumes tokens, reduces the visibility of important rules, and distracts the model.

A well-designed tool first sees concise file descriptions or metadata and then loads only the documents related to the task. Task skills, retrieval, and RAG systems follow the same principle: all knowledge does not stay in context all the time; the right knowledge is retrieved when it is needed.

The name and contents of a file therefore matter alongside its description and trigger. An excellent .md file that no workflow ever calls is archived knowledge, not working context.

Two approaches

The same knowledge, two different architectures.

The design question is not only whether Markdown is used. It is how knowledge is divided and when each part enters context.

Fragile approach

One giant prompt

  • The role, rules, all domain knowledge, and every example live in one text.
  • The entire body enters context for every request.
  • A small edit may affect unrelated tasks.
  • Contradictions, duplication, and stale information are difficult to find.
Sustainable approach

Modular .md files

  • Shared principles, workflows, knowledge, and examples occupy separate layers.
  • Only relevant files load when needed.
  • The scope and owner of each change are clearer.
  • A behavior change can be reviewed as a small Git diff.

Show, do not only tell

EXAMPLES.md can be more useful than ten pages of rules.

AI models learn strongly from patterns as well as explicit rules. 'Write a concise, technical, non-accusatory explanation' provides direction; a good example simultaneously demonstrates length, tone, level of detail, and paragraph rhythm.

Good-and-bad example pairs are especially valuable for output schemas, error messages, report formats, and tool-routing decisions. They show the model what an acceptable result looks like and what must not pass. This is often more effective than adding more adjectives and abstract instructions.

An example should not become the only correct answer. A small representative set should expose the boundaries of behavior without forcing the model to copy names and sentences mechanically.

The right information in the right layer

.md is not a replacement for everything else.

A custom AI tool works through several layers with different responsibilities. Markdown is an important part of the system, not the whole system.

  1. 01ModelLLM

    Reasons about context, interprets ambiguity, and produces natural language.

  2. 02Behavior and domain knowledge.md

    Carries purpose, workflow, rules, terminology, and examples.

  3. 03Deterministic operationcode

    Makes calculations, validation, file conversion, and API operations repeatable.

  4. 04ConfigurationJSON / YAML

    Stores schemas, parameters, and values that machines must parse exactly.

  5. 05Current or large-scale dataAPI / DB / vector search

    Retrieves volatile records and high-volume knowledge when needed.

Version control

A change to a .md file is a change to behavior.

When instruction files live in a version-control system such as Git, changes to the tool's behavior become visible. Teams can inspect which rule was added, why an exception changed, and how the previous version worked line by line. The change can be rolled back when necessary.

This moves prompt editing away from private experimentation and closer to a managed engineering activity. A domain expert can review the wording, a developer can assess technical feasibility, and the modified behavior can be tested again with the same example tasks.

History alone does not guarantee quality. It does, however, replace 'the model answered differently again' with a concrete check of whether the behavior definition supplied to the model also changed.

Boundaries

Not everything belongs in a .md file.

Passwords, access keys, and sensitive personal information should not live in readable text files. Constantly changing inventory, prices, and user lists should not be copied into Markdown either; they should come directly from the current system. Markdown may explain how to use a source, but it should not replace a live source.

Deterministic work such as exact calculation, authorization, schema validation, and data transformation should not rely on natural-language instructions. If the same input must always produce the same result, code should enforce that behavior.

Finally, a well-written file does not guarantee correct behavior. The system must actually load it, the rules must remain consistent, and the tool must be tested against positive and negative scenarios. Documentation creates control; it does not replace verification.

A practical starting point

Five clear decisions are enough for a first version.

Before increasing the file count, make the tool's operating logic visible through five questions.

  1. 01

    Which problem does the tool solve, for whom, and which work is explicitly out of scope?

  2. 02

    Which sources are authoritative during the task, and which domain terms need a fixed meaning?

  3. 03

    Which steps, decision points, and completion criteria define the workflow?

  4. 04

    Which operations belong in code or tools, and when must the system ask the user or stop?

  5. 05

    What do a good result, a bad result, and a boundary case look like in concrete examples?

↗

Working with .md files is not merely saving one long prompt into a document. The real design work is separating the tool's identity, knowledge, workflow, rules, and examples into manageable parts. Building a strong custom AI tool is therefore not only prompt engineering; it is also requirements engineering and system design.