How do I install the Docs Sync skill?

Run npx skillmds@latest add engsimsoft/docs-sync in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Docs Sync safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Docs Sync?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Docs Sync free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Docs Sync?

engsimsoft (@engsimsoft) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Docs Sync by engsimsoft — Agent Skill

Name: Docs Sync
Author: engsimsoft

Docs Sync

Use this skill ALWAYS at the end of ANY code-changing task to synchronize project memory with reality. Trigger this skill after closing any TZ, after fixing any bug, after completing any refactor, after adding any feature, after creating any ADR — even if the user did not explicitly request docs update. This skill is MANDATORY before declaring a task complete.

engsimsoft d0a503d 2.9 KB Updated Sep 17, 2026

File contents

Docs-sync workflow

Synchronize docs/agent/ with what ACTUALLY happened in code. Code is truth, docs are derived.

When to run

End of any task that modified code
After bugfix, refactor, feature work
After creating an ADR
During /close-tz finalization
When called manually via /docs-sync

Procedure (in order)

1. Determine what changed

git log --oneline <last_synced_commit>..HEAD
git diff --stat <last_synced_commit>..HEAD

The last_synced_commit is in docs/agent/00_current_state.md frontmatter.

2. Read current docs/agent/ files

00_current_state.md — for durable facts cache
03_active_plan.md — for closed task removal
04_changelog.md — to append new entries
06_known_issues.md — to update resolved/new issues
07_handoff.md — to refresh next-step

3. Update each file with FACTS from diff (not narrative)

00_current_state.md — only DURABLE facts:

"Auth uses NextAuth + email" — durable
"Currently working on TZ-15" — NOT durable, remove

04_changelog.md — concise entries from diff:

## YYYY-MM-DD — TZ-NN: <title>
- Added: ... (what new code does)
- Changed: ... (what behavior changed)
- Fixed: ... (what bug is no longer)
- Commit: <hash>

03_active_plan.md — remove closed tasks, surface next ones.

07_handoff.md — diff-based, NOT narrative:

## What was done (facts from git)
- Commit abc123: feat(tz-15) summary
- Files: src/api/foo.py (+45/-12), src/db/models.py (+8/-0)
- Tests: pytest tests/test_foo.py PASS (12/12), mypy clean

## Where we stopped
- Current position: TZ-15 stage 4 of 7
- Next concrete action: <exact command or exact edit>

## NOT what we think is true
- (no hypotheses here, only facts)

4. ADR if non-trivial decision was made

Use /adr slash command
INDEX.md will auto-regenerate via post-tool-edit hook

5. Update version-stamps

At the top of each modified docs/agent/ file:

---
last_updated_at: 2026-MM-DD
last_updated_commit: <new HEAD hash>
last_updated_by: <session-id or "claude-code-sync">
---

6. Do NOT invent work

If diff doesn't show it, you didn't do it
Don't add aspirational entries ("planning to...") to changelog
Don't add features that aren't in the code

Anti-patterns

✗ Update docs by copying old docs (they get more stale)
✗ Update CLAUDE.md to reflect new feature (CLAUDE.md is navigation, not detail)
✗ Skip docs-sync because "tests pass = done"
✗ Add narrative to HANDOFF (use diff facts only)

---name: docs-syncdescription: Use this skill ALWAYS at the end of ANY code-changing task to synchronize project memory with reality. Trigger this skill after closing any TZ, after fixing any bug, after completing any refactor, after adding any feature, after creating any ADR — even if the user did not explicitly request docs update. This skill is MANDATORY before declaring a task complete.---# Docs-sync workflowSynchronize `docs/agent/` with what ACTUALLY happened in code. Code is truth, docs are derived.## When to run- End of any task that modified code- After bugfix, refactor, feature work- After creating an ADR- During /close-tz finalization- When called manually via /docs-sync## Procedure (in order)### 1. Determine what changed```bashgit log --oneline <last_synced_commit>..HEADgit diff --stat <last_synced_commit>..HEAD```The `last_synced_commit` is in `docs/agent/00_current_state.md` frontmatter.### 2. Read current docs/agent/ files- `00_current_state.md` — for durable facts cache- `03_active_plan.md` — for closed task removal- `04_changelog.md` — to append new entries- `06_known_issues.md` — to update resolved/new issues- `07_handoff.md` — to refresh next-step### 3. Update each file with FACTS from diff (not narrative)**00_current_state.md** — only DURABLE facts:- "Auth uses NextAuth + email" — durable- "Currently working on TZ-15" — NOT durable, remove**04_changelog.md** — concise entries from diff:```## YYYY-MM-DD — TZ-NN: <title>- Added: ... (what new code does)- Changed: ... (what behavior changed)- Fixed: ... (what bug is no longer)- Commit: <hash>```**03_active_plan.md** — remove closed tasks, surface next ones.**07_handoff.md** — diff-based, NOT narrative:```## What was done (facts from git)- Commit abc123: feat(tz-15) summary- Files: src/api/foo.py (+45/-12), src/db/models.py (+8/-0)- Tests: pytest tests/test_foo.py PASS (12/12), mypy clean## Where we stopped- Current position: TZ-15 stage 4 of 7- Next concrete action: <exact command or exact edit>## NOT what we think is true- (no hypotheses here, only facts)```### 4. ADR if non-trivial decision was made- Use `/adr` slash command- INDEX.md will auto-regenerate via post-tool-edit hook### 5. Update version-stampsAt the top of each modified docs/agent/ file:```yaml---last_updated_at: 2026-MM-DDlast_updated_commit: <new HEAD hash>last_updated_by: <session-id or "claude-code-sync">---```### 6. Do NOT invent work- If diff doesn't show it, you didn't do it- Don't add aspirational entries ("planning to...") to changelog- Don't add features that aren't in the code## Anti-patterns- ✗ Update docs by copying old docs (they get more stale)- ✗ Update CLAUDE.md to reflect new feature (CLAUDE.md is navigation, not detail)- ✗ Skip docs-sync because "tests pass = done"- ✗ Add narrative to HANDOFF (use diff facts only)

Frequently asked questions