// Context-efficient codebase exploration using AST analysis. Use when exploring Kosmos architecture, understanding code structure, or preparing documentation for AI programmers. Triggers: xray, map structure, skeleton, interface, architecture, explore kosmos, warm start, token budget, context compression.
| name | kosmos-xray |
| description | Context-efficient codebase exploration using AST analysis. Use when exploring Kosmos architecture, understanding code structure, or preparing documentation for AI programmers. Triggers: xray, map structure, skeleton, interface, architecture, explore kosmos, warm start, token budget, context compression. |
Specialized tools for analyzing the Kosmos codebase efficiently within limited context windows. Uses AST parsing to extract structural information (classes, methods, signatures) without loading implementation details, achieving ~95% token reduction.
The skeleton extractor now captures:
name: str = Field(...) visible in output@dataclass, @property, @tool shown above definitionsCONFIG_VAR = "value" at module level# L{line} for navigationIMPORTANT: Always use these features when exploring - they reveal data structures that would otherwise appear as empty pass statements.
Shows file tree with token estimates. Identifies context hazards (large files).
# Map entire project
python .claude/skills/kosmos-xray/scripts/mapper.py
# Map specific directory
python .claude/skills/kosmos-xray/scripts/mapper.py kosmos/workflow/
# Get summary only (no tree) - RECOMMENDED FIRST STEP
python .claude/skills/kosmos-xray/scripts/mapper.py --summary
# JSON output for parsing
python .claude/skills/kosmos-xray/scripts/mapper.py --json
Extracts Python file skeletons via AST. Now shows Pydantic fields, decorators, constants, and line numbers.
# Single file skeleton (includes line numbers by default)
python .claude/skills/kosmos-xray/scripts/skeleton.py kosmos/workflow/research_loop.py
# Directory with pattern filter
python .claude/skills/kosmos-xray/scripts/skeleton.py kosmos/ --pattern "**/base*.py"
# Filter by priority (critical, high, medium, low) - USE THIS FOR ONBOARDING
python .claude/skills/kosmos-xray/scripts/skeleton.py kosmos/ --priority critical
# Include private methods (_method) for internal understanding
python .claude/skills/kosmos-xray/scripts/skeleton.py kosmos/agents/ --private
# Omit line numbers if not needed
python .claude/skills/kosmos-xray/scripts/skeleton.py kosmos/config.py --no-line-numbers
# JSON output for programmatic use
python .claude/skills/kosmos-xray/scripts/skeleton.py kosmos/models/ --json
What skeleton.py reveals:
# Before (old behavior): Data models appeared empty
class Hypothesis(BaseModel):
pass
# After (enhanced): Full data structure visible
@dataclass
class PaperAnalysis: # L34
paper_id: str # L36
executive_summary: str # L37
confidence_score: float # L42
Maps import relationships between modules. Identifies architectural layers and circular dependencies.
# Analyze dependencies (text output)
python .claude/skills/kosmos-xray/scripts/dependency_graph.py kosmos/
# With root package name (recommended)
python .claude/skills/kosmos-xray/scripts/dependency_graph.py kosmos/ --root kosmos
# Focus on specific area
python .claude/skills/kosmos-xray/scripts/dependency_graph.py kosmos/ --focus workflow
# Generate Mermaid diagram for documentation - USE FOR WARM_START.md
python .claude/skills/kosmos-xray/scripts/dependency_graph.py kosmos/ --root kosmos --mermaid
# Combined: Mermaid focused on workflow
python .claude/skills/kosmos-xray/scripts/dependency_graph.py kosmos/ --root kosmos --mermaid --focus workflow
# JSON output
python .claude/skills/kosmos-xray/scripts/dependency_graph.py kosmos/ --json
mapper.py --summary to see codebase size and large filesskeleton.py --priority critical to see core interfaces WITH FIELDSdependency_graph.py --mermaid for visual map--priority critical first to understand core architecture--mermaid output for documentation diagrams--private when understanding internal agent behaviorThis skill is automatically loaded by the kosmos_architect agent. You can also use it directly for targeted analysis.
# Use the agent for full onboarding documentation (uses ALL features)
@kosmos_architect generate
# Or use individual tools directly
@kosmos-xray Map the workflow directory
configs/ignore_patterns.json - Directories and files to skipconfigs/priority_modules.json - Module priority levels and patterns| Operation | Typical Tokens | Use When |
|---|---|---|
| mapper.py --summary | ~500 | First exploration |
| mapper.py full | ~2-5K | Understanding structure |
| skeleton.py (1 file) | ~200-500 | Understanding interface |
| skeleton.py --priority critical | ~5K | Core architecture |
| dependency_graph.py text | ~2-3K | Architecture analysis |
| dependency_graph.py --mermaid | ~500 | Documentation diagrams |
| Full file read | Varies | Need implementation details |
For detailed API documentation, see reference.md. For quick command reference, see CHEATSHEET.md.