diff --git a/tests/website/test_generate_skill_docs.py b/tests/website/test_generate_skill_docs.py
index 95ecb06a78..fca5651919 100644
--- a/tests/website/test_generate_skill_docs.py
+++ b/tests/website/test_generate_skill_docs.py
@@ -106,3 +106,11 @@ def test_box_drawing_detection_covers_common_chars(gen_module):
     # Sample from real SKILL.md diagrams (segment-anything, research-paper-writing, etc.)
     for ch in "┌┐└┘─│├┤┬┴┼═║╔╗╚╝╭╮╯╰▶◀▲▼":
         assert ch in gen_module._BOX_DRAWING_CHARS, f"missing: {ch!r}"
+
+
+def test_bundled_catalog_explains_missing_local_skills(gen_module):
+    """The bundled catalog should explain how to restore a listed skill that
+    was removed from the local profile's skills tree."""
+    result = gen_module.build_catalog_md_bundled([])
+    assert "respects local deletions and user edits" in result
+    assert "hermes skills reset <name> --restore" in result
diff --git a/website/docs/reference/skills-catalog.md b/website/docs/reference/skills-catalog.md
index a550730458..221b07fdc0 100644
--- a/website/docs/reference/skills-catalog.md
+++ b/website/docs/reference/skills-catalog.md
@@ -8,6 +8,8 @@ description: "Catalog of bundled skills that ship with Hermes Agent"
 
 Hermes ships with a large built-in skill library copied into `~/.hermes/skills/` on install. Each skill below links to a dedicated page with its full definition, setup, and usage.
 
+Hermes also syncs bundled skills on `hermes update`, but the sync manifest respects local deletions and user edits. If a skill listed here is missing from your profile's `~/.hermes/skills/` tree, it is still shipped with Hermes; restore it with `hermes skills reset <name> --restore`.
+
 If a skill is missing from this list but present in the repo, the catalog is regenerated by `website/scripts/generate-skill-docs.py`.
 
 ## apple
diff --git a/website/scripts/generate-skill-docs.py b/website/scripts/generate-skill-docs.py
index c63769041c..d55c6e55c3 100755
--- a/website/scripts/generate-skill-docs.py
+++ b/website/scripts/generate-skill-docs.py
@@ -481,6 +481,8 @@ def build_catalog_md_bundled(entries: list[tuple[dict[str, Any], dict[str, Any]]
         "",
         "Hermes ships with a large built-in skill library copied into `~/.hermes/skills/` on install. Each skill below links to a dedicated page with its full definition, setup, and usage.",
         "",
+        "Hermes also syncs bundled skills on `hermes update`, but the sync manifest respects local deletions and user edits. If a skill listed here is missing from your profile's `~/.hermes/skills/` tree, it is still shipped with Hermes; restore it with `hermes skills reset <name> --restore`.",
+        "",
         "If a skill is missing from this list but present in the repo, the catalog is regenerated by `website/scripts/generate-skill-docs.py`.",
         "",
     ]