explain

Files (4)

• SKILL.md
• .gitkeep · assets/
• .gitkeep · references/
• .gitkeep · scripts/

SKILL.md (first lines)

# Explain - Deep Code Explanation

Get a comprehensive explanation of code, files, directories, or architectural concepts. Automatically dispatches a general-purpose agent preloaded with the most relevant `-ops` skill and uses modern CLI tools for analysis.

## Arguments

$ARGUMENTS

- `<target>` - File path, function name, class name, directory, or concept
- `--depth <shallow|normal|deep|trace>` - Level of detail (default: normal)
- `--focus <arch|flow|deps|api|perf>` - Specific focus area

## Architecture

```
/explain <target> [--depth] [--focus]
    |
    +-> Step 1: Detect & Classify Target
    |     +- File exists? -> Read it
    |     +- Function/class? -> ast-grep to find definition
    |     +- Directory? -> tokei for overview
    |     +- Concept? -> rg search codebase
    |
    +-> Step 2: Gather Context (parallel)
    |     +- structural-search skill -> find usages
    |     +- code-stats skill -> assess scope
    |     +- Find related: tests, types, docs
    |     +- Load: AGENTS.md, CLAUDE.md conventions
    |
    +-> Step 3: Route to Explainer (general-purpose + skill preload)
    |     +- .ts/.tsx -> general-purpose, preload typescript-ops or react-ops
    |     +- .py -> general-purpose, preload python-* skill by topic
    |     +- .vue -> general-purpose, preload vue-ops
    |     +- .sql/migrations -> general-purpose, preload postgres-ops
    |     +- agents/skills/commands -> general-purpose, preload claude-code-ops
    |     +- Default -> general-purpose
    |     +- All explainers preload: debug-ops (systematic analysis)
    |
    +-> Step 4: Generate Explanation
    |     +- Structured markdown with sections
    |     +- Mermaid diagrams (flowchart/sequence/class)
    |     +- Related code paths as file:line refs
    |     +- Design decisions and rationale
    |
    +-> Step 5: Integrate
          +- Offer to save to ARCHITECTURE.md (if significant)
          +- Link to /save if working on related task
```

## Execution Steps

### Step 1: Detect Target Type

```bash
# Check if target is a file
test -f "$TARGET" && echo "FILE" && exit

# Check if target is a directory
test -d "$TARGET" && echo "DIRECTORY" && exit

# Otherwise, search for it as a symbol
```

**For files:** Read directly with bat (syntax highlighted) or Read tool.

**For directories:** Get overview with tokei (if available):
```bash
command -v tokei >/dev/null 2>&1 && tokei "$TARGET" --compact || echo "tokei unavailable"
```

**For symbols (function/class):** Find definition with ast-grep:
```bash
# Try ast-grep first (structural)
command -v ast-grep >/dev/null 2>&1 && ast-grep -p "function $TARGET" -p "class $TARGET" -p "def $TARGET"

# Fallback to ripgrep
rg "(?:function|class|def|const|let|var)\s+$TARGET" --type-add 'code:*.{ts,tsx,js,jsx,py,vue}' -t code
```

### Step 2: Gather Context

Run these in parallel where possible:

**Find usages (structural-search skill):**
```bash
# With ast-grep
ast-grep -p "$TARGET($_)" --json 2>/dev/null | head -20

# Fallback
rg "$TARGET" --type-add 'code:*.{ts,tsx,js,jsx,py,vue}' -t code -l
```

**Find related files:**
```bash
# Tests
fd -e test.ts -e spec.ts -e test.py -e spec.py | xargs rg -l "$TARGET" 2>/dev/null

# Types/interfaces
fd -e d.ts -e types.ts | xargs rg -l "$TARGET" 2>/dev/null
```

**Load project conventions:**
- Read AGENTS.md if exists
- Read CLAUDE.md if exists
- Check for framework-specific patterns

### Step 3: Route to Explainer

Dispatch is skills-first: the generic `general-purpose` subagent preloads the relevant `-ops` skill based on file extension and content:

| Pattern | Dispatch | Preload | Condition |
|---------|----------|---------|-----------|
| `.ts` | general-purpose | `skills/typescript-ops/SKILL.md` | No JSX/React imports |
| `.tsx` | general-purpose | `skills/react-ops/SKILL.md` | JSX present |
| `.js`, `.jsx` | general-purpose | `skills/javascript-ops/SKILL.md` | - |
| `.py` | general-purpose | relevant `skills/python-*/SKILL.md` by topic | - |
| `.vue` | general-purpose | `skills/vue-ops/SKILL.md` | - |
| `.sql`, `migrations/*` | general-purpose | `skills/postgres-ops/SKILL.md` | - |
| `agents/*.md`, `skills/*`, `commands/*` | general-purpose | `skills/claude-code-ops/SKILL.md` | Claude extensions |

From 0xDarkMatter/claude-mods, MIT.

More from 0xDarkMatter/claude-mods