feat(analyzer): add phase-1 structured skill summaries

src/skillspector/multi_skill.py

@@ -26,6 +26,7 @@
 from pathlib import Path
 
 from skillspector.logging_config import get_logger
+from skillspector.structured_skill import _SKIP_DIRS, extract_structured_skill_context
 
 logger = get_logger(__name__)
 
@@ -71,9 +72,11 @@ def detect_skills(directory: Path) -> MultiSkillDetectionResult:
     for child in sorted(directory.iterdir()):
         if not child.is_dir():
             continue
+        if child.name in _SKIP_DIRS:
+            continue
         if child.name.startswith("."):
             continue
-        if _has_skill_md(child):
+        if _has_skill_md(child) or _is_structured_skill_bundle(child):
             name = _extract_skill_name(child)
             skills.append(
                 SkillDirectory(
@@ -91,6 +94,11 @@ def detect_skills(directory: Path) -> MultiSkillDetectionResult:
     )
 
 
+def _is_structured_skill_bundle(child_dir: Path) -> bool:
+    """Return true when a child directory contains a valid AISOP/AISP bundle."""
+    return extract_structured_skill_context(child_dir) is not None
+
+
 def _has_skill_md(directory: Path) -> bool:
     """Check if directory contains a SKILL.md or skill.md at root level."""
     return (directory / "SKILL.md").is_file() or (directory / "skill.md").is_file()

src/skillspector/nodes/analyzers/__init__.py

@@ -76,6 +76,9 @@
     node as static_patterns_tool_misuse_node,
 )
 from skillspector.nodes.analyzers.static_yara import node as static_yara_node
+from skillspector.nodes.analyzers.structured_skill_roles import (
+    node as structured_skill_roles_node,
+)
 
 ANALYZER_NODE_IDS: list[str] = [
     "static_patterns_prompt_injection",
@@ -98,6 +101,7 @@
     "mcp_least_privilege",
     "mcp_tool_poisoning",
     "mcp_rug_pull",
+    "structured_skill_roles",
     "semantic_security_discovery",
     "semantic_developer_intent",
     "semantic_quality_policy",
@@ -124,6 +128,7 @@
     "mcp_least_privilege": mcp_least_privilege_node,
     "mcp_tool_poisoning": mcp_tool_poisoning_node,
     "mcp_rug_pull": mcp_rug_pull_node,
+    "structured_skill_roles": structured_skill_roles_node,
     "semantic_security_discovery": semantic_security_discovery_node,
     "semantic_developer_intent": semantic_developer_intent_node,
     "semantic_quality_policy": semantic_quality_policy_node,

src/skillspector/nodes/analyzers/structured_skill_roles.py

@@ -0,0 +1,62 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Structured skill role summary analyzer (SSR-*)."""
+
+from __future__ import annotations
+
+from skillspector.state import AnalyzerNodeResponse, SkillspectorState
+
+ANALYZER_ID = "structured_skill_roles"
+
+
+def _string_list(value: object) -> list[str]:
+    """Return a compact list of string values for summary payload fields."""
+    if not isinstance(value, list):
+        return []
+    return [str(item) for item in value if str(item)]
+
+
+def _build_summary(context: dict[str, object]) -> dict[str, object]:
+    """Build a single SSR-1 structured summary from validated context."""
+    protocol = str(context.get("protocol", "AISOP/AISP"))
+    layout_kind = str(context.get("layout_kind", "structured"))
+    bundle_path = str(context.get("bundle_path", ""))
+    declared_tools = sorted(_string_list(context.get("declared_tools")))
+    workflow_nodes = _string_list(context.get("workflow_nodes"))
+    constraints = _string_list(context.get("constraint_anchors"))
+    resources = _string_list(context.get("resource_anchors"))
+
+    return {
+        "id": "SSR-1",
+        "message": f"Structured {layout_kind} bundle detected ({protocol})",
+        "file": bundle_path,
+        "protocol": protocol,
+        "layout_kind": layout_kind,
+        "declared_tools": declared_tools,
+        "workflow_nodes": workflow_nodes,
+        "constraints": constraints,
+        "resources": resources,
+        "tags": ["AISOP", "AISP", "structured-skill"],
+    }
+
+
+def node(state: SkillspectorState) -> AnalyzerNodeResponse:
+    """Emit one SSR-1 structured summary when structured context is present."""
+    context = state.get("structured_skill_context")
+    if not isinstance(context, dict):
+        return {"findings": []}
+
+    return {"findings": [], "structured_summaries": [_build_summary(context)]}

src/skillspector/nodes/build_context.py

@@ -29,6 +29,7 @@
 from skillspector.constants import build_model_config
 from skillspector.logging_config import get_logger
 from skillspector.state import SkillspectorState
+from skillspector.structured_skill import extract_structured_skill_context
 
 logger = get_logger(__name__)
 
@@ -84,12 +85,12 @@ def _walk_skill_files(skill_dir: Path) -> list[str]:
     for item in skill_dir.rglob("*"):
         if not item.is_file():
             continue
-        if any(skip in item.parts for skip in _SKIP_DIRS):
-            continue
-        if item.name.startswith(".") and not item.name.startswith(".claude"):
-            continue
         try:
             rel = item.relative_to(skill_dir)
+            if any(skip in rel.parts for skip in _SKIP_DIRS):
+                continue
+            if item.name.startswith(".") and not item.name.startswith(".claude"):
+                continue
             # Use forward slashes on every OS: these relative paths are dict keys
             # and SARIF/URI locations, so they must be portable (not OS-specific
             # backslashes on Windows).
@@ -239,8 +240,9 @@ def build_context(state: SkillspectorState) -> dict[str, object]:
     file_cache = _read_file_cache(skill_dir, components)
     manifest = _parse_manifest(skill_dir)
     component_metadata, has_executable_scripts = _build_component_metadata(skill_dir, components)
+    structured_skill_context = extract_structured_skill_context(skill_dir)
 
-    return {
+    result = {
         "components": components,
         "file_cache": file_cache,
         "ast_cache": {},
@@ -250,3 +252,8 @@ def build_context(state: SkillspectorState) -> dict[str, object]:
         "component_metadata": component_metadata,
         "has_executable_scripts": has_executable_scripts,
     }
+
+    if structured_skill_context is not None:
+        result["structured_skill_context"] = structured_skill_context
+
+    return result