| description | Load when setting up code-docs in a new repo, migrating existing docs to use frontmatter, or troubleshooting initial configuration. | |||
|---|---|---|---|---|
| lastValidated | 2026-03-28 | |||
| maxAgeDays | 90 | |||
| tags |
|
|||
| title | Get started |
This guide walks through adding code-docs to an existing repo that already has a docs/ folder. By the end, your repo will have automated frontmatter generation, an AGENTS.md index, and staleness detection.
The reusable template strategy section in the automation workflow doc has the authoritative file checklist. In summary, you need:
- Workflows:
.github/workflows/docs-sync.ymland.github/workflows/docs-staleness.yml - Task prompt:
.github/agents/frontmatter-prompt.md - Scripts:
scripts/agents/(all three files:build-index.py,check-staleness.py,frontmatter.py) - Dependencies:
requirements.txt(PyYAML >= 6.0) - Config:
.agentsrc.yaml - Index:
AGENTS.mdwith boundary markers
Copy these from the code-docs repo into your repo, preserving the directory structure.
After copying, two things need attention:
GitHub Actions secret. Add ANTHROPIC_API_KEY to your repo's GitHub Actions secrets (Settings > Secrets and variables > Actions). The docs-sync.yml workflow uses this to call Claude Code for frontmatter generation.
Staleness trigger paths. Open .github/workflows/docs-staleness.yml and update the push.paths section to include your repo's actual code paths (e.g., src/**, lib/**). Without this, the workflow only performs time-based staleness checks — it won't detect when code changes make a doc stale.
The default config sets a single value:
defaults:
maxAgeDays: 90This is the fallback staleness threshold for any doc that doesn't set its own maxAgeDays in frontmatter. Adjust it to match your team's review cadence. 90 days is a reasonable default for most repos.
Open AGENTS.md and customize the preamble to describe your repo. The preamble is the first thing agents read on every session. Keep it to three to five sentences that explain what the repo contains and what kind of work agents are likely to do.
Everything above the <!-- AGENTS-INDEX-START --> marker is human-authored and never touched by automation. Everything between the markers is regenerated by build-index.py on every run.
If your repo already has Markdown files in docs/, they need YAML frontmatter before they can appear in the AGENTS.md index. There are two paths: manual and automated.
Add a YAML frontmatter block to the top of each doc. The fields appear in alphabetical order:
---
description: "Load when [trigger conditions for when an agent should read this doc]."
lastValidated: "2026-03-28"
maxAgeDays: 90
paths:
- "src/auth/**"
- "src/middleware/session.ts"
tags:
- auth
- security
title: "Authentication flow"
---Two fields are yours to set:
lastValidated— set this to today's date. You are confirming the doc is accurate as of now.maxAgeDays— set this to your preferred review interval, or omit it to inherit the default from.agentsrc.yaml.
The other four fields (title, description, paths, tags) are LLM-owned. You can write them yourself, or leave them empty and let the automation fill them in (see below). If you write them manually, the automation will never overwrite them.
The description field is the most important. Write it as a trigger condition starting with "Load when", not a topic summary. Keep it under 160 characters.
For docs that don't map to specific code paths (architectural overviews, onboarding guides, process docs), set paths: [] to indicate there are no code paths. Staleness detection will use time-based checks only. If you omit paths, automation may add paths: [] for you.
If you prefer, add minimal frontmatter to each doc (just lastValidated and maxAgeDays) and push:
---
lastValidated: "2026-03-28"
maxAgeDays: 90
---When the push lands, docs-sync.yml detects the changed files and calls Claude Code to generate the missing title, description, paths, and tags. It opens a PR with the generated values so you can review them before merging.
This is the fastest path for migrating many docs at once. Push them all in one commit, review the generated descriptions in the PR, and correct any that don't read as clear trigger conditions.
After adding frontmatter to your docs (manually or via automation), run the index builder to confirm everything is wired correctly:
python scripts/agents/build-index.pyCheck the output in AGENTS.md:
- Each doc should have a row in the index table with correct title, description, date, and status.
- No rows should show
missing fieldswarnings. If they do, the doc is missing one of the four required frontmatter fields (title,description,lastValidated,maxAgeDays).
If you're using a virtual environment for Python dependencies, set it up first:
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txtThe default build-index.py scans docs/*.md — a flat glob that does not recurse into subdirectories. If your repo organizes docs in a nested structure like docs/guide/, you need to update the --docs-dir argument and fix the path resolution in the script.
The main issue is the repo-root derivation. The script uses os.path.dirname(docs_dir) to find the repo root, which assumes a single directory level. For docs/guide/, you need an extra os.path.dirname() call:
# Default: one level up from docs/ -> repo root
repo_root = os.path.dirname(docs_dir)
# Nested: two levels up from docs/guide/ -> repo root
repo_root = os.path.dirname(os.path.dirname(docs_dir))Without this fix, AGENTS.md links will have wrong relative paths (e.g., guide/getting-started.md instead of docs/guide/getting-started.md).
Docs not appearing in AGENTS.md. The doc is missing a valid frontmatter block (delimited by --- at the top of the file), or one of the four required fields (title, description, lastValidated, maxAgeDays) is absent. build-index.py skips files with no frontmatter and emits a warning row for files with incomplete frontmatter. Run build-index.py locally and check for warnings.
docs-sync PR not appearing after push. The ANTHROPIC_API_KEY secret is not set, or the Claude Code step failed. The workflow uses continue-on-error: true on the Claude Code step, so failures are silent. Check the workflow run logs in GitHub Actions for details. The index regeneration step (build-index.py) still runs even if Claude Code fails, so the AGENTS.md table will update — but LLM-owned fields that were missing will stay missing.
Poor auto-generated descriptions. Descriptions are never auto-regenerated after initial creation. If Claude Code produced a vague or inaccurate description, you must manually edit the description field in the doc's frontmatter. Review generated descriptions carefully on the first PR — this is the one chance to catch them.
Markdownlint MD025 errors. If your repo uses markdownlint, the YAML frontmatter title: field is treated as an H1 heading by default. Combined with a # Heading in the doc body, this triggers MD025 (multiple top-level headings). Add this to your .markdownlint-cli2.yaml:
MD025:
front_matter_title: ""AGENTS.md invisible to git. Some tools (such as OpenAI Codex CLI) add generated files to .git/info/exclude, which makes them invisible to git status. Run git check-ignore -v AGENTS.md to check. If it is excluded, remove the relevant line from .git/info/exclude.
pip install PyYAML fails with PEP 668. On modern systems with externally managed Python environments, direct pip install is blocked. Use a virtual environment instead:
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txtMulti-commit pushes miss changed files. The default docs-sync.yml uses HEAD~1..HEAD to detect changed files, which only sees the last commit. For pushes with multiple commits, use the full push range in your workflow:
env:
BEFORE_SHA: ${{ github.event.before }}
AFTER_SHA: ${{ github.sha }}
run: |
FILES=$(git diff --name-only --diff-filter=AM "$BEFORE_SHA" "$AFTER_SHA" -- 'docs/*.md')