explain_skill

Overview

This skill provides deep, structured explanations of code, files, directories, symbols, or architectural concepts. It routes requests to the most relevant expert agent, gathers context with structural search and project heuristics, and produces readable outputs that include mermaid diagrams and concrete code references. Use depth and focus flags to control granularity and analysis scope.

How this skill works

The skill first detects the target type (file, directory, or symbol) and reads or locates definitions using CLI tools. It gathers context in parallel: structural searches for usages, nearby tests and types, and project conventions. Next it selects an expert agent by file type or pattern and runs a focused analysis. The final output is a structured explanation with diagrams, code references, design rationale, and suggestions for follow-up actions.

When to use it

• You need a clear, human-readable explanation of unfamiliar code or a specific function/class.
• Assess architecture, module boundaries, or data/control flow across a codebase.
• Identify dependencies, integration points, or potential performance bottlenecks.
• Prepare documentation or architecture notes to share with teammates.
• Trace a runtime path or request flow from entry point to persistence or external services.

Best practices

• Start with --depth normal for a balanced overview, use --deep or --trace for full internals or end-to-end flow.
• Use --focus to constrain analysis (arch, flow, deps, api, perf) when you have a specific goal.
• Point the tool at a narrow target (file or symbol) for precise diagrams and references; use directory targets for broad summaries.
• Run structural searches in the same codebase to get accurate cross-file references and test coverage.
• Save important outputs to project docs when the explanation captures lasting architectural decisions.

Example use cases

• Explain a backend module to onboard a new engineer: /explain src/core/engine.ts --deep --focus arch
• Trace a bug by following a login request: /explain handleLogin --trace
• Generate a concise overview of a utilities directory before refactoring: /explain src/utils --depth shallow
• Audit package.json and imports for risky dependencies: /explain package.json --focus deps
• Produce a sequence diagram for a client-server interaction to include in design notes.