# Docs Sync

Find and fix the docs and agent guidance that a branch makes stale - agent skills and...

- Repository: https://github.com/Kiln-AI/Kiln (5247 stars)
- Category: AI and agents
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add Kiln-AI/Kiln --skill docs-sync -g -a claude-code -y`
Codex: `npx skills add Kiln-AI/Kiln --skill docs-sync -g -a codex -y`
Cursor: `npx skills add Kiln-AI/Kiln --skill docs-sync -g -a cursor -y`
Gemini CLI: `npx skills add Kiln-AI/Kiln --skill docs-sync -g -a gemini-cli -y`

## Description

Find and fix the docs and agent guidance that a branch makes stale - agent skills and their reference files, AGENTS.md and .agents/*.md prompts, READMEs, docs/ folders, and code-adjacent docs that name a changed path, command, symbol, env var, setting, endpoint or behaviour. Use before opening a PR, before pushing new commits to an open PR, and when asked to update docs or skills after a change. The open-pr skill runs it every time.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Docs sync: keep docs and skills true to the code

A change that renames a script or removes a function leaves every doc that names it wrong, and the next agent follows the wrong doc. Run this before you open a PR and before each push to an open PR. It finds what changed, finds the docs that mention it, and fixes them in the same PR.

Run every command from the repo root. Shell variables do not carry over between commands: run each code block as one command.

## 1. Find what changed

```bash
BASE=$(gh pr view --json baseRefName --jq .baseRefName 2>/dev/null) || BASE=<the base from open-pr Step 2, else main>   # no PR yet
git fetch -q origin "$BASE"; B="origin/$BASE"
git diff --name-status -M "$B"...HEAD    # A/M/D/R per file
git log --format='%h %s%n%b' "$B"..HEAD   # intent, new conventions
git diff -U0 "$B"...HEAD | grep -E '^[-+](\s*(async )?def |\s*class |export (async )?(function|const|class|type|interface|enum) |\s*@app\.(get|post|put|patch|delete)\()|os\.(environ|getenv)|env_var=|process\.env|import\.meta\.env'
git diff -U0 "$B"...HEAD | grep -E '^@@' | sed -E 's/^@@ [^@]* @@ ?//' | sort -u   # functions and classes whose bodies changed
git diff --stat "$B"...HEAD -- '*.sh' '*pyproject.toml' '*package.json' .github/workflows .agents
```

Turn that output into a list of search terms. Use the old name; for a rename, the new name is the replacement.

The rest: https://github.com/Kiln-AI/Kiln/blob/HEAD/.agents/skills/docs-sync/SKILL.md