Allow users to browse complete Team Skill directories

[Gandy2025]

Status

Deferred / backlog. Do not start implementation until this is explicitly prioritized.

Problem

First Tree now stores a Team Skill as one authoritative immutable ZIP bundle and the Client Runtime materializes the complete directory, including SKILL.md, references/, scripts/, assets, and binary files. This landed through #2062 and #2078.

The Web still exposes only the derived Skill description or SKILL.md body. A user cannot inspect the supporting files that the agent actually receives, so they cannot understand or verify the complete Skill from Agent Detail or Settings.

Proposed experience

Add one reusable read-only Skill directory viewer.

• Agent Detail → Tools & skills: clicking a Skill title opens the viewer.
• Settings → Resources: the existing Skill preview action opens the same viewer.
• Desktop: a minimal two-column dialog with the file tree on the left and the selected file on the right.
• Narrow screens: replace the left tree with a file selector above the content.
• Select SKILL.md by default.
• Keep the dialog chrome to the Skill name and close action.

File rendering:

• SKILL.md: hide YAML frontmatter and render the instruction body as Markdown.
• Other Markdown: render with the existing safe Markdown component.
• Text, source, JSON, YAML, and scripts: show as read-only plain text.
• PNG, JPEG, GIF, and WebP: show an image preview.
• SVG, HTML, and unsupported binary files: keep them visible in the tree, but show an unsupported-preview state. Never execute bundle content.

Technical direction

Reuse the existing bundle and attachment path rather than introducing another content model:

Resource bundle attachment id
  -> existing authenticated attachment download
  -> thin browser-only read adapter
  -> read-only file tree and selected-file preview

• Settings already receives ResourceRow.bundleAttachmentId.
• Enabled Agent resources already receive EffectiveResourceRow.skillBundle.attachmentId.
• For a disabled Team Skill, resolve the bundle id from the existing availableTeamResources collection by resourceId.
• Fetch the immutable ZIP lazily only when the viewer opens; do not increase the initial Agent Resources payload.
• Use the Web's existing fflate dependency for browser reads and reuse the shared Skill path/size contracts where applicable.
• Do not duplicate the Server or Node Runtime's full ZIP validation model. The browser adapter is a defensive read-only presentation layer.
• The existing Node Runtime extractor cannot be imported into Web because it depends on Node filesystem, streams, Buffer, and yauzl.
• A legacy bundle-less Skill may degrade to a virtual single-file SKILL.md view. A referenced-but-unreadable authoritative bundle must show an error rather than silently falling back to a potentially divergent inline projection.

No Server route, shared DTO, database migration, attachment permission change, Client Runtime change, CLI change, or new dependency should be needed for the first version.

Non-goals

• Editing files
• Search
• Download
• Syntax highlighting
• Source, format, file-count, read-only, or metadata chrome
• Multiple view modes
• Automatic navigation for relative links inside Markdown

Acceptance criteria

• Any member who can view the Skill on the current surface can open its read-only directory viewer.
• Agent Detail and Settings use the same viewer implementation.
• The viewer lists the complete normalized directory and opens SKILL.md by default.
• Supported Markdown, text/source, and raster image files render correctly.
• Unsupported binary content is never executed and has a clear preview-unavailable state.
• Disabled Team Skills remain inspectable without toggling them on.
• Skill-title activation does not interfere with the enable Switch or overflow menu.
• Bundle download and extraction happen only after opening the viewer and expose loading, error, and retry states.
• The viewer is keyboard accessible and works at desktop and 430 px widths.
• Object URLs and cached uncompressed bytes are released after bounded inactivity.
• Parser, dialog, Agent Detail, and Settings behavior have focused automated coverage.
• Desktop and narrow-screen flows are verified in a real browser with a multi-file uploaded Skill ZIP.