doc-sync-tool_skill

Overview

This skill automates synchronization of Agents.md, claude.md, and gemini.md files across a project to keep content consistent. It supports both a one-time sync and a continuous watch mode, with optional background process management like PM2. The tool is lightweight, configurable, and designed to reduce duplicate manual edits across agent documentation.

How this skill works

The tool recursively scans a target directory for the three target files and groups matches by folder. For each group it either creates missing files by copying an existing one or uses the most recently modified file as the source to update the others. In watch mode it monitors file changes and triggers incremental syncs in real time. Configuration options let you change target file names, scan path, and excluded directories.

When to use it

• When multiple agent docs (Agents.md, claude.md, gemini.md) must share the same instructions or configs.
• During active development to ensure docs for different AI agents stay consistent.
• In CI or pre-commit workflows to auto-generate missing agent files before commits.
• When you want a lightweight background service to keep documentation aligned across folders.

Best practices

• Run the tool from your project root or set scanPath to the repository root to capture all groups.
• Keep the tool under version control so generated changes are visible in diffs and PRs.
• Exclude large or generated directories (node_modules, .git, .next, dist) to avoid noise.
• Use PM2 or a process manager for long-running watch mode in production or CI runners.
• Prefer editing the canonical file in a group (the most recently modified will be used) to avoid conflicts.

Example use cases

• A mono-repo containing multiple agent integrations where each folder needs identical agent instructions.
• A documentation pipeline step that ensures claude.md and gemini.md exist and match Agents.md before publishing.
• Local development: run one-time sync before running tests to guarantee agent docs are present.
• Continuous watch on a dev machine so edits to any one agent doc instantly propagate to its siblings.