执行步骤

步骤 1：检测目标类型

# 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

对于文件： 使用 bat（语法高亮）或 Read 工具直接读取。

对于目录： 使用 tokei 获取概览（如果可用）：

command -v tokei >/dev/null 2>&1 && tokei "$TARGET" --compact || echo "tokei unavailable"

对于符号（函数/类）： 使用 ast-grep 查找定义：

# 首先尝试 ast-grep（结构化搜索）
command -v ast-grep >/dev/null 2>&1 && ast-grep -p "function $TARGET" -p "class $TARGET" -p "def $TARGET"

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

步骤 2：收集上下文

尽可能并行运行以下操作：

查找使用情况（structural-search 技能）：

# 使用 ast-grep
ast-grep -p "$TARGET($_)" --json 2>/dev/null | head -20

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

查找相关文件：

# 测试文件
fd -e test.ts -e spec.ts -e test.py -e spec.py | xargs rg -l "$TARGET" 2>/dev/null

# 类型/接口文件
fd -e d.ts -e types.ts | xargs rg -l "$TARGET" 2>/dev/null

加载项目约定：

• 如果存在，读取 AGENTS.md
• 如果存在，读取 CLAUDE.md
• 检查特定框架的模式

步骤 3：路由到专家代理

根据文件扩展名和内容确定最佳专家：

通过 Task 工具调用：

Task tool with subagent_type: "[detected]-expert"
Prompt includes:
  - File content
  - Related files found
  - Project conventions
  - Requested depth and focus

步骤 4：生成解释

专家代理生成结构化的解释：

# Explanation: [target]

## Overview
[1-2 sentence summary of purpose and role in the system]

## Architecture

[Mermaid diagram - choose appropriate type]

### Flowchart (for control flow)
` ` `mermaid
flowchart TD
    A[Input] --> B{Validate}
    B -->|Valid| C[Process]
    B -->|Invalid| D[Error]
    C --> E[Output]
` ` `

### Sequence (for interactions)
` ` `mermaid
sequenceDiagram
    participant Client
    participant Server
    participant Database
    Client->>Server: Request
    Server->>Database: Query
    Database-->>Server: Result
    Server-->>Client: Response
` ` `

### Class (for structures)
` ` `mermaid
classDiagram
    class Component {
        +props: Props
        +state: State
        +render(): JSX
    }
` ` `

## How It Works

### Step 1: [Phase Name]
[Explanation with code references]

See: `src/module.ts:42`

### Step 2: [Phase Name]
[Explanation]

## Key Concepts

### [Concept 1]
[Explanation]

### [Concept 2]
[Explanation]

## Dependencies

| Import | Purpose |
|--------|---------|
| `package` | [why it's used] |

## Design Decisions

### Why [decision]?
[Rationale and tradeoffs considered]

## Related Code

| File | Relationship |
|------|--------------|
| `path/to/file.ts:123` | [how it relates] |

## See Also

- `/explain path/to/related` - [description]
- [External docs link] - [description]

深度模式

浅层示例

/explain src/auth/token.ts --shallow

输出：单个段落 + 导出列表。

深度示例

/explain src/core/engine.ts --deep

输出：完整的内部细节、算法分析、性能说明、边界情况。

追踪示例

/explain handleLogin --trace

输出：追踪数据流从入口到数据库再到响应的过程。

聚焦模式

CLI 工具集成

命令使用现代 CLI 工具，并提供优雅的回退方案：

检查可用性：

command -v tokei >/dev/null 2>&1 || echo "tokei not installed - skipping stats"

使用示例

# 解释一个文件
/explain src/auth/oauth.ts

# 解释一个函数（自动查找）
/explain validateToken

# 解释一个目录
/explain src/services/

# 深度探索，聚焦架构
/explain src/core/engine.ts --deep --focus arch

# 追踪数据流
/explain handleUserLogin --trace

# 快速概览
/explain src/utils/helpers.ts --shallow

# 聚焦依赖关系
/explain package.json --focus deps

集成

持久化

在生成重要的解释后，可能会提供以下选项：

Would you like to save this explanation?
  1. Append to ARCHITECTURE.md
  2. Append to AGENTS.md (if conventions-related)
  3. Don't save (output only)

这可以将有价值的架构知识保存在 git 跟踪的文档中。

注意事项

• 解释基于代码分析，而非文档
• 复杂系统可能需要多次调用 /explain
• 对于不熟悉的代码库，使用 --deep
• Mermaid 图表在 GitHub、GitLab、VSCode 和大多数 Markdown 查看器中均可渲染
• 专家代理提供特定框架的见解

每周安装次数

19

仓库

0xdarkmatter/claude-mods

GitHub 星标数

8

首次出现

2026年1月25日

安全审计

Gen Agent Trust HubFailSocketPassSnykFail

安装于

opencode16

gemini-cli16

claude-code16

codex15

antigravity14

cursor14

Execution Steps

Step 1: Detect Target Type

# 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):

command -v tokei >/dev/null 2>&1 && tokei "$TARGET" --compact || echo "tokei unavailable"

For symbols (function/class): Find definition with ast-grep:

# 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):

# 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:

# 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 Expert Agent

Determine the best expert based on file extension and content:

Invoke via Task tool:

Task tool with subagent_type: "[detected]-expert"
Prompt includes:
  - File content
  - Related files found
  - Project conventions
  - Requested depth and focus

Step 4: Generate Explanation

The expert agent produces a structured explanation:

# Explanation: [target]

## Overview
[1-2 sentence summary of purpose and role in the system]

## Architecture

[Mermaid diagram - choose appropriate type]

### Flowchart (for control flow)
` ` `mermaid
flowchart TD
    A[Input] --> B{Validate}
    B -->|Valid| C[Process]
    B -->|Invalid| D[Error]
    C --> E[Output]
` ` `

### Sequence (for interactions)
` ` `mermaid
sequenceDiagram
    participant Client
    participant Server
    participant Database
    Client->>Server: Request
    Server->>Database: Query
    Database-->>Server: Result
    Server-->>Client: Response
` ` `

### Class (for structures)
` ` `mermaid
classDiagram
    class Component {
        +props: Props
        +state: State
        +render(): JSX
    }
` ` `

## How It Works

### Step 1: [Phase Name]
[Explanation with code references]

See: `src/module.ts:42`

### Step 2: [Phase Name]
[Explanation]

## Key Concepts

### [Concept 1]
[Explanation]

### [Concept 2]
[Explanation]

## Dependencies

| Import | Purpose |
|--------|---------|
| `package` | [why it's used] |

## Design Decisions

### Why [decision]?
[Rationale and tradeoffs considered]

## Related Code

| File | Relationship |
|------|--------------|
| `path/to/file.ts:123` | [how it relates] |

## See Also

- `/explain path/to/related` - [description]
- [External docs link] - [description]

Depth Modes

Shallow Example

/explain src/auth/token.ts --shallow

Output: Single paragraph + exports list.

Deep Example

/explain src/core/engine.ts --deep

Output: Full internals, algorithm analysis, performance notes, edge cases.

Trace Example

/explain handleLogin --trace

Output: Traces data flow from entry to database to response.

Focus Modes

CLI Tool Integration

Commands use modern CLI tools with graceful fallbacks:

Check availability:

command -v tokei >/dev/null 2>&1 || echo "tokei not installed - skipping stats"

Usage Examples

# Explain a file
/explain src/auth/oauth.ts

# Explain a function (finds it automatically)
/explain validateToken

# Explain a directory
/explain src/services/

# Deep dive with architecture focus
/explain src/core/engine.ts --deep --focus arch

# Trace data flow
/explain handleUserLogin --trace

# Quick overview
/explain src/utils/helpers.ts --shallow

# Focus on dependencies
/explain package.json --focus deps

Integration

Persistence

After significant explanations, you may be offered:

Would you like to save this explanation?
  1. Append to ARCHITECTURE.md
  2. Append to AGENTS.md (if conventions-related)
  3. Don't save (output only)

This keeps valuable architectural knowledge in git-tracked documentation.

Notes

• Explanations are based on code analysis, not documentation
• Complex systems may need multiple /explain calls
• Use --deep for unfamiliar codebases
• Mermaid diagrams render in GitHub, GitLab, VSCode, and most markdown viewers
• Expert agents provide framework-specific insights

Weekly Installs

19

Repository

0xdarkmatter/claude-mods

GitHub Stars

8

First Seen

Jan 25, 2026

Security Audits

Gen Agent Trust HubFailSocketPassSnykFail

Installed on

opencode16

gemini-cli16

claude-code16

codex15

antigravity14

cursor14

AI新闻播客制作技能：实时新闻转对话式播客脚本与音频生成

1,200 周安装