# Skill Sync Checker > Detects content drift between skill files and their source documents. Helps maintain skills that are derived from other documentation by comparing content and flagging outdated sections. - Skill: `diegosouzapw/skill-sync-checker` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add diegosouzapw/skill-sync-checker` - Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/skill-sync-checker/raw - Safety review: pending (external: skill-scanner PASS, skillspector WARNING) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: diegosouzapw (https://skillmd.com/u/diegosouzapw) - Updated: 2026-09-08 - Page: https://skillmd.com/skills/diegosouzapw/skill-sync-checker --- # Skill Sync Checker A utility skill that detects when skill content has drifted from its source documents. Any skill file that includes a `` marker can be checked for freshness and updated accordingly. ## When to Use This Skill ### User-Initiated (Agent Requested) Use this skill when the user: - Asks to check if a skill's content is up to date - Has modified source documentation and wants to sync derived skills - Is preparing a skill for publishing and wants to verify freshness - Asks "is this skill still accurate?" or "has the source changed?" - Performs routine maintenance on skills ### Auto-Triggered (via Cursor globs) This skill is automatically injected into context when the user edits `README.md` (configurable via `.cursor/rules/skill-sync-checker.mdc` globs). When auto-triggered, follow this lightweight flow: 1. Scan `skills/**/SKILL.md` for `` markers referencing the file being edited 2. If a match is found, **briefly remind** the user that a skill depends on this file and may need syncing 3. Do **not** automatically run the full detection workflow or modify any files — just notify Example notification: ``` Note: skills/reskill-usage/SKILL.md is derived from README.md (last synced: 2026-02-12). If your changes affect CLI commands, options, or usage examples, the skill may need updating. Run a sync check when you're done editing. ``` ## Source Marker Convention Skill files that are derived from other documents should include source markers as HTML comments at the top of the file (before or after the YAML frontmatter): ```markdown --- name: my-skill description: ... --- # My Skill ... ``` ### Marker Format | Marker | Required | Description | | ------------------------- | -------- | ---------------------------------------------------- | | `` | Yes | Relative path to the source file (from project root) | | `` | No | ISO date of last sync (YYYY-MM-DD) | A file can have **multiple source markers** if it derives from several documents: ```markdown ``` ### Where to Place Markers - Place source markers at the very top of the file - If the file has YAML frontmatter (`---`), markers can go before or after it - Markers are HTML comments and will not render in the skill content ## Detection Workflow When asked to check a skill for sync status, follow these steps: ### Step 1: Find Source Markers Scan all `.md` files in the target skill directory. For each file, look for `` comments. Files without source markers are original content and can be skipped. ### Step 2: Read Source Files For each source marker, read the referenced file. If the source file does not exist, report it as an error — the source may have been moved or deleted. ### Step 3: Compare Content Compare the skill file against its source document(s). Focus on **structural and factual differences**, not formatting: **Key things to check:** - Commands, options, or features mentioned in the source but missing from the skill - Commands, options, or features in the skill that no longer exist in the source - Changed default values, paths, or configuration formats - New sections in the source that should be reflected in the skill - Deprecated or removed functionality still mentioned in the skill **Ignore:** - Minor wording differences (the skill may rephrase for agent consumption) - Formatting differences (tables vs lists, heading levels) - Content the skill intentionally omits (internal details, development docs) - Order of sections ### Step 4: Report Results Present findings in a clear summary: ``` Sync Check: skills/reskill-usage/SKILL.md Source: README.md Last synced: 2026-02-11 Status: ⚠ Out of sync Differences found: 1. New command `find` added in source (missing from skill) 2. Option `--registry` added to `install` command 3. New agent "Gemini" added to Multi-Agent Support table Recommendation: Update the skill to reflect these changes. ``` If everything is in sync: ``` Sync Check: skills/reskill-usage/SKILL.md Source: README.md Last synced: 2026-02-11 Status: ✓ In sync No significant differences found. ``` If the `` marker is absent, report "Last synced: unknown": ``` Sync Check: skills/example/SKILL.md Source: docs/example-spec.md Last synced: unknown Status: ⚠ Out of sync ... ``` ## Update Workflow When differences are detected and the user confirms they want to update: ### Step 1: Show Differences Present each difference with the relevant content from the source file so the user can review what changed. ### Step 2: Update Skill Content After user confirmation, update the skill file to reflect the source changes. Preserve the skill's structure and agent-specific content (When to Use, Workflows, Troubleshooting) — only update the sections that correspond to source material. ### Step 3: Update Synced Date Update the `` marker to today's date: ```markdown ``` ## Detecting Potentially Relevant New Documents When checking a skill, also scan the project for new documentation that might be relevant but is not yet tracked: ### Heuristic Rules | File Pattern | Likely Relevant | Action | | --------------------------------------- | ------------------------ | ------------------------ | | `*-spec.md`, `*-summary.md` | Yes — user-facing specs | Suggest adding as source | | `README.md`, `README.*.md` | Yes — user-facing docs | Suggest adding as source | | `API.md`, `docs/*.md` | Yes — user-facing docs | Suggest adding as source | | `CHANGELOG.md` | No — auto-generated | Skip | | `CONTRIBUTING.md` | No — contributor guide | Skip | | `*-design.md` | No — internal design | Skip | | `*-plan.md`, `*-implementation-plan.md` | No — internal plans | Skip | | `*-migration-plan.md` | No — internal migration | Skip | | `*-adaptation.md` | No — internal adaptation | Skip | When a potentially relevant new document is found, notify the user: ``` New document detected: docs/new-feature-spec.md This looks like a user-facing spec that might be relevant to the skill. Would you like to review it for inclusion? ``` **Never automatically add new sources or modify skill content without user confirmation.** ## Example: Checking reskill-usage Here is a complete example of checking the `reskill-usage` skill: ``` User: "Check if the reskill-usage skill is up to date" Agent steps: 1. Read skills/reskill-usage/SKILL.md 2. Find marker: 3. Read README.md 4. Compare commands table, source formats, configuration, etc. 5. Report: "The skill is missing the new `find` command that was added to README.md. Would you like me to update it?" ``` After user confirms: ``` Agent steps: 1. Add `find` command to the Commands table in SKILL.md 2. Update 3. Report: "Updated SKILL.md — added `find` command, synced date updated to 2026-02-12" ``` ## Batch Checking To check all skills in a project at once: ``` User: "Check all skills for sync status" Agent steps: 1. Find all SKILL.md files in the project (skills/, .cursor/skills/, etc.) 2. For each file with source markers, run the detection workflow 3. Present a summary of all results: Sync Check Summary: ✓ skills/find-skills/SKILL.md — no source markers (original content) ⚠ skills/reskill-usage/SKILL.md — 2 differences found (source: README.md) ✓ skills/skill-sync-checker/SKILL.md — no source markers (original content) ``` ## Limitations - This skill guides the agent through a manual comparison process — it does not run automated diffing tools - The agent uses judgment to determine what constitutes a "significant" difference - Source markers are a convention, not enforced — files without markers are simply skipped - The heuristic rules for new document detection are suggestions, not definitive classifications