Recent content on Dachary Carey
Organizations have been pushing official company skills out the door because skills look like just a markdown file, and that seems simple and trivial. But when you dig into the lifecycle of an official skill that you intend to support, distribute, and stand behind, it's a lot more than a markdown file. I'm not sure a single organization shipping skills today recognizes how much more. 
 This is…
In the last ~6 months, Agent Skills have gone from a new feature introduced by Claude Code to a widely adopted paradigm across the industry. Companies that want to signal they understand customer AI adoption and consider it as part of the developer experience have been publishing official skills. I have been part of such an effort at my own company, where I have learned a ton from our experience…
As I have been re-scoring documentation sites with my updated afdocs tool, I have had the opportunity to see a snapshot of various docs sites a few weeks apart as the industry is starting to pay a lot more attention to how to make documentation agent-friendly. I got a surprise when I re-scored the docs for Astro , a web framework that is well-regarded. In the prior scoring run, Astro got a C (78)…
I'm working on a new research report that starts by scoring a wide cross-section of documentation sites with afdocs . Consider it an industry-wide audit driven by specific research questions. This has given me an excuse to dig into different platforms, web hosts, documentation sizes, and documentation strategies. I've really been surprised and intrigued by the different approaches I've seen in the…
If you're a documentation team trying to figure out what "agent-ready" means for your site, you've probably noticed that several different organizations are now offering to score you. Cloudflare just launched isitagentready.com . Fern has an Agent Score directory powered by my Agent-Friendly Documentation Spec and its CLI tool , which runs 22 checks against any docs site. There will probably be…
With my work on the Agent-Friendly Documentation Spec and the companion AFDocs tool , I've been talking with a lot of people about what all this means. I've been writing about the different failure modes in a way that might make sense to a web developer, or a documentarian with a strong technical understanding of how websites work, but there are a lot of pieces involved. It's not just about the…
Almost exactly a month ago, I wrote an article about poking around in my server logs attempting to measure agent web traffic: How to Measure Agent Web Traffic . I was trying to give our documentation platform team information to help them identify agents in our web traffic. My conclusion at the time was this: 
 
 So when it comes to user agents, I don't think we can reliably correlate a…
After sharing my article yesterday about the verification gap in AI content pipelines , someone on LinkedIn replied: "I'll take humble human mistakes over confident machine gibberish any day." It's a great line and I appreciate the sentiment, but there's an angle to it that warrants digging into. My first thought was: "I wonder if this commenter knows about the research on how humans are more…
I've been running an AI-assisted editorial pipeline for about a month now. Seven stages. Two competing model drafts per topic. Automated fact-checking. Automated copy editing. Governed inputs from a curated news-gathering system . Twenty published articles on aeshift.com . 
 Every single article required factual corrections that the automated verification missed. 
 Not formatting issues.…
Recently, Vercel published an Agent Readability Spec (Timothy Jordan, last updated March 23, no publication date), a scoring system for how well websites serve AI agents. It covers llms.txt, markdown mirrors, content negotiation, structured data, robots.txt, and a checklist of other recommendations. Four days later, they followed up with "Make Your Documentation Readable by AI Agents" (Rich…
I wrote the other day about the AI news gathering pipeline I set up that collects and tags news items for different downstream consumers. One of those downstream sources is my new blog, aeshift.com . I wanted the site to have an editorial voice and lens serving practitioners - software developers and people in the tech industry who need to understand how developments in the agent ecosystem affect…
When I decided I might be doing more than just digging into AI a little, I started to think about how I might want to learn about AI in a more realistic way. There were two facets to the problem: how do I find out about interesting AI-related developments, and how do I get more practical exposure to different AI workflows? 
 On the discovery front, the AI firehose is massive. So many companies…
Someone made a feature request on the skill-validator tool: support for the evals/ directory introduced by Anthropic's recent updates to its skill-creator skill. This is the third or fourth Claude Code-specific request I've gotten regarding skill-validator development, and the tool is quickly accumulating custom flags to enable support for Claude Code-specific functionality while trying to…
The Agent Skills spec claims to be "A simple, open format for giving agents new capabilities and expertise." But the creator of Agent Skills, Anthropic, is also the company behind the spec's maintenance. And when a platform both owns a spec and competes with the platforms implementing it, the incentives stop being aligned. Let me tell you a tale of how Anthropic has quietly broken Agent Skill…
You shipped your llms.txt . You linked to your docs pages. Maybe you even set up progressive disclosure with per-product files. You're done, right? 
 Probably not. An llms.txt that was accurate when you launched it can silently drift out of sync with your actual documentation. New pages get added to the site but not to llms.txt . Old pages get removed or reorganized. The file becomes a stale…
A month ago, I published an ecosystem-scale analysis of 673 Agent Skills from 41 repositories. I looked at Anthropic's own skills, company-published collections from Microsoft and Stripe, community collections, and individual repos. The takeaway was that the ecosystem has real quality problems: 22% of skills fail structural validation, over half of all tokens are wasted on non-standard files, and…
There's a growing body of advice about how to write documentation for AI. Some of it is grounded in real observations. A lot of it is grounded in vibes: intuitions extrapolated from LLM research that was never designed to test documentation, recommendations passed around conference talks and blog posts until they calcify into "best practices," and vendor guidance that may or may not reflect how…
After sharing my recent findings about how agents use docs with the folks at work, one of the first questions (from multiple people!) was: how do we measure the impact of these problems? Writ large, how do we know things like: 
 
 How many agents are trying to access our docs and running into issues? 
 How many docs pages are adversely impacted by these issues? 
 How can we tie…
Apparently I live in the "agent" space now, so let's talk about what's inside an agent! I've been seeing conversations, and learning more myself, and have realized that maybe a lot of people haven't stopped to think about what the component parts of an agent actually are . For the purposes of this article, I'm talking specifically about coding agents, but a lot of the bits and bobs are…
With all the writing I've been doing lately around agent-friendly docs, I decided that all new websites I set up will be agent-friendly from the beginning. I designed my two newest websites, the Agent-Friendly Documentation Spec and aeshift , to be agent-friendly from day one. Particularly with the spec, I thought that people might want to point agents at the spec , and I wanted to enable that. I…
When I did the research for my recent Agent Skill research paper , I took two approaches to trying to understand the impact of Skills in developer workflows: take a wide, zoomed-out look at Skills across different segments, verticals, and use cases, and take a closer look at a subset of those Skills where I had interesting theories I wanted to probe more closely. One of the skills I took a closer…
I've been writing a lot about agents and docs lately, and one thing I keep bumping into in conversations is confusion about what "AI-friendly docs" actually means. Someone says their leadership has mandated that docs need to be optimized for AI, and when I ask what that means in practice, the answer is usually some variation of "I don't know, they just said AI." And honestly? I get it. "AI" is…
I've been posting a lot of content lately and having a lot of conversations with people in various roles as a result. One message was from someone who I think was in a similar position to a lot of us right now. As I traded messages with them, I realized that because a lot of people are seeing my content right now, this is exactly when I need to write this article. So here was the question, and my…
After posting about Agent-Friendly Docs , I got some very good questions that I wanted to dig into. I love the documentation community - such thinkers! So today, I present my spelunking in the agent Web Fetch tool. My goal was to figure out if I could provide a quick answer to whether agent platforms document the truncation limits of their various web fetch implementations, so documentarians can…
Contents 
 
 Change, thy name is Agent! 
 Agents and Docs URLs 
 
 Agents Start Specific 
 Agent URL Failure Modes 
 
 
 Agents Don't Know about llms.txt 
 Agents Don't Know about Markdown Docs 
 Agents Skip Long Docs Pages 
 Access Patterns: What Works and What Doesn't 
 Fun Aside: When Background Agents Can't Browse 
 Fun Aside: Anthropic…
Claude introduced Agent Skills in fall 2025, and they have quickly become the next hot thing in AI-assisted development. Agent Skills give your AI buddy just-in-time context to help it succeed with tasks that require specific domain expertise or resources. Anthropic released an Agent Skills specification , and other agentic platforms have been rushing to add support for it. In turn, individual…
In my last article , I wrote about why we designed a simplified testing framework approach to help technical writers test the code examples in our documentation. A major component of this is the unified Expect.that() comparison API we created to give writers a single entrypoint to validate our code examples. This API abstracts all of the field/value comparisons that validate that when we execute…
I've written before about why you should test the code examples in your documentation and why your docs team should write the code examples . I've even written about how to test them and what you should test compared to engineering tests. But I wrote that content through a very specific lens; as a member of a team of developers who happened to be writing documentation. My team was already…
My wife has been using a word-diffing tool called dwdiff for years. It's a ~25-year-old C program. Neither of us writes C. She made an attempt to understand it many years ago and port it to some other language she works in more regularly, but never finished the job. When she commented on using it in a pipeline with another Go tool I had written for her, I thought: "How hard could it be to make a…
After a months-long code example audit process that included: 
 
 Aligning about definitions and types of code examples 
 Building out tooling to programmatically ingest code examples into a database 
 Creating queries to give us different views of the data 
 Refining our data and tracking capabilities based on evolving stakeholder requests 
 
 We had enough information…
With our code example audit data ingested into the database, we were no longer constrained to static analysis at the time of parsing the data. We had the freedom to analyze the data in a variety of different ways as we explored different theories and questions. I started with a simple count of code examples broken down by programming languages. As I explored the data, this evolved into 19…
As we worked our way through this initial code example audit process, requirements emerged sporadically. At the core of this project, our department wanted to understand our code example content distribution and communicate about it to leadership. That became "count the code examples" by category and programming language. Even as we iterated on the tooling to perform the initial count, new…
With over 35,000 code examples, there's no way our docs organization could afford for people to spend time manually assigning a category to each code example. Humans apply criteria selectively, too, which means we would categorize code examples inconsistently. When we started talking about an audit, I had recently written code examples using Go with a local LLM, Ollama , to perform some embedding…
Having defined categories to better quantify our code examples, and identified the data we wanted to track, we were ready to start the audit - right? One more technical design decision awaited us - how should we access the content we wanted to audit? Our directive was to "count the code examples in our documentation" with the ability to "break down counts by programming language." Our…
Now that we had defined what we were going to count as a code example , we just needed to count them - right? As I worked on refining the brand-new-tooling we were building out to track this information, I realized we needed a lot more information about what we wanted to track, and how we might want to use the information, to make sure the tooling captured the right details in the right way. As I…
When the Education AI team provided an initial count of code examples across our documentation corpus, broken down by programming language, the numbers were much higher than some members of the org expected. We apparently had tens of thousands of code examples, and nearly 9,000 of those were JavaScript. That couldn't possibly be right, could it? And more importantly, because the number was so…
My company uses a docs-as-code workflow. We have historically split our documentation by product, for reasons related to our platform's implementation of table of contents and documentation/product versioning. This means we have documentation in a lot of different repositories (60+ by my last count), and the people who write and manage that documentation are split across four separate…
Apparently writing Shattered Ring a few years ago whetted my appetite for useful tools that do what I want in the way I want. A mere month after releasing Shattered Ring, I started working on PR Focus : a macOS app that tracks pull requests across GitHub repositories. After more than two years of nights-and-weekends development, and several incarnations along the way, I have now released PR Focus…
My team documents a product that represents 9 different SDKs in 9 different programming languages. (And these things are not a 1:1 correlation!) To date, we have maintained 9 individual sets of SDK documentation - one for each SDK. I successfully made the case that we should consoldiate these individual doc sets into one single set of documentation, but now we have to do the work! This is the…
My team documents a product that represents 9 different SDKs in 9 different programming languages. (And these things are not a 1:1 correlation!) 
 To date, we have maintained 9 individual sets of SDK documentation - one for each SDK. Our decision to consolidate these documentation sets probably warrants a separate blog post, so I'm making a mental note to do that soon. But for now, just know…
I wrote last month about how to test docs code examples . Now, let's look at what to test in docs code examples. 
 
 Test the claims you make in docs 
 Use the APIs you document 
 Demonstrate common usage patterns and best practices 
 Figure out where you can safely omit boilerplate code 
 
 There are also a couple of "don'ts" when writing and testing docs code…
A few months ago, I wrote about why you should test docs code examples . Today, I'm going to look at how to test docs code examples. 
 The specifics may vary from team to team and tool to tool, but this is the broad shape of what this process looks like: 
 
 Write docs examples in unit test suites 
 Excerpt example code for inclusion in docs 
 Include example code in docs 
…
I have been a fan of the folks at Critical Role for many years. I've watched them since their Geek & Sundry days, when they were just a plucky group of friends live-streaming their home game at a few crappy folding tables in some Geek & Sundry lunchroom or break room or whatever it was. I have been so happy for their success. I have laughed, and cried, at the stories they've told. As they have…
In this final installment in my hackathon series, let's take a look at the MongoDB Charts I made from all the lovely data I've liberated from Google Sheets. 
 Starting with an Aggregate Dashboard 
 I had some ideas of what information I wanted to track, but nothing concrete. So I started out by playing with the different chart types available in MongoDB Charts . 
 When you start a new…
Defining a data model 
 MongoDB is a document database. Developers love document databases because they make it easy to evolve a data model. But that wide-open flexibility can be a mixed blessing. It's easy to add data without thinking very much about how you want to use it and what structure the data should have. 
 For my hackathon project, I had to consider what questions I wanted to ask…
One of my favorite things about working at MongoDB is that we do a hackathon once or twice a year. It's a one-week extravaganza where we can work on PoCs, improve tooling, build skills, or try interesting projects. Some of my teammates have even built things during hackathon that have made it into the product! It's great for making improvements and getting us to think creatively. 
 My idea…
A few weeks ago, I wrote about the benefits of testing the code examples in your documentation . 
 That article has sparked some interesting conversations. The topic kept turning to who should be writing the code examples. 
 I’m more convinced than ever that engineers should not write the code examples in your documentation. There are a lot of benefits to the way my team does it: the…
As documentarians, our role doesn't stop at creating new documentation. We're also responsible for keeping existing documentation updated. If you’re part of a downstream team that is not involved in planning, finding out when the documentation needs updates can be challenging. 
 This is one part a process problem, and one part a people problem. You can solve process problems. People problems…
When I interviewed to join the Developer Education team at MongoDB, one thing really stood out to me: they maintain their documentation code examples in unit test suites. In fact, they wrote a tool, Bluehawk , to mark up and extract code snippets for use in documentation. They explained to me that this helped them ensure accuracy - the code was free of typos and would compile. 
 In the nearly…
Experienced documentation writers know that grammar isn't the only important aspect of documentation. Readability is a huge part of what makes documentation good. Readable documentation: 
 
 Is scannable, with lots of clear sections and bullet points. 
 Has short, simple sentences. 
 Uses common vocabulary and avoids jargon. 
 
 Why Readability is Important 
 The…