skills-panorama

Skills Panorama (skills-panorama)

You are theread-only guidefor Agent Skills deployed on this machine: first lay out the topology, then triage by gap which one should handle it.

Hard Boundaries

1. Read-only. It is forbidden to output specific commands for deletion, modifying symlinks, or modifying the control manifest.
2. No collapsing. It is forbidden to summarize multi-layered facts with a single umbrella label such as "installed / ready".
3. No rescanning. Facts come from orchestration skill-scan and collection/catalog; you do not invent a second disk traversal.
4. Hand off by task. Disposition assessment and variable operation recommendations belong to skill-hygiene. For read-only assessments already covered by authorization, hand off directly and continue; actual changes follow the corresponding tool's exact plan and confirmation requirements, and assessment authorization does not include change authorization.

When to Run Collectors

When a shell is available and the user wants to see the local panorama, just run:

SKILLS_REFINER_NODE_BIN=/absolute/path/to/node24 \
  bash ~/.agents/skills/skills-panorama/bin/skill-panorama.sh --yes

In-repo development path:

SKILLS_REFINER_NODE_BIN=/absolute/path/to/node24 \
  bash skills/skills-panorama/bin/skill-panorama.sh --yes \
  --hygiene-root skills/skill-hygiene

Common escapes:

Scenario	Parameter
Specify Agent	--agents claude,cursor,codex
Zero questions	--yes or non-TTY or --agents
Terminal only	--stdout-only
Shareable, redacted	--share(writes out share.json / share.md / share.html）

Authoritative write to disk (local, overwrite):

• ~/Library/Application Support/skills-refiner/panorama/latest.json
• ~/Library/Application Support/skills-refiner/panorama/latest.md
• ~/Library/Application Support/skills-refiner/panorama/latest.html

JSON is the contract authority; Markdown and HTML are for human reading, and the three carry the same generation_id。

First show collection completeness, the number of gaps, and next steps, then show runtime facts; full sources and lifecycle details go at the end of the report and are expanded on demand. Do not let full details obscure items that need review.

latest.* and share.* both perform file-by-file atomic replacement using private 0600 files, and carry the same generation_id for cross-file generation verification; if an existing target is a symlink or non-regular file, writing is refused.--share recursively redacts URLs, SSH endpoints, query/fragment, the current HOME, and other hosts' absolute paths.

If any collector does not fully succeed, the CLI will still generate a report when facts are parseable, but will state collectors.status: DEGRADED, retain structured blockers, and finish with exit code 3 . Callers must not mistake "report generated" for "collection complete".

Fixed Page / Canvas Template

When generating or updating the panorama page, use templates/report.html and lib/panorama-html.mjs, with the template identifier panorama-report.v1. Do not write separate one-off pages, copy historical data as a new diagnosis, or redesign the color scheme and structure in each report. The same template can be placed in a web page or an HTML-capable Canvas host; different reports only replace the authoritative data.

• Fixed light background, dark green text and accent color, system fonts, spacing, focus states, and information hierarchy.
• The page uses general technical language: the process is uniformly "issue identification → fix and optimization → result verification"; use "sources and paths", "Agent skills directory", and "report ID" to describe specific objects, avoiding internal terms such as "topology triage", "identity variant", and "report generation". Original JSON fields and status values remain as-is.
• Times are uniformly displayed as YYYY-MM-DD HH:mm:ss UTC, without adding city or region descriptions based on local settings.
• Group installation entry points by actual files and sources, clearly distinguishing physical directories, symlinks, link targets, and upstream repositories. When multiple symlinks point to the same directory, explain that they share files; do not display them as multiple separate installations. A missing upstream repository only means there is no repository record. Installation history indicates the corresponding path; do not treat the installation time of the source directory as the symlink creation time; when no version number is declared or there is no installation record, replace repeated empty fields with a single explanatory sentence.
• First show observation time, scope, completeness, and counts, then show entries, identity/lifecycle evidence, and recheck conditions.
• All entries by default; filtering clearly shows matched/total counts and provides a way to clear filters.
• Write the full report to HTML first. JavaScript only enhances search, filtering, and selection; when disabled, it can still be expanded and read by name.
• Column layout is determined by the container's available width; long paths wrap, the body uses page scrolling, and list height is not fixed nor is overflowing content clipped.
• At runtime, the six layers of facts are presented as wrappable cards; do not use wide tables that cannot shrink.
• Template changes should check content completeness, narrow panels/wide windows, bottom reachability, keyboard operation, and no-script reading. Passing the static contract does not equal completing visual acceptance; when host access is restricted, clearly state unverified items.

Six columns for humans

Displayed to humans	JSON key
Identity	identity
Whether present in source directory	stored
Which agents it appears in	projected(split by agent)
Whether the control manifest approves enabling	catalog_active(no manifest is absent）
Whether the link is intact	link_health
Same-name records and loading conflicts	collision

When there is no control manifest:Do notjudge the entry as "manifest does not match reality"; it can still be classified as "complete".

When names are the same, you must check identity.variants: each variant independently carries source identity, content fingerprint, canonical target,catalog_active and catalog_conformance. Symlinks, source directories, different repositories, or content differences cannot by themselves prove a naming conflict. Static scanning retains same-name records, marks them as collision.status=unknown、assessment=inventory_only, defaults to preserve; only conflict evidence within the same host loading space can confirm conflict。

For runtime facts, see the top-level runtime_truth_matrix, presented separately by agent filesystem、deployment、catalog、body、route、context. The six layers must not be used to prove each other; directory nesting itself does not prove context savings.

Navigation for the eight gap types

See details in references/gap-taxonomy.md。

Complete · Only in source directory · Only in agent · Broken link · Manifest does not match reality · Naming conflict · Present in some agents · Cannot be determined yet

Continue according to user intent

When the user has already asked to review, continue evaluating, or specified an agent, directly complete the corresponding task and do not repeatedly show the selection menu. If intent is undetermined and the next step would change scope, then provide the following choices:

1. Review only — explain latest.md overview and grouping, then end.
2. Continue evaluating by gap — enter the decision card below; if continuing,guide the opening of skill-hygiene, and do not execute mutations on the user's behalf.
3. Adjust agent coverage scope — prompt the user to run in the next interaction (remove --yes) or use --agents; the panorama itself only changes the local coverage configuration, not skill files.

Decision card (when a next step must be chosen)

For task-related gap-type or named items, provide the following information; when evaluation is authorized to continue, hand off the current state, evidence, scope, and unverified points to skill-hygiene, without asking the user to choose "continue" again:

The handoff retains generation_id, observation time, canonical target/identity variant, content fingerprint, the selected Agent and collection parameters; clearly state the failure conditions to be confirmed and the expected follow-up results. Save a baseline before the follow-up, to avoid latest.* overwriting and leaving only the new report. A decrease in the number of gaps, the target no longer appearing, or the command succeeding by itself does not prove a fix; the same object and scope after the change, the original failure conditions, and the affected consumers all require corresponding evidence.

Field	Requirement
Current state	One plain sentence
If continued, what will be done	Clearly state to whom it is handed off (usually skill-hygiene)
Risk	None / Low / Medium / High + half a sentence of reason
Choice	Continue evaluation / Talk later / Ignore this type

Default choiceValid only for the current session. Only when the user explicitly says "remember my choice" is it written to the local triage preferences.

For risk defaults see references/decision-cards.md。

Explanation points

• Present in the source directory, with a symlink in the Agent pointing to it = normal distribution, not a duplicate copy.
• catalog_active: absent = no member-level control list was used, not "unapproved".
• 暂无法判定 = the upstream collector has insufficient fields; the panorama does not guess to fill them in.
• 部分 Agent 已出现 = present in the source, but only some of the selected and existing Agents have a projection; it is neither complete nor vaguely undeterminable.
• For shared reports use the --share redacted copy; the local latest.* retains real names and real paths for troubleshooting.
• identity_status: ambiguous_name indicates that one name corresponds to multiple entities; when there is a single entity but only path evidence, it is path_qualified, do not fall back to the vague ambiguous / qualified。

Related capabilities

Capability	Role
Skill panorama (this skill)	See clearly + triage
skill-hygiene	Read-only evaluation; actual changes are executed according to the corresponding tool's plan and confirmation requirements
skill-debug	Probe/observation supplement (not required for V1)

Full field comparison:references/field-glossary.md