Skill 透视镜 · Skill Lens
Turn one local Skill into a scenario-first trust brief rather than an evidence
explorer. The standalone HTML answers when the Skill is the right choice, shows
its input-to-outcome transformation as one uninterrupted reading path, and then
separates source declarations, supporting capability, checks, and unproven
effect. Mermaid remains editable secondary evidence, not the primary interface
and not proof that the target Skill works.
Triggers
Activate when
- 用户提供本地 Skill 目录或
SKILL.md,说“画出这个 Skill 的运行逻辑”。
- 用户说“把 Skill 的触发、步骤、分支和依赖生成 Mermaid 流程图”。
- The user says “visualize this skill workflow” or “generate a Mermaid diagram for this Skill”.
Do not activate when
- 用户只要把已经整理好的流程美化成通用 SVG;交给通用 diagram renderer。
- 用户要审计并修改 Skill 质量、版本或分发同步;交给
lov-skill-optimizer。
- 用户要展示多个 Skill 之间的目录依赖,而非单个 Skill 的运行契约;使用目录依赖可视化能力。
User Profile (cross-session)
Every generated Skill is connected to the shared user-profile/v1 contract in
skill.yaml. Read the shared user, brand, workspace, preferences, and this
Skill's skills.<skill_id> namespace at the start of every run. Keep the source
portable: resolved personal values belong in the shared profile, never here.
When the user directly states a durable preference or brand fact, persist it
through scripts/profile_store.py and report the saved profile path. Put
Skill-specific values under records.<field>; use brand.<field> or
user.<field> for shared values. Do not persist inferred secrets or credentials.
See references/user-profile.md for the complete contract.
Skill Group Composition
Read references/skill-composition.md before deciding whether to invoke or
extend any adjacent capability. The record distinguishes optional upstream and
downstream handoffs from embedded Kit modules. Do not silently depend on a
sibling Skill that is not shipped with this source.
Workflow (MANDATORY)
You MUST follow these steps in order.
Step 0: Resolve skill root, dependencies, and runtime context
- Use
SKILL_DIR if the environment provides it.
- Otherwise infer the installed skill directory from the current skill context.
- Verify every required local module, reference, script, and asset before work.
- If a required resource is missing, name its expected relative path and stop
before producing a partial result.
When running scripts manually:
export SKILL_DIR="/path/to/lov-skill-visualizer"
Resolve context.profile on every invocation. The precedence is current request,
project context, Skill-specific profile records, shared preferences, shared
brand/user profile, then safe defaults. A direct user statement about a durable
preference or brand fact should be saved with scripts/profile_store.py record
using --confirm, followed by a concise saved-path report.
Step 1: Understand the requested outcome
- Resolve the explicit Skill directory or
SKILL.md path. Resolve symlinks, but
show only Skill-relative paths in the report.
- Default to a Markdown report with Mermaid, a sibling standalone HTML review,
and a JSON model. Respect explicit output paths, diagram direction, language,
or reference depth.
- If the user supplied a valid target, do not ask them to choose parser or
renderer machinery. Mermaid is the default because it remains editable.
Step 1.5: Analyze nearby Skills before implementation
- Inspect related local and installed Skills by routing contract and concrete
input/output, not by filename alone.
- Record upstream, core, downstream, overlap, and not-composed decisions in
references/skill-composition.md.
- Keep sibling Skills optional and artifact-based. When stages require hard
coupling for one outcome, create a self-contained Kit instead.
Step 2: Extract the declared runtime contract
Run the standalone extractor:
python3 "$SKILL_DIR/scripts/visualize_skill.py" "$TARGET_SKILL" \
--output "$OUTPUT_MARKDOWN" \
--json "$OUTPUT_JSON" \
--language auto \
--direction TB \
--max-depth 2
--output path/report.md also writes path/report.html by default. Use
--html path/custom.html to choose another location or --no-html when the
standalone review is intentionally not required.
- Accept either a Skill directory or its
SKILL.md.
- Extract routing examples, workflow steps, explicit conditional rules,
frontmatter dependencies, Profile runtime context, Skill Kit pipelines, and
local resources reachable from the controller.
- Preserve each step's authored actions, criteria, decisions, guardrails,
commands, and verification instructions as line-bound detail items.
- Parse embedded Kit module workflows and quality gates, then associate a
controller step only when the module or pipeline is explicitly named.
- Build a trust model that separates traceable declarations, supporting
modules/resources, deterministic implementation, declared checks, observed
artifacts, and unproven runtime effect.
- Follow linked local Markdown references up to
--max-depth. Inventory
packaged scripts, references, assets, and modules even when they are not
linked, so dead or implicit resources remain visible.
- Treat only declared text as fact. Do not invent a branch, dependency, or
success state to make the diagram look complete.
Read references/logic-model.md for the JSON fields, extraction rules, Mermaid
structure, and known static-analysis limits.
Step 3: Review diagnostics and evidence
- Every extracted trigger, step, and condition keeps a relative file and line
span. Use those spans to resolve ambiguity in the source instead of guessing.
error diagnostics mean the report is structurally incomplete, such as a
missing workflow or referenced file. warning and info preserve useful
gaps without blocking an exploratory report.
- Use
--strict when the report is part of a quality gate. Exit code 3 means
extraction completed but at least one error diagnostic remains; exit code
2 means the target or runtime could not be processed.
- Open the standalone HTML in a browser for review. The first screen must answer
what concrete situation justifies this Skill and what cross-step problem it
solves. Do not begin with coverage metrics, an abstract feature list, or a
graph the reviewer must explore.
- The primary runtime graph starts at internal execution. Activation and
non-trigger examples belong to an explicitly external, collapsed host-routing
section and must never appear as a yes/no branch in the internal graph.
- Turn the selected workflow or Kit pipeline into one fixed, fully visible
narrative: starting state, internal transformations, resulting state, why the
Skill is a better fit than narrower tools, and the explicit non-use boundary.
- Do not require node clicking, dragging, zooming, tab switching, or an evidence
inspector to understand the primary logic. The reviewer must be able to read
the complete path by scrolling once.
- Keep rendered Mermaid views for internal runtime, resources, and optional Kit
pipelines inside one secondary technical-evidence disclosure. Nodes are not
navigation controls. Raw Mermaid, routing, resources, diagnostics, and JSON
remain available for verification after the conclusion.
- Resolve
records.html_review_presentation from the shared Profile. Default to
a restrained, purpose-first layout. When the resolved language is Chinese,
localize interface and display labels wherever semantics can be preserved;
keep filenames, paths, Skill IDs, commands, source code, and Mermaid syntax in
their original form.
- Resolve
records.review_narrative as the presentation contract. Prefer a
scenario-first single page, read-only linear logic, and collapsed technical
evidence. Do not turn evidence coverage into a generic card wall.
- The HTML embeds all CSS, JavaScript, Mermaid 11.12.2, Mermaid source, and JSON,
so it requires no network or hosted renderer. Use optional downstream
renderers only for alternate presentation formats.
Step 4: Validate the deliverable
- Confirm the requested Markdown, HTML, and JSON output files exist and are
UTF-8 readable.
- Check that the Markdown contains Mermaid
flowchart blocks and that the JSON
declares lovstudio/skill-logic/v1.
- Check that the HTML contains the embedded
logic-model, has no external
scripts or stylesheets, and remains usable at desktop and mobile widths.
- Confirm technical evidence is closed by default, Chinese display labels are
present for a Chinese report, and the extracted JSON model remains unchanged.
- Assert that the primary page contains no node selector, zoom control, diagram
tabs, or button-driven evidence workspace.
- Use a real browser to require every declared Mermaid host to contain an SVG
after rendering, external routing to remain absent from the runtime graph,
the linear stages to fit the desktop layout, and the page itself to avoid
horizontal overflow at mobile width.
- Report extracted step, condition, linked-resource, and missing-resource
counts. Preserve diagnostics in the handoff; a generated file is not proof of
full coverage.
- For source validation, run
python3 scripts/validate_skill.py .; for focused
parser tests, run PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests.
Dependencies
- Python 3.8 or newer.
- PyYAML for frontmatter and manifest parsing.
- Vendored Mermaid 11.12.2 browser runtime under
assets/vendor/.
- No Mermaid CLI, network access, or sibling Skill is required to generate or
review the outputs. A modern browser renders the embedded runtime.
1---2name: lov-skill-visualizer3description: >4 把本地 Agent Skill 目录或 SKILL.md 解析成场景先行的一页式信任审阅、内部5 运行图和 JSON 模型;先说明什么时候非它不可,再连续展示输入、内部转化、6 交付结果、源码依据与未证明缺口。当用户要理解、审阅或信任一个 Skill 时使用。7license: MIT8depends_on:9 - lov-branding-consistency10metadata:11 source: https://skillmd.com/skills/lovstudio/lov-skill-visualizer12 author: contributors13 version: "0.6.1"14 card_standard: lovstudio/skill-card/v115 tags:16 - skill-visualization17 - mermaid18 - workflow19 - static-analysis20 compatibility: "Python 3.8+ and PyYAML; generated HTML embeds Mermaid 11.12.2 and works offline in a modern browser."21 dependencies:22 - python323 - PyYAML24---2526# Skill 透视镜 · Skill Lens2728Turn one local Skill into a scenario-first trust brief rather than an evidence29explorer. The standalone HTML answers when the Skill is the right choice, shows30its input-to-outcome transformation as one uninterrupted reading path, and then31separates source declarations, supporting capability, checks, and unproven32effect. Mermaid remains editable secondary evidence, not the primary interface33and not proof that the target Skill works.3435## Triggers3637### Activate when3839- 用户提供本地 Skill 目录或 `SKILL.md`,说“画出这个 Skill 的运行逻辑”。40- 用户说“把 Skill 的触发、步骤、分支和依赖生成 Mermaid 流程图”。41- The user says “visualize this skill workflow” or “generate a Mermaid diagram for this Skill”.4243### Do not activate when4445- 用户只要把已经整理好的流程美化成通用 SVG;交给通用 diagram renderer。46- 用户要审计并修改 Skill 质量、版本或分发同步;交给 `lov-skill-optimizer`。47- 用户要展示多个 Skill 之间的目录依赖,而非单个 Skill 的运行契约;使用目录依赖可视化能力。4849## User Profile (cross-session)5051Every generated Skill is connected to the shared `user-profile/v1` contract in52`skill.yaml`. Read the shared user, brand, workspace, preferences, and this53Skill's `skills.<skill_id>` namespace at the start of every run. Keep the source54portable: resolved personal values belong in the shared profile, never here.5556When the user directly states a durable preference or brand fact, persist it57through `scripts/profile_store.py` and report the saved profile path. Put58Skill-specific values under `records.<field>`; use `brand.<field>` or59`user.<field>` for shared values. Do not persist inferred secrets or credentials.60See `references/user-profile.md` for the complete contract.6162## Skill Group Composition6364Read `references/skill-composition.md` before deciding whether to invoke or65extend any adjacent capability. The record distinguishes optional upstream and66downstream handoffs from embedded Kit modules. Do not silently depend on a67sibling Skill that is not shipped with this source.6869## Workflow (MANDATORY)7071**You MUST follow these steps in order.**7273### Step 0: Resolve skill root, dependencies, and runtime context7475- Use `SKILL_DIR` if the environment provides it.76- Otherwise infer the installed skill directory from the current skill context.77- Verify every required local module, reference, script, and asset before work.78- If a required resource is missing, name its expected relative path and stop79 before producing a partial result.8081When running scripts manually:8283```bash84export SKILL_DIR="/path/to/lov-skill-visualizer"85```8687Resolve `context.profile` on every invocation. The precedence is current request,88project context, Skill-specific profile records, shared preferences, shared89brand/user profile, then safe defaults. A direct user statement about a durable90preference or brand fact should be saved with `scripts/profile_store.py record`91using `--confirm`, followed by a concise saved-path report.9293### Step 1: Understand the requested outcome9495- Resolve the explicit Skill directory or `SKILL.md` path. Resolve symlinks, but96 show only Skill-relative paths in the report.97- Default to a Markdown report with Mermaid, a sibling standalone HTML review,98 and a JSON model. Respect explicit output paths, diagram direction, language,99 or reference depth.100- If the user supplied a valid target, do not ask them to choose parser or101 renderer machinery. Mermaid is the default because it remains editable.102103### Step 1.5: Analyze nearby Skills before implementation104105- Inspect related local and installed Skills by routing contract and concrete106 input/output, not by filename alone.107- Record upstream, core, downstream, overlap, and not-composed decisions in108 `references/skill-composition.md`.109- Keep sibling Skills optional and artifact-based. When stages require hard110 coupling for one outcome, create a self-contained Kit instead.111112### Step 2: Extract the declared runtime contract113114Run the standalone extractor:115116```bash117python3 "$SKILL_DIR/scripts/visualize_skill.py" "$TARGET_SKILL" \118 --output "$OUTPUT_MARKDOWN" \119 --json "$OUTPUT_JSON" \120 --language auto \121 --direction TB \122 --max-depth 2123```124125`--output path/report.md` also writes `path/report.html` by default. Use126`--html path/custom.html` to choose another location or `--no-html` when the127standalone review is intentionally not required.128129- Accept either a Skill directory or its `SKILL.md`.130- Extract routing examples, workflow steps, explicit conditional rules,131 frontmatter dependencies, Profile runtime context, Skill Kit pipelines, and132 local resources reachable from the controller.133- Preserve each step's authored actions, criteria, decisions, guardrails,134 commands, and verification instructions as line-bound detail items.135- Parse embedded Kit module workflows and quality gates, then associate a136 controller step only when the module or pipeline is explicitly named.137- Build a trust model that separates traceable declarations, supporting138 modules/resources, deterministic implementation, declared checks, observed139 artifacts, and unproven runtime effect.140- Follow linked local Markdown references up to `--max-depth`. Inventory141 packaged scripts, references, assets, and modules even when they are not142 linked, so dead or implicit resources remain visible.143- Treat only declared text as fact. Do not invent a branch, dependency, or144 success state to make the diagram look complete.145146Read `references/logic-model.md` for the JSON fields, extraction rules, Mermaid147structure, and known static-analysis limits.148149### Step 3: Review diagnostics and evidence150151- Every extracted trigger, step, and condition keeps a relative file and line152 span. Use those spans to resolve ambiguity in the source instead of guessing.153- `error` diagnostics mean the report is structurally incomplete, such as a154 missing workflow or referenced file. `warning` and `info` preserve useful155 gaps without blocking an exploratory report.156- Use `--strict` when the report is part of a quality gate. Exit code `3` means157 extraction completed but at least one error diagnostic remains; exit code158 `2` means the target or runtime could not be processed.159- Open the standalone HTML in a browser for review. The first screen must answer160 what concrete situation justifies this Skill and what cross-step problem it161 solves. Do not begin with coverage metrics, an abstract feature list, or a162 graph the reviewer must explore.163- The primary runtime graph starts at internal execution. Activation and164 non-trigger examples belong to an explicitly external, collapsed host-routing165 section and must never appear as a yes/no branch in the internal graph.166- Turn the selected workflow or Kit pipeline into one fixed, fully visible167 narrative: starting state, internal transformations, resulting state, why the168 Skill is a better fit than narrower tools, and the explicit non-use boundary.169- Do not require node clicking, dragging, zooming, tab switching, or an evidence170 inspector to understand the primary logic. The reviewer must be able to read171 the complete path by scrolling once.172- Keep rendered Mermaid views for internal runtime, resources, and optional Kit173 pipelines inside one secondary technical-evidence disclosure. Nodes are not174 navigation controls. Raw Mermaid, routing, resources, diagnostics, and JSON175 remain available for verification after the conclusion.176- Resolve `records.html_review_presentation` from the shared Profile. Default to177 a restrained, purpose-first layout. When the resolved language is Chinese,178 localize interface and display labels wherever semantics can be preserved;179 keep filenames, paths, Skill IDs, commands, source code, and Mermaid syntax in180 their original form.181- Resolve `records.review_narrative` as the presentation contract. Prefer a182 scenario-first single page, read-only linear logic, and collapsed technical183 evidence. Do not turn evidence coverage into a generic card wall.184- The HTML embeds all CSS, JavaScript, Mermaid 11.12.2, Mermaid source, and JSON,185 so it requires no network or hosted renderer. Use optional downstream186 renderers only for alternate presentation formats.187188### Step 4: Validate the deliverable189190- Confirm the requested Markdown, HTML, and JSON output files exist and are191 UTF-8 readable.192- Check that the Markdown contains Mermaid `flowchart` blocks and that the JSON193 declares `lovstudio/skill-logic/v1`.194- Check that the HTML contains the embedded `logic-model`, has no external195 scripts or stylesheets, and remains usable at desktop and mobile widths.196- Confirm technical evidence is closed by default, Chinese display labels are197 present for a Chinese report, and the extracted JSON model remains unchanged.198- Assert that the primary page contains no node selector, zoom control, diagram199 tabs, or button-driven evidence workspace.200- Use a real browser to require every declared Mermaid host to contain an SVG201 after rendering, external routing to remain absent from the runtime graph,202 the linear stages to fit the desktop layout, and the page itself to avoid203 horizontal overflow at mobile width.204- Report extracted step, condition, linked-resource, and missing-resource205 counts. Preserve diagnostics in the handoff; a generated file is not proof of206 full coverage.207- For source validation, run `python3 scripts/validate_skill.py .`; for focused208 parser tests, run `PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests`.209210## Dependencies211212- Python 3.8 or newer.213- PyYAML for frontmatter and manifest parsing.214- Vendored Mermaid 11.12.2 browser runtime under `assets/vendor/`.215- No Mermaid CLI, network access, or sibling Skill is required to generate or216 review the outputs. A modern browser renders the embedded runtime.