Markdown is the New API: How SKILL.md and AI Gateways Unlock AI-Native Organizations

Hello people!

Today I want to talk about something that genuinely got me excited over the last months, how we are building AI systems inside engineering organizations, and more importantly, how we should think about them architecturally.

I’ve been spending a lot of time designing, experimenting, breaking, and rethinking AI-driven tools in real production environments. Not as demos, not as side projects, but as systems that engineers actually rely on to do their jobs better.

During this journey, I started noticing a recurring pattern: most of the complexity we add around AI integration is not coming from the models themselves, it’s coming from how we try to connect AI to our tools, data, and processes.

Recently, while following the work around Clawdbot / Moltbot and reading thoughts from its creator, I came across a deceptively simple idea that completely changed how I think about AI integration: what if instead of building heavy protocols and servers, we simply taught AI agents how to use tools using Markdown?

At the same time, I was proposing the concept of an AI Gateway, a centralized, secure, and model-agnostic way to connect AI agents to internal systems with proper governance, context, and cost control.

That’s when it clicked.

My idea with this article is to share how these two concepts, SKILL.md (Markdown as an interface) and AI Gateways (central orchestration), are not competing ideas, but complementary ones. Together, they form a powerful foundation for what I believe is the next step in engineering organizations: AI-native architecture.

This article is not about implementation details or specific tools. It’s about mindset, leverage, and how small architectural decisions can unlock massive productivity, better governance, and long-term ROI.

If you’re an engineering leader, architect, or someone thinking seriously about AI beyond chatbots and copilots, I hope this perspective resonates with you.

Let’s dive in.

Introduction: From Complexity to Clarity in AI Integration

AI agents are rapidly becoming co-workers in modern organizations, but integrating them with existing tools and data is often daunting. Traditional approaches have involved building complex integrations or Model-Context Protocol (MCP) servers for each system, essentially bespoke APIs or plugins so an AI can use a tool. This has meant high engineering effort and heavy context overhead.

Today, two ideas are converging to simplify this problem in a surprisingly elegant way:

1. Using simple Markdown “skill” files as the interface to tools
2. Deploying a centralized AI Gateway as an orchestration layer for all internal systems

Together, these approaches democratize tool integration, accelerate AI readiness, and lay the foundation for truly AI-native software architecture. In this article, we’ll explore how Markdown-as-interface and Gateway-as-orchestrator complement each other, and why embracing both can unlock outsized ROI, developer productivity gains, and a durable competitive edge.

SKILL.md: Markdown as the AI Interface to Tools

The “old” way

To make an AI agent use a service or API, teams have been creating MCP servers or custom plugins, essentially middleware that translates AI requests into API calls. This often duplicates functionality that already exists in command-line tools or simple scripts. Worse, MCP integrations tend to bloat the AI’s context window with lengthy specifications.

In practice, many MCPs end up re-implementing capabilities already available in mature CLI tools, flooding the context with unnecessary information and degrading agent performance. A concrete example: an official GitHub MCP initially consumed ~50k tokens of context (later ~23k) just to teach the agent how to create issues or merge code, functionality that already exists in the lightweight gh CLI.

The new way

After the rapid success of Clawdbot / Moltbot, I became curious about why it worked so well and why adoption happened so quickly. Instead of focusing on the model itself, I started digging into the ideas behind the tool and reading content from its creator, Peter Steinberger.

The insight was refreshingly simple.

Rather than building MCP servers, the agent is given access to a shell and a Markdown file, typically called SKILL.md , that explains how to use a tool in plain language. In many cases, the instructions don’t even need to be verbose: the agent can invoke a CLI command, inspect --help output, and infer usage patterns on its own.

A SKILL.md file is essentially a concise user manual written for an AI agent.

More precisely:

Skills are Markdown files that teach an AI agent how to interact with tools in a specific environment, what the tool does, how to invoke it, expected inputs and outputs, examples, and operational constraints, without modifying or retraining the underlying model.

In practice, this means that if you already have a CLI for your database, ticketing system, or internal service, you can add a SKILL.md with a clear explanation of how it works. The next time the agent needs to retrieve a customer record or close a Jira ticket, it reads the Markdown and executes the appropriate commands via shell access.

No custom servers.
No protocol ceremony.
No retraining.

Why “Markdown is all you need”

This approach flips tool integration from a heavy engineering task into a documentation task.

Markdown is all you need, sorry for the analogy, but nothing better than using the same paper name that introduced Transformers (the heart of modern AI models and agents) to create an impactful term for this article.

Markdown skill files are developer-friendly, lightweight, and fast to produce. They carry almost zero runtime overhead: the skill is only loaded when needed and doesn’t permanently consume context. CLI tools already expose their affordances through help text and conventions, so the agent pays virtually no “context tax” compared to always-loaded MCP specifications.

In other words, a good README can often replace an entire integration layer.

This dramatically lowers the barrier to making internal tools AI-ready. Any engineer who can explain how something works can enable an agent to use it. The result is a true democratization of tool integration: you don’t need to wait for a platform team to ship an official plugin, a single SKILL.mdgets the job done.

Boosting velocity and consistency

Using Markdown as the interface also unlocks scale and consistency.

Organizations can curate libraries of skill files, version-controlled alongside code, encoding everything from cloud deployments to compliance checks. These become executable operational knowledge.

The same skill file can be reused across multiple AI platforms because it’s just text. This creates a “write once, deploy everywhere” effect (yes, if you know this term, you are a JVMdinosaur, and if you know me, you know I love Java*, especially the JVM nature*).

Consistency improves as well. If every agent reads from the same SKILL.md, procedures and standards are followed the same way every time. Instead of building one-off AI integrations, teams write down what their best engineer would do, and let the agent follow the playbook.

The ROI is immediate: minimal onboarding cost and rapid productivity gains. Clawdbot itself demonstrated this clearly, a single developer, empowered with a large set of CLI-based skills, was able to achieve output that normally requires a team.

The AI Gateway: A Central Orchestrator for Context and Tools

If SKILL.md files are decentralized, developer-first interfaces, the AI Gateway is the centralized layer that allows those skills to operate safely and coherently across an organization.

Think of the AI Gateway as an AI control tower. It connects to source code repositories, documentation, ticketing systems, data warehouses, dashboards, and internal services, exposing a unified and secure API to AI agents.

Instead of point-to-point integrations, the gateway acts as a model-agnostic middleware that any agent can use to interact with internal systems under clearly defined rules.

Solving fragmentation with orchestration

Modern platforms increasingly ship their own AI assistants, Atlassian Rovo, GitHub Copilot, and others. Without a unifying layer, this quickly turns into a fragmented landscape of isolated AI capabilities.

The AI Gateway addresses this by centralizing orchestration. It coordinates multiple specialized agents, enables tool chaining across systems, and enforces organizational policies consistently. The focus shifts from optimizing individual agents to designing a coherent, enterprise-wide AI fabric.

Full context, full control

AI agents are only as capable as the context they can access.

A centralized gateway can dynamically inject relevant internal knowledge into an agent’s reasoning flow, dashboards, logs, code, or data, allowing the agent to reason holistically instead of operating in silos.

At the same time, the gateway acts as a guardrail layer. Authentication, permission enforcement, auditing, and rate limiting all happen in one place. This prevents agents from accessing data they shouldn’t, executing unsafe actions, or generating untraceable side effects.

Model-agnostic and future-proof

Because the gateway abstracts model access, organizations can adopt new models over time without rebuilding integrations. Internal systems integrate once with the gateway; agents evolve independently.

This decoupling is fundamental to AI-first architecture. You can upgrade the brain without rewiring the body.

The gateway also enables complex, multi-step workflows. An onboarding agent can provision accounts, create records, send messages, and update systems in sequence, all orchestrated centrally and audited end-to-end. Individual skills become instruments; the gateway becomes the conductor.

Dual Architecture: AI Agents with Knowledge and Action

Individually, Skills and the AI Gateway solve different problems. Together, they form a powerful dual architecture.

• Markdown Skills = what to do.
  They teach the agent what actions exist, when to use them, and how to execute them correctly.
• AI Gateway = how and where to do it.
  It routes those actions into real systems, with the right permissions, context, and safeguards.

When an agent tackles a task, it follows a simple loop:

1. Understand — load relevant SKILL.md files and plan actions
2. Execute — invoke those actions through the AI Gateway

This unlocks adaptive, context-aware agents that can both learn and act. And yes, you got it right: using proper skills, you can save a huge amount of money in LLM/SLM fine-tuning and often achieve even more accurate results, without preparing massive training datasets.

We’re effectively giving agents a brain (reasoning + documentation) and a body (tools + execution), designed to work together.

Convention Over Configuration: AI Edition

If all of this is starting to feel familiar, that’s because it is.

What this architecture is really doing is enabling one of the most successful ideas in software engineering to finally work for AI systems: Convention over Configuration.

For decades, Convention over Configuration helped engineering teams move faster by eliminating unnecessary decisions. Instead of forcing developers to configure everything explicitly, frameworks defined sensible defaults and clear conventions. If you followed the convention, things just worked. Configuration was still possible, but only when you truly needed it.

Skills and AI Gateways bring that exact same principle into the AI world.

A SKILL.md establishes a convention for how an AI agent should interact with a tool:

• where the entry point is
• how commands are invoked
• what inputs and outputs look like
• what rules and constraints must be respected

There’s no custom wiring per agent, no bespoke prompts per use case, no endless configuration knobs. If a tool follows the convention (CLI + SKILL.md), the agent already knows how to use it.

The AI Gateway completes the picture by enforcing conventions at the execution layer:

• how identity is propagated
• how permissions are evaluated
• how costs are tracked
• how actions are audited
• how models are selected

From the agent’s perspective, every system now looks familiar. Different tools, same mental model.

This is incredibly powerful.

Instead of configuring every agent for every system, we define shared conventions once and let agents operate within them. The cognitive load shifts from “how do I make this work?” to “what do I want the agent to do?”.

Just like Rails or Spring Boot did for application development, this architecture removes accidental complexity and lets teams focus on outcomes rather than plumbing.

And this is where the real leverage comes from:
When AI systems can rely on conventions instead of configuration, they become predictable, composable, and scalable by default.

That’s not just good engineering, that’s how you turn AI from an experiment into infrastructure.

AI-Native Architecture: ROI, Productivity, and Competitive Edge

These ideas represent a strategic shift toward AI-native architecture.

Instead of bolting AI onto legacy systems, AI-native systems assume agents exist from day one. Documentation is written for humans and agents. APIs are exposed with agent interaction in mind. Infrastructure is designed to reason, act, and audit.

The ROI compounds quickly. Writing a SKILL.md replaces weeks of integration work. Once connected through a gateway, agents can take over large portions of operational toil, deployments, diagnostics, reporting, data aggregation.

Consistency improves, errors are reduced, and onboarding accelerates as institutional knowledge becomes written, shared, and executable instead of implicit. As models improve, the architecture benefits automatically, without rewrites.

Conclusion: Embracing the AI-First Future

The convergence of Markdown-based skills and centralized AI gateways points to a new operating model.

Any internal tool can become AI-usable simply by being explained. Any agent action can be governed centrally. By combining these ideas, we can create a symbiotic system where tools document themselves for agents and agents operate safely within organizational boundaries.

If you are an engineering leader, the path forward is clear: treat SKILL.md as a first-class artifact and invest in an AI Gateway as foundational infrastructure. Together, they unlock a dual architecture that turns AI from a feature into a capability woven throughout the organization.

The knowledge is already there.
The tools already exist.
Now we just need to let agents read, and act.

My hope is that this perspective helps engineering leaders think differently about AI, not as a feature to bolt on, but as a capability to architect for. When knowledge becomes executable and access is governed by design, AI stops being risky and starts being transformational.

Happy agenting, see you in the next article.