Your Documentation Is Out of Date. Let an AI Agent Keep It in Sync

A developer has proposed a `sync-docs` agent skill that keeps technical Markdown documentation aligned with source code by storing a `commit` and `updated` date in each document's frontmatter. The agent uses the recorded commit as a baseline, inspects everything changed since then, and reviews the existing documentation against the current implementation rather than simply appending Git summaries. The approach treats source code as the source of truth and aims for accuracy over activity.

We've all been there. You join a new team, open the repository, and find a beautifully written README.md , an architecture document, and a collection of Markdown files explaining how everything works. You start reading. A few minutes later, you notice that the architecture diagram doesn't match the actual implementation. The documentation references tools that no longer exist. Some configuration options have changed, and a few important components are missing entirely. The documentation is there, but can you trust it? This is one of the most common problems in software engineering: documentation slowly drifts away from the source code. And it's not because developers don't understand the importance of documentation. It's because maintaining it is a continuous task, and it's very easy to forget. But what if we could delegate this responsibility to an AI agent? Let's start with one simple principle: The source code is always the source of truth. Documentation is a human-friendly representation of how the system works. It helps developers understand the architecture, discover available tools, learn conventions, and onboard new team members. But documentation should never override the implementation. Whenever the implementation changes, the relevant documentation should be reviewed and updated if necessary. The problem is knowing when documentation needs attention. Here's a simple trick. What if every technical Markdown document included metadata describing the last commit against which it was reviewed? For example: --- commit: '9b6f166af5227ff4093af7347084d8f7d2a81e4f' updated: '2026-11-04' --- That's it. Two simple pieces of information: commit : The Git commit against which the document was last reviewed and synchronized. updated : The date the document was last reviewed. This small addition gives us something very useful: a reference point. When someone opens a Markdown document, they can immediately see when it was last reviewed and how far behind the codebase that review was. More importantly, an AI agent can use that commit as a starting point for reviewing the document. For example, if the document references commit 9b6f166 , the agent can inspect everything that has changed since that commit and determine whether any of those changes affect the documentation. We now have a simple, explicit relationship between our documentation and the source code. sync-docs skill Imagine having an agent skill called sync-docs . Its responsibility is straightforward: Make sure technical documentation accurately reflects the current state of the codebase. The workflow could look something like this: For example, the agent might discover that since the last documentation review: It can then inspect the relevant source files and update the documentation accordingly. Notice something important: the agent isn't simply summarizing the latest Git changes and appending them to a document. It needs to understand the existing documentation, inspect the current implementation, and determine whether the document still accurately describes the system. The goal is accuracy, not just activity. Let's make this concrete. We need two things: The important distinction is that the skill owns the logic. The workflow simply orchestrates it. Let's create the following structure: .agents/ skills/ sync-docs/ SKILL.md The SKILL.md file contains the actual instructions the agent must follow. Here is an example implementation: .agents/skills/sync-docs/SKILL.md --- name: sync-docs description: Review and synchronize Markdown documentation against the current source code. --- Sync Documentation Your responsibility is to ensure that technical documentation accurately reflects the current implementation in the repository. The source code is always the source of truth. 1. Discover documentation Find all Markdown files containing the following frontmatter fields: - commit - updated These fields identify the last source-code commit against which the document was reviewed. Ignore files without this metadata. 2. Review each document For every document: 1. Read its recorded commit. 2. Verify that the commit exists in the repository. 3. Identify the source files relevant to the document. 4. Inspect changes introduced since the recorded commit: git diff <recorded-commit ..HEAD 5. Inspect the current implementation of the affected components. 6. Determine whether the documentation still accurately describes the implementation. Do not assume that every code change requires a documentation change. 3. Update documentation When documentation is outdated: - Update incorrect descriptions. - Add missing architectural information. - Remove references to obsolete tools, components or configuration. - Update examples that no longer match the implementation. - Preserve useful explanations and the existing writing style. Never invent implementation details. Never modify application source code. 4. Update synchronization metadata After successfully reviewing a document, update its frontmatter: commit: <current HEAD commit updated: <current date The commit must represent the exact source-code revision that was reviewed. If the review cannot be completed confidently, do not advance the metadata. If the document is already accurate, its content does not need to change, but its review metadata should still be updated. 5. Report findings At the end, provide a summary containing: - Documents reviewed. - Documents updated. - Documents already accurate. - Documents that could not be reviewed. - Architectural inconsistencies discovered. - Potential bugs or unexpected implementation changes worth investigating. Do not fix application code or architectural issues as part of this task. Leave those findings for human review. That's the entire skill. The interesting thing is that it doesn't know anything about GitHub, pull requests, or scheduling. It only knows how to perform one job: keep documentation synchronized with the source code. This makes it reusable. You can invoke it manually from your coding agent whenever you want: Use the sync-docs skill to review and synchronize the technical documentation in this repository. Or you can use it as part of a larger agent workflow. Now let's automate it. Create the following file: .github/ workflows/ sync-docs.md The workflow is intentionally simple. It doesn't contain any documentation synchronization instructions because those already live in our skill. Its only responsibility is to invoke the skill and create a PR with the results. .github/workflows/sync-docs.md --- name: Sync Documentation on: weekly on monday permissions: contents: read pull-requests: read safe-outputs: create-pull-request: title-prefix: " docs-sync " labels: - documentation allowed-files: - docs/ - README.md --- Synchronize Technical Documentation Your task is to maintain the technical documentation in this repository. Instructions 1. Read and follow the skill located at: .agents/skills/sync-docs/SKILL.md 2. Invoke the sync-docs skill and let it perform the complete documentation review. 3. Inspect the resulting changes and findings. 4. If documentation or synchronization metadata has changed, create a pull request containing: - The updated Markdown documents. - A summary of documents reviewed. - A summary of documentation changes. - Any architectural inconsistencies or potential issues discovered. 5. If there are no changes to propose, do not create an empty pull request. Important Never merge pull requests automatically. All documentation changes must be reviewed and approved by a human. Do not modify application source code. The workflow uses a scheduled trigger, invokes our reusable skill, and creates a PR when there are changes to propose. Notice how little logic the workflow contains. That's intentional. We don't want to maintain two implementations of the same process. The skill defines how documentation is synchronized. The workflow defines when it happens and what to do with the results . GitHub Agentic Workflows can compile these Markdown workflow definitions into standard GitHub Actions workflow files using the gh aw CLI: gh extension install github/gh-aw gh aw compile The compilation generates a .lock.yml workflow alongside the Markdown source. You commit both files to the repository. You can choose a different schedule, such as every two weeks or once a month, depending on how quickly your codebase evolves. For more information, see the GitHub Agentic Workflows documentation https://github.github.com/gh-aw/ . Note: The example assumes that the selected agent runtime supports the skill format and that the skill is available in its execution environment. The workflow must be configured to load and invoke it; simply referencing a file path does not automatically execute a skill. Imagine a PR created by the workflow: Title: docs-sync Synchronize architecture and tooling documentation It might contain: | Document | Result | |---|---| | docs/architecture.md | Updated service dependencies | | docs/development-tools.md | Removed obsolete CLI reference | | docs/deployment.md | Reviewed, no content changes needed | | docs/api.md | Updated endpoint descriptions | The PR description could also highlight findings that deserve attention: This is where things get particularly interesting. The PR is no longer just a documentation update. It becomes another opportunity for the engineering team to inspect the system and discover things that might otherwise go unnoticed. We are using AI to maintain documentation, but we're also using documentation reviews to improve the quality of the software itself. A timestamp tells us when something happened. A Git commit tells us exactly which version of the source code was reviewed. This distinction is important. Suppose a document was last reviewed two weeks ago. During those two weeks, the codebase might have changed significantly, or perhaps nothing relevant to that document changed at all. With a commit reference, the agent can inspect the actual changes rather than guessing based on the document's age. It also makes the process incremental. The agent doesn't need to rediscover the entire history of the project every time it runs. It can start from the last reviewed commit and investigate what happened since then. Of course, the commit reference is not a guarantee that the document is accurate. It's a record of the last successful review. The quality of that review still matters. There is one important detail here: the workflow should open pull requests, never merge documentation updates automatically. Why? Because reviewing these PRs is valuable in itself. Imagine the agent updating an architecture document because it discovered that a service behaves differently from what the documentation describes. During the review, a developer might realize that the implementation has drifted from the intended architecture. Or perhaps the agent discovers an undocumented configuration change, an unexpected dependency, or a tool that is no longer being used. These are useful signals. A documentation synchronization PR can become an opportunity to spot architectural inconsistencies, accidental complexity, missing documentation, and even potential bugs. The agent does the investigation and proposes the updates. Developers review the changes, challenge the findings, and decide whether to merge them. This keeps humans in the loop while making the maintenance process much less painful. There are some important details to get right when implementing this. 1. Only update the commit after a successful review The commit in the frontmatter should represent the latest code version actually reviewed, not simply the latest HEAD. If the agent fails to inspect a document or cannot confidently determine whether it is accurate, it shouldn't silently advance the commit reference. 2. Don't change documentation just for the sake of changing it If the source code changes but the documentation remains accurate, there is no reason to modify the document's content. The agent can still update its review metadata to record that the document has been checked against the newer commit. 3. Never merge automatically Always open a pull request and let a developer review it. Apart from preventing incorrect documentation updates from reaching the main branch, these reviews can expose problems that might otherwise go unnoticed. 4. Make the review scope explicit Not every Markdown file needs to describe the entire codebase. An architecture document might depend on changes across multiple services, while a tool reference might only depend on a particular directory. The skill should use the document's content to determine which parts of the repository are relevant. 5. Handle invalid or unavailable commits gracefully A document might reference a commit that is no longer available locally, or a commit that doesn't exist in the current repository history. The agent shouldn't guess where to start. It should flag the document for human investigation rather than silently replacing its reference. I particularly like this idea because it changes how we think about documentation. Today, documentation is often treated as something we write when we create a feature, launch a project, or onboard a new developer. Then it slowly gets forgotten. But documentation should be treated more like code: something that needs continuous maintenance. We already have automated tests, linters, formatters, dependency updates, and security scans running against our repositories. Why shouldn't documentation have its own maintenance workflow? With a small piece of metadata, a reusable AI skill, and a scheduled GitHub workflow, we can make documentation maintenance a continuous process rather than an occasional cleanup exercise. And there's an additional benefit: every synchronization PR gives the team another opportunity to inspect the system, question architectural decisions, and spot inconsistencies. Your source code evolves. Your documentation should evolve with it. And perhaps the best part is that the next developer joining your team won't have to wonder whether the architecture document they're reading is describing the system you actually have today. They can see when it was last reviewed, what version of the code it was checked against, and trust that the team has a process for keeping it up to date.