--- name: docs-sync description: | Synchronize documentation indices and cross-references. Use after adding, renaming, moving, or deleting documentation files. Finds orphaned docs, stale links, and broken cross-references, then fixes them and reports changes. --- # docs-sync ## Purpose Keep documentation indices, cross-reference links, and table-of-contents files consistent after docs are added, renamed, moved, or deleted. Prevent stale links and orphaned pages. ## Required Reads - `.agents/project.json` -- confirm design facet is enabled - `docs/` directory listing -- current documentation tree - Any existing index files (e.g., `docs/index.md`, `docs/overview.md`) -- current state of indices - `.agents/pm/pm-current-state.md` -- recent changes that may have affected docs ## Procedure 1. List all markdown files under `docs/` recursively. 2. Read each existing index or table-of-contents file in the docs tree. 3. Compare the file list against index entries. Identify: - Files present on disk but missing from indices (orphaned docs). - Index entries pointing to files that no longer exist (stale links). - Cross-reference links within docs that point to renamed or moved targets. 4. For each orphaned doc, add an entry to the appropriate index with the file path and a one-line summary derived from the document's first heading. 5. For each stale link, either update the link to the new location or remove the entry and flag it in the output. 6. For broken cross-references inside documents, fix the link target. If the target cannot be determined, insert a `` comment and list it in the output. 7. If `docs/overview.md` exists, verify its section list matches the current doc tree structure. Update if needed. 8. Write a brief sync report to the user listing changes made and any items needing manual review. ## Output - Updated index and table-of-contents files under `docs/` - Fixed cross-reference links within documentation files - Sync report listing: files added to indices, stale links removed, broken links flagged ## Completion Criteria - Every markdown file under `docs/` appears in at least one index. - No index entry points to a nonexistent file. - All fixable cross-reference links have been updated. - Any unfixable links are marked with a TODO comment and reported to the user. ## Error Handling - If the design facet is not enabled in `project.json`, warn the user and ask whether to proceed anyway. - If no `docs/` directory exists, stop and tell the user there is nothing to synchronize. - If an index file uses a format that cannot be parsed, skip it and report it as needing manual review. --- Source attribution: AMDResearch Original project: https://github.com/AMDResearch/omniprobe/blob/913ae319f727f8014e4db442a80e84915c8cf3a0/.agents/skills/docs-sync/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice ------------------------------------------------------------------------------- MIT License Copyright (c) 2026 Advanced Micro Devices, Inc. All Rights Reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ------------------------------------------------------------------------------- # Mega AI Hub resource metadata Creator / publisher: AMDResearch Original project: https://github.com/AMDResearch/omniprobe/blob/913ae319f727f8014e4db442a80e84915c8cf3a0/.agents/skills/docs-sync/SKILL.md Attribution basis: Source repository record Fields of work: Content & Media, Design, Project & Program Management Roles: Project Manager, Technical Writer, UX Writer Specialties: API Tools: Tool not specified Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 48a5a37992bfefcb3213c816e105f477ade05a6f20b970c0fe07137e6c87fcfd