Skip to content
Skills Library
Documents & office · Writing

analyze-plugin

/analyze-plugin

Analyze a plugin's source repository and generate enriched documentation content with presentation-quality SVG diagrams for the skills-registry documentation site. Use when the user wants to document a plugin, generate diagrams for skills, create enriched content for the site, or says things like "analyze the rfe-creator plugin", "generate diagrams for agent-eval-harness", or "update the docs for test-plan".

Licence
Apache-2.0
Last repository change
22.10.2026

Assessment and security

95/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content30 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Analyze a plugin's source repository and generate enriched documentation content with presentation-quality SVG diagrams for the skills-registry documentation site. Use when the user wants to document a plugin, generate diagrams for skills, create enriched content for the site, or says things like "analyze the rfe-creator plugin", "generate diagrams for agent-eval-harness", or "update the docs for test-plan".

Triggers from the description

analyze the rfe-creator plugingenerate diagrams for agent-eval-harnessupdate the docs for test-plan
Original author description

Analyze a plugin's source repository and generate enriched documentation content with presentation-quality SVG diagrams for the skills-registry documentation site. Use when the user wants to document a plugin, generate diagrams for skills, create enriched content for the site, or says things like "analyze the rfe-creator plugin", "generate diagrams for agent-eval-harness", or "update the docs for test-plan".

How it works

  1. Arguments
  2. Instructions
Original SKILL.md headings · 509 lines, 3,689 words
SKILL.md preview
---
name: analyze-plugin
description: >
  Analyze a plugin's source repository and generate enriched documentation content
  with presentation-quality SVG diagrams for the skills-registry documentation site.
  Use when the user wants to document a plugin, generate diagrams for skills, create
  enriched content for the site, or says things like "analyze the rfe-creator plugin",
  "generate diagrams for agent-eval-harness", or "update the docs for test-plan".
user-invocable: true
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
  - Agent
  - Skill
  - Glob
  - Grep
---

# analyze-plugin

Analyze a plugin's source repository, extract detailed content from its SKILL.md files,
and generate enriched documentation pages with SVG diagrams for the skills-registry site.

## Arguments

- `<plugin-name>` — Name of the plugin as it appears in `registry.yaml` (e.g., `rfe-creator`).
  If omitted, list available plugins and ask the user to choose.
- `--no-diagrams` — Skip diagram generation (Steps 5-6). Only clone, read SKILL.md files,
  and generate the enrichment YAML. Useful for refreshing descriptions, arguments, and
  argument hints without the slow diagram pipeline.

## Instructions

### 1. Find the plugin in the registry

Read `registry.yaml` and locate the plugin entry matching the provided name.
Extract `source`, `skills[]`, `agents[]`, `mcp_servers[]`, `includes[]`, and all
metadata. The `source` comes in three shapes — note which one this plugin uses,
because it changes how you clone (Step 2) and where SKILL.md files live (Step 3):

| `source.type` | Fields | Repo to clone | Plugin lives at | Skills at |
|---------------|--------|---------------|-----------------|-----------|
| `github` | `repo` (`owner/name`), `ref`, `skills_dir?` | `https://github.com/<repo>.git` | repo root | `<skills_dir or .claude/skills>/<name>/SKILL.md` |
| `git` | `url`, `ref`, `skills_dir?` | `<url>` | repo root | `<skills_dir or .claude/skills>/<name>/SKILL.md` |
| `git-subdir` | `url`, `path`, `ref` | `<url>` | `<path>/` inside the repo | `<path>/skills/<name>/SKILL.md` |

Call the plugin's directory inside the clone `<SUBDIR>` — it is `.` for `github`/`git`
and `<source.path>` for `git-subdir`. Agents live at `<SUBDIR>/agents/`.

**Meta-plugins (bundles).** If the entry has a non-empty `includes: [members...]`, it is a
bundle — it installs those member plugins and has **no skills of its own**. Skip the
skill-reading and per-skill diagram steps for it; instead follow *Bundle handling* below.
The members are their own top-level registry entries (usually `git-subdir`) and are
analyzed on their own runs.

If the plugin name is not found, list available plugins and exit.

#### Bundle handling (plugins with `includes`)

For a bundle, produce an enrichment that describes the toolkit rather than skills it
does not have:

- Write `_enriched.yaml` with a synthesized `description` (what the bundle installs and
  why) and an `architecture_notes` that lists the member plugins from `includes` and, if
  useful, reads each member entry's `description` from `registry.yaml`. Do **not** emit a
  `skills:` map.
- For diagrams (unless `--no-diagrams`), generate only a **pipeline** overview whose nodes
  are the member plugins (one node per member, the bundle as entry). Skip per-skill
  diagrams — the bundle has none.
- You may still clone the bundle's `<SUBDIR>` to read its `plugin.json`/`README.md` for
  the overview, but there are no `<SUBDIR>/skills/` to iterate.

### 2. Clone the source repository

Clone inside the project directory under `.tmp/skill-repos/` (not a system temp dir —
sub-agents need read access and can't reach paths outside the project).

**Validate inputs first — before building any path or running `rm`/`git clone`.**
`<plugin-name>` and `source.path` come from `registry.yaml` and are interpolated into
`CLONE_DIR`/`WORKDIR` that `rm -rf` and `git clone` then act on, so a traversal value must
be rejected *up front* (the Step 5 sanitize runs too late — after these commands). Confirm
`<plugin-name>` is a plain slug (`^[a-z0-9][a-z0-9._-]*$` — no `/`, no `..`), and confirm
`source.path` (git-subdir) is a safe **relative** path — reject a leading `/` and any `..`
segment, allow `packages/foo`. Abort the run on either (path traversal / unintended
deletion — CWE-22 / CWE-73).

Then pick `CLONE_URL`, `CLONE_DIR`, `WORKDIR`, and `SKILLS_DIR` from the source shape
identified in Step 1:

- **`CLONE_URL`** — `https://github.com/<source.repo>.git` for `github`; `<source.url>`
  for `git` and `git-subdir`.
- **`CLONE_DIR`** — `.tmp/skill-repos/<plugin-name>` for **every** source type (one dir
  per plugin). A `git-subdir` member clones its whole monorepo here and reads only its
  subdir. Keep it per-plugin (not per-repo): `generate-site` fans this skill out in
  parallel, so a shared per-repo dir would let concurrent clones/pulls race and corrupt
  the checkout. The cost is that members of one monorepo each shallow-clone it — redundant
  but safe; a future optimization could clone the shared repo once before the fan-out.
- **`WORKDIR`** — `<CLONE_DIR>/<SUBDIR>` (recall `<SUBDIR>` is `.` for `github`/`git`,
  `<source.path>` for `git-subdir`). All later steps read SKILL.md/agents under `WORKDIR`.
- **`SKILLS_DIR`** — `<skills_dir>` if the entry sets one; else `.claude/skills` for
  `github`/`git`, `skills` for `git-subdir`. Skills resolve at
  `<WORKDIR>/<SKILLS_DIR>/<name>/SKILL.md`; use this **same** value in Step 3 and in the
  Step 6 agent prompt (don't hardcode `skills`, which is wrong for a default github/git plugin).

If the directory already exists, check that it points to the correct repo:

```bash
if [ -d "$CLONE_DIR" ]; then
  remote=$(cd "$CLONE_DIR" && git remote get-url origin 2>/dev/null)
  if [ "$remote" != "$CLONE_URL" ]; then
    echo "Repo URL changed ($remote → $CLONE_URL), re-cloning"
    rm -rf "$CLONE_DIR"
  fi
fi
```

Clone fresh, or (for an existing clone) **fetch and check out the requested `<ref>`** — the
`ref` in `registry.yaml` may have changed since the last run, and this also handles a tag
or SHA checkout cleanly (a plain `git pull --ff-only` fails on a detached/tag checkout and
would silently keep the old branch):

```bash
mkdir -p .tmp/skill-repos
if [ ! -d "$CLONE_DIR" ]; then
  # git-subdir needs the subdir, so a plain shallow clone of the repo is fine here.
  git clone --depth 1 --branch <ref> "$CLONE_URL" "$CLONE_DIR"
else
  git -C "$CLONE_DIR" fetch --depth 1 origin <ref>
  git -C "$CLONE_DIR" checkout -q -f FETCH_HEAD   # switch to the requested ref (branch/tag/SHA)
fi
```

The `.tmp/` directory is already in `.gitignore`.

### 2.5. Clean up stale files

Compare existing site files against the current registry skill names. Remove files
from previous runs that no longer correspond to registered skills (e.g., after a
skill rename from `test-plan.create` to `test-plan-create`).

```bash
# Build the set of expected file stems
expected_stems="pipeline index _enriched"
for skill in <registered skill names>; do
  expected_stems="$expected_stems $skill"
done

# Remove orphaned diagram/page files
for file in site/docs/plugins/<plugin-name>/*; do
  stem=$(basename "$file" | sed 's/\.[^.]*$//')  # strip last extension
  # Skip _enriched.yaml, index.md, pipeline.*, artifacts/
  if echo "$expected_stems" | grep -qw "$stem"; then continue; fi
  if [ -d "$file" ]; then continue; fi  # skip directories like artifacts/
  echo "Removing stale file: $file"
  rm -f "$file"
done
```

This handles:
- Skill renames (e.g., `test-plan.create` → `test-plan-create`)
- Removed skills (skill deleted from registry but files remain)
- Repo moves (old diagrams from previous repo version)

### 3. Read all SKILL.md files

For each skill listed in the plugin's registry entry, read the corresponding SKILL.md file
at `<WORKDIR>/<SKILLS_DIR>/<skill-name>/SKILL.md` using the `WORKDIR` and `SKILLS_DIR`
resolved in Step 2. Concretely, a `git-subdir` member resolves to
`<CLONE_DIR>/<source.path>/skills/<skill-name>/SKILL.md`, and a default `github`/`git`
plugin to `<CLONE_DIR>/.claude/skills/<skill-name>/SKILL.md`.

(Skip this step entirely for a bundle — it has no skills; see *Bundle handling* in Step 1.)

If a skill's SKILL.md is not found at the expected path, try common name transformations:
- Replace `-` with `.` (dashes to dots): `test-plan-create` → `test-plan.create`
- Replace `.` with `-` (dots to dashes): `test-plan.create` → `test-plan-create`

Report any name mapping used so the user knows.

If a skill listed in `registry.yaml` is not found in the repo after trying transformations,
skip it and add it to the "skipped" list in the report. Do not fail — continue with the
remaining skills.

Extract from each SKILL.md:
- **Frontmatter** fields (description, allowed-tools, user-invocable, argument-hint, etc.)
- **Detailed description** — the full markdown content beyond the frontmatter
- **argument-hint** — if present in frontmatter, store it as `argument_hint` in the
  enrichment. Then use it as the starting point for building the arguments list:
  parse each token (`<NAME>` = required, `[NAME]` = optional, `--flag` = flag),
  then search the SKILL.md body for descriptions of each argument name. Look for
  the argument name in headings, table rows, bullet lists, or prose near "Parse
  Arguments", "Inputs", "Arguments", or "Usage" sections.
- **Arguments** — look for "Parse Arguments", "Arguments", "Usage", "Inputs" sections.
  Extract from markdown tables, bullet lists, or usage code blocks. Capture: name,
  type/format, required/optional, default value, description. If `argument-hint`
  was already parsed, merge — the hint provides names and required/optional status,
  the body provides descriptions and types.
- **Usage examples** — any example invocations or usage patterns
- **Input/output** — what the skill takes and produces
- **Architecture notes** — how the skill works internally (sub-agents, scripts, prompts)

Also read any agent definitions from `<WORKDIR>/<agents_dir or agents>/<agent-name>.md` if
the plugin has agents. If the plugin declares `mcp_servers` in `registry.yaml`, note them
for the enrichment description — they already render as their own table via
`generate_site.py`, so enrichment only needs to add context, not re-list them.

### 4. Generate the enrichment file

Write the extracted content to `site/docs/plugins/<plugin-name>/_enriched.yaml`:

```yaml
description: |
  Multi-paragraph description synthesized from all SKILL.md files
  and the overall plugin structure.
architecture_notes: |
  How the plugin's skills connect and work together.
  Internal architecture patterns (sub-agents, scripts, prompt chains).
skills:
  skill-name:
    description: |
      Detailed description from the SKILL.md content.
    argument_hint: "<REQUIRED_ARG> [OPTIONAL_ARG] --flag"
    arguments:
      - name: "REQUIRED_ARG"
        required: true
        description: "Description inferred from SKILL.md body"
      - name: "OPTIONAL_ARG"
        required: false
        description: "Description inferred from SKILL.md body"
      - name: "--flag"
        type: "(value type)"
        required: false
        default: "default-value"
        description: "What this argument does"
    usage_examples:
      - "/skill-name <REQUIRED_ARG> [OPTIONAL_ARG]"
      - "/skill-name --flag value"
  # ... repeat for each skill
```

The description should be richer than the one-line registry description — it should
explain what the plugin does, why, and how. Keep it concise but informative (2-4 paragraphs).

### 5. Set up diagram generation

**Skip Steps 5-6 if `--no-diagrams` is set.**

Diagrams are authored by parallel sub-agents that each follow the durable recipe at
`references/diagram-agent-instructions.md` (next to this SKILL.md). Set up once:

1. **Locate AND verify diagram-skills.** Find the local `diagram-skills` checkout (the
   `skill-diagram` + `diagram-layout` skills live there; commonly
   `~/Development/diagram-skills`). Call its path `<DIAGRAM_SKILLS>`. Sub-agents read
   AND `python3`-execute its scripts, so it is **trusted code** — verify it before use,
   then add it to `permissions.additionalDirectories`:

   ```bash
   git -C <DIAGRAM_SKILLS> remote get-url origin   # must be the known diagram-skills repo
   git -C <DIAGRAM_SKILLS> rev-parse HEAD           # the exact commit whose Python will run
   ```

   **Fail closed:** if `origin` is not the allowlisted diagram-skills repo, or the path is
   not a git checkout you can verify, do NOT spawn the diagram agents (they would execute
   its Python). Otherwise surface the HEAD SHA to the user and proceed only after they
   confirm it (or it matches a previously-approved SHA). Treat an unverified checkout as
   untrusted third-party code (CWE-494 / CWE-829 supply-chain execution).
2. **Grant sub-agents least privilege.** Sub-agents CANNOT get interactive approval — any
   tool call not on the allow-list is auto-denied and the agent hangs. Because each agent
   reads a target plugin's SKILL.md/scripts **cloned from an arbitrary URL in
   `registry.yaml`** (untrusted input — see the recipe's *Trust boundary*), grant them only
   the minimum they need:
   - **Agent-facing minimum:** `Write(.tmp/diagram-work/**)`,
     `Write(site/docs/plugins/<plugin-name>/**)` (scope to THIS run's plugin dir — not all
     of `plugins/**`), `Read(.tmp/skill-repos/**)`, `Read(.tmp/diagram-work/**)`,
     `Bash(python3 *)`, `Bash(mkdir *)`, `Bash(mv *)` (scratch tmp-renames in Step 4 of the
     recipe), `Bash(grep *)` (Step 8 verification), and
     `additionalDirectories: [<DIAGRAM_SKILLS>]`.
   - **Main-thread ONLY (never invoked by sub-agents):** `Bash(rm *)`, `Bash(find *)`,
     `git clone`/`git pull`, `Bash(open *)` — the orchestrator uses these for backup,
     clean-slate, clone, cleanup, and SVG export.

   **Limitation — be honest about it:** `.claude/settings.*.json` permissions are shared by
   the orchestrator and every sub-agent; the Agent tool has no per-agent ACL, so the
   destructive forms cannot be technically withheld from agents while the main thread keeps
   them. The agent restriction is therefore enforced **behaviorally** by the recipe's *Trust
   boundary* (agents are told never to run `rm`/destructive/network/out-of-scope commands),
   plus keeping the committed `.claude/settings.json` minimal (no `Write`/`rm`). Adding
   permission rules needs explicit user consent (the self-modification guard blocks silent
   widening) — ask first. Then run ONE cheap smoke-test agent (Write to `.tmp/diagram-work/`
   and `site/docs/plugins/`, `python3 --version`) to confirm the perms are live before the
   expensive batch.

   **Sanitize the target clone before spawning agents** (it came from an arbitrary
   `registry.yaml` URL): (a) reject **escaping** symlinks -- any symlink under the clone
   dir from Step 2 (`.tmp/skill-repos/<plugin-name>`) whose target resolves OUTSIDE that
   dir. Abort the run if one exists: a symlink like `SKILL.md -> ~/.ssh/id_rsa` would let
   an agent read host files through the allowed read scope. A symlink resolving back
   inside the clone is fine and must NOT abort -- in-repo symlinks are a legitimate and
   common layout (e.g. a compatibility plugin that re-exports its siblings' skills), and
   rejecting them outright blocks whole monorepos while giving no extra protection,
   since the threat is escaping the read scope, not indirection as such:

   ```bash
   python3 - "$CLONE_DIR" <<'PY'
   import sys
   from pathlib import Path
   root = Path(sys.argv[1]).resolve()
   bad = []
   for p in root.rglob("*"):
       if not p.is_symlink():
           continue
       try:
           target = p.resolve()
       except (OSError, RuntimeError) as e:
           # pathlib raises RuntimeError (not OSError) on a symlink loop, so both
           # must be caught or the sweep dies with a traceback instead of a verdict.
           bad.append((p, f"unresolvable: {e}")); continue
       if not target.is_relative_to(root):
           bad.append((p, f"-> {target}"))
   for p, why in bad:
       print(f"ESCAPING SYMLINK: {p} {why}")
   sys.exit(1 if bad else 0)
   PY
   ```

   A dangling link whose target path is *inside* the clone is not escaping and does not
   abort -- it resolves nowhere, so there is nothing to read.

   And (b) confirm `<plugin-name>` / `<skill-name>` / `<dir-name>` / `<source.path>` are
   plain slugs (no `..`) before building any path, so a crafted name cannot escape
   `.tmp/diagram-work/*` or `site/docs/plugins/*`.
3. **Back up + clean-slate.** Copy any existing `*.d2`/`*.drawio`/`*.svg` in
   `site/docs/plugins/<plugin-name>/` to `.tmp/diagram-backup/<plugin-name>/`, then
   delete them from the output dir (so no agent mistakes stale output for "done").
   Clear this run's scratch -- the single dir `.tmp/diagram-work/plugins/<plugin-name>/`
   (see the SCRATCH naming rule in Step 6; everything for this plugin lives under it).
   A stale `layout-plan.json` in a shared dir renders the WRONG plugin's pipeline, and
   because `generate-site` runs 6-8 `analyze-plugin` agents CONCURRENTLY, a shared dir
   is a live write race between plugins, not just staleness between runs. Clear only
   your own plugin's dir -- never all of `.tmp/diagram-work/`, which would delete a
   concurrently-running sibling's intermediates.

   **One run per plugin at a time.** Two concurrent `/analyze-plugin <same-plugin>`
   invocations are not supported and scratch isolation cannot make them safe: they also
   share `site/docs/plugins/<plugin-name>/`, so this very step would delete the other
   run's outputs and both would write the same `.d2`/`.drawio`. `generate-site`
   dispatches one agent per plugin, so its fan-out never does this -- just don't start a
   second run for a plugin already being analyzed.
4. **Derive per-skill flows.** From the SKILL.md files read in Step 3 (and a skim of
   each skill's `scripts/`), write a brief node/edge **suggested flow** per skill and
   for the pipeline: ordered nodes with roles pre-assigned (entry / processing /
   decision / llm / external / output / callout), the expected llm-node count, the
   **primary output artifact to call out**, and any per-skill reserved-id traps.
   These outlines are the main quality lever — derive them yourself so agents refine
   rather than re-derive, and so callouts land on the right artifact.

### 6. Generate the diagrams (parallel agents), export, verify

**Skip this step if `--no-diagrams` is set.**

#### Detail requirements (non-negotiable — this is where diagrams silently regress)

Every individual skill diagram MUST clear skill-diagram's **Detail Floor**
(see `skill-diagram/prompts/analysis-guide.md` — read it, not just `d2-conventions.md`,
which is only the *style* guide). The floor:

- **≥1 callout detail box** per non-trivial skill — above all the skill's **primary
  output artifact's structure** (its schema/fields), plus any central file tree or
  config snippet. Read the actual script that writes it (e.g. `workspace.py`, the
  config template) to get the *real* structure — do not approximate.
- **Data-flow edge labels**: name the artifact that flows between steps
  (`summary.yaml`, `collection.json`) on the edges, not just conditions.
- **Containers for composite subsystems** (e.g. a scoring system's judge types),
  nested where a member is itself multi-step — never flatten into one node.
- **Decision branches and back-edges** preserved (mode branches, retry loops,
  cache/fast-path short-circuits).
- **~10-16 boxes** for a rich skill with 2-5 concrete bullets each (real
  script/flag/file names). A lean 5-9-node outline is the regression signature.

This means each diagram agent must **read the skill's `scripts/` and `references/`**
(not only its SKILL.md) to source callout content — SKILL.md gives the flow, the
scripts give the concrete artifacts. Author the `.d2` accordingly, then verify:

```bash
python3 <diagram-skills>/skills/skill-diagram/scripts/validate_d2.py <output>.d2
```

and clear the `detail_warnings` (missing callout / no data-flow labels / too few
nodes) before accepting the diagram.

The reliable path is to have each agent **author its `.d2` directly following the
recipe** (`references/diagram-agent-instructions.md`), then run the layout pipeline —
agents that call `/skill-diagram` as a nested Skill tend to shortcut.

For each skill AND the pipeline overview, spawn ONE `general-purpose` sub-agent that
reads the recipe and follows it, passing the inputs the recipe expects:

```text
Agent({
  subagent_type: "general-purpose",
  run_in_background: false,   // barrier: put all calls of a batch in ONE message
  description: "diagram <skill-name>",
  prompt: `Read <abs>/.claude/skills/analyze-plugin/references/diagram-agent-instructions.md and follow it EXACTLY.
    name: <skill-name>
    OUT_DIR: <abs>/site/docs/plugins/<plugin-name>
    SCRATCH: <abs>/<scratch-path>   # see the SCRATCH naming rule below -- two disjoint namespaces
    SKILL_MD: <abs>/<WORKDIR>/<SKILLS_DIR>/<dir-name>/SKILL.md   # WORKDIR + SKILLS_DIR from Step 2; git-subdir member -> <abs>/.tmp/skill-repos/<plugin-name>/<source.path>/skills/<dir-name>/SKILL.md
    DIAGRAM_SKILLS: <DIAGRAM_SKILLS>
    Suggested flow: <the per-skill outline from Step 5.4 — roles + llm count>
    Callout target: <the skill's primary output artifact to ground a callout>
    Reserved-id traps: <per-skill, e.g. mlflow: push->push-fb; check: filter->filter-classify>`
})
```

Use `<dir-name>` from the Step 3 name mapping; `<skill-name>` from the registry for
output paths (so site files match registry names). Launch in **barrier batches of ~6**
(all Agent calls in a single message, then wait for the batch). For the pipeline, pass
`name: pipeline` and a whole-plugin flow (one node per skill, fan-out + feedback
edges); the per-skill callout floor is relaxed for that overview.

**SCRATCH naming rule (prevents cross-plugin corruption).** Every scratch path is rooted
at the plugin, so nothing is shared between two concurrently-running plugins:

| diagram | `<scratch-path>` |
|---|---|
| pipeline overview | `.tmp/diagram-work/plugins/<plugin-name>/pipeline/artifacts` |
| per-skill | `.tmp/diagram-work/plugins/<plugin-name>/skills/<skill-name>/artifacts` |

This matters because `generate-site` launches 6-8 `analyze-plugin` agents **in
parallel**, and any shared dir means they concurrently write the same `graph-spec.json`
and `layout-plan.json`. The damage is silent: a page gets a diagram rendered from
another plugin's layout plan, with no error anywhere.

Two collisions make the plugin root necessary, and neither is avoided by a cleverer flat
name:

- **Pipeline.** A bare `.tmp/diagram-work/pipeline/` is the same string for every plugin.
  Qualifying it as `<plugin-name>-pipeline` in a flat namespace still collides with a
  skill literally *named* `<plugin-name>-pipeline` -- `odh-documentation` ships
  `doc-pipeline`, so a plugin named `doc` would land on it.
- **Per-skill.** Skill names are **not** unique across plugins. `check_duplicates()` in
  `validate_registry.py` only rejects duplicate *plugin* names, and the registry today
  has three skill names in more than one plugin: `export-rubric` (`strat-creator`,
  `assess-rfe`, `assess-strat`), `failure-analysis` (`autoqa-skills`,
  `python-package-skills`) and `gitlab-code-review` (`code-review-skills`,
  `productization-skills`). A bare `skills/<skill-name>/` dir is therefore a **live**
  race: `assess-rfe` and `assess-strat` both generate `export-rubric` in the same
  `generate-site` fan-out.

`OUT_DIR` is already per-plugin, so output filenames are unaffected -- only scratch paths
change. Rooting everything at `plugins/<plugin-name>/` also makes the Step 3 clean-slate
a single directory to clear, with no way to touch a sibling's.

Agents produce only `<name>.d2` + `<name>.drawio` (no SVG). **You (main thread) then
export SVGs sequentially** — do NOT let agents export (draw.io desktop contention):

```bash
# Verify + recover FIRST (Detail-Floor check and transient-failure recovery below);
# export only diagrams whose .drawio exists and passed — a missing input would
# otherwise abort the loop mid-way.
for name in pipeline <skill-1> <skill-2> ...; do
  drawio=site/docs/plugins/<plugin-name>/$name.drawio
  [ -f "$drawio" ] || { echo "SKIP $name — no .drawio yet, recover it first"; continue; }
  python3 <DIAGRAM_SKILLS>/skills/diagram-layout/scripts/export_diagram.py \
    "$drawio" site/docs/plugins/<plugin-name>/$name.svg
done
# Clean draw.io backup side-effects, scoped to the plugin output dir (never repo-wide):
find site/docs/plugins/<plugin-name> \( -name '*.drawio.bkp' -o -name '.*.drawio.bkp' \) -delete
```

**Verify every diagram clears the Detail Floor:** `<mxCell` count > 2, `value=""` == 0,
≥1 callout (`grep -c 'JetBrains Mono' <name>.drawio` ≥ 1), `double=1` count == the
designed llm-node count and == the `strokeWidth=3` count (no thick-vs-double drift),
and SVG size in a healthy range (~150k–1.3M). Re-author or fix any diagram that misses
the floor — an under-detailed diagram is not done.

**Verify SEMANTICS, not just density** (the mechanical floor above is necessary but
not sufficient — it catches style/density regressions, not accuracy). Run
`validate_d2.py` (it now also flags one-exit and unlabeled-branch decisions) and clear
its `detail_warnings`, then check each diagram against its SKILL.md for the classes a
linter can't see: (a) each output-artifact callout is anchored to the node that
PRODUCES it, not a downstream consumer; (b) every decision fans out to ≥2
condition-labeled branches; (c) no script-internal flag/behavior absent from the
SKILL.md is shown as user-facing (read the *documented* interface, use scripts only for
artifact structure); (d) each artifact uses one canonical path and callout claims match
the actual commands. For a thorough run, spawn a cheap per-diagram verify agent (or a
workflow adversarial-verify pass) that reads the diagram + its SKILL.md and reports
these — then fix what it finds. This is the class of defect that otherwise surfaces
only in downstream code review.

**Recovery for transient failures.** At this fan-out, agents occasionally die on
`Stream idle timeout` / `Connection closed mid-response` (not a task problem). If an
agent wrote a fresh `layout-plan.json`, finish it in the main thread
(`fix_layout.py → validate_layout.py → render_drawio.py`); if it wrote nothing,
relaunch it. If the skill's SKILL.md is unchanged vs the backed-up baseline and that
backup already clears the Detail Floor, restore the backup `.d2`/`.drawio` and just
re-export its SVG.

Skip diagram generation for placeholder skills with no real workflow (e.g., "not yet
implemented"). Reserved-id note: draw.io export fails (silently or hard) on cell ids
`filter`, `push`, `output`, `find` — the recipe handles renaming; surface any per-skill
occurrence in the agent's task prompt.

### 7. Regenerate site pages

Run the generation script to merge the new enrichment data into the site pages:

```bash
python3 scripts/generate_site.py
```

### 8. Report results

Report:
- Number of skills analyzed
- Enrichment file path
- Number of diagrams generated (pipeline + individual)
- Any skills skipped (not found in repo, too simple for diagrams)
- Any diagram export failures (with suggested fixes)

### Cleanup

The cloned repo in `.tmp/skill-repos/<plugin-name>` (a `git-subdir` member clones its
whole monorepo here; its subdir is `WORKDIR`) can be left in place for future
re-runs (it's gitignored). To force a fresh clone, delete it before running.
Files in this package (2)
  • SKILL.md 27 KB
  • references/diagram-agent-instructions.md 15 KB

Versions

The database has no other skills named analyze-plugin.

Database snapshot: 13.11.2026 · package version 9cdd841a93db (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100generate-site
    Orchestrate full documentation site generation for the skills-registry — structural pages from registry.yaml plus AI-enriched content and presentation-quality SVG diagrams for all plugins. Use when the user wants to rebuild the docs, update the website, regenerate pages after…
  • 100creating-docs-diagrams
    Creates accessible hand-authored inline SVG architecture and sequence diagrams for documentation. Use when adding, replacing, or reviewing docs diagrams, especially Mermaid flowcharts.
  • 100plugin-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.
  • 95docs-manager
    Documentation management workflow for MkDocs sites and standalone markdown files -- initialize, generate, update docs, and create change summaries. Use when asked to "create docs", "write README", "update documentation", "generate docs site", "write CONTRIBUTING", "manage…
  • 95docs-manager
    Documentation management workflow for MkDocs sites and standalone markdown files -- initialize, generate, update docs, and create change summaries. Use when asked to "create docs", "write README", "update documentation", "generate docs site", "write CONTRIBUTING", "manage…
  • 90d2
    Create, validate, render, or revise D2 diagrams using d2-mcp. Use for architecture, flow, dependency, sequence, and data diagrams when D2 source or a PNG, SVG, or ASCII artifact is wanted.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.