plugin-visual

Analyze agent extensions and generate self-contained HTML wiki reports with security audit and architecture diagrams. Use when asked to analyze, audit, or document a plugin. Triggers on GitHub plugin URLs or local plugin paths.

Jump to install

Repository: aibot88/sec_skill_store
Last source activity: May 27, 2026 at 03:47
Detected SKILL.md language: English
Stars: 3
Forks: 0

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

A direct command skips the review prompt. Inspect the source before running it.

npx skills add https://github.com/aibot88/sec_skill_store --skill plugin-visual

The command stays on one line. Scroll horizontally to inspect it before copying.

Prefer a local copy? Download the files currently available to SkillsMP.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

File Explorer

2 files

SKILL.md

Source instructions · Read-only preview

Back to search Back to installation

014-agile-user-story

Guides the creation of agile user stories and Gherkin feature files. Use when the user wants to create a user story, write acceptance criteria, define Gherkin scenarios, or author BDD feature files. This should trigger for requests such as Create a user story; Write a user story; I need to write a user story. Part of cursor-rules-java project

2026-05-27

composio-toolkit-integraci-n-de-servicios-para-agentes-ia

Guía técnica completa para integrar 250+ servicios externos con agentes IA usando Composio. Cubre instalación, autenticación OAuth, gestión de herramientas, triggers y flujos multi-servicio.

2026-05-27

032-architecture-adr-non-functional-requirements

Facilitates conversational discovery to create Architectural Decision Records (ADRs) for non-functional requirements using the ISO/IEC 25010:2023 quality model. Use when the user wants to document quality attributes, NFR decisions, security/performance/scalability architecture, or design systems with measurable quality criteria. This should trigger for requests such as Create ADR for Non-functional requirements; Document Non-functional requirements; Capture Non-functional requirements; Generate Non-functional requirements in an ADR. Part of cursor-rules-java project

2026-05-27

View all from this repository

File Explorer

2 files

SKILL.md

Source instructions · Read-only preview

name	plugin-visual
disable-model-invocation	true
description	Analyze agent extensions and generate self-contained HTML wiki reports with security audit and architecture diagrams. Use when asked to analyze, audit, or document a plugin. Triggers on GitHub plugin URLs or local plugin paths.
argument-hint	path-or-url [--format html\|md] [--lang code]
allowed-tools	Read, Glob, Grep, Agent, AskUserQuestion, Bash(gh repo clone ), Bash(rm -rf /tmp/plugin-visual-), Bash(git branch ), Bash(git log ), Bash(git rev-parse ), Bash(open ), Bash(node ), Bash(which ), Bash(echo *)

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:

Path contains / → local path (resolve relative to cwd)
Contains github.com or https:// → GitHub URL
Other text → installed plugin name (search ~/.claude/plugins/cache/)
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:

Explicit language argument: --lang <code> (e.g., --lang ko, --lang fr, --lang zh) → use that language. Any language code is valid
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
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:

Audience: Who will read this? (yourself, your team, plugin marketplace reviewers)
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):
3. Extract owner/repo for cloning
4. Extract the subpath after /tree/{branch}/ (e.g., plugins/foo)
5. 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 (< 5 files found), run additional Glob calls (never Bash):

Glob("*", path: {target-directory})
Glob("**/*", path: {target-directory})

Then run targeted Glob on discovered directories (e.g., skills/**/*, agents/**/*, commands/**/*).

Step 3: Classify results into component types:

Component	Path pattern
Skill	`skills/*/SKILL.md`
Skill auxiliary	`skills//` (non-SKILL.md)
Agent	`agents/*.md`
Command	`commands/*.md`
Rule	`rules/*.md` or root-level `RULE.md`
Hook config	`hooks/hooks.json` or `hooks/*.json`
MCP config	`.mcp.json`
LSP config	`.lsp.json`
Config	`settings.json` (plugin root)
Plugin manifest	`**/plugin.json`

Build a component inventory with counts and file lists.

Step 4: Determine platform from Glob results (no additional Glob calls needed).

Check the file list from Step 1 for platform-unique signals:

Platform	Unique signals (any match → detected)
Claude Code	`.claude-plugin/plugin.json`, `CLAUDE.md`, `.claude/` directory, `agents/*.md`, `hooks/hooks.json`, `.mcp.json`
Codex (not yet supported)	`.codex/` directory, `AGENTS.md`, `agents/*.toml`

If no known platform is detected, ask the user: "Could not detect the agent platform. Currently supported: Claude Code. Is this a Claude Code plugin?"

If Codex is detected, inform the user that Codex analysis is not yet supported.

Set {platform} variable for subsequent phases. Currently only claude-code is implemented.

Phase 3: Metadata Collection

Why: Reading identity files here avoids duplicate reads inside sub-agents, saving tokens.

Read identity files in a single message with parallel Read calls:

plugin.json (or .claude-plugin/plugin.json — whichever Phase 2 found)
hooks/hooks.json (only if found in Phase 2)

Existence of LICENSE, CHANGELOG.md, tests/ is already known from Phase 2.

Do NOT read README.md, SKILL.md, agent.md, command.md, or hook script files. Sub-agents read these files directly — the feature-architect reads README.md in its own analysis procedure. Reading them here wastes tokens through duplication.

Output for Phase 4: plugin identity + file path inventory + existence flags + language.

Phase 4: Parallel Analysis

Why: Feature and security analysis are independent concerns — parallel execution halves wall-clock time.

For overview mode, skip this phase — go directly to Phase 5.

For analyze and security modes, delegate to agents in parallel.

Agent prompt: Provide each agent with:

Plugin identity (name, version, author, description — from plugin.json)
Target directory path
Component file paths grouped by type (from Phase 2 Glob)
Output language
Analysis mode
Source context: source_type, source_base, github_url (if applicable) — so feature-architect can include relative paths that the orchestrator will later combine with source_base for links

For analyze mode with large plugins (total components > 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 <= 15):

Task(subagent_type: "vision-powers:feature-architect", prompt: {all file paths})
Task(subagent_type: "vision-powers:security-auditor", prompt: {all file paths})

For security mode — launch only security-auditor:

Task(subagent_type: "vision-powers:security-auditor", prompt: {all file paths})

Phase 4.5: Environment Fit Diagnosis (analyze mode only)

Why: Even a well-built plugin can be wrong for the user's environment. This step catches conflicts, redundancies, and budget overruns before they cause confusion.

Diagnose whether this plugin is a good fit for the user's current environment — not just "can it run?" but "should it be installed here?"

Full procedure: Read ${CLAUDE_PLUGIN_ROOT}/skills/plugin-visual/references/platforms/claude-code/env-fit-diagnosis.md for the detailed 5-step process covering:

Extract plugin characteristics from feature-architect output (including rules, CLAUDE.md @imports, bundle source)
Run the environment scan script (env-fit-scan.js) — collects installed plugins, skills, commands, hooks, MCP servers, context metrics
Perform eight diagnostic analyses:
- Via script data (steps 3A-3E, 3H): installation status, dependency check, context budget, functional overlap, hook impact, component dependencies
- Via orchestrator (steps 3C extras, 3F, 3G): rules context cost (from feature-architect's rules analysis), CLAUDE.md @import chain, scope impact analysis, bundle source detection (from Phase 1 source context and plugin cache inspection)
Determine overall verdict (RECOMMENDED / CONDITIONAL / REDUNDANT / CONFLICTING)
Build diagnosis data structure for Phase 5/5R (includes scope_impact, bundle_source, and enhanced context_budget with always-loaded/deferred breakdown)

The environment scan script provides baseline data:

Bash(node {plugin-root}/scripts/env-fit-scan.js --plugin-name {plugin-name})

The orchestrator then supplements with:

Rules context cost: Count rules from feature-architect output, classify as always-loaded (no paths:) or on-demand (paths: present), estimate tokens as file_size / 4
Scope impact: All marketplace plugins install globally; check for framework-specific hooks/MCP that may warrant per-project activation
Bundle source: Determine from Phase 1 source_type (local/github) or plugin cache path patterns (marketplace/symlink)

Save the combined environment_fit data for Phase 5/5R. Omit empty categories.

Phase 5: Report Assembly (inline markdown)

For security mode, overview mode, or analyze mode with --format md — assemble inline markdown report:

Assemble the report using ${CLAUDE_PLUGIN_ROOT}/skills/plugin-visual/references/platforms/claude-code/report-template.md format:

overview mode: Identity + Component Inventory sections only
security mode: Security-focused report with risk summary, permission matrix, findings
analyze mode (--format md): Full report with analysis, Environment Fit Diagnosis, Skill Design Quality, and Plugin Profile

For Plugin Profile and Skill Design Quality, apply criteria from ${CLAUDE_PLUGIN_ROOT}/skills/plugin-visual/references/platforms/claude-code/analysis-criteria.md. For risk levels, apply rules from ${CLAUDE_PLUGIN_ROOT}/skills/plugin-visual/references/platforms/claude-code/security-rules.md. Environment Fit Diagnosis is a standalone section between Feature Deep Dive and Usage (not part of Plugin Profile). Include the full diagnosis from Phase 4.5: verdict, context budget (200K/1M scenarios), installation status, dependency check, overlap/trigger findings, hook impact, component dependencies, and recommendations. Skill Design Quality includes: skill category distribution, per-skill design assessment (description quality, progressive disclosure, gotchas, scripts, hooks, data persistence, maturity level), and improvement recommendations. This data comes from the feature-architect's Skill Design Quality output.

Output the report in the detected language, using ${CLAUDE_PLUGIN_ROOT}/skills/plugin-visual/references/platforms/claude-code/report-template.md format. Translate all section headers, labels, and descriptions to the target language. Keep component names, file paths, and technical terms (CRITICAL, HIGH, MEDIUM, LOW) untranslated.

Output the report directly to the user (inline markdown).

Phase 5R: HTML Report Generation (analyze mode — default format)

For analyze mode with HTML format (the default), generate a self-contained HTML file.

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 (e.g., 2026-03-14)
- {plugin-name} is from plugin.json name field (or directory name if no plugin.json)
The Write tool creates parent directories automatically — no mkdir needed.

Existing report check: Before generating, use Glob to search for *-{plugin-name}-report.html in ${CLAUDE_PLUGIN_DATA}/reports/. If any exist, use AskUserQuestion:
Found existing report(s) for {plugin-name}:
- {filename1}
- {filename2}
1. Create new report ({today's date})
2. Update {most-recent-filename}
(Translate to output language.)
- If user chooses "create new" → use the default dated path
- If user chooses "update" → use the existing file path as output
- If no existing reports found → proceed with default dated path without asking
Resolve paths and read references:

Use ${CLAUDE_PLUGIN_ROOT} — it expands to the plugin install directory at invocation time, which is stable across local/marketplace installs and does not depend on the current working directory.
- Template: ${CLAUDE_PLUGIN_ROOT}/templates/plugin-visual.html
- JSON schema: ${CLAUDE_PLUGIN_ROOT}/skills/plugin-visual/references/sections-data-schema.md
- Semantic tokens: ${CLAUDE_PLUGIN_ROOT}/references/design-system/semantic-tokens.md
- Diagram type selection: ${CLAUDE_PLUGIN_ROOT}/references/design-system/diagram-type-selection.md
- Diagram density rules: ${CLAUDE_PLUGIN_ROOT}/references/design-system/diagram-density-rules.md
- Taste gate: ${CLAUDE_PLUGIN_ROOT}/references/design-system/taste-gate.md
- JSON validator script: ${CLAUDE_PLUGIN_ROOT}/scripts/validate-sections-data.js
- Render script: ${CLAUDE_PLUGIN_ROOT}/scripts/render-sections.js
- Assembler script: ${CLAUDE_PLUGIN_ROOT}/scripts/assemble-report.js

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.

Reference Files

references/platforms/claude-code/analysis-criteria.md — Plugin Profile criteria (component inventory, docs, quality checklist, skill categories, design quality)
references/platforms/claude-code/security-rules.md — Security patterns and risk classification (with context modifiers)
references/platforms/claude-code/report-template.md — Report output format templates (inline markdown)
references/platforms/claude-code/env-fit-diagnosis.md — Environment Fit Diagnosis detailed steps (Phase 4.5)
references/sections-data-schema.md — JSON data schema for all 11 report sections. Visual-report-writer reads it to generate sections-data.json
references/section-structure.md — HTML structure patterns for each report section (used by render-sections.js, not by the writer in JSON mode)
../../templates/plugin-visual.html — HTML template with all CSS/JS baked in. The assembler script combines it with section files
../../scripts/validate-sections-data.js — JSON contract validator that must pass before rendering sections-data.json
../../scripts/render-sections.js — Render script (Node.js) that converts validated sections-data.json into HTML section files + metadata.json with correct CSS class names
../../scripts/assemble-report.js — Assembler script (Node.js) that merges template + section files + metadata into the final HTML report
../../references/design-system/semantic-tokens.md — Font pairing and color token selection guide. Read by the orchestrator in Phase 5R step 2 and passed as content to visual-report-writer
../../references/design-system/taste-gate.md — Quality checklist for report writing. Read by the orchestrator in Phase 5R step 2 and passed as content to visual-report-writer

name	plugin-visual
disable-model-invocation	true
description	Analyze agent extensions and generate self-contained HTML wiki reports with security audit and architecture diagrams. Use when asked to analyze, audit, or document a plugin. Triggers on GitHub plugin URLs or local plugin paths.
argument-hint	path-or-url [--format html\|md] [--lang code]
allowed-tools	Read, Glob, Grep, Agent, AskUserQuestion, Bash(gh repo clone ), Bash(rm -rf /tmp/plugin-visual-), Bash(git branch ), Bash(git log ), Bash(git rev-parse ), Bash(open ), Bash(node ), Bash(which ), Bash(echo *)

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:

Path contains / → local path (resolve relative to cwd)
Contains github.com or https:// → GitHub URL
Other text → installed plugin name (search ~/.claude/plugins/cache/)
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:

Explicit language argument: --lang <code> (e.g., --lang ko, --lang fr, --lang zh) → use that language. Any language code is valid
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
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

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:

Audience: Who will read this? (yourself, your team, plugin marketplace reviewers)
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):
3. Extract owner/repo for cloning
4. Extract the subpath after /tree/{branch}/ (e.g., plugins/foo)
5. 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}`

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 (< 5 files found), run additional Glob calls (never Bash):

Glob("*", path: {target-directory})
Glob("**/*", path: {target-directory})

Then run targeted Glob on discovered directories (e.g., skills/**/*, agents/**/*, commands/**/*).

Step 3: Classify results into component types:

Component	Path pattern
Skill	`skills/*/SKILL.md`
Skill auxiliary	`skills//` (non-SKILL.md)
Agent	`agents/*.md`
Command	`commands/*.md`
Rule	`rules/*.md` or root-level `RULE.md`
Hook config	`hooks/hooks.json` or `hooks/*.json`
MCP config	`.mcp.json`
LSP config	`.lsp.json`
Config	`settings.json` (plugin root)
Plugin manifest	`**/plugin.json`

Build a component inventory with counts and file lists.

Step 4: Determine platform from Glob results (no additional Glob calls needed).

Check the file list from Step 1 for platform-unique signals:

Platform	Unique signals (any match → detected)
Claude Code	`.claude-plugin/plugin.json`, `CLAUDE.md`, `.claude/` directory, `agents/*.md`, `hooks/hooks.json`, `.mcp.json`
Codex (not yet supported)	`.codex/` directory, `AGENTS.md`, `agents/*.toml`

If no known platform is detected, ask the user: "Could not detect the agent platform. Currently supported: Claude Code. Is this a Claude Code plugin?"

If Codex is detected, inform the user that Codex analysis is not yet supported.

Set {platform} variable for subsequent phases. Currently only claude-code is implemented.

Phase 3: Metadata Collection

Why: Reading identity files here avoids duplicate reads inside sub-agents, saving tokens.

Read identity files in a single message with parallel Read calls:

plugin.json (or .claude-plugin/plugin.json — whichever Phase 2 found)
hooks/hooks.json (only if found in Phase 2)

Existence of LICENSE, CHANGELOG.md, tests/ is already known from Phase 2.

Output for Phase 4: plugin identity + file path inventory + existence flags + language.

Phase 4: Parallel Analysis

Why: Feature and security analysis are independent concerns — parallel execution halves wall-clock time.

For overview mode, skip this phase — go directly to Phase 5.

For analyze and security modes, delegate to agents in parallel.

Agent prompt: Provide each agent with:

Plugin identity (name, version, author, description — from plugin.json)
Target directory path
Component file paths grouped by type (from Phase 2 Glob)
Output language
Analysis mode
Source context: source_type, source_base, github_url (if applicable) — so feature-architect can include relative paths that the orchestrator will later combine with source_base for links

For analyze mode with large plugins (total components > 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 <= 15):

Task(subagent_type: "vision-powers:feature-architect", prompt: {all file paths})
Task(subagent_type: "vision-powers:security-auditor", prompt: {all file paths})

For security mode — launch only security-auditor:

Task(subagent_type: "vision-powers:security-auditor", prompt: {all file paths})

Phase 4.5: Environment Fit Diagnosis (analyze mode only)

Why: Even a well-built plugin can be wrong for the user's environment. This step catches conflicts, redundancies, and budget overruns before they cause confusion.

Diagnose whether this plugin is a good fit for the user's current environment — not just "can it run?" but "should it be installed here?"

Full procedure: Read ${CLAUDE_PLUGIN_ROOT}/skills/plugin-visual/references/platforms/claude-code/env-fit-diagnosis.md for the detailed 5-step process covering:

Extract plugin characteristics from feature-architect output (including rules, CLAUDE.md @imports, bundle source)
Run the environment scan script (env-fit-scan.js) — collects installed plugins, skills, commands, hooks, MCP servers, context metrics
Perform eight diagnostic analyses:
- Via script data (steps 3A-3E, 3H): installation status, dependency check, context budget, functional overlap, hook impact, component dependencies
- Via orchestrator (steps 3C extras, 3F, 3G): rules context cost (from feature-architect's rules analysis), CLAUDE.md @import chain, scope impact analysis, bundle source detection (from Phase 1 source context and plugin cache inspection)
Determine overall verdict (RECOMMENDED / CONDITIONAL / REDUNDANT / CONFLICTING)
Build diagnosis data structure for Phase 5/5R (includes scope_impact, bundle_source, and enhanced context_budget with always-loaded/deferred breakdown)

The environment scan script provides baseline data:

Bash(node {plugin-root}/scripts/env-fit-scan.js --plugin-name {plugin-name})

The orchestrator then supplements with:

Rules context cost: Count rules from feature-architect output, classify as always-loaded (no paths:) or on-demand (paths: present), estimate tokens as file_size / 4
Scope impact: All marketplace plugins install globally; check for framework-specific hooks/MCP that may warrant per-project activation
Bundle source: Determine from Phase 1 source_type (local/github) or plugin cache path patterns (marketplace/symlink)

Save the combined environment_fit data for Phase 5/5R. Omit empty categories.

Phase 5: Report Assembly (inline markdown)

For security mode, overview mode, or analyze mode with --format md — assemble inline markdown report:

Assemble the report using ${CLAUDE_PLUGIN_ROOT}/skills/plugin-visual/references/platforms/claude-code/report-template.md format:

overview mode: Identity + Component Inventory sections only
security mode: Security-focused report with risk summary, permission matrix, findings
analyze mode (--format md): Full report with analysis, Environment Fit Diagnosis, Skill Design Quality, and Plugin Profile

Output the report directly to the user (inline markdown).

Phase 5R: HTML Report Generation (analyze mode — default format)

For analyze mode with HTML format (the default), generate a self-contained HTML file.

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 (e.g., 2026-03-14)
- {plugin-name} is from plugin.json name field (or directory name if no plugin.json)
The Write tool creates parent directories automatically — no mkdir needed.

Existing report check: Before generating, use Glob to search for *-{plugin-name}-report.html in ${CLAUDE_PLUGIN_DATA}/reports/. If any exist, use AskUserQuestion:
Found existing report(s) for {plugin-name}:
- {filename1}
- {filename2}
1. Create new report ({today's date})
2. Update {most-recent-filename}
(Translate to output language.)
- If user chooses "create new" → use the default dated path
- If user chooses "update" → use the existing file path as output
- If no existing reports found → proceed with default dated path without asking
Resolve paths and read references:

Use ${CLAUDE_PLUGIN_ROOT} — it expands to the plugin install directory at invocation time, which is stable across local/marketplace installs and does not depend on the current working directory.
- Template: ${CLAUDE_PLUGIN_ROOT}/templates/plugin-visual.html
- JSON schema: ${CLAUDE_PLUGIN_ROOT}/skills/plugin-visual/references/sections-data-schema.md
- Semantic tokens: ${CLAUDE_PLUGIN_ROOT}/references/design-system/semantic-tokens.md
- Diagram type selection: ${CLAUDE_PLUGIN_ROOT}/references/design-system/diagram-type-selection.md
- Diagram density rules: ${CLAUDE_PLUGIN_ROOT}/references/design-system/diagram-density-rules.md
- Taste gate: ${CLAUDE_PLUGIN_ROOT}/references/design-system/taste-gate.md
- JSON validator script: ${CLAUDE_PLUGIN_ROOT}/scripts/validate-sections-data.js
- Render script: ${CLAUDE_PLUGIN_ROOT}/scripts/render-sections.js
- Assembler script: ${CLAUDE_PLUGIN_ROOT}/scripts/assemble-report.js

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.

Reference Files

references/platforms/claude-code/analysis-criteria.md — Plugin Profile criteria (component inventory, docs, quality checklist, skill categories, design quality)
references/platforms/claude-code/security-rules.md — Security patterns and risk classification (with context modifiers)
references/platforms/claude-code/report-template.md — Report output format templates (inline markdown)
references/platforms/claude-code/env-fit-diagnosis.md — Environment Fit Diagnosis detailed steps (Phase 4.5)
references/sections-data-schema.md — JSON data schema for all 11 report sections. Visual-report-writer reads it to generate sections-data.json
references/section-structure.md — HTML structure patterns for each report section (used by render-sections.js, not by the writer in JSON mode)
../../templates/plugin-visual.html — HTML template with all CSS/JS baked in. The assembler script combines it with section files
../../scripts/validate-sections-data.js — JSON contract validator that must pass before rendering sections-data.json
../../scripts/render-sections.js — Render script (Node.js) that converts validated sections-data.json into HTML section files + metadata.json with correct CSS class names
../../scripts/assemble-report.js — Assembler script (Node.js) that merges template + section files + metadata into the final HTML report
../../references/design-system/semantic-tokens.md — Font pairing and color token selection guide. Read by the orchestrator in Phase 5R step 2 and passed as content to visual-report-writer
../../references/design-system/taste-gate.md — Quality checklist for report writing. Read by the orchestrator in Phase 5R step 2 and passed as content to visual-report-writer

Bash(node ${CLAUDE_PLUGIN_ROOT}/scripts/aesthetic-rotation.js recent --n 3)

Delegate to visual-report-writer agent (JSON mode):

Task(subagent_type: "vision-powers:visual-report-writer", prompt: {
  **Output mode: JSON**
  Write a single file: {sections-data-json-path}

  feature-architect analysis results (full text, including Plugin Summary, Raw Content Excerpts, and Skill Design Quality),
  security-auditor analysis results (full text),
  plugin metadata (name, version, author, license, keywords, description),
  output language,
  JSON schema content (full text read in step 2),
  semantic tokens content (full text read in step 2),
  taste gate content (full text read in step 2),
  report title: "Agent Extension Visual: {plugin-name}",
  aesthetic hint: "Editorial",
  source context: { source_type, source_base, github_url (if applicable) },
  environment fit diagnosis: { verdict, verdict_summary, installation_status,
    context_budget: {
      always_loaded: { skill_descriptions, rules, claude_md, total_tokens },
      deferred: { mcp_tools, zero_cost_skills, on_demand_rules, total_tokens },
      rows (backward compat — render script uses always_loaded/deferred when available),
      hook_injection },
    dependency_check, overlap_findings, trigger_collisions,
    hook_impact: { current, adding, projected, types, event_collisions, severity },
    component_deps,
    scope_impact: { installation_scope, affected_scopes, scope_conflicts, appropriateness },
    bundle_source: { type, identifier },
    recommendations } (from Phase 4.5; when RECOMMENDED with no findings, pass minimal verdict-only data),
  skill design quality: { category_distribution, design_assessment[], summary }
    (from feature-architect's Skill Design Quality output; include in Plugin Profile section)
})

Pass the file contents read in step 2, not paths. This eliminates the agent's read turn. The agent writes a single sections-data.json file (1 Write call instead of ~13 in HTML mode).

Do NOT background this agent. Plugin-defined agents silently ignore permissionMode, so the visual-report-writer needs user approval for the Write call. Backgrounded agents cannot prompt for permissions and will fail silently. Always run in the foreground.

Validate sections data — enforce the JSON contract before rendering:

Bash(node {json-validator-path} {sections-data-json-path} --expected-sections 11)

{json-validator-path} = {plugin-root}/scripts/validate-sections-data.js

This is the boundary between the LLM writer and deterministic renderer. It checks that schema array fields are arrays, not table wrappers like {note, rows} or {headers, rows}.

If FAIL: do not write Python fixup scripts and do not continue to render. Re-run visual-report-writer in JSON mode with the validator errors and require a full sections-data.json rewrite. Retry at most twice; if validation still fails, report the schema errors to the user.

Render sections — convert validated JSON data into HTML section files + metadata.json:

Bash(node {render-script-path} --data {sections-data-json-path} --output {sections-dir})

This script produces section-1.html through section-11.html and metadata.json with correct CSS class names hardcoded. No LLM-generated class names.

Assemble report — run the assembler script to combine template + sections:

Bash(node {assembler-path} --template {template-path} --sections {sections-dir} --metadata {sections-dir}/metadata.json --shared {shared-dir-path} --output {output-path})

Report validation — run the validation script:

Bash(node {validator-path} {output-path} --expected-sections 11)

{validator-path} = {plugin-root}/scripts/validate-report.js

The script checks: unreplaced placeholders (section + metadata), section content density, Mermaid diagram-type keywords, Chart.js data arrays, and section count. It exits 0 on PASS, 1 on FAIL with a list of issues.

If FAIL because report content or Mermaid syntax is invalid: edit sections-data.json, then re-run render, assemble, and report validation. The final HTML is a generated artifact; do not edit it directly for report content. Only edit the final HTML for assembler/template injection defects that cannot be represented in sections-data.json.

Optional Coherence Review — if --verify flag was specified or auto_verify is true in user config: Run the coherence review agent (see ../../references/report-generation-workflow.md Step 6). If HIGH severity issues are found, apply content fixes in sections-data.json, then re-run render, assemble, and validation.

Optional Chrome visual verification — only if --verify flag was specified AND mcp__claude-in-chrome__* tools are available. Skip entirely otherwise:

Start a local HTTP server to serve the report (Chrome extensions cannot access file:// URLs):
```
Bash(python3 -m http.server 0 -d "$(dirname {output-path})" 2>&1 & echo $!)
```
Capture the PID and port from the output.
Call tabs_context_mcp (with createIfEmpty: true) to get or create an MCP tab group.
Use navigate to open http://localhost:{port}/{filename} in the MCP tab.
Use javascript_tool to check for Mermaid render errors (document.querySelectorAll('.mermaid svg').length) and empty sections.
Fix content issues in sections-data.json, then re-run data validation, render, assemble, and report validation.
Kill the server: Bash(kill {pid} 2>/dev/null)

Report completion + Feedback Loop:

Use AskUserQuestion with the file:// URL embedded in the question text itself:

Report generated: [Open Report](file://{output-path})

Review the report. Each section has a ✎ button — write feedback and click **Save**.
When done, click **"Copy to Clipboard"** at the bottom bar and paste here.
Or just tell me what to change directly.

(Translate to output language. {output-path} is the actual path determined in step 1. Always include the file:// URL as a markdown link — this is how the user opens the report.)

If the user pastes exported feedback JSON → parse it and apply changes to sections with status: "issue". Do NOT read the full HTML file — only Edit the specific sections that need changes. This prevents context bloat.
If the user describes changes in natural language → apply modifications via targeted Edit calls on the HTML file
After applying changes, ask again with the same URL
If the user confirms completion → proceed to Phase 7

plugin-visual

Source facts

Install options

Review the source files

More from this repository

More from this repository

Agent Extension Visual

Instructions

Input Parsing

Language Detection

Analysis Mode Detection

Output Format Detection

Intent Check

Workflow

Phase 1: Source Acquisition

Phase 2: Discovery

Phase 3: Metadata Collection

Phase 4: Parallel Analysis

Phase 4.5: Environment Fit Diagnosis (analyze mode only)

Phase 5: Report Assembly (inline markdown)

Phase 5R: HTML Report Generation (analyze mode — default format)

Phase 7: Cleanup

Gotchas

Reference Files

Agent Extension Visual

Instructions

Input Parsing

Language Detection

Analysis Mode Detection

Output Format Detection

Intent Check

Workflow

Phase 1: Source Acquisition

Phase 2: Discovery

Phase 3: Metadata Collection

Phase 4: Parallel Analysis

Phase 4.5: Environment Fit Diagnosis (analyze mode only)

Phase 5: Report Assembly (inline markdown)

Phase 5R: HTML Report Generation (analyze mode — default format)

Phase 7: Cleanup

Gotchas

Reference Files