Skip to content

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

Open
rodboev wants to merge 3 commits into
NVIDIA:mainfrom
rodboev:pr/structured-skill-role-summary
Open

feat(analyzer): add phase-1 structured skill summaries#211
rodboev wants to merge 3 commits into
NVIDIA:mainfrom
rodboev:pr/structured-skill-role-summary

Conversation

@rodboev

@rodboev rodboev commented Jun 25, 2026

Copy link
Copy Markdown

Summary

SkillSpector currently scans AISOP/AISP bundles as generic directories and never says that a structured workflow format was found or which workflow roles were present. This phase-1 slice teaches recursive discovery and build-context to recognize valid *.aisop.json bundles, then emits one LOW informational summary finding without changing scoring or existing rule behavior.

Refs #130

This follows the phased implementation sketch and AISOP/AISP bundle examples in #130.

Root cause

src/skillspector/multi_skill.py only recognizes root SKILL.md layouts or immediate subdirectories that contain SKILL.md or skill.md, so --recursive misses structured subdirectories that are expressed only through valid AISOP/AISP bundle files. src/skillspector/nodes/build_context.py builds generic scan context and never classifies those bundles, while src/skillspector/nodes/analyzers/__init__.py has no structured-skill analyzer in the registry-driven graph. The bundle parser also needed to follow the issue schema itself, with workflow nodes at user.content.functions and constraint strings in functions.*.constraints, rather than an invented nested aisop.functions shape. The result is simple: valid structured bundles can be scanned, but the report has no structured-skill summary surface at all.

Diff Notes

  • Add src/skillspector/structured_skill.py as the shared detector for valid *.aisop.json AISOP/AISP bundles and their summarized metadata, reading workflow nodes from user.content.functions and AISP resources from user.content.aisp_contract.resources.
  • Reuse that detector in src/skillspector/multi_skill.py so --recursive can treat immediate structured subdirectories as skills while preserving root SKILL.md precedence.
  • Populate structured_skill_context in src/skillspector/nodes/build_context.py and src/skillspector/state.py without changing the public report schema.
  • Add src/skillspector/nodes/analyzers/structured_skill_roles.py and register it in src/skillspector/nodes/analyzers/__init__.py so the graph emits one LOW SSR-1 structured summary finding.
  • Add focused coverage in tests/test_multi_skill.py, tests/nodes/test_build_context.py, tests/nodes/analyzers/test_registry.py, tests/nodes/analyzers/test_structured_skill_roles.py, and tests/unit/test_cli.py.

Scope

  • Phase 1 only. This PR detects valid AISOP/AISP bundles and summarizes them with one additive LOW finding.
  • No severity adjustments, no meta_analyzer changes, and no changes to existing static, behavioral, MCP, or semantic findings.
  • No report-schema additions beyond the existing Finding fields.
  • No Pi extension changes in extensions/skillspector.ts.
  • No full role-aware score downgrades, no malformed-bundle warning surface, and no claim of complete AISOP/AISP spec coverage.

Verification

  • python -m pytest tests/test_multi_skill.py tests/nodes/test_build_context.py tests/nodes/analyzers/test_registry.py tests/nodes/analyzers/test_structured_skill_roles.py tests/unit/test_cli.py -q - pass, 46 passed, 1 warning
  • uv run ruff check src/ tests/ - pass
  • uv run ruff format --check src/ tests/ - pass
  • CI Lint & Test (Python 3.12), Lint & Test (Python 3.13), and DCO Check - pending maintainer approval if fork checks are gated

Notes

  • This slice stops at detection and summary. Role-aware severity adjustments remain follow-up work on top of the new structured context.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant