The Declarative Agent Trap

The Assembly Language of AI

The core principle is old. Declarative programming expresses what you want computed, not how to compute it. SQL is declarative: you describe the data you want. A Python for-loop is imperative: you describe how to fetch it step by step.

Applied to AI agents, this means specifying the inputs, outputs, and constraints of a task rather than scripting prompt templates, API calls, and control flow. DSPy, the Stanford project whose creators compare their work to the shift from assembly to C, embodies this at the framework level. DSPy lets developers write "signatures" (natural-language typed declarations like "consume questions and return answers") instead of crafting prompt strings. An optimizer then automatically refines the underlying prompts by maximizing task-specific metrics.

The results are striking. In one demonstration, a DSPy optimizer raised a ReAct agent's accuracy from 24% to 51% with no human prompt authoring. For comparison, LangChain's codebase in September 2023 contained over 50 strings exceeding 1,000 characters and 54 files dedicated to prompt engineering. DSPy's codebase contains zero hand-written prompts.

IBM's Prompt Declaration Language takes a complementary path: a YAML-based format with 15 block types that handles chat templates, message accumulation, and model interactions declaratively. Salesforce built Agent Script, a DSL that compiles into an "Agent Graph" consumed by its Atlas Reasoning Engine. Microsoft's Foundry workflows offer bidirectional visual and YAML editing where each save creates an immutable version integrated with CI/CD pipelines.

The pattern is consistent across vendors: describe what the agent should accomplish, and let the framework handle execution.

Skills in Markdown

The framework layer handles how agents execute. A separate layer, built on Markdown files, handles what agents know how to do.

Anthropic published the Agent Skills specification on December 18, 2025, defining a skill as a directory containing a SKILL.md file: YAML frontmatter for metadata, Markdown body for instructions. The design uses progressive disclosure. Agents load only a skill's name and description at startup, then pull the full content into context when the skill becomes relevant. The recommended body size is under 500 lines with fewer than 5,000 tokens.

Simon Willison called the specification "deliciously tiny." Microsoft, OpenAI, GitHub, Atlassian, Figma, and Cursor adopted it within weeks. Skills written for Claude Code work in GitHub Copilot by copying SKILL.md files between directories.

AGENTS.md serves a complementary role: a project-level README for AI agents, adopted by over 60,000 open-source projects since August 2025. Martin Fowler's team observed that nearly all forms of AI coding context engineering "ultimately involve a bunch of markdown files with prompts."

The distinction between these two layers matters. DSPy operates at the programming level, abstracting how LLM calls are optimized. SKILL.md operates at the knowledge level, encoding what an agent can do in a specific domain. Both are declarative. Both are typically used together.

The practical consequence: domain experts (product managers, compliance officers, customer support leads) can define and modify agent behavior through the same pull request workflow that engineers use for code. dbt's team invested dozens of hours of focused expert work per skill. Mintlify auto-generates skill.md files for documentation sites, regenerating them with every update. Distribution hubs and CLI tools make installation a one-command operation. The barrier to authoring agent behavior is now literacy, not programming skill.

Read that last sentence again. Literacy is the only prerequisite for defining what an AI agent does in production. That is simultaneously the strongest argument for declarative agents and the clearest description of their attack surface.

Version Control as Governance

When agent behavior lives in text files, it inherits the full power of version control.

Every change becomes a commit. Every commit has an author, a timestamp, and a diff. Teams can review behavioral changes through pull requests, roll back to previous versions, and maintain audit trails showing exactly what an agent was instructed to do at any point in time.

This is not a convenience; it is becoming a compliance requirement. ISACA argues that agent logic should be maintained under version control and audited with the same rigor as business logic. Microsoft mandates that actions of every agent must be auditable. Decagon's Agent Versioning system applies CI/CD principles where every agent change is a versioned commit, with product teams using a console for reviewing diffs and rolling back.

The institutional infrastructure is forming to support this. The Agentic AI Foundation, established December 2025 under the Linux Foundation, governs foundational projects including MCP, goose, and AGENTS.md. Platinum members include AWS, Anthropic, Google, Microsoft, and OpenAI.

For regulated industries, this matters enormously. When a regulator asks "what was your AI doing on March 15th?", a git log provides a precise, verifiable answer. Imperative code scattered across application logic cannot offer the same clarity.

The Security Problem

Ease of authoring creates a corresponding ease of attack. The same simplicity that lets domain experts write agent skills in Markdown also lets attackers craft malicious ones.

Snyk's ToxicSkills study analyzed nearly 4,000 agent skills and found that 13.4% contain critical-level security issues: malware distribution, prompt injection, and exposed secrets. At any severity level, 36.8% have at least one flaw. Cisco's broader scan of 31,000 skills found vulnerabilities in 26%.

The attack surface is novel and potent. The SkillJect framework demonstrated that skill-based prompt injection succeeds 95.1% of the time, compared to only 10.9% for direct command injection. Skills are loaded into context as trusted instructions, so malicious content in a SKILL.md file bypasses the guardrails that protect against untrusted user input. Traditional antivirus cannot detect this: the file is plain text, and malicious commands exist only momentarily during execution.

Community marketplace infrastructure is not yet equipped to handle this. A single threat actor uploaded 677 malicious packages to the ClawHub marketplace, exploiting a minimum barrier of just a one-week-old GitHub account. Cisco responded by releasing an AI Defense Skill Scanner with end-to-end supply chain security. The security community is catching up, but the gap between adoption velocity and security tooling is real.

This is not an argument against declarative definitions. Imperative code has security vulnerabilities too. But the declarative approach concentrates trust in a small number of text files that are easy to modify and hard to audit automatically. Organizations adopting this paradigm need to treat skill files with the same security posture they apply to dependency management: signed sources, automated scanning, and human review for anything that enters production.

Where This Goes

Gartner predicts that over 40% of agentic AI projects will be canceled by end of 2027 due to escalating costs, unclear value, or inadequate controls. Declarative agent definitions directly address two of those three factors. They reduce costs by compressing development cycles. They improve controls by making agent behavior auditable and version-controlled. But "inadequate controls" is doing a lot of work in that sentence, and it is precisely the factor that declarative adoption has not solved.

The approach has clear limits. Complex decision trees, iterative reasoning loops, and workflows that exceed context window constraints (roughly one million tokens today, while enterprise monorepos routinely exceed that) still require imperative code. Microsoft's documentation acknowledges this explicitly. Declarative is a powerful default, not a universal solution.

The trajectory is unmistakable. When Fred Brooks documented the productivity gains of moving from assembly to high-level languages, the industry did not go back. The shift from hand-crafted prompts to declarative text files follows the same logic. But Brooks also noted that the move to high-level languages introduced an entire class of new vulnerabilities that took decades to address. We are at month 18 of a similar transition, with adoption curves moving faster than security tooling. The declarative agent pattern will win. The question is how many breaches happen before the industry treats SKILL.md files with the same rigor it learned to apply to package.json.