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

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?

The source code is the source of truth

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.

Add a Git commit reference to your Markdown files

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.

Introducing the 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:

1. Find Markdown documents containing the synchronization metadata.
2. Read the commit recorded in each document's frontmatter.
3. Compare that commit with the current HEAD.
4. Review the changes introduced since that commit.
5. Identify which changes affect the document.
6. Inspect the current implementation to verify its accuracy.
7. Update the documentation to reflect the current implementation.
8. Update the commit and updated metadata.
9. Open a pull request containing the documentation changes.

For example, the agent might discover that since the last documentation review:

• A new service was introduced.
• An existing API changed.
• A configuration option was removed.
• A new development tool was added.
• The architecture was refactored.
• A dependency was replaced.

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.

What would the implementation look like?

Let's make this concrete.

We need two things:

1. An agent skill that knows how to synchronize documentation.
2. A GitHub Agentic Workflow that periodically invokes that skill and opens a pull request.

The important distinction is that the skill owns the logic. The workflow simply orchestrates it.

1. Implementing the sync-docs skill

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.

2. Automating the skill with GitHub Agentic Workflows

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.

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.

3. What does a synchronization PR give us?

Imagine a PR created by the workflow:

Title: [docs-sync] Synchronize architecture and tooling documentation

It might contain:

The PR description could also highlight findings that deserve attention:

• The architecture document describes a synchronous interaction, but the implementation now uses asynchronous messaging.
• A configuration option exists in the code but is missing from the documentation.
• An internal tool is still documented but appears to have been removed.

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.

Why use a commit instead of a timestamp?

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.

Why not merge the PR automatically?

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.

A few things worth considering

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.

The bigger picture

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.