Plugin Visual

Agent Extension Visual

Analyze agent extensions and generate self-contained HTML wiki reports (or inline markdown) with security audit and plugin profiles. Currently supports Claude Code plugins.

Instructions

Input Parsing

Determine the analysis target from the user's message:

1. Path contains / → local path (resolve relative to cwd)
2. Contains github.com or https:// → GitHub URL
3. Other text → installed plugin name (search ~/.claude/plugins/cache/)
4. Nothing specified → current directory (scan .claude/, CLAUDE.md, plugins/)

For GitHub URLs, support subpath patterns:

• github.com/owner/repo → clone entire repo
• github.com/owner/repo/tree/branch/plugins/foo → clone repo, analyze subpath only

Language Detection

Determine the output language:

1. Explicit language argument: --lang (e.g., --lang ko, --lang fr, --lang zh) → use that language. Any language code is valid
2. User message text: Detect the language of the message (excluding URL/path) and match it

• Examples: Korean text → Korean, Japanese text → Japanese, "en español" → Spanish, "auf Deutsch" → German

1. URL only with no other text: Use AskUserQuestion to ask the user's preferred language

Pass the detected language to sub-agents and use it for Phase 5 report assembly.

Analysis Mode Detection

Determine what to analyze:

| Mode | Trigger Keywords | Scope | |------|-----------------|-------| | analyze (default) | "analyze", "inspect", "report", "wiki", "document" | Full analysis and Plugin Profile | | security | "security audit", "permission analysis" | Security only | | overview | "overview", "summary" | Identity + inventory only |

Output Format Detection

Determine how to present the result (independent of analysis mode):

| Format | Trigger | Applies to | |--------|---------|------------| | HTML (default) | Default for analyze mode | analyze only | | Inline markdown | "--format md", "markdown", "md", "inline", "text" | analyze only | | Inline markdown (always) | — | security, overview (too brief for HTML) |

Intent Check

Why: An analysis for potential users focuses on capabilities and compatibility; an analysis for security reviewers focuses on permissions and risk. The audience shapes emphasis across all report sections.

If the user's message already conveys clear intent (e.g., "security audit", "is this plugin safe", or a specific analysis mode keyword), skip this step.

If the request is ambiguous (e.g., just a plugin path with no other context), use AskUserQuestion to ask up to 2 questions:

1. Audience: Who will read this? (yourself, your team, plugin marketplace reviewers)
2. Focus: Any specific concern? (security, architecture, compatibility, general overview)

Defaults:

• Audience: the user themselves (evaluating the plugin)
• Focus: balanced full analysis

Pass audience and focus context to the analysis and report generation phases.

Workflow

Phase 1: Source Acquisition

• Local path: Verify directory exists, proceed directly
• Installed plugin: Search ~/.claude/plugins/cache/ for matching directory
• GitHub URL: Clone to /tmp/plugin-visual-{dirname}:

1. Generate {dirname} — pick any 8-character hex string yourself (e.g., a1b2c3d4)
2. Clone directly (no mkdir needed — git creates the target directory):

`` Bash(gh repo clone {owner/repo} /tmp/plugin-visual-{dirname}) ` This is the only Bash command needed for cloning. Do not add extra commands for saving state or generating random strings. For subpath URLs (github.com/owner/repo/tree/branch/plugins/foo`):

1. Extract owner/repo for cloning
2. Extract the subpath after /tree/{branch}/ (e.g., plugins/foo)
3. Clone the full repo, then set the analysis target to the subpath within the clone

• Current directory: Use cwd

If source cannot be found, inform user and stop.

Source context — save for later phases (source links in report):

| Source type | source_type | source_base | github_url | |-------------|--------------|---------------|-------------| | Local path | local | {absolute-path} | — | | Installed plugin | local | {cache-path} | — | | GitHub URL (root) | github | /tmp/plugin-visual-{dirname} | https://github.com/{owner}/{repo}/blob/{branch} | | GitHub URL (subpath) | github | /tmp/plugin-visual-{dirname}/{subpath} | https://github.com/{owner}/{repo}/blob/{branch}/{subpath} |

When cloning a subpath URL (e.g., github.com/owner/repo/tree/main/plugins/foo), include the subpath in both source_base and github_url so that relative paths from the plugin root produce correct source links.

Phase 2: Discovery

Why: Accurate component inventory prevents analysis agents from missing or hallucinating plugin components.

Scan the target directory for all plugin components.

Step 1: Run 3 Glob calls in parallel (single message):

| # | Pattern | Captures | |---|---------|----------| | 1 | **/*.md | SKILL.md, agent .md, command .md, CLAUDE.md, README.md, CHANGELOG.md | | 2 | **/*.json | plugin.json, hooks.json, .mcp.json, .lsp.json, settings.json | | 3 | LICENSE* | License files |

Step 2: If Glob results are sparse ( 15)** — split feature-architect into batches.

Count total = skills + agents + commands. Split each type in half:

S = number of skills, A = number of agents, C = number of commands

Task(subagent_type: "vision-powers:feature-architect", prompt: {
  skills 1..ceil(S/2) + agents 1..ceil(A/2) + commands 1..ceil(C/2)
})
Task(subagent_type: "vision-powers:feature-architect", prompt: {
  skills ceil(S/2)+1..S + agents ceil(A/2)+1..A + commands ceil(C/2)+1..C + MCP + LSP
})
Task(subagent_type: "vision-powers:security-auditor", prompt: {all file paths})

MCP, LSP, hooks, and rules are lightweight — keep them in Batch 2 only. All three tasks run in parallel. Merge feature-architect batch results before Phase 5.

**For analyze mode with standard plugins (total components to . No visual template, no intermediate JSON, no agent chains: the design is yours to author from scratch. (The md mode's report-template.md` is an information-structure schema for the inline-markdown path, not a visual template — it doesn't apply here.)

1. Determine output path:

Default output path: ${CLAUDE_PLUGIN_DATA}/reports/{YYYY-MM-DD}-{plugin-name}-report.html

Where:

• {YYYY-MM-DD} is today's date
• {plugin-name} is from plugin.json name field (or directory name if no plugin.json)

Existing report check: Before generating, use Glob to search for *-{plugin-name}-report.html in ${CLAUDE_PLUGIN_DATA}/reports/. If any exist, use AskUserQuestion to let the user choose between creating new or updating existing.

2. Write the HTML report:

Include all analysis data from Phase 4 (feature-architect + security-auditor) and Phase 4.5 (environment fit diagnosis). The report should contain these sections (adapt based on analysis results):

| Section | Content | |---|---| | Identity & Overview | Plugin name, version, author, description, component inventory chart | | Architecture | Component map diagram — skills, agents, commands, hooks, MCP connections | | Feature Deep Dive | Per-component analysis from feature-architect | | Security Audit | Risk summary, permission matrix, findings from security-auditor | | Environment Fit | Verdict, context budget, overlap, hook impact from Phase 4.5 | | Skill Design Quality | Category distribution, per-skill assessment from feature-architect | | Plugin Profile | Maturity, documentation, quality checklist | | Recommendations | Grouped by priority |

Skip sections with no data (e.g., no security findings → slim security section).

Diagrams: Read these reference files for implementation:

• ${CLAUDE_PLUGIN_ROOT}/references/design-system/mermaid-patterns.md — Mermaid syntax, theming, dark mode, zoom
• ${CLAUDE_PLUGIN_ROOT}/references/design-system/semantic-tokens.md — Color/font roles, Mermaid themeVariables
• ${CLAUDE_PLUGIN_ROOT}/references/design-system/diagram-type-selection.md — 13-type selection guide
• ${CLAUDE_PLUGIN_ROOT}/references/design-system/diagram-density-rules.md — Complexity budgets

Key diagram rules (always apply):

1. Max 9 nodes, 12 arrows per diagram. Over budget → split
2. 1-2 focal accents only
3. No rgba() or color: in Mermaid classDef — parser breaks
4. No violet/fuchsia "AI purple" hexes (#8b5cf6/#7c3aed/#a78bfa/#d946ef) — the gate fails on these
5. Always theme: 'base' with themeVariables from semantic-tokens
6. Architecture diagrams with 15+ components → show 3-5 representatives per layer with total counts, keep under 25 nodes

The gate also fails on dead links, alt-less images, and leftover scaffolding: give every ` a real href, every an alt (alt="" if decorative), and leave no {{ }}/lorem/[STUB]` placeholders.

CSS essentials: Write your own CSS inline. Must support:

• prefers-color-scheme: dark via CSS custom properties
• Korean font stack (CJK font in font-family)
• transform: scale() for Mermaid zoom (not zoom property)
• min-width: 0 on flex/grid children
• prefers-reduced-motion: reduce
• Status indicators: colored dots via CSS, no emoji

Source links: When source_type is github, make file paths clickable with {github_url}/{relative-path} links. For local sources, use file:// URLs.

Content integrity: All analysis data from sub-agents must survive intact in the report — specific numbers, finding details, risk levels, recommendations. If you're writing "the security audit found issues" instead of listing the actual findings — that's compression.

This cardinal rule (call it summary-leak) is one of seven authoring reflexes that pass every mechanical gate and still flatten the output. Read ${CLAUDE_PLUGIN_ROOT}/references/design-system/anti-slop-tells.md for the full catalogue — linear dump, forced diagram, generic label, uniform density, empty decoration, accent overuse. They're named defaults to break, not design rules: layout and taste stay yours, the catalogue just flags the habits worth resisting (e.g. a forced flowchart on a flat permission list, or every section — security, architecture, dependency map — rendered at the same weight).

3. Validate: Run artifact-gate after writing:

node ${CLAUDE_PLUGIN_ROOT}/scripts/artifact-gate.js 

If violations found: fix inline, max 2 retries.

4. Visual self-audit (HTML only):

The gate reads the HTML as text — it never sees the rendered picture. An architecture or dependency-map diagram can pass the density check and still render as an unreadable tangle; a long permission-matrix label can clip at the container edge; the security/architecture/profile hierarchy that reads fine in source can collapse into a flat wall once styled. After the gate passes, render the report and look at it before delivering:

node ${CLAUDE_PLUGIN_ROOT}/scripts/render-report.js 

On success it prints a PNG path. Read that PNG (you read images multimodally) and scan it for what the text gate can't judge:

• Density — is any section a uniform grey wall, or is the architecture/dependency diagram past its budget and unreadable?
• Hierarchy — does anything draw the eye first, or are the security, architecture, and component-map sections all the same weight? (see uniform density / accent overuse in anti-slop-tells.md)
• Mermaid integrity — did the component map or security diagram render as raw `` text or as crossing/overlapping edges?
• Overflow — does a diagram, permission matrix, or label run past its container or off the page?

Fix what you see and re-render. Cap at 2 audit passes — if something still looks off after the second, ship with a one-line note to the user rather than looping. This catches gross breakage, not pixel-perfection.

If Chrome is absent, render-report.js exits 1 (non-zero). Skip the audit and tell the user it was skipped (e.g. "rendered-image check skipped: Chrome not found — set CHROME_BIN or install Chrome"). The report already passed the gate; the visual pass is an enhancement and never blocks delivery.

Full procedure, limits (fixed-height clipping, downscaling, render cost), and the rationale for not mechanizing this with a measurement script live in ${CLAUDE_PLUGIN_ROOT}/references/design-system/visual-self-audit.md.

5. Open and present: Run open . Tell the user the report is ready and ask if they want changes.

Phase 7: Cleanup

Clean up temporary files:

Bash(rm -rf /tmp/plugin-visual-{dirname}-sections)

If the source was also cloned from GitHub:

Bash(rm -rf /tmp/plugin-visual-{dirname})

After cleanup, suggest optional next steps:

• /fact-check — verify the report's factual accuracy against the actual codebase
• /report-manager refine — refine specific sections based on feedback
• --verify — if not used this time, mention that coherence review is available for future runs

This is informational — just a brief suggestion, not an automatic invocation.

Gotchas

• GitHub URL analysis requires gh CLI: gh repo clone is used for source acquisition from GitHub URLs. If gh is not installed or not authenticated, GitHub URL analysis will fail. Local path and installed plugin analysis work without gh.
• $() command substitution triggers security prompt: The Bash(echo $(date)) pattern causes Claude Code to show a separate permission dialog regardless of allowed-tools. Use literal values or Bash(date) with separate processing instead.
• GitHub rate limiting: gh repo clone and gh api calls can fail silently with HTTP 403 when the user's token is rate-limited. If clone fails, check gh auth status before retrying.
• Plugin cache has multiple versions: ~/.claude/plugins/cache/ stores every installed version (e.g., 2.6.0/, 2.7.1/). Phase 4.5 uses the session context directly (not cache scanning), but if you ever need to inspect the cache manually, always pick the latest version per plugin to avoid counting stale entries.
• Large plugin batching threshold: The 15-component threshold for splitting feature-architect is approximate. Plugins with many small commands but few skills may not need splitting, while plugins with 10 dense skills might. Use judgment — the goal is keeping each agent under context limits.
• Existing report overwrite prompt: The "create new or update" prompt uses AskUserQuestion. If the user is running non-interactively or in a pipeline, this blocks. Default to "create new" if no user response is available.
• Temp directory collision: The 8-char hex {dirname} has a negligible collision risk, but if a previous run crashed without cleanup, /tmp/plugin-visual-* directories may linger. The cleanup phase handles the current run only — it does not garbage-collect stale dirs.
• Skill category misclassification: Skills that span multiple categories (e.g., a deploy skill with review features) should be classified by primary purpose — what the user invokes it for. Don't try to assign multiple categories; pick the best fit and note the overlap in the description.
• Design quality false negatives: A skill with no scripts/ directory isn't necessarily "Basic" — some skills genuinely don't need scripts (pure knowledge/reference skills). Apply the N/A classification for criteria that don't apply to the skill type.
• New hook events: The security-auditor knows about 22 hook events as of 2026-03. If new events are added to Claude Code, the event list in security-rules.md and security-auditor.md may need updating.
• Plugin agent ignored frontmatter fields: permissionMode, hooks, mcpServers are silently ignored on plugin agents. The fields effort, model, tools, disallowedTools, maxTurns, skills, `m

…

Source & license

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

• Author: LeeJuOh
• Source: LeeJuOh/claude-code-zero
• License: MIT

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