Forge:understand

Understand

Analyze code or documentation to extract clear explanations of structure, design, and behavior.

Usage

/forge:understand [target] [--mode code|docs] [--depth quick|detailed|deep]

Arguments

| Argument | Required | Description | | ---------- | -------- | ------------------------------------------------------------------------------ | | target | Optional | File, directory, question, or instruction on what to explain (defaults to cwd) | | --mode | Optional | code or docs (default: auto-detected from target) | | --depth | Optional | quick, detailed, or deep (default: detailed) | | --output | Optional | Write result to file instead of conversation (e.g., explanation.md) |

Execution

Follow these steps in order. Do not skip steps.

Step 1: Resolve Target

$ARGUMENTS is the target. It may be a file path, directory, question, or free-form instruction. If it starts with @, strip the prefix (Claude Code file reference syntax). If $ARGUMENTS is empty, default to the current working directory.

Recognized flags (extract from $ARGUMENTS if present):

• --mode — code or docs
• --depth — quick, detailed, or deep
• --output — write result to file instead of conversation

Never ask the user to clarify. If $ARGUMENTS contains anything, proceed immediately.

Step 2: Detect Mode

If --mode was not specified, auto-detect from the target (first match wins):

| Pattern | Mode | | ------------------------------------------------------------------------------ | ---- | | *.md, *.rst, *.txt | docs | | *.py, *.ts, *.js, *.go, *.rs, *.java | code | | Path starts with docs/, design/, adr/, rfcs/ | docs | | Path starts with src/, lib/, pkg/, cmd/ | code | | README*, CLAUDE.md, CHANGELOG* | docs | | Question contains "design", "architecture", "rationale", "ADR", "why we chose" | docs | | Question contains "bug", "function", "class", "method", "how does" | code | | Default | code |

Do not ask the user -- just apply the rules.

Step 3: Load Instruction File

Do NOT start the analysis until this step is complete.

Model family: !forge session context "${CLAUDE_SESSION_ID}" --field model_family 2>/dev/null || true

Pick one instruction file (first match wins, read only one):

1. If model family is non-empty: ${CLAUDE_SKILL_DIR}/resources/{mode}-{family}.md
2. Otherwise (or if the above doesn't exist): ${CLAUDE_SKILL_DIR}/resources/{mode}.md

If model family lookup returns empty output or errors, treat it as "no family" and immediately select ${CLAUDE_SKILL_DIR}/resources/{mode}.md. Do not probe multiple variants.

Tool-call hygiene (normative)

When reading the selected instruction file, call Read with exactly one argument:

{"file_path":"/absolute/path/to/instruction-file.md"}

Rules:

• Do NOT send empty-string values for optional fields
• Do NOT include assistant-generated commentary or repair text in tool arguments

A PreToolUse hook may strip extra Read parameters (offset, limit, pages) for skill instruction files, but callers must still send Read with only file_path.

Read that one file using the Read tool with just the file_path parameter. Do not read both. If the chosen file is missing, report the path and stop.

After loading, tell the user in one message:

Analyzing {target} in {mode} mode (depth: {depth}).
  model_family: {family or "(none — using default)"}
  instruction:  {instruction_file_name}

Do not read target files or begin analysis until after you have:

1. Resolved the target
2. Resolved the mode
3. Resolved the instruction file
4. Emitted the preflight summary message

Step 4: Execute Analysis

If the selected instruction file refers to an Explore subagent, use the Agent tool with subagent_type: "Explore". Do not interpret Task in resource files as a separate tool.

If the selected instruction file mentions disallowed or unavailable tools, stop and report the mismatch instead of substituting another tool.

For depth handling inside this skill:

• quick: perform a concise local analysis using the allowed tools in this skill
• detailed: perform a fuller local analysis using the allowed tools in this skill
• deep: perform the deepest local analysis available with the allowed tools in this skill

Do not call mcp__zen__* tools from this skill.

Execute analysis following the loaded instructions with the specified depth. The instruction file defines the structure and output format -- follow it.

Depth levels:

| Depth | Output Size | Execution | | ---------- | ----------- | -------------------------------- | | quick | \<500 words | Local analysis, concise | | detailed | 500-1000 | Local analysis, fuller coverage | | deep | Full | Local analysis, maximum coverage |

When a resource file contains tool guidance that conflicts with this skill's allowed tools, this SKILL.md file wins. Do not improvise around the conflict.

Output routing: If --output was specified, write the complete explanation to that path using the Write tool (create parent directories if needed). Print a one-line confirmation: Wrote explanation to {path}. Do not also print the full result in the conversation. If --output was not specified, print the result in the conversation as usual.

Source & license

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

• Author: thomsonreuters
• Source: thomsonreuters/claude-forge
• License: Apache-2.0
• Homepage: https://pypi.org/project/tr-claude-forge/

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