The case for running AI agents on Markdown files instead of MCP servers

A two-layer architecture is emerging in production AI agent systems: Markdown skill files for encoding domain knowledge (workflows, conventions, policies) and MCP servers strictly for runtime execution (API calls, database queries). The key insight is that many MCP servers were built to solve knowledge problems rather than execution problems, resulting in massive token waste — the GitHub MCP server consumes 23,000–50,000 tokens vs. ~200–500 tokens for an equivalent SKILL.md file, a 100x difference. Real-world examples include Brad Feld's CompanyOS (12 Markdown files + 8 MCP servers), Supabase's agent-skills repo, and Microsoft's .NET Skills Executor. The practical framework: if an agent needs to *know* something, use a skill file; if it needs to *do* something at runtime, use MCP. Skill files also benefit from git-native workflows — editable as plain text, reviewable in PRs, with no redeployment needed to change agent behavior.