Kiln-AI/Kiln / .agents/skills/docs-sync
docs-sync
VerifiedFind 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.
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
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.
- Each A, M, D and R file: its full repo path and its file name with the extension. For a Python file, also its dotted import path (
app.desktop.desktop_server; underlibs/, start at the package:kiln_ai.adapters.ml_model_list). Do not use bare stems such asutilsorconfig. - Each rename or move: the old path too. When a whole directory moved, add the old directory path.
- Each M file: the names of the functions and classes from the
@@hunk headers (a header names the nearest earlier top-level line, not always the changed one), and the key nouns of the commit subjects. These find the docs that describe the changed behaviour, not only the docs that name the file. - Each removed or renamed public symbol: a
def,classor export on a-line with no matching+line. - Each removed, renamed or added env var, setting, endpoint path, CLI command, script, check or CI workflow.
- Each new convention or gotcha (a new place where a kind of file goes, a new required step, a new command). These have no old name to search; note the area they belong to.
2. Find the docs that mention them
TERMS=(-e app/desktop/old_script.sh -e old_script.sh -e old_function) # one -e per term from step 1
DOCS=(AGENTS.md .agents '*.md' '*.mdx' .github .config)
NOT_DOCS=(':!AGENTS.md' ':!.agents' ':!*.md' ':!*.mdx' ':!.github' ':!.config')
SKIP=(':!specs/projects' ':!.agents/playwright_project' ':!*kiln_ai_server_client*' ':!app/web_ui/src/lib/api_schema.d.ts')
git grep -n -F "${TERMS[@]}" -- "${DOCS[@]}" "${SKIP[@]}" # docs, skills, prompts, configs
git grep -n -F "${TERMS[@]}" -- . "${NOT_DOCS[@]}" "${SKIP[@]}" # code-adjacent mentions
- The first grep covers skills and their reference files and scripts,
AGENTS.md,.agents/*.mdprompts, every README,docs/,app/*/docs/, the PR template, CI workflows and.config/. - The second grep covers everything else: comments, docstrings,
--helpand usage text, theMakefile,pyproject.tomlscripts, and the scripts that skills link to. - If you work on an active spec project, add
specs/projects/<project>to both greps. - Add
-wfor short symbol names that match inside longer names. Add-ifor terms that docs write in prose. - For a new convention or command from step 1, find its closest home:
git grep -n -l -i '<area word>' -- AGENTS.md .agents '*.md' '*.mdx' .github .config, and read thedescriptionlines in.agents/skills/*/SKILL.md.
Read each hit. Judge whether the text describes the changed behaviour, not only whether the name matches. Each hit gets a decision in step 3.
3. Update each stale statement in place
- Rewrite the sentence, command, path or table row so it describes the code as it is now. Point to the replacement when one exists. Delete the statement when nothing replaces it.
- Add guidance where the change introduces something a future agent must know: a new gotcha, a new "where things go" rule, a new command or check. Put it in the closest existing skill, reference file or prompt. Create a new file only when nothing fits.
- When a hit is still true (a different thing with the same name, or a historical mention in a commit or spec), leave it and note why.
- Match the style of the file you edit.
open-prand other files written in Simplified Technical English stay in it.
4. Do not make these edits
- Do not rewrite docs that the change did not make stale.
- Do not edit generated files:
CLAUDE.md,.claude/,.cursor/,.mcp.json,.worktreeinclude, the generated API client underkiln_ai_server_client/,app/web_ui/src/lib/api_schema.d.ts. Edit their sources (AGENTS.md,.agents/,.config/wt/). - Do not touch the human header of
.github/pull_request_template.md(everything above# Agentic PR Summary). If it holds stale text, tell the user in your end-of-task summary. - Do not add history to docs: no "renamed from", "previously", "as of" or changelog notes. Docs describe the current state.
- Do not edit anything under
specs/projects/**except the active project's own files.
5. Commit and report
Commit the doc updates in the same PR, as their own commit:
git add <doc files>
git commit -m "docs: <what the docs now say>"
Re-run your agent setup script if you changed .agents/.
When the PR has an Agentic PR Summary, add one line to it, or update the line that is there. List every doc file that the PR changes:
**Docs and skills updated:** <files>, <one-line reason>., or**Docs and skills updated:** none needed, <one-line reason>.
6. Done when
- You looked at every hit from step 2 and updated it or noted why it stays.
- Nothing left refers to a removed path or symbol. This final check prints only the hits that you noted as still true:
git grep -n -F -e <removed path> -e <removed symbol> -- . ':!specs/projects' ':!.agents/playwright_project' ':!*kiln_ai_server_client*' ':!app/web_ui/src/lib/api_schema.d.ts'
Add the active spec project back to that check if you work on one.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 468k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 197k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |