fix(agentdoc): hide skill lifecycle hooks

Signed-off-by: Paul Furgale <pfurgale@nvidia.com>

Author: furgalep

src/nooa/agentdoc/_structured.py

@@ -1516,12 +1516,17 @@ def _extract_methods(obj: type) -> list[CallableInfo]:
 
     methods = []
     seen_names = set()
+    always_hidden_names = {
+        name for klass in obj.__mro__ for name in getattr(klass, "__agentdoc_hidden_methods__", ())
+    }
 
     # Walk the MRO dictionaries directly instead of inspect.getmembers().
     # inspect.getmembers() calls getattr() for every name and can execute arbitrary
     # descriptors while formatting an object.
     for klass in obj.__mro__:
         for name, raw in vars(klass).items():
+            if name in always_hidden_names:
+                continue
             value = raw
             if isinstance(raw, (classmethod, staticmethod)):
                 value = raw.__func__
@@ -1556,6 +1561,8 @@ def _extract_methods(obj: type) -> list[CallableInfo]:
     except TypeError:
         fields_meta = {}
     for name, meta in fields_meta.items():
+        if name in always_hidden_names:
+            continue
         if meta.get("hidden") is not False:
             continue
         if name in seen_names:

src/nooa/skill.py

@@ -271,6 +271,10 @@ class MyAgent(Agent, llm=llm):
     # Skills show a brief one-liner wherever they appear as a field type.
     __agentdoc_skip__ = True
 
+    # Lifecycle hooks are framework plumbing, never model-callable capabilities.
+    # The marker is inherited so overrides remain hidden for every Skill subclass.
+    __agentdoc_hidden_methods__ = frozenset({"attach", "detach"})
+
     # Skills are reconstructed on agent init (e.g., LibraryManager rescans libs/).
     # They shouldn't be serialized in snapshots — mark them as nosnapshot.
     __nosnapshot__ = True

tests/agentdoc/test_skill_lifecycle_visibility.py

@@ -0,0 +1,54 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Skill lifecycle hooks are framework plumbing, not model-facing tools."""
+
+from typing import Any
+
+from nooa.agentdoc import doc, spec
+from nooa.skill import Skill
+
+
+class ExampleSkill(Skill):
+    """A useful example skill."""
+
+    def useful(self, value: str) -> str:
+        """Return a useful value."""
+        return value
+
+
+class OverridingSkill(ExampleSkill):
+    """A skill that customizes its lifecycle hooks."""
+
+    def attach(self, agent: Any) -> None:
+        self.agent = agent
+
+    def detach(self) -> None:
+        self.agent = None
+
+
+def test_skill_lifecycle_hooks_are_hidden_from_docs():
+    rendered = doc(ExampleSkill)
+
+    assert "def useful(" in rendered
+    assert "def attach(" not in rendered
+    assert "def detach(" not in rendered
+
+
+def test_overridden_skill_lifecycle_hooks_remain_hidden_from_docs():
+    rendered = doc(OverridingSkill)
+
+    assert "def useful(" in rendered
+    assert "def attach(" not in rendered
+    assert "def detach(" not in rendered
+
+
+def test_skill_lifecycle_hooks_cannot_be_explicitly_unhidden():
+    class ExplicitlyUnhiddenSkill(Skill):
+        def attach(self, agent: Any) -> None:
+            self.agent = agent
+
+    spec(ExplicitlyUnhiddenSkill, "attach", hidden=False)
+
+    rendered = doc(ExplicitlyUnhiddenSkill())
+    assert "def attach(" not in rendered
+    assert "def detach(" not in rendered