If you’re developing open source libraries today, your users are just as much AI coding agents as human developers. Like most open-source maintainers, we notice this while building the DBOS durable workflows library: a lot of usage and submitted issues/PRs come from coding agents trying (and sometimes failing) to use our library.
That means it’s important to design software, and especially its documentation, in a way AI tools can understand. This post is a set of notes on what we tried to make DBOS easier for agents to use, including what worked, what didn't, and where things still break.
Documentation: Still Matters But Not Enough
The first point of reference for agents trying to use a library is its documentation. The first thing we did was clean up our documentation so it's easier for agents to consume. We set up an automated GitHub action to generate an llms.txt file on every docs publish, and we also expose the raw Markdown file for every page (<url>.md). The goal is to make sure LLMs can actually read the content of our documentation without the noise of HTML tags, headers, or navbars.
While documentation is critical, you can’t solely rely on it. It takes a long time for documentation updates to be trained into models, and you need to get information to your users’ coding agents faster. Additionally, unless your library is extremely popular, an agent that was trained on its documentation but has no other source of reference will poorly grasp less common features or usage patterns. Therefore, you need a way to deliver up-to-date documentation directly to agents.
Prompts: Work And Bloat
Our next attempt to ship documentation for agents was by providing prompts. The idea was to build a large prompt that was a summary of our documentation and ask developers to provide it to their agent through an AGENTS.md file or similar. We hand-wrote an initial prompt based on our tutorials, then added detailed API information by asking an agent to summarize the docs into the prompt. You can see one of these prompts at the bottom of this page.
While using a prompt was more effective than doing nothing and provided agents with up-to-date API information, the problem with it is that it grew too large. To allow agents to accurately use the library, we essentially needed to include in the prompt a complete API reference. Otherwise, coding agents would hallucinate nonexistent features or wrong names for parameters. However, this huge prompt caused context bloat, leading to excessive token usage and degraded agent performance. We needed to find a way to get information to agents without exploding user context.
Skills: Reduce The Bloat
Building on what we learned from prompts, we next adopted agent skills. The idea behind skills is to solve the context bloat problem by progressively and selectively disclosing information to agents. Skills consist of a skills.md file and a folder of references. Only the skills.md file, which should be small, is loaded into the agent prompt. It contains an index into the references, so that when an agent needs a specific skill (for example, it’s building with a specific library API), it can load the reference to “learn the skill.”
We built our initial skills by agentically generating them from the docs and prompts. We then iteratively reviewed, tested, and hand-tuned them. To distribute the skills, we use the excellent skills.sh toolchain. All DBOS skills are open-source here.
In practice, skills work even better than prompts and are easier to maintain. By only loading information the agent actually needs, they avoid context bloat. The biggest issue we found with skills is that sometimes, the agent could not figure out which skill to load, leading to churn or even hallucinations. This is especially likely if the user prompts are too general or imprecise. This is a known problem with skills that agent and model developers are actively working on improving, so performance will likely improve over time.
MCP: Debugging Is Equally Important
Skills are helpful for agentically building applications, but less so for debugging them, especially in production. If you have an issue with a running application and want to investigate it agentically, you need a tedious back-and-forth of copying and pasting log or trace data into your agent prompt. To make this easier, we need a way to allow agents to directly access an application's observability or telemetry information.
One solution to this problem is the model context protocol (MCP). Essentially, this is a standard for connecting AI applications to external systems. You provide an “MCP server” that consists of a number of tools, each with their own prompt describing how to use it. The agent can call these tools to query your API.
To make agentic debugging easier, we built an MCP server for our workflows library. The server covers workflow observability and management. For example, there are tools to list workflows and introspect workflow steps. Each tool consists of a prompt describing the API and a Python function implementing it (for example, a Python function querying workflow status and returning it in a documented structured format). This allows an agent to autonomously analyze the behavior of a running system (for example querying what workflows failed and why) to debug and propose solutions, all without human intervention. The MCP server is open source here.
Here is a demo of MCP in action:
Learn More
If you like building scalable and reliable agentic systems, we’d love to hear from you. At DBOS, our goal is to make durable workflows as simple and performant as possible. Check it out:
- Quickstart: https://docs.dbos.dev/quickstart
- GitHub: https://github.com/dbos-inc
- Discord community: https://discord.gg/eMUHrvbu67
