Executable Skills for Agents Are Better Than Docs

57% of documentation teams don’t track whether their docs drive any business outcome. 88% say docs matter for purchase decisions. (GitBook State of Docs 2026.) Meanwhile, nearly half of all documentation site traffic now comes from AI agents — who can’t tell you whether they found what they needed (Mintlify).

The audience for documentation changed. The format didn’t.

The Writer Changed

For decades, the flow was simple: a human wrote a spec, then implemented code to match. Documentation was the source of truth.

That order has reversed. AI agents generate code and documentation simultaneously, in a format designed for other agents to consume. The spec and the implementation are now the same artifact.

graph TD
  subgraph era1 ["Until 2025"]
      direction LR
      A["Human dev writes docs"] --> B["Human dev implements code"]
  end
  subgraph era2 ["2023–2026"]
      direction LR
      C["AI agent writes code"] --> D["AI agent updates docs"]
  end
  subgraph era3 ["2026+"]
      direction LR
      E["AI agent writes docs + code"] --> F["Another agent consumes skills"]
  end
  B -.-> C
  D -.-> E

The first generation of agent-oriented documentation — OpenWiki, Mintlify, AGENTS.md — solved a real problem: agents needed context about unfamiliar codebases. But the solution created a new one: generating human-readable summaries of code for an agent that can already read code. The middleman is redundant but requires maintenance.

Current Approaches Don’t Work

Today’s documentation ecosystem has four approaches. Each one fails in a different way.

graph LR
  A["Traditional docs"] -->|"Written for humans"| B["Nobody reads them"]
  B --> C["Stale, unmaintained"]

  D["Code-first docs"] -->|"Generated for agents"| E["Agents can read code directly"]
  E --> F["Redundant middleman"]

  G["Spec-driven"] -->|"Comprehensive specs"| H["Context rot degrades performance"]
  H --> I["Counterproductive"]

Chroma evaluated 18 LLMs in July 2025 and found that “model performance varies significantly as input length changes, even on simple tasks” — a phenomenon they called context rot (Chroma Technical Report). Anthropic’s context engineering guide (September 2025) describes the same problem: “LLMs have an ‘attention budget’ that they draw on when parsing large volumes of context. Every new token introduced depletes this budget” (Anthropic).

ThoughtWorks Technology Radar Vol 34 (April 2026) flagged agent instruction bloat as a Caution: “Context files such as AGENTS.md and CLAUDE.md tend to accumulate over time… Instructions become long and sometimes conflict with each other. Models tend to attend less to content buried in the middle of long contexts” (ThoughtWorks).

Docs Are Redundant for Agents

The problem isn’t that documentation is badly written. It’s that every page of documentation duplicates the code sitting next to it.

Code-first documentation solves the “why” problem — Mintlify co-founder Han Wang: “Code only tells you what got built, not why.” But the solution introduces staleness, maintenance, and token cost. Every documentation page is a derivative of the code next to it. For an agent that can read the code, the derivative is redundant.

ThoughtWorks Technology Radar Vol 34 rated context engineering as Adopt and progressive context disclosure as Trial — the recommendation is to “start with a lightweight index of what’s available, let the agent determine what’s relevant, and pull in only what’s needed” (ThoughtWorks).

Skills Instead of Documentation

The alternative to generating documentation is generating skills.

graph TD
  subgraph trad ["Traditional docs"]
      direction LR
      A1["Human writes"] --> A2["Markdown file"]
      A2 --> A3["Agent reads as context"]
  end
  subgraph code ["Code-first docs"]
      direction LR
      B1["Code exists"] --> B2["Agent generates markdown"]
      B2 --> B3["Another agent reads markdown"]
  end
  subgraph skill ["Skills"]
      direction LR
      C1["Domain expert chats"] --> C2["Agent generates skill"]
      C2 --> C3["Human verifies"]
      C3 --> C4["Sandboxed VM executes"]
  end
  A3 -.-> B1
  B3 -.-> C1

Skills use the same packaging as documentation — markdown, YAML frontmatter, structured references. But they’re consumed by agents, not humans. The critical difference: they contain executable TypeScript functions that run in a sandboxed VM on every incoming customer message.

A spa owner types: “our deep tissue massage costs $90 for 60 minutes, $120 for 90 minutes, and we offer a 10% discount for members.” The platform generates a quoteOrder() function that returns $108 for a 90-minute member booking. Every time.

export function quoteOrder(order: Order): QuoteResult {
  const item = order.items[0];
  const base = offerings[item.service].durations[item.duration];
  const memberDiscount = order.member ? 0.9 : 1.0;
  return { total: base * memberDiscount };
}

The output lives in structured skill directories:

/sales-assistant/skills/
  offerings/
    skill.md              # YAML frontmatter + instructions
    reference.md          # Structured product catalog
    schema/
      schema.json         # JSON Schema (source of truth)
      schema.ts           # TypeScript types (auto-derived)
  pricing-rules/
    skill.md
    reference.md          # Pricing rules in structured markdown
    scripts/
      function.js         # quoteOrder(order) -> QuoteResult

The Workflow

graph LR
  A["Domain expert describes business rule"] -->|"Natural language"| B["Agent generates skill"]
  B --> C{"Human reviews"}
  C -->|"Approves"| D["Skill versioned in MongoDB"]
  C -->|"Edits"| E["Modified and re-approved"]
  D --> F["Loaded at runtime"]
  F --> G["Sandboxed VM executes"]
  G --> H["Deterministic result with audit trail"]

Human Review: Still Necessary

Skills are written for agents, but humans verify them before they go live. Every skill change goes through an approval gate. The business owner sees the generated code, can edit it, or reject it.

This serves two purposes. First, the domain expert confirms the skill matches their intent — they described the rule in natural language, and now they see the executable version. Second, human approval creates an audit trail for compliance.

Skills are human-readable so that verification is possible. The human’s role is judgment, not authorship.

Market Validation

ThoughtWorks Technology Radar Vol 34 rated two related patterns:

• Agent Skills as Trial: “Agents load skills only when needed based on their descriptions, which reduces token consumption and mitigates context window exhaustion and problems such as agent instruction bloat” (ThoughtWorks).
• Progressive context disclosure as Trial: “Instead of overwhelming an agent with instructions upfront, you give it a lightweight discovery phase in which it selects what it needs based on the user’s prompt, loading detailed information into the context window only when it becomes relevant” (ThoughtWorks).

Both patterns describe the same solution: give the agent a menu of skills, let it choose what it needs, execute only what’s relevant.

graph LR
  A["Agent receives task"] --> B{"Index"}
  B -->|"pricing"| C["pricing-rules skill"]
  B -->|"scheduling"| D["scheduling skill"]
  B -->|"validation"| E["validation skill"]
  C --> F["Execute"]
  D --> F
  E --> F
  F --> G["Deterministic output"]

When to Use What

What Changes

Documentation isn’t obsolete. Markdown works for humans. But when AI agents are your primary reader, the most useful format isn’t prose about code — it’s code.

Skills turn business rules into executable functions. Agents load them, run them, and return deterministic results. Humans verify instead of writing. The system regenerates skills when rules change.

The shift is from describing behavior to encoding it.

Related Reading

• OpenWiki vs QuotyAI — two LangChain DeepAgents projects, two architectures
• Spec-Driven vs Code-First vs Chat-to-Code — three philosophies for teaching AI about your business
• Determinism as Infrastructure — why AI platforms need deterministic execution
• Open Knowledge Format vs Agent Skills — why deterministic execution beats static knowledge files

Frequently Asked Questions

If agents can read code, why do they need documentation at all? Token cost. Reading 5 source files costs thousands of tokens. A well-structured skill file costs less and contains only what the agent needs. Progressive context disclosure means the agent loads skills on demand, not everything upfront (ThoughtWorks).

What is the difference between a skill and documentation? Documentation describes what code does. Skills are code — executable, versioned, validated, and run in a sandboxed VM on every request. A documentation page tells the agent “pricing works like this.” A skill gives the agent a quoteOrder() function that returns $108.

Why not just use AGENTS.md or CLAUDE.md? Those are static, human-authored files that degrade over time. ThoughtWorks rated agent instruction bloat as a Caution — “Instructions become long and sometimes conflict with each other. Models tend to attend less to content buried in the middle of long contexts” (ThoughtWorks).

Isn’t “skills for agents” just documentation with extra steps? No. Documentation is passive context. Skills are active execution. A documentation page tells the agent “pricing works like this.” A skill gives the agent a quoteOrder() function that runs and returns $108. It’s the difference between reading about a function and calling it.

Who maintains skills when business rules change? The business owner describes the change in natural language. The system regenerates all affected skills automatically. The owner approves. No documentation to update, no stale pages to catch.

Tags: documentation agent-skills context-engineering ai-agents coding-agents context-rot deterministic-ai progressive-context-disclosure agent-instruction-bloat