A decade ago, we began orchestrating containers, declaring services, and configuring CI/CD with YAML; a decade later, we begin defining AI behaviors, rules, and collaboration patterns with Markdown.
From Kubernetes’ deployment.yaml to GitHub’s .prompt.md, AGENTS.md, and SpecKit, we are experiencing a new “declarative revolution”—from declaring infrastructure to declaring intelligence.
From Cloud-Native to AI-Native: The Shift from YAML to Markdown
In the cloud-native era, developers’ mission was to “make machines understand our configurations.” YAML became a descriptive programming language—it isn’t a program, yet it drives everything. Kubernetes, Terraform, Helm, Ansible… We abstracted system behaviors into declarations, turning deployment logic into state descriptions.
But entering the AI-native era, we face new challenges: We no longer need to tell machines “how to run containers,” but rather “how to think and act.”
Thus, Markdown becomes the new specification language (Specification Language). Developers begin using Markdown to standardize AI’s tone, steps, and collaboration methods, treating prompts, rules, skills, and specs as maintainable “AI manuals.” This is the starting point of specification-driven development (Spec-Driven Development, SDD).
Markdown: The “Declarative Language” of the AI-Native Era
Previously, we wrote deployment.yaml to tell clusters how to deploy services; now we write .prompt.md to tell Copilot how to understand our code.
A typical Copilot Prompt file:
# .github/prompts/docs.prompt.md
You are the technical documentation assistant for this repository.
All outputs must use Chinese Markdown.
Keep it concise, use headings, lists, and tables.
These few lines can change the entire IDE’s behavior. In environments like GitHub Copilot, VS Code, and Cursor, these .prompt.md files are automatically loaded, forming the “context layer” of the AI IDE.
This means: AI behavior is no longer hidden in invisible system prompts, but becomes part of the repository.
From .prompt.md to AGENTS.md, to Anthropic’s SKILL.md and GitHub’s SpecKit, Markdown gradually evolves into a new programming language—one that describes “how intelligent agents should do things.”
From Prompt to Skill to Spec: The Evolutionary Path of AI Specifications
| Stage | Specification Carrier | Core Objective | Representative Practices |
|---|---|---|---|
| Cloud-Native Era | YAML | Declare Infrastructure | Kubernetes, Terraform |
| Prompt Engineering Era | Markdown | Prompt Context | Copilot .prompt.md, AGENTS.md |
| Skill Module Era | Markdown + Scripts | Encapsulate Capabilities | Anthropic Agent Skills, Cursor Rules |
| Specification-Driven Era | Markdown + DSL | Standardize Collaboration | GitHub SpecKit |
This evolution is not accidental. YAML and Markdown actually solve the same problem: How to convey human intentions to machines in a structured way.
YAML describes the “state and configuration” of machine behavior; Markdown describes the “context and rules” of intelligent agent behavior. From Cloud-Native to AI-Native, we’ve simply replaced the declared object from containers to intelligent agents.
Anthropic Agent Skills: From “Declaring Configuration” to “Declaring Capabilities”
Anthropic’s Agent Skills is a typical representative of this trend. Each skill (Skill) is an independent directory, with the core file being SKILL.md:
---
name: pdf-processing
description: Extract and analyze PDF form content
---
# PDF Processing Skill
1. Read the file.
2. Extract fields.
3. Check form consistency.
Claude loads only the skill names and descriptions on startup (a few dozen tokens), and dynamically loads the full content when a task is triggered—this is the so-called progressive disclosure.
This is strikingly similar to how Kubernetes loads CRDs: The control plane doesn’t need to know every field detail immediately, it just parses them when executing. Thus, the AI’s “knowledge scope” achieves dynamic expansion—modularizing knowledge with Markdown, activating skills with the execution environment.
Skills are not just documentation; they can also include scripts. Claude can run these scripts in a secure sandbox, calling external logic like executing containers. This unites “reading documentation” and “executing tasks”—AI can understand instructions and complete operations itself.
Copilot Prompt, Cursor Rules, and Skills: The Middle-Layer Revolution of AI Specifications
These three mechanisms actually solve the same problem: How to define “context + rules + behavior” in AI IDEs.
| Hierarchy | Carrier | Defined Content | Scenario |
|---|---|---|---|
| Prompt Layer | .github/prompts/*.prompt.md | Tone, Context, Style | Copilot, VS Code |
| Rule Layer | .cursor/rules/*.md | Project Rules, Constraints | Cursor IDE |
| Skill Layer | skills/*/SKILL.md | Capability Modules, Scripts | Claude Code |
- Copilot Prompt defines “Who am I”;
- Cursor Rules define “How should I write”;
- Skills define “What can I do”.
This is a natural transition from context to capabilities. The next phase is from capabilities to governance—SpecKit.
GitHub SpecKit: Enabling AI to Develop by Specifications
SpecKit elevates “development specifications” into a comprehensive governance system. It uses the hierarchy of “Constitution (Constitution) → Spec (Specification) → Plan (Plan) → Task (Task)” to allow AI to execute development like a project manager following rules.
In the .specify/ directory, developers define:
# Constitution
AI must comply with:
- All code follows PEP8
- Unit test coverage >= 90%
Stage tasks are defined in specs/, where AI executes, provides feedback, and validates according to stages. This is no longer just prompt or style guidance, but a governance mechanism (governance layer).
In other words, SpecKit is “GitOps for AI team collaboration.”
From Declarative to Speculative: The Second Paradigm Shift in AI Programming
We can view this transformation as a continuation of cloud-native philosophy.
| Era | Driving Force | Core Problem | Solution |
|---|---|---|---|
| Cloud-Native | Infrastructure Automation | How to make machines execute configurations? | Declarative YAML |
| AI-Native | Knowledge and Intelligent Collaboration | How to make intelligent agents execute specifications? | Speculative Markdown |
Kubernetes manages containers with YAML, SpecKit manages intelligence with Markdown. We are moving from “Infrastructure as Code” to “Intelligence as Specification.”
This isn’t a joke. YAML hell hasn’t gone away yet, Markdown hell is on the way.
Specification-Driven Development (Spec-Driven Development, SDD)
SDD lets us redefine the meaning of “development”:
- Prompt is a context configuration file (defining identity and style)
- Skill is a capability module (defining behavior and tools)
- Spec is the project constitution (defining rules and objectives)
These three layers together form the “specification architecture” of AI IDEs. Future IDEs will no longer be text editors, but “cognitive operating systems”—equipped with memory, skills, and specifications.
Practical Suggestions: Enabling Specification Layers in Your Repository
Taking your website/ repository as an example:
- Create
.github/prompts/- Define
.github/prompts/docs.prompt.md - Specify writing tone, style, language, and format.
- Define
- Write
AGENTS.md- Describe the project’s development processes, dependencies, build commands, and testing methods.
- Enable Copilot or Cursor to have “local rule awareness” within the project.
- Integrate SpecKit
- Define project constitution and stage tasks in the
.specify/directory. - Allow AI to participate in development in a standardized manner.
- Define project constitution and stage tasks in the
- Optional: Introduce Skills Modules
- Encapsulate common content generation, translation, and publishing scripts into skills.
- Future Claude or Gemini can invoke them.
Through these steps, your repository upgrades from a traditional repository to an AI-Ready Repository.
From YAML DevOps to Markdown AIOps
Cloud-native DevOps taught us:
“Make configurations reproducible.”
AI-native AIOps teaches us:
“Make intelligence reproducible.”
YAML defined the container lifecycle; Markdown defines the intelligent agent lifecycle.
We are experiencing a historic turning point—from orchestrating infrastructure to orchestrating intelligence.
From DevOps to CollabOps: The Philosophical Shift of Specification-Driven Development
The DevOps revolution first convinced us—through declarations and automation, machines can collaborate reliably with humans.
A decade later, we enter another collaboration paradigm—CollabOps (Collaborative Operations): Not just collaboration between machines, but an autonomous network where humans, intelligent agents, and code participate together.
In the cloud-native era, YAML was a trust contract: We wrote configurations into files, letting the cluster implement them; the system became an “obedient executor.”
In the AI-native era, Markdown becomes the new contract: We write rules into documents, letting intelligent agents comply; the system becomes a “sensible collaborator.”
The difference lies in:
- DevOps solves “how commands are executed more accurately”;
- CollabOps solves “how intentions are correctly understood.”
This is the philosophical foundation of specification-driven development (Spec-Driven Development):
Describe intelligent behaviors in a readable and collaborative way, letting machines understand humans’ “why,” not just “what.”
It inherits the declarative spirit of YAML, while absorbing the interpretability of Markdown. YAML is the minimal truth machines can parse; Markdown is the maximum ambiguity humans can read. AI happens to exist between the two.
Future developers may no longer be “people who write code,” but “people who design specifications”—they define the roles, boundaries, and collaboration methods of agents; they write Skills, Prompts, Specs like DevOps writing CI/CD; they build not programs, but cognitive collaboration systems.
Just as cloud-native taught us to tame complexity with YAML, AI-native will teach us to tame intelligence with Markdown. This transformation is not just a tool upgrade, but a continuation of development philosophy.
From Infrastructure as Code to Intelligence as Collaboration—this is our era’s new programming manifesto.
Conclusion: The Future of AI-Native is the Future of Specifications
When Prompt becomes a configuration file, Skill becomes a plugin, and Spec becomes a governance mechanism, AI IDEs are no longer auxiliary tools, but cognitive members of the team.
YAML declared the state of machines; Markdown declares the intent of intelligence.
This migration from YAML to Markdown is not just a syntactic change, but a paradigm shift in development philosophy:
Cloud-native made computing orchestrable; AI-native makes intelligence orchestrable.
Summary
This article explores the technological evolution from YAML to Markdown, revealing the rise of specification-driven development in the AI-native era. By comparing the declarative paradigms of cloud-native and AI-native, the article elucidates how Markdown becomes a new language for describing intelligent agent behaviors, and through the hierarchical evolution of Prompt, Skill, and Spec, demonstrates the philosophical shift from infrastructure automation to intelligent collaboration. Practical suggestions provide developers with specific paths to enable specification layers, ultimately emphasizing the significance of CollabOps as a future collaboration paradigm. This transformation not only changes development tools but also reshapes the collaboration between developers and AI.