How Markdown Became a Control Plane

Modern AI agent frameworks such as CrewAI, LangGraph, AutoGen, and countless enterprise-built implementations rely heavily on markdown files to configure agent behavior. A file like sales_agent.md might contain a complete behavioral specification: the agent's role and tone, which internal databases it's authorized to query, escalation rules for edge cases, and explicit hard limits on what it must never do. A guardrails.md file might define the safety constraints that apply across every agent in a deployment — data access restrictions, prohibited actions, compliance requirements.

Beyond individual agent configurations, the agents.md standard is spreading across toolchains as a persistent instruction layer for coding agents, telling them how to structure code, which libraries to use, and how to run checks. As this convention becomes more widespread, markdown is solidifying as the de facto configuration layer for agentic AI, both in open-source projects and inside enterprises.

These files are not static reference material. They are active inputs that shape agent behavior on every run. The framework loads them, parses the natural language, and feeds the contents into prompts that govern what the agent does.

A one-line change in a markdown file can expand or shrink the agent's access to tools and data, alter how it interprets ambiguous situations, or weaken safety rules without touching any executable code. The file format did not change. Its role did.

The Lifecycle Gap

Despite this power, the lifecycle of agent markdown files still looks like documentation management, not code governance. A developer writes agent_rules.md to define an agent's persona and behavioral boundaries. The file is committed to a shared Git repository. A CI/CD pipeline pulls it. The agent framework loads it at runtime. At no point in that chain is the file hashed or cryptographically signed. At no point is there a change review process comparable to what a code deployment would require. At no point does an auditable trail record who modified the file and when.

Anyone with access to modify that file in Git can change how the agent behaves in production. In many organizations, that is a long list including engineers, automation scripts, and sometimes external contributors if the repository was cloned from an open-source project.

Worse, these files often arrive from outside the organization entirely. Developers copy agents.md or skill markdown files from public GitHub repositories and drop them into internal agent deployments to get started quickly. Community-shared skills for AI coding tools and agent platforms are distributed as markdown instructions with minimal review. This is software supply chain territory but it is a layer that most security reviews still do not reach.

Five Attack Scenarios

1. Silent behavioral manipulation: An attacker modifies an agent's behavior file in a shared repository; no exploits, no shellcode, just slightly altered natural language. The agent begins favoring certain vendors when options are comparable, suppressing certain data sources from its analysis, or rephrasing negative findings in softer language. Code review tools looking for suspicious imports or function calls see nothing. The diff is text. The agent's decisions drift quietly over time.

2. Guardrail override: Safety constraints in AI agents are often defined in the same plain-text format as everything else. Weakening them can be as simple as editing a sentence. "Never send raw customer PII to external systems" becomes "Avoid sending raw PII unless explicitly asked." "Do not call tools that write to production databases" becomes "Use write tools when necessary to complete tasks." No policy engine changed. Only markdown.

3. Cascading contamination in multi-agent pipelines: In architectures where agents hand off outputs to other agents, a poisoned configuration file in one agent can corrupt every downstream process. Agent A reads a compromised .md file and produces tainted analysis. Agent B treats that analysis as trusted context. Agent C takes actions based on Agent B's output. One modified file, and the entire pipeline is compromised.

4. Data exfiltration through tool instructions: An agent's tool-use specifications, often defined in markdown, can be modified to craft API calls that route sensitive data to an external endpoint. An attacker might instruct the agent to add a blind-copy endpoint to a normal API payload, serialize more fields than intended into a "logging" call, or send intermediate analysis to an external URL under the guise of backup or monitoring. Because the agent already has authorization to make API calls as part of its normal function, the exfiltration happens inside the agent's existing permissions, staying invisible to controls that are not looking at behavioral configuration.

5. Worm-like propagation through shared skills: Because .md skill files spread so easily, a single malicious file in a popular GitHub repository can propagate quickly as teams clone and reuse it. Combined with emerging agent-to-agent communication protocols, a compromised agent can begin seeding poisoned instructions throughout a wider agentic ecosystem. One compromised node spreading its behavioral manipulation downstream through the same channels that make multi-agent collaboration possible in the first place.

Defending the Configuration Layer

The defense strategy starts with accepting a simple premise: if a file can change an agent's behavior in production, it does not belong in the documentation bucket.

• Governance parity: Every .md file that influences agent behavior should be subject to the same review, approval, and change management process as a code deployment. Pull requests, mandatory named reviewers, and auditable change histories are foundational requirements. If an agent behavior file can be modified without going through that process, the governance structure has a gap.

• Integrity controls: Agent instruction files should be hashed and cryptographically signed. Frameworks should verify integrity at load time and alert on unauthorized drift from approved baselines. The underlying mechanisms like content hashing, cryptographic signing, and file integrity monitoring already exist and are mature in most organizations for binaries and configuration files. They simply have not been extended to this file class.

• Behavioral auditing: Static code analysis will not catch a sentence that quietly instructs an agent to de-prioritize a business rule or route data to a new endpoint. Security teams need review processes that evaluate what an agent is instructed to do, not just the code that enables it to act. Practically, this means evaluation harnesses that exercise critical agents end-to-end against expected behavioral boundaries, simulate common attack patterns including prompt injections and malicious tool instructions, and run regression checks whenever agent markdown changes, not only when code changes.

• Clear ownership: AI supply chain risk sits at the intersection of application security, data governance, and ML engineering. In many organizations today, that means no single team owns the .md configuration layer: security assumes the AI team handles it, the AI team assumes DevOps handles it, and DevOps treats it like documentation. Explicit ownership must be assigned and documented. This is the same gap that software supply chain security fell into before high-profile incidents forced organizations to address it and it will be closed the same way, either proactively or in response to a breach.

Start with Visibility and Governance, Follow with Runtime Security

Shifting how teams develop and review agent configuration files is necessary. But good governance also requires knowing what you are governing in the first place. And most organizations deploying AI agents today do not have a clear, maintained picture of which agents are running, what skills they are loading, or how their behavior is configured.

This is the problem that SuperAlign is focused on. Before you can enforce a review process for .md files, you need to know they exist. Before you can monitor behavioral drift, you need a baseline of what the agent is actually supposed to do. Visibility and governance are the prerequisites for everything else.

In practice, that means helping security and AI teams answer questions they often cannot currently answer: Which agents are deployed across your environment, and what .md-based configuration are they loading? Who has access to modify those files, and has anyone done so recently? Where are agents pulling in external skills or instruction files from public repositories, and have those files changed since you last reviewed them?

Surfacing that picture across devices, repositories, and SaaS tools is where the work of governing agent supply chain risk has to start. Knowing where your behavioral attack surface actually is makes it possible to prioritize code review, provenance controls, and integrity checks where they matter most, rather than applying them uniformly and ineffectively across everything.

Treating .md files like code is the right direction. Getting visibility into which .md files are shaping your agents' behavior is what makes that governance actionable.

Even with signed .md files, careful reviews, and clear ownership, things will go wrong. A trusted maintainer can still make a bad or malicious change. A previously safe skill file from GitHub can behave differently after an upstream update.

This is where SuperAlign solution comes into the picture, providing real-time visibility and governance over how AI agents are being used across the enterprise.

Concretely, that means:

• Discovering AI agents and skills in use across endpoints and SaaS tools, including where .md-based configuration is being loaded and by whom.

• Logging all AI interactions so teams can see when live agent behavior diverges from what the markdown actually says.

• Detecting suspicious behavioral patterns such as new external endpoints appearing in tool calls, unusual sequences of high-risk actions like prompt injection or PII leak, or agents that begin operating outside their documented guardrails.

• Enforcing policies for granular control, so that even if a markdown file quietly expands an agent's permissions, that expansion cannot translate into dangerous operations without being flagged.

• Scoring risk across agents and skills based on their permissions, origin, and observed behavior, which makes it easier to prioritize security review and provenance work where it actually matters.

Treating .md files like code addresses the supply chain problem. Having a safety layer that monitors what agents actually do with those instructions addresses the runtime problem.

An Alignment Problem, Not Just a Security Problem

There is a dimension to this risk that sits beyond conventional cybersecurity framing. When an agent's behavioral configuration is tampered with, the agent does not behave maliciously from its own initiative. It follows instructions carefully and without hesitation. The agent has no native mechanism to distinguish a legitimate instruction from an adversarially crafted one if both arrive through the same trusted channel.

This is, at its core, an alignment problem. An AI agent faithfully executing a poisoned configuration file is doing exactly what it was designed to do: follow its instructions. The failure is in the system that allowed unverified instructions to reach it in the first place.

Building AI agents that reliably behave as intended across diverse contexts, adversarial inputs, and evolving configurations requires attending to the full stack. Not just model training and fine-tuning, but the runtime configuration layer that shapes how agents behave in deployment. Security over agent markdown files is not just an IT hygiene issue. It is part of what it means to field AI that actually does what you intend it to do.

Markdown has become a control plane for AI agents. That makes it part of your supply chain, and it deserves the scrutiny and runtime visibility you already apply to code and binaries. By focusing on both both network activity and endpoint-level visibility, SuperAlign helps complete the security and governance loop for AI agents in the modern enterprise.