# Code To Uml

> Use when generating, updating, repairing, validating, or reviewing Code-To-UML .ctu/HTML source-analysis reports for a project, module, file, class, function, existing report, or validator/rendering failure.

- Skill: `pingwurth/code-to-uml` (Agent Skill, multi-file: 33 files)
- Install (CLI): `npx skillmds@latest add pingwurth/code-to-uml`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pingwurth/code-to-uml/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: pingwurth (https://skillmd.com/u/pingwurth)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pingwurth/code-to-uml

---


# Code-To-UML Reports

## Core Rule

Generate, update, repair, validate, or review source-grounded Code-To-UML `.ctu`/HTML reports.
Analyzed source is read-only unless the user asks for code changes. Keep report content in `.ctu` data files, keep HTML as a thin data-driven shell, and add UML only when it reduces reader effort.

## Absolute Path Rule

- Resolve `CTU_SKILL_ROOT` to the absolute directory containing this `SKILL.md` before reading skill resources or running skill scripts.
- Resolve `CTU_HOME` to the absolute Code-To-UML root before reading templates, writing artifacts, validating reports, or starting the server. Treat `$CTU_HOME` in this skill as a resolved logical variable; it does not have to exist as a pre-set environment variable.
- Treat every `$CTU_SKILL_ROOT/...` and `$CTU_HOME/...` path in this document as absolute because both root variables must contain absolute paths.
- Do not use bare relative paths, `.` paths, `..` paths, or commands whose meaning depends on the shell working directory.

## CTU_HOME Bootstrap

Resolve `CTU_HOME` before choosing output paths or running any command. Never fail only because the environment variable is unset.

A valid Code-To-UML root must contain all project sentinels: `$CTU_HOME/cache/_TEMPLATE.html`, `$CTU_HOME/data/_TEMPLATE.ctu`, `$CTU_HOME/demo.html`, and `$CTU_HOME/serve.js`. Use the first valid absolute candidate from this ordered list:

1. An explicit user-provided Code-To-UML root path.
2. The repository that bundles this skill: when `CTU_SKILL_ROOT` ends with `skills/code-to-uml`, test `dirname(dirname(CTU_SKILL_ROOT))`.
3. The `CTU_HOME` environment variable, if set.
4. The current shell working directory, then each ancestor of it.
5. The nearest ancestor of any explicit report HTML, data, template, or output path in the request.

After selecting the root, store it as an absolute local variable for every command and pass it explicitly as `--root "$CTU_HOME"` to validators. Do not rely on environment variables persisting between tool calls. If multiple valid candidates conflict, use the explicit user-provided root first; otherwise prefer the `CTU_SKILL_ROOT`-derived repository root and mention the mismatch.

Only ask the user to run `node install.js` or provide a root after all candidates fail. When that happens, report the candidates checked and which sentinel files were missing.

## Mode Picker

Choose the mode before reading references or changing files.

| User intent | Mode | Writes | Required references | Validation |
| --- | --- | --- | --- | --- |
| New comprehensive project/module/file report, or explicit "full" request | Full report | Yes | `$CTU_SKILL_ROOT/references/report-contract.md`, `$CTU_SKILL_ROOT/references/code-to-uml-template.md`, and absolute diagram/UML reference paths as needed | `--mode full` |
| Narrow function/class/small file report, or explicit "compact" request | Compact report | Yes | `$CTU_SKILL_ROOT/references/report-contract.md`, `$CTU_SKILL_ROOT/references/code-to-uml-template.md`, and absolute diagram/UML reference paths as needed | `--mode compact` |
| Refresh an existing report | Update existing report | Yes | Existing report plus refs for changed surfaces | Existing mode, usually `--mode full` or `--mode compact` |
| Validator, artifact, PlantUML, or runtime failure | Fix validation/rendering | Yes | Failing artifact plus relevant contract/script | Reproduce and rerun the failing command |
| Inspect a skill, report, or artifact | Review only | No unless asked | File under review; refs only for checked claims | Optional |

## Defaults

- Target: resolve "this project/current repo" to the current repository's absolute root path with scope `project`.
- Scope: infer `module` from a directory, `file` from a source file, and `function`/`class` from an explicit symbol when structural tools can resolve it.
- Report language: use the user's language; use `zh` for Chinese-dominant requests and `en` for English-dominant requests.
- Report mode: explicit user mode wins; otherwise use compact for small functions/classes/low-complexity files, full for project/module/file or comprehensive requests.
- Output path: if omitted for generated HTML, use `$CTU_HOME/cache/<target-slug>_analysis.html`.
- CTU root: always use the `CTU_HOME Bootstrap` algorithm above and keep the result absolute.
- Relative output paths requested by the user are always relative to the resolved CTU root and must immediately become absolute `$CTU_HOME/...` paths, never the analyzed repository cwd, skill directory, or shell cwd.
- An output path outside the resolved CTU root is allowed only when the user explicitly provides an absolute path and clearly requests external placement.
- Ask only when the target/action cannot be inferred safely, multiple targets match, or an existing report cannot be mapped to source/data.

Before generating artifacts, state the resolved absolute CTU root and absolute HTML/data output paths.

## Required Workflow

1. Resolve mode, target, scope, language, CTU root, output paths, and read-only constraints. Normalize every relative artifact path against the CTU root before any write.
2. Read local project instructions, then only the required references from the Reference Map.
3. Analyze source structurally first for definitions, callers, callees, signatures, impact, and subsystem boundaries; use `rg` and focused reads for literal text and snippets.
4. Classify complexity from `$CTU_SKILL_ROOT/references/report-contract.md`, then plan cards from real target mechanisms rather than minimum card counts.
5. Generate or update `$CTU_HOME/data/<report-slug>/` `.ctu` files and a template-based HTML shell under `$CTU_HOME/cache/` unless the user gave an explicit path.
6. Validate with `$CTU_SKILL_ROOT/scripts/validate-report.js` using the selected mode, scope, complexity, language, and `--strict`.
7. For HTML reports, provide a browser URL when runtime behavior is relevant or the user expects one. Start the server only when needed for runtime/API/topbar verification.

## Non-Negotiable Checks

- Preserve template structure, data conventions, CSS/JS dependencies, script order, `[FIXED]` selectors, and allowed `[EDIT]` / `[CONFIG]` boundaries.
- Before writing, verify that normalized HTML and data paths are under the resolved CTU root unless the user explicitly requested an absolute external path.
- Write generated HTML and `.ctu` files as valid UTF-8; do not rely on Windows shell-default encoding.
- The report language must match the user's question language unless the user explicitly requests another language.
- Use real target-specific content for every required `Section-ID: Sxx_...`; never use section markers as placeholders.
- `S13_MAINTAINER_REFERENCE` must be a Markdown table, not prose or bullets.
- `[Description]` and `[Detail]` must use Markdown structures that fit the content: paragraphs, bullet lists, numbered steps, indentation, and Markdown tables.
- Break lines when content contains sentence-ending punctuation such as periods and semicolons; do not hard-wrap prose by visual length.
- Full reports must pass coverage and depth. Large or multi-subsystem targets use `--complexity high` and cover all major subsystems.
- Compact reports may merge sections, but each merged ID must include concrete evidence or a clear reason no separate content exists.
- The intro `<p data-markdown>` is a concise whole-report Markdown overview, not a category overview.
- Text must carry the analysis; diagrams are optional and every non-empty `[UML]` block needs useful `[Detail]`.
- Ground claims in concrete source evidence: paths, symbols, constants, routes, commands, side effects, failure paths, line/symbol references, or explicitly marked inference.
- Handle topbar links deliberately: keep truthful, replace truthfully, or remove the whole link.
- Add `--render` only when both Java and `$CTU_HOME/plantuml.jar` are available; otherwise state that render validation was skipped.

## Reference Map

| Need | Read/use |
| --- | --- |
| Section catalog, scope applicability, complexity, quality gates, final response shape | `$CTU_SKILL_ROOT/references/report-contract.md` |
| HTML shell, `.ctu` syntax, path/category/runtime contract | `$CTU_SKILL_ROOT/references/code-to-uml-template.md` |
| Whether a diagram is useful and which type to choose | `$CTU_SKILL_ROOT/references/diagram-decision-table.md` |
| Authoring or checking non-empty PlantUML blocks | `$CTU_SKILL_ROOT/references/uml-standards.md` |
| Artifact/content/runtime validation | `$CTU_SKILL_ROOT/scripts/validate-report.js` |
| Validator or report-contract changes | `$CTU_SKILL_ROOT/scripts/validate-fixtures.js` and `$CTU_SKILL_ROOT/fixtures/` |

For review-only requests, do not load every reference by default. Read the file under review first, then load only the reference that owns the claim being checked.

## Validation Command

Use this shape for generated or updated HTML reports:

```bash
node "$CTU_SKILL_ROOT/scripts/validate-report.js" \
  --root "$CTU_HOME" \
  --html "$CTU_HOME/cache/<report-file>.html" \
  --lang <zh|en> \
  --scope <project|module|file|class|function> \
  --complexity <low|medium|high> \
  --mode <compact|full> \
  --strict
```

Add `--render` only when Java and `$CTU_HOME/plantuml.jar` are available.
After changing the validator or report contract, run:

```bash
node "$CTU_SKILL_ROOT/scripts/validate-fixtures.js"
```

## Completion

For generated/updated reports, return the concise final status from `$CTU_SKILL_ROOT/references/report-contract.md`: HTML path, template reuse status, split-file decision, validation/PlantUML result, section summary, and browser URL when runtime validation was performed or expected.
For review-only or partial work, state the validation scope and any runtime or render checks not performed.