# Explain

> Explains code/architecture with Mermaid diagrams and sequence flows. Triggers: what does X do, how does Y work, explain code, sequence diagram.

- **Type:** Skill
- **Install:** `agentstack add skill-softspark-ai-toolkit-explain`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [softspark](https://agentstack.voostack.com/s/softspark)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [softspark](https://github.com/softspark)
- **Source:** https://github.com/softspark/ai-toolkit/tree/main/app/skills/explain
- **Website:** https://softspark.eu

## Install

```sh
agentstack add skill-softspark-ai-toolkit-explain
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Explain

$ARGUMENTS

Generates visual architecture explanations.

## Output Format

### 1. High-Level Role
"This module handles [Responsibility]. It interacts with [Dependencies]."

### 2. Dependency Graph (Mermaid)
Generate a graph showing imports/exports.
```mermaid
graph TD
    A[AuthService] -->|uses| B[UserRepo]
    A -->|validates| C[Schema]
    D[Controller] -->|calls| A
```

### 3. Key Flows (Sequence)
If logical flows are detected:
```mermaid
sequenceDiagram
    User->>Controller: Login
    Controller->>Service: Validate
    Service->>DB: Check Creds
    DB-->>Service: Result
    Service-->>Controller: Token
```

## Protocol
1. **Scan**: Read file contents to identify classes and functions.
2. **Link**: Identify imports to find collaborators.
3. **Visualize**: Generate standard Mermaid syntax.

## Automated Dependency Graph

Run the bundled script to extract imports and generate a Mermaid diagram:

```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/dependency-graph.py src/auth.py
```

## Rules

- **MUST** start from what the user already knows — if it is unclear, ask one question before explaining
- **MUST** ground the explanation in the actual code (file:line references), not in generic framework theory
- **NEVER** use an analogy when a direct definition is clearer — analogies add a translation step for the reader
- **NEVER** produce a diagram that the text does not already justify — diagrams illustrate, they do not replace the explanation
- **CRITICAL**: when the code base is large, scope the explanation to one entry point plus its immediate collaborators. Explaining "the whole system" in one pass fails for any non-trivial project.
- **MANDATORY**: if the user asks for a short answer, give a one-paragraph summary without diagrams — not every request needs a Mermaid graph

## Gotchas

- Mermaid renders differently across GitHub, VS Code preview, and static generators. Features added post-2023 (e.g., class diagram relations, `accTitle`) may render as raw text on older renderers. Stick to the basic subset unless you know the target.
- `dependency-graph.py` parses imports statically; dynamic imports (`__import__`, `importlib.import_module`, JavaScript `await import()`) are invisible. Note explicitly when the generated graph is likely incomplete.
- Sequence diagrams have no notion of async vs sync. Two parallel calls render as sequential; distinguish with a `par` block or a note.
- Architectural explanations that name "the service layer" or "the controller" leak framework jargon. If the project does not use those terms, use the project's own names — otherwise the reader is translating twice.
- Long Mermaid graphs wrap awkwardly on narrow screens. For >20 nodes, split into a high-level graph and drill-down graphs rather than one giant diagram.

## When NOT to Use

- To critique or improve the code — use `/review` or `/refactor`
- To find a specific function across the codebase — use `/explore` or `Grep`
- To write the documentation that the explanation turns into — use `/docs`
- For a full architecture audit or redesign — use `/architecture-audit`
- When the user asks "why is this broken" — use `/debug`, not `/explain`

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [softspark](https://github.com/softspark)
- **Source:** [softspark/ai-toolkit](https://github.com/softspark/ai-toolkit)
- **License:** MIT
- **Homepage:** https://softspark.eu

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-softspark-ai-toolkit-explain
- Seller: https://agentstack.voostack.com/s/softspark
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.