What Are AI Instruction Files?

An AI instruction file is a plain-text document — usually Markdown — that tells an AI model how to behave. It defines the model's persona, rules, skills, and constraints before a single user message is sent. Think of it as a contract between you and the model: "Here's who you are, here's what you can do, here's what you must never do."

Why instruction files matter

Without instructions, every AI model defaults to a generic assistant persona — helpful but directionless. Instruction files transform a general model into a specialized tool. A senior code reviewer. A Socratic tutor. A security auditor who never rubber-stamps.

The difference between a good instruction file and no instruction file is the difference between a junior intern and a senior hire. Same brain, completely different output.

Common formats

Different AI coding tools expect instruction files in different formats, but the content is the same: structured Markdown that defines behavior. Here are the most common:

CLAUDE.md

Used by Claude Code (Anthropic's CLI agent). Placed at the project root, it's automatically loaded into context. Supports nested files in subdirectories.

.cursorrules

Used by Cursor, the AI-native IDE. Lives at the project root and instructs the embedded AI assistant on coding style, project conventions, and constraints.

.windsurfrules

Used by Windsurf (Codeium's IDE). Similar concept to Cursor rules — project-level instructions loaded automatically into context.

system-prompt.txt

Used by OpenAI Assistants and custom GPT configurations. Plain text injected as the system message before user conversation begins.

All four formats solve the same problem: giving the model a role, rules, and context before the conversation starts. MarkedDown can transpile a single instruction file into all four formats automatically.

What goes in an instruction file?

Instruction files typically contain some combination of these elements:

  • Role definition — who the model should act as ("You are a senior TypeScript engineer")
  • Behavioral rules — constraints like "never suggest console.log for production logging"
  • Output format — how responses should be structured (code blocks, bullet points, specific templates)
  • Domain knowledge — project-specific context, API conventions, architecture decisions
  • Escalation logic — when to ask for clarification vs. making assumptions
  • Anti-patterns — explicit "do not" lists that prevent common failure modes

The portability problem

Here's the issue: an instruction file that works brilliantly on Claude Sonnet might produce garbage on GPT-4o. Models interpret instructions differently. Some follow ordered lists religiously; others ignore numbered priorities. Some respect "never" constraints; others treat them as suggestions.

This is exactly the problem MarkedDown was built to solve. Every file in our library is scored with deterministic, reproducible tests across multiple models — so you can see compatibility before you download.

Types of instruction files

MarkedDown organizes instruction files into seven types, each serving a different purpose:

  • Skills — teach the model a specific capability (code review, data analysis, API design)
  • Personas — define a complete character with expertise, communication style, and judgment
  • Rules — enforce constraints and coding standards
  • Agents — autonomous workflows with decision loops and tool usage patterns
  • Souls — deep identity definitions with values, instincts, and worldview
  • Memories — persistent context files for project history and user preferences
  • Workflows — structured multi-step processes (PR review, incident response, deployment)

Getting started

The fastest way to understand instruction files is to read a few and try them:

  1. Browse the library — filter by type and category to find files relevant to your work
  2. Pick a file and read its content — every file page shows the full Markdown source
  3. Download it for your tool — one-click download for Cursor, Windsurf, Claude, or OpenAI
  4. Check the compatibility scores — see how well it performs on the model you use

Have an instruction file of your own? Publish it and we'll score it across models automatically.