The Death of Human Documentation: Inside chroma-core/agent-skills

How the popular vector database uses a strict compiler pipeline to turn static documentation into type-safe, executable behaviors for AI agents.

7 min read • View on GitHub • More from chroma-core

A massive 19th-century printing press converting jagged code gears into rigid metal punch-cards, illustrating the conversion of raw code into machine-readable instructions. — Agent Skills compile messy, human-written code into strict operational instructions for AI.

Key Takeaways

Traditional software documentation fails LLM agents by relying on prose and implicit context, leading to hallucinated API calls.
Chroma solves this by treating documentation as a compiled artifact, using a precise build pipeline to inject type-safe code into markdown templates.
The resulting SKILL.md files act as state machines, forcing agents to pause and request architectural decisions before generating implementation code.
By enforcing production-grade patterns like Reciprocal Rank Fusion, the repository prevents agents from defaulting to naive, fragile RAG implementations.

The End of the README Era

AI agents do not read documentation the way humans do. When developers feed a standard README or a PDF of API docs into an agent, the system inevitably struggles. It ignores nuanced prose, misunderstands vague directives, and hallucinates API methods that do not exist.

The chroma-core/agent-skills repository recognizes a fundamental shift. If you want an AI to implement your tool correctly, you have to treat documentation as a compiled, type-safe software artifact. This is a masterclass in Knowledge-as-Code, abandoning human-readable tutorials for machine-executable operations.

The key insight is that modern LLMs are good enough to follow detailed procedural instructions written in plain text. You don’t need to encode your workflow as a graph of Python functions. You can just describe it, and the agent will execute it step by step, calling tools and making decisions exactly as instructed.

Eric Murphy, Author · Agent Skills Are Quietly Replacing Agent Code

Compiling Context: The Build Pipeline

The most impressive aspect of the repository is not the markdown files themselves, but the engine that generates them. The team uses a rigorous build pipeline powered by Bun, TypeScript, and Pyright to guarantee that the AI only ever reads syntactically perfect code.

The transclusion engine guarantees that agents only ever see code that has passed compiler checks.

Inside scripts/build-skills.ts, a custom regex-based parser scans raw source files for snippet markers. It then injects these validated snippets into specified gaps in markdown templates. If a developer introduces a syntax error, the build fails entirely, and the documentation is never published.

The State Machine of SKILL.md

The output of this pipeline is a standard SKILL.md file, but it functions more like a state machine than a static document. It provides a strict decision workflow for the agent.

Instead of immediately generating code, the skill instructs the agent to pause and ask clarifying questions. It forces the agent to determine the user's deployment target, preferred search type, and embedding model before writing a single line of implementation. This prevents the agent from making assumptions that lead to brittle architectures.

Instead of loading everything upfront, they use progressive disclosure. At startup, the agent loads only the metadata of available skills, just the name and a short description, which comes to around 50 tokens per skill. When a request matches a skill's description, only then does the agent read the full SKILL.md into context.

Chromatic Labs, Engineering Blog · Context Engineering 103

Forcing the Upgrade to Hybrid Search

The payload of these skills reveals Chroma's intent to push developers past naive Retrieval-Augmented Generation. The repository explicitly teaches agents how to implement production-grade hybrid search, refusing to settle for standard tutorials.

A close-up of a train track switch mechanism heavily padlocked, forcing a train off a broken path onto a reinforced steel track. — The skill repository restricts agents from taking the naive path, forcing them to implement robust patterns.

By enforcing the use of Reciprocal Rank Fusion, SPLADE, and BM25, the skill prevents the agent from taking the easy route of simple semantic search. It introduces high-level abstractions for fluent filtering, treating vector queries with the ergonomics of a modern ORM.

The New DevRel Standard

We are entering an era where providing a REST API without a compiled agent skill will be equivalent to shipping a C library without header files. The chroma-core/agent-skills repository provides the necessary blueprint for this transition.

Attribute	Human Documentation	Agent Skills
Format	Prose and explanatory paragraphs	Exact command invocations and state rules
Delivery	Read entirely upfront	Progressive disclosure based on task context
Code Quality	Often outdated or uncompiled	CI/CD validated via strict compiler checks
Failure Mode	Developer gets confused and Googles	Agent hallucinates an API call and breaks build